This is the reference documentation for server-side scripting. If you're looking for documentation on client-side scripting, see Clientside Scripting. A serverside scripting example can be found here: http://www.rigsofrods.com/threads/89834-server-scripts-(download)?p=1007274&viewfull=1#post1007274

Enable scripting support

Main article: Compiling Server

The rorserver.exe that comes with the game doesn't have support for scripting by default, so before you can start using scripts on your server, you'll need to enable support for it. You can do this by compiling the server from source, with scripting support enabled.

1. Linux: Follow the Compiling Server tutorial, but add -DRORSERVER_WITH_ANGELSCRIPT=1 to the cmake command:
   1. cmake -DCMAKE_INSTALL_PREFIX:STRING=/usr -DRORSERVER_WITH_ANGELSCRIPT=1 .
2. Windows: Follow the Compiling Server tutorial, but change the RORSERVER_WITH_ANGELSCRIPT option to "ON" when you can.

When you've done this, you can use scripts by specifying the script file in the configuration file via
script = <path-to-your-angelscript-file>
or via the command line by using
-script <path-to-your-angelscript-file>

AngelScript

Main article: AngelScript Scripting

RoR uses AngelScript as scripting language. You can find more documentation on AngelScript in the manual. You'll also find a basic scripting file to start from at the bottom of this article.

script callbacks

There are currently 6 AngelScript functions, that will be called by the server at certain events. There are 2 methods to use these 'callbacks':

1. Define the function with the correct name as a global function.
2. Use the server.setCallback method to set the callback to a global function or object method. The type (first argument of server.setCallback) should then be set to the same name as the global function would have ('playerDeleted', 'playerAdded', 'playerChat', 'frameStep', 'gameCmd').

void main()

void main()

This method will get called when the server starts.
Note: You cannot add callbacks for when the server starts using the server.setCallback method.

void playerDeleted(int, int)

void playerDeleted(int uid, int crash)

This method will get called when a player leaves the server. Two arguments are given with this function:

1. int uid: The Unique Userid of the player that left;
2. int crash: This is 1 if the player left because his local client crashed and 0 if he left on request.

void playerAdded(int)

void playerAdded(int uid)

This method will get called when a player joins the server. One argument is given with this function:

1. int uid: The Unique Userid of the player that joined;

int playerChat(int, string)

int playerChat(int uid, string msg)

This function will get called when a player says something via the chat system. Two arguments are given with this function:

1. int uid: The Unique Userid of the player that said something;
2. string msg: What the player said;

This function has to return broadcasting level of the message. You can choose from the following:

1. BROADCAST_AUTO: Do not change the broadcasting level;
2. BROADCAST_ALL: broadcast to all clients including sender;
3. BROADCAST_NORMAL: broadcast to all clients except sender;
4. BROADCAST_AUTHED: broadcast to authed users (admins);
5. BROADCAST_BLOCK: Block the message, do not broadcast it;

void frameStep(float)

void frameStep(float dt)

This method will get called at every frame (by default, 5 times a second). One argument is given with this function:

1. float dt: Time since last time it was called (in milliseconds);

void gameCmd(int, string)

void gameCmd(int uid, string message)

This method will get called for every incoming game command. Two arguments are given with this function:

1. int uid: The Unique Userid of the player of whom the command originated;
2. string msg: The received command;

The server class

The server class, is a class that you can use in your scripts. The functions inside the server class are defined by default and they allow interaction with the server.

void say(string, int, int)

void server.say(string msg, int uid, int from)

Example: server.say("This message will be shown in the chatbox of all players on your server.", TO_ALL, FROM_NONE);
The server.say method allows you to broadcast a message to a/all player(s). The sent message will appear in the chatbox. This method returns no value, and takes 3 arguments:

1. string msg: The message you want to send;
2. int uid: The Unique Userid of the player you want to send it to (use the constant TO_ALL to broadcast to all players);
3. int from: Who is saying this. You can use any of following constants as value:
   1. FROM_NONE: Nothing will be added in front of your message;
   2. FROM_HOST: Will add "Host(general): " in front of your message if broadcasted to all players, or "Host(private): " if broadcasted to one player. This is recommended because this allows players to know if a certain message was sent only to them, or to everyone;
   3. FROM_SERVER: Will add "SERVER: " in front of your message;
   4. FROM_RULES: Will add "Rules: " in front of your message;
   5. FROM_MOTD: Will add "MOTD: " in front of your message.

You can also use colors in your message by adding hexadecimal codes to it (e.g.: server.say("#000000hi", TO_ALL, FROM_SERVER);)

void log(string)

void server.log(string msg)

Example: server.log("This message will be shown in your log file.");
This logs something to the server logfile.

void kick(int, string)

bool server.kick(int uid, string msg)

Example: server.kick(74, "Please read our rules before joining!");

Warning: Do only use in the frameStep method!

This kicks a player from the server. This function returns true on success and false on failure. It takes 2 arguments:

1. int uid: The Unique Userid of the player you want to kick;
2. string msg: The reason why he is being kicked (At the moment, the player that gets kicked won't be able to see the reason);

void ban(int, string)

bool server.ban(int uid, string msg)

Example: server.ban(84, "We won't see you here again!");

Warning: Do only use in the frameStep method!

This IP-bans a player from the server. This function returns true on success and false on failure. It takes 2 arguments:

1. int uid: The Unique Userid of the player you want to ban;
2. string msg: The reason why he is being banned (At the moment, the player that gets banned won't be able to see the reason);

void unban(int)

bool server.unban(int uid)

Example: server.unban(12);
This unbans a player from the server. This function returns true on success and false on failure. It takes 1 arguments:

1. int uid: The Unique Userid of the player you want to ban;

void getUserName(int)

string server.getUserName(int uid)

Example: string username = server.getUserName(45);
This gets the username for an unique user-ID. This function returns a username or an empty string on failure. It takes 1 arguments:

1. int uid: The Unique Userid of the player;

void getUserAuth(int)

string server.getUserAuth(int uid)

Example: string authlevel = server.getUserAuth(45);
This gets the authorization string for an unique user-ID. This function returns one of the following values: "admin", "moderator", "ranked", "bot", "none". It takes 1 arguments:

1. int uid: The Unique Userid of the player;

void getUserAuthRaw(int)

int server.getUserAuthRaw(int uid)

Example: int authlevel = server.getUserAuthRaw(45);
This gets the authorization number for an unique user-ID. This function returns a number representing the different authorization levels that the user has (AUTH_NONE, AUTH_ADMIN, AUTH_MOD, AUTH_BOT, AUTH_RANKED). It takes 1 arguments:

1. int uid: The Unique Userid of the player;

string getServerTerrain()

string server.getServerTerrain()

Example: string terrain = server.getServerTerrain();
This returns the terrain that is being used by the server.

int cmd(int, string)

int server.cmd(int uid, string cmd)

Example: server.cmd(24, "game.flashMessage(\"^2The race will start in 5 seconds!\", 2, 0.05);";);
This sends a game command to a player. This function returns 0 on success and -1 on failure. It takes 2 arguments:

1. int uid: The Unique Userid of the player;
2. string cmd: The command;

int getNumClients()

int server.getNumClients()

Example: int clientCount = server.getNumClients();

Warning: Do only use in the frameStep method!

This returns the amount of players that are currently online.

int getUserColourNum(int)

int server.getUserColourNum(int uid)

Example: int clientColour = server.getUserColourNum (45);
This returns the number of the colour of the player. You can translate this colour to a number: [1] [2] It takes 1 arguments:

1. int uid: The Unique Userid of the player;

string getUserToken(int)

string server.getUserToken(int uid)

Example: string token = server.getUserToken(45);
This returns the number of the usertoken of the player in an encoded form or an empty string if the player didn't fill in a usertoken. You can use this to identify a user across sessions. It takes 1 arguments:

1. int uid: The Unique Userid of the player;

int getTime()

int server.getTime()

Example: int time = server.getTime();
This returns the current servertime in unix time form.

int getStartTime()

int server.getStartTime()

Example: int serverStartTime = server.getStartTime();
This returns the time when the server was started in unix time form.

void setCallback(string, string, ?&in@)

void server.setCallback(const string &in type, const string &in method, ?&in @object)

Example: server.setCallback("frameStep", "myFrameStepMethod", @this);
Example: server.setCallback("frameStep", "myFrameStepGlobalFunction", null);

Warning: If you use this method to call an a method of an object, make sure to remove the callback again before the object goes out of scope!

This sets a callback for the server. It takes 3 arguments:

1. string type: The type can be any of the following: 'frameStep', 'gameCmd', 'playerAdded', 'playerDeleted', 'playerChat' (note: the uppercase letters have to be upper case);
2. string method: The name of the method of function that will get called by the callback. This function needs to have the arguments like the default callbacks.;
3.  ?&in object: The object that has the method of the second parameter or null if the method is a global function;

void deleteCallback(string, string, ?&in@)

void server.deleteCallback(const string &in type, const string &in method, ?&in @object)

Example: server.deleteCallback("frameStep", "myFrameStepMethod", @this);
Example: server.deleteCallback("frameStep", "myFrameStepGlobalFunction", null);

Warning: This is quite complicated to explain, but: calling this method from inside a destructor of the same object as the callback uses is not a good idea because the destructor won't get called until you remove the callback (and because your removeCallback call is inside the desctructor, the callback and the object will never get removed). Always remove all callbacks of an object, before it goes out of scope!

Warning: Do not remove a callback of the type that is being called, except if it's the exact callback that is being called at the time you remove it or one that was already called in the same cycle.

Removes a callback set by the setCallback method. It takes 3 arguments:

1. string type: The type can be any of the following: 'frameStep', 'gameCmd', 'playerAdded', 'playerDeleted', 'playerChat' (note: the uppercase letters have to be upper case);
2. string method: The name of the method of function that will get called by the callback. This function needs to have the arguments like the default callbacks.;
3.  ?&in object: The object that has the method of the second parameter or null if the method is a global function;

void throwException(string)

void server.throwException(const string &in message)

Example: server.throwException("You did something seriously wrong, and the script is unable to continue.");
This will throw an exception that will stop the current executing script, and show a traceback in the server log. This is useful to avoid programmer errors or to debug a script. It takes 1 argument:

1. string message: A description of what went wrong and how to fix it.;

string version

Example: string revision = server.version;
This attribute contains the version of the rorserver.

string asVersion

Example: string revision = server.asVersion;
This attribute contains the AngelScript version of the server.

string protocolVersion

Example: string revision = server.protocolVersion;
This attribute contains the protocol version.

uint maxClients

Example: uint clientArraySize = server.maxClients;
This attribute contains the maximum amount of client that the server can hold.

string serverName

Example: string name = server.serverName;
The name of the server.

string IPAddr

Example: string ip = server.IPAddr;
The IP address of the server (or 0.0.0.0 in LAN mode when not specified).

uint listenPort

Example: uint port = server.listenPort;
The port on which the server is listening.

int serverMode

Example: int mode = server.serverMode;
The servermode. This can be one of the following constants:

1. SERVER_LAN
2. SERVER_INET
3. SERVER_AUTO

string owner

Example: string owner = server.owner;
Gives the owner of the server.

string website

Example: string website = server.website;
Gives the website of the server.

string ircServ

Example: string ircServ = server.ircServ;
Gives the IRC server of the server.

string voipServ

Example: string voipServ = server.voipServ;
Gives the VoIP server of the server.

Script add-ons

The server allows you to use some of the basic AngelScript add-ons. The add-ons are listed here with a bit of documentation about what they allow you to do.

string

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_std_string.html

This add-on allows you to use the type 'string'.

array template object

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_array.html

any object

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_any.html

ref object

The feature below is not available in any released version yet. It may be available with the next version.

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_handle.html

dictionary object

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_dict.html

file object

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_file.html

Limitations:

1. You can only load and save files from the scripts/storage directory inside the server resource directory. You can set the resource directory using the 'resdir' config option.
2. You can only load and save files with the '.asdata' extension.

These limitations were put in place to prevent malicious scripts to do any damage to the computer that the server is running on.

math functions

AngelScript documentation: http://www.angelcode.com/angelscript/sdk/docs/manual/doc_addon_math.html

math3D

class vector3
{
	// object properties
	float x;
	float y;
	float z;
 
	// constructors
	vector3();
	vector3(const vector3 &in other);
	vector3(float x, float y = 0, float z = 0);
 
	// operator overloads
	vector3 &opAddAssign(const vector3 &in other);
	vector3 &opSubAssign(const vector3 &in other);
	vector3 &opMulAssign(float s);
	vector3 &opDivAssign(float s);
	bool opEquals(const vector3 &in other) const;
	vector3 opAdd(const vector3 &in other) const;
	vector3 opSub(const vector3 &in other) const;
	vector3 opMul(float s) const;
	vector3 opMul_r(float s) const;
	vector3 opDiv(float s) const;
 
	// object methods
	float length() const;
 
	// swizzle operators
	vector3 get_xyz() const;
	vector3 get_yzx() const;
	vector3 get_zxy() const;
	vector3 get_zyx() const;
	vector3 get_yxz() const;
	vector3 get_xzy() const;
	void set_xyz(const vector3 &in other);
	void set_yzx(const vector3 &in other);
	void set_zxy(const vector3 &in other);
	void set_zyx(const vector3 &in other);
	void set_yxz(const vector3 &in other);
	void set_xzy(const vector3 &in other);
}

Examples

Announcement system

This script will broadcast an announcement every 5 minutes.

float time_ms = 0;
int time_secs  = 0;
string COLOUR_MAGENTA  = "#FF00FF";
void main() {}
 
// timer callback
void frameStep(float dt)
{
	time_ms += dt;
	bool secondPassed=false;
	if(time_ms > 999.0f)
	{
		secondPassed=true;
		time_ms -= 1000.0f;
		time_secs++;
	}
 
	if(secondPassed)
	{
		if((time_secs%300)==0)
		{ // broadcast an announcement every 5 minutes (= 300 seconds)
			array<string> announcements = {
				"This is an announcement!",
				"This is another anouncement!"
			};
			server.say(COLOUR_MAGENTA+"ANNOUNCEMENT: "+announcements[(time_secs/300)%announcements.length()]
				, TO_ALL, -1);
		}
	}
}

Commands system

This script will respond if a player says "brb", "afk" or "back".

// We don't need the function 'main', but the script engine expects it to be present.
void main() {}
 
// called for every chat message
int playerChat(int uid, string msg)
{
	// We split the message up in words
	array<string> emsg = msg.split(" ");
 
	// If the message consists out of 1 or more words
	if(emsg.length()>0)
	{
		if( emsg[0] == "brb" ) // if word 1 = brb
		{
			// Tell everyone that the user who said this, will be right back
			server.say(server.getUserName(uid) + " will be right back!", -1, FROM_HOST);
		}
		else if( emsg[0] == "afk" ) // if word 1 = afk
		{
			// Tell everyone that the user who said this, is now away from keyboard
			server.say(server.getUserName(uid) + " is now away from keyboard :(", -1, FROM_HOST);
		}
		else if( emsg[0] == "back" ) // if word 1 = back
		{
			// Tell everyone that the user that said this, is now back
			server.say(server.getUserName(uid) + " is now back :D", -1, FROM_HOST);
		}
		else if( emsg[0] == "!help" ) // if word 1 = !help
		{
			// Tell this user, what commands that he can use
			server.say("Commands available for you: !rules, !vehiclelimit, !website, !irc,", uid, FROM_HOST);
			server.say("!owner, !version, !motd, !help, !voip", uid, FROM_HOST);
			// we block this message from being broadcasted to other players
			return BROADCAST_BLOCK;
		}
	}
 
	// default: don't edit broadcasting level
	// default levels: block for all lines starting with '!', else broadcast to everyone except sender
	return BROADCAST_AUTO;
}

Troubleshooting

You can post your script and your problems in the scripting forum.