Running Scripts Remotely

Starting with ACR 1.87, servers support an IPC message type that allows a server to be directed to run a script in-game. The run script request can come from another server, or from an external source that has database access, such as an external process or a website-driven activity.

Remotely Executed Script Prototype

Scripts that are remotely executed follow a standard prototype:

void main(int SourceServerID, string Argument);

The SourceServerID argument specifies the server ID of the server that initiated the request. This may be zero if the request came from a source other than a server, such as website-based automation. The Argument argument supplies an optional, script-defined parameter provided by the party that created the run script request.

Note that no reliable acknowledgement semantics are provided; if acknowledgement is required, it should be implemented in the form of a reply run script IPC request initiated by the script that was executed (for which the SourceServerID may be used for routing purposes when generating a reply run script request).

Like other IPC requests, a run script request cannot be enqueued to a server that is offline (and will be discarded when the server starts up).

NWScript and C# APIs

From NWScript, a server can request that a script runs on another server with the ACR_RunScriptOnServer function, present in acr_server_ipc_i:

int ACR_RunScriptOnServer(int DestinationServerID, string ScriptName, string ScriptArgument);

The API requests that the destination server (whose ID is given by DestinationServerID) runs a script named "ScriptName" (without extension). The ScriptArgument value is passed to the script entrypoint according to the standard prototype.

From C#, the ALFA.ALFADatabase class provides an ACR_RunScriptOnServer API with the same prototype. (If writing code in the ACR_ServerCommunicator module, the RunScriptOnServer method on the ACR_ServerCommunicator class can be used instead.)

In all cases, a caller must be prepared to deal with a request to run a script that is never processed (for example, the remote server could go offline).

Database record (server_ipc_events)

The server_ipc_events record for a run script request uses the following event code:

const int ACR_SERVER_IPC_EVENT_RUN_SCRIPT = 6;

The SourcePlayerID and DestinationPlayerID columns are not used for this request and must be set to zero. If the source of the request was a game server, its server ID must be listed as the SourceServerID, otherwise zero should be supplied. The destination server is listed as the DestinationServerID.

The EventText column is formatted as follows:

ScriptName:Argument

The :Argument portion may be omitted if the script takes no arguments. Note that the script name, colon delimiter, and argument must still fit within the 256 character limit of the EventText column.