Server API

External API

Server scripts have the following Lua APIs available:

In addition, server scripts have access to the 'server' API, which is composed of:

server.eventhandler()

This returns a standard Targetware event handler. When the event handler's function(s) are called, the first argument indicates the type of event.

server.idle. This will be followed by one additional argument, which is the number of seconds that have elapsed since the last time a server.idle event occurred.
server.login. This will be followed by two additional arguments. The first is the numerical network identifier for the player logging in, the second is a string containing the name of the player logging in.
server.logout. This has the same arguments as server.login.
server.shutdown. This is called just before the server script terminates, allowing any necessary final actions.
server.message. This also has the same arguments as server.login, but can be followed by an arbitrary number of additional arguments. This is the event that is called when the Client API sends a message to the server.

server.idlefrequency(): This returns the time in seconds between server.idle calls to the event handler. Zero or a negative value will result in the server.idle event not occurring.

server.setidlefrequency( <number> ): This sets the time between server.idle calls to the event handler. Note that the elapsed time may not always be exactly the time requested, but it will always be at least the time requested.

server.online(): This returns true if the server is online and registered with the metaserver, false otherwise.

server.quit(): This shuts down the server. It's the server script's responsibility to save any persistent data before making this call.

server.pingmessage(): This returns a string containing the message included when a client or webpage asks the server for its current status.

server.clientscript(): This returns a string containing the filename of the script clients will be asked to execute when logging in to the server. A client must have the correct script in order to log in. Note that if this is called while clients are currently logged in, those clients will be forced to change their client script immediately.

server.send( <recipient>, ... ): This sends a message to a single client. The first argument, the recipient, may either be the numerical network identifier for a player, or a string containing the name of a player. Zero or more additional arguments can be included afterwards - the client will receive them as a message. The additional arguments can be nil, booleans, numbers, strings, or tables that can be derived from a configuration file only.

server.sendall( ... ): This sends a message to all clients. It works like server.send(), but without the recipient argument.

server.kick( <string> ): The argument is the name of a player, who is immediately kicked off the server. The server will receive a server.logout event for the player, as usual.

server.ban( <string> ): This works like kick, but also prevents the player from ever logging on again. Note that the player does not need to be online at the time of being banned. Bans are persistent, not only across sessions of a server, but regardless of which server script Targetware is running.

server.allow( <string> ): This allows the player named to log in to the server. If they were previously banned, this removes the ban. In addition, this allows the player named to log in to the server even if it's a private server. Allows, like bans, are persistent.

server.isadmin( <string> ): This returns true or false depending on whether the player named is considered an administrator on this server. It's up to the server script to implement any desired administrative functions. Administrative privileges are persistent, like bans and allows.

server.setadmin( <string>, <boolean> ): This sets administrative privileges for the specified user to true or false.