Server actions file

Actions are a collection of methods associated with an object or person, written in a simple C/pascal like language interpreted by the sim server. An action for an object controls what happens when something is done to that object, while an action for a person provides the 'intelligence' for the person.

The format of the actions file is : 

action name {
	type name
	type name
	...
	method name ... {
		type name
		type name
		...
		code
		}
	}

action name {
	...
	}

...
Each action must have a unique name, corresponding to the name of the object or person it is associated with. Inside the action are :

Variables

The format of variable declaration is :

type [[size]] name [= expression] ;

Some example variable declarations : 
str x;                   A string variable.
dbl n = 10;              A floating point variable, intialised to 10.
str myString = "hello";  A string variable with an initialiser.
str[10] arr;             An array of string variables.
dbl[3] darr = [5;6;7];   An array of floating points, initialised to
                         darr[0] = 5, darr[1] = 6 and darr[2] = 7.
dbl[] foo = someFunc();  An array initialised by the result of a
                         function that returns an array.
dbl baz = "hello";       A type mismatch error. Note that is will not
                         be detected until the action or method that
                         contains this is run.
By default, all variables are local (non-persistent). Variables in a method will be re-initialised each time that method is called, while variables outside methods will be re-initialised when any method of that action is called. The alternative to this is to declare variables as static, by putting the keyword static before the variable type. Such variables will have their values kept between calls to methods, even if the server is shutdown and restarted.

Some more variable declaration examples : 

static str y;            A persistent string variable.
local dbl x = 10;        A non-persistent floating point variable.
dbl foo = 3+2;           A non-persistant floating point.
static str bar = "hi";   A persistent string variable, initially set
                         to "hi".
Local variables outside of methods are always initialised before variables inside the method being called, which are themselves always initialised before method code is called. Static variables inside and outside of methods are initialised when the action is read in by the server for the first time.

Every action has 4 variables that do not need to be explicitly declared, and that are automatically initialised whenever an action method is called. They are :

Methods

The format of method declarations is : 
method name name ... {
        variable
        variable
        ...

        statement
        statement
        ...
        }
A method can be called by any one of it's names, so you could have an action for a switch that has a method called when the switch is pressed, pushed or toggled for example. Method code is sort of C-like, but without some of the constructs that make it hard to easily interpret (like goto and break).

Statements

Valid statments inside a method are :

Expressions

An expression is something like x + 6, foo = 7 or print("hello"). All expression returns a value of one of the types dbl, str, dbl[] or str[], or void for expressions that don't really return any value. Some example expressions and their types are : 
x + 6                       dbl
"hello " & "world"          str
print("hi\n")               void
[5;6;7]                     dbl[]
myString = "hi"             str
["one";"two"]               str[]
rand(10)                    dbl
myString[1]                 str
Most expressions work just the same as in C. The main types of expression are :

Inbuilt functions

The various inbuilt functions allow action code to do such things as move shapes, send messages to players and open paths. This section describes the parameters, return value and effects of all the functions, and gives an example of it's use :

Special methods

Actions created to be associated with and control a person are different to actions associated with objects in that their methods are not called by users. Instead, two special actions called think and listen can be defined, to be called automatically by the server in the following circumstances :

An action associated with an object can have methods that are for internal use only, not callable by users. Any method with a name starting with an underscore _ is not visible to users, but may be called using the domethod() function from other methods of the action.

One special case of this is the _trigger method. If an action has such a method and the object associated with it is at some location then this method will be called whenever any person 'steps on' that object. This is useful for creating things like pressure plates that activate when someone steps on them, for example.
When this method is called, the actions's player variable is set to the name of the person who triggered it and it's params variable set to an empty array.

Errors

If an error of any kind occurs in the execution of a method, it's execution will immediately terminate and an error message written to the server log file (and sent to the client of the user who invoked the method, if applicable). Possible errors are :
Return to the [final report]