Reality Factory Scripting Documentation

Table of Contents

• Script Engine
• Script Object
• Script File
  • Script
  • Data Types
  • Order
  • Script Methods
  • Script Errors
  • Comments
  • High Level vs. Low Level
  • Sample Script

Script Engine

The Script Engine used to drive Pawns, LevelControllers, Messages, the Skydome, the Inventory etc. is called Simkin. It is a C style script interpreter that has been integrated into the Reality Factory code base.

Script Object

A Script Object represents a game component like a Pawn that can be controlled via a Script. There are several Global Objects that do not require their own script but can be used in any script instead.

Script File

The behaviour of a Script Object is controlled by a Script. The file containing this Script is specified in the Pawn entity by the entry ScriptName. A Script File is a text file stored in the scripts folder of Reality Factory. It can have any extension but to avoid confusion usually .s is used. More than one Pawn can use the same Script File.

Script

A Script is the data contained with in a Script File. It starts with a { and ends with a }. So at its simplest an empty script would be:

{
 
}

Data Types

Type	Description	Example
self	a reference to the object owning the script	self.EntityName
bool	a truth value	true or false
int	a signed integer	32
float	a signed floating point number	32.33
string	an arbitrary length piece of text enclosed in "" to embed " or \ in the text you must put a slash and then the character in question (\" or \\).	"Hello World!"
object	another Simkin object with methods and fields	GUI

The type of a variable is implied by its value, and Simkin will convert to different types as required.

Note:

If a string variable specifying a Pawn's animation is "" (empty string) then the previous animation will continue to be used. If the animation does not exist then the default pose will be used.

If a string variable specifying a sound is "" then no sound file will be played. All sounds are looped and end when the action ends.

Order

An Order contains the actual script data that controls the Pawn's actions. There can be many orders in a Script, each with a different name. In the Pawn entity the entry SpawnOrder is the name of the Order used by the Pawn when it is first created (or spawned). All Orders must be contained within the Script itself for them to be valid. An Order has a specific layout which, at it's simplest, looks like this:

OrderName[()
{
 
}]

This would be an empty Order with no actions for the Pawn to execute. The name of the Order is case sensitive so Orders named Start and start are different.

Script Methods

Script Methods are the actual commands to the Pawn to make it perform its actions. These are contained within an Order and are executed one after the other. Script Methods are similar to C-style function calls and the general syntax for a script method is:

ScriptMethodName(..parameters..);

Each Script Method can have a different amount of parameters, with each parameter separated from the previous one by a comma (,). Each Script Method must be terminated with a semicolon (;). For example:

NextPoint(); has no parameters.

Delay("idle", 2, ""); has 3 parameters.

Script Errors

If you have errors in your Script you may receive an error message through a Windows error dialog box and the program will exit. Look in RealityFactory.log (located in the root folder of your Reality Factory installation) to see where the error occurred. If the error was not fatal then the program will run but the Pawns will not execute their script. Again look in RealityFactory.log for the location of the error.

Comments

C and C++ style comments can be placed in the script file to comment the Orders but there appears to be problems associated with them in the Script Engine and they sometimes can cause an error to occur. To avoid errors do the following:

Note:

• Never start a line with //, /* or */. Place a space or a tab first.
• Don't put the name of an order at the start of the comment.
• Don't use ( or ) in a comment.

If you get a Reader Script error then it probably is a problem with a comment in the script.

High Level vs. Low Level

Scripts can be written using high level methods, low level methods or a combination of both.

Note:

In Pawn scripts an order must be all high level or all low level. You cannot mix the two within an individual order.

High level methods are script actions that can take more than one frame to execute. High level actions such as MoveToPoint can take many seconds to complete and the order that they are in can take even longer to finish.

Low level methods are script actions that are run one after the other in a single frame until the end of the order is reached. This is more like normal C style programming.

To summarize: in high level scripting the current order being executed can take many frames to complete. In low level scripting the current order is completely executed each frame.

Sample Script

The following is a sample of a simple script that could control a Pawn.

{
   Start[()
   {
      RotateToPoint("idle", 90, "");
      MoveToPoint("walk", 20, "");
      NewOrder("Next");
   }]

   Next[()
   {
      Jump("jump", 40, false, "bong.wav");
      RestartOrder();
   }]
}

In the Pawn entity you would specify:

ScriptName	the file that contains this script
SpawnOrder	Start
SpawnPoint	the name of a valid ScriptPoint entity

When the Pawn is spawned it will start off by executing the Script Actions contained in the Order 'Start'. It will rotate to face the SpawnPoint and then move toward it. When it reaches that point it will switch execution to the 'Next' Order. It will then jump in the air. The 'Next' Order will then restart from the beginning, causing the Pawn to continue jumping.