RoverScript: 3DML Scripting Reference

RoverScript is a scripting language interpreted by the Flatland Rover. The open source scripting engine, called SimKin, was developed by Simon Whiteside. For more information on SimKin, visit www.simkin.co.uk.

Just as JavaScript extends the functionality of HTML web pages from static content to dynamic content, RoverScript extends the functionality of 3DML spots.

This guide is current for Rover version 3.4.

The <define> tag

Defines script variables and functions. The <define> tag can be contained by <body> and <create> tags. Variable name, attributes, and values follows this format:

     <define>
          <variablename>variablevalue</variablename>
          <!-- or -->
          <variablename attribute="value" />
     </define>

The <function> tag

Defines a named script function. Contained by <define> tags.

     <function name="functionname">
     ... function definition ... 
     </function>

Note: A function with name="start" will run automatically before the spot is rendered.

The <script> tag

Call functions and perform other scripting operations.

     <script trigger="(delay|proximity|roll on|roll off|
      click on|step in|step out|proximity|timer|location|
      key down|key hold|key up)" delay="seconds" 
      radius="#_of_blocks" key="keyvalue">
     ... script ...
     </script>

Comments

     // text following double slashes is ignored to end of line
     /* text between slash-asterix is ignored,
     even on multiple lines */

Syntax

A single statement may be spread over multiple lines. All statements must end in a semi-colon.

Operators

Mathematical

Addition

     x + y

Subtraction

     x - y

Multiplication

     x * y

Division

     x / y

Modulus

     x % y

Assignment

x = y

Comparison

Equality

     x = y

Inequality

     x != y

Greater Than

     x gt y

Greater Than or Equal To

     x ge y

Less Than

     x lt y

Less Than or Equal To

     x le y

Logical

AND

     x and y

     x or y

NOT (negation)

     not x

String Concatenation

     myString = "My" # "String"

Statements

Compound

     {
          do this;
          do that;
     }

If-Else

     if ( expression ) 
     { do this } 
     else 
     { do that }

Switch-Case

     switch (x) 
     { 
          case y { do this } 
          case z { do that } 
          default { do default } 
     }

While-Do loop

     while ( expression ) { do this }

Do-While loop

     do { do this } while ( expression )

For loop

     for loopvar = startval to endval { do this }
          <!-- or -->
     for loopvar = startval to endval step stepval { do this }

For-Each loop

     for each item in collection { do this with item }

Pre-defined objects

spot

The spot object holds miscellaneous information about the spot and the PC it is running on. It also holds all of the global variables and functions defined in the stand-alone <define> tag in a spot.

Variable	Type	Access	Description	Example
`spot.title`	string	read/write	A string that holds the title of the spot.	spot_title_time.3dml
`spot.time:hour`	integer	read only	The current hour (0-23).	spot_title_time.3dml
`spot.time:minute`	integer	read only	The current minute (0-59).	spot_title_time.3dml
`spot.time:second`	integer	read only	The current second (0-59).	spot_title_time.3dml
`spot.time:millisecond`	integer	read only	The current millisecond (usually measured since the PC was booted, but the start point should be considered undefined).	spot_title_time.3dml
`spot.user_can_move`	boolean	read/write	Flag indicating whether the user is permitted to move around via the mouse or keyboard.	spot_user_can_move.3dml
`spot.user_can_look`	boolean	read/write	Flag indicating whether the user is permitted to look around via the mouse or keyboard.	spot_user_can_look.3dml

Function	Return Type	Description
`spot.new_array()`	array object	Creates a new array object with no elements.
`spot.free_array(array)`		Destroys the array object passed in the argument.
`spot.log(string)`		Writes a string to the log file.
`spot.start()`		Supplied by the builder of the spot: will be called when the spot starts, before anything else happens. This function is optional.
`spot.stop()`		Supplied by the builder of the spot: will be called when the spot stops. This function is optional.

array

An array object holds zero or more elements of any type. Note that in the following table, "array" is a placeholder for the name of the variable holding an array object.

Variable	Type	Access	Description
`array.elements`	integer	read only	The number of elements in the array.
`array[index]`	any type	read/write	The array element at the given index.

Function	Return Type	Description
`array.insert(index, value)`		Inserts a new element before the given index.
`array.prepend(value)`		Inserts a new element at the start of the array.
`array.append(value)`		Inserts a new element at the end of the array.
`array.delete(index)`		Deletes the element at the given index.

math

The math object provides mathematical functions and constants.

Variable	Type	Access	Description
`math.pi`	real	read only	Holds the constant p.

Function	Return Type	Description
`math.random(min,max)`	integer	Returns a random integer between min and max.
`math.sqrt(x)`	real	Returns the square root of x.
`math.sin(x)`	real	Returns the sine of x; x is in radians.
`math.cos(x)`	real	Returns the cosine of x; x is in radians.
`math.tan(x)`	real	Returns the tangent of x; x is in radians.
`math.asin(x)`	real	Returns the arc sine of x in radians.
`math.acos(x)`	real	Returns the arc cosine of x in radians.
`math.atan(x)`	real	Returns the arc tangent of x in radians.
`math.rad(x)`	real	Converts x from degrees to radians.
`math.deg(x)`	real	Converts x from radians to degrees.
`math.abs(x)`	real	Returns the absolute (positive) value of x.

fog

The fog object controls the appearance of the fog in a spot.

Variable	Type	Access	Description	Example
`fog.color:red`	real	read/write	The red component of the fog color (0-255).
`fog.color:green`	real	read/write	The green component of the fog color (0-255).
`fog.color:blue`	real	read/write	The blue component of the fog color (0-255).
`fog.density`	real	read/write	The density of the fog, as a percentage (0-100).
`fog.startradius`	integer	read/write	The starting distance of the fog, in blocks.
`fog.endradius`	integer	read/write	The ending distance of the fog, in blocks.

sky

The sky object controls the look of the sky in a spot.

Variable	Type	Access	Description	Example
`sky.brightness`	real	read/write	The brightness of the sky, as a percentage (0-100).	sky_brightness_color.3dml
`sky.color:red`	real	read/write	The red component of the sky color (0-255).	sky_brightness_color.3dml
`sky.color:green`	real	read/write	The green component of the sky color (0-255).	sky_brightness_color.3dml
`sky.color:blue`	real	read/write	The blue component of the sky color (0-255).	sky_brightness_color.3dml
`sky.texture`	string	read/write	The URL of the sky texture.	sky_texture.3dml

ambient_light

The ambient_light object controls the behaviour of the ambient light in a spot.

Function	Type	Access	Description	Example
`ambient_light.brightness`	real	read/write	The brightness of the ambient light, as a percentage (0-100).	ambient_light.3dml
`ambient_light.color:red`	real	read/write	The red compoent of the ambient light color (0-255).	ambient_light.3dml
`ambient_light.color:green`	real	read/write	The green component of the ambient light color (0-255).	ambient_light.3dml
`ambient_light.color:blue`	real	read/write	The blue component of the ambient light color (0-255).	ambient_light.3dml

ambient_sound

The ambient_sound object controls the behaviour of the ambient sound in a spot.

Variable	Type	Access	Description	Example
`ambient_sound.file`	string	read/write	The URL of the wave file.	ambient_sound.3dml
`ambient_sound.volume`	real	read/write	The volume of the sound, as a percentage (0-100).	ambient_sound.3dml
`ambient_sound.playback`	string	read/write	The playback mode of the sound, which is one of the following: "looped", "random", "single", "once".	ambient_sound.3dml
`ambient_sound.delay:minimum`	real	read/write	The minimum delay between playbacks, in seconds.	ambient_sound.3dml
`ambient_sound.delay:range`	real	read/write	The maximum additional delay between playbacks, in seconds.	ambient_sound.3dml

orb

The orb object controls the appearance of the orb and its light source in a spot.

Function	Type	Access	Description	Example
`orb.brightness`	real	read/write	The brightness of the orb light, as a percentage (0-100).	orb_all.3dml
`orb.color:red`	real	read/write	The red component of the orb light color (0-255).	orb_all.3dml
`orb.color:green`	real	read/write	The green component of the orb light color (0-255).	orb_all.3dml
`orb.color:blue`	real	read/write	The blue component of the orb light color (0-255).	orb_all.3dml
`orb.position:angle_x`	real	read/write	The angle of the orb above or below the horizon (90 is directly above, -90 is directly below).	orb_all.3dml
`orb.position:angle_y`	real	read/write	The direction of the orb (0 is north, 180 is south).	orb_all.3dml
`orb.texture`	string	read/write	The URL of the orb texture.	orb_all.3dml
`orb.href`	string	read/write	The URL of the orb hyperlink.	orb_all.3dml
`orb.target`	string	read/write	The target window of the orb hyperlink.	orb_all.3dml
`orb.text`	string	read/write	The popup text of the orb hyperlink.	orb_all.3dml

player

The player object represents the user's position and viewpoint in the spot.

Variable	Type	Access	Description
`player.location:column`	integer	read only	The column the player is nearest to.
`player.location:row`	integer	read only	The row the player is nearest to.
`player.location:level`	integer	read only	The level the player is nearest to.
`player.location:x`	real	read/write	The x coordinate of the player.
`player.location:y`	real	read/write	The y coordinate of the player.
`player.location:z`	real	read/write	The z coordinate of the player.
`player.orientation:look_angle`	real	read/write	The look angle of the player (-90 is up, 90 is down).
`player.orientation:turn_angle`	real	read/write	The turn angle of the player (0 is north, 180 is south).
`player.size:x`	real	read/write	The player size along the X axis.
`player.size:y`	real	read/write	The player size along the Y axis.
`player.size:z`	real	read/write	The player size along the Z axis.
`player.camera:x`	real	read/write	The camera offset along the X axis.
`player.camera:y`	real	read/write	The camera offset along the Y axis.
`player.camera:z`	real	read/write	The camera offset along the Z axis.
`player.move_forward`	string	read/write	The key(s) for moving forward. ¹
`player.move_back`	string	read/write	The key(s) for moving back. ¹
`player.move_left`	string	read/write	The key(s) for turning/sidling left. ¹
`player.move_right`	string	read/write	The key(s) for turning/sidling right. ¹
`player.look_up`	string	read/write	The key(s) for looking up. ¹
`player.look_down`	string	read/write	The key(s) for looking down. ¹
`player.sidle_mode`	string	read/write	The key(s) that when held down change turning to sidling. ¹
`player.fast_mode`	string	read/write	The key(s) that when held down causes the player to move at maximum speed. ¹
`player.go_faster`	string	read/write	The key(s) for increasing speed. ¹
`player.go_slower`	string	read/write	The key(s) for decreasing speed. ¹
Notes: ¹The syntax of the string is the same for the equivilant attributes of the <player> tag, i.e. a key is either an alphanumeric character, or a special key name in square brackets (such as "[page up]"). At most two keys can be assigned to one player function, the key names must be seperated by a comma.

map

The map object provides variables and functions associated with the map.

Variable	Type	Access	Description
`map.dimensions:columns`	integer	read only	The number of columns in the map.
`map.dimensions:rows`	integer	read only	The number of rows in the map.
`map.dimensions:levels`	integer	read only	The number of levels in the map.

Function	Return Type	Description
`map.get_block(column, row, level)`	block object	Returns the fixed or movable block at the given map location, or null if there is none. A fixed block takes precedence.
`map.get_block(symbol)`	block object	Returns the fixed or movable block with the given symbol.
`map.get_blocks(column, row, level)`	array object	Returns an array of fixed and movable blocks at the given map location. Array is automatically deallocated.
`map.get_blocks(symbol)`	array object	Returns an array of fixed or movable blocks with the given symbol. Array is automatically deallocated.
`map.set_block(column, row, level, symbol)`		Places a block with the given symbol on the given map location, replacing whatever block may have been there.
`map.move_block(column1, row1, level1, column2, row2, level2)`		Moves a block from one map location to another. The original map location becomes empty, and the block that was at the new map location, if any, is replaced.

block

A block object represents one block on the map, and provides ways to manipulate it. Note that in the following tables, "block" is a placeholder for a variable that is holding the block object. Also note that the variables below are only writable if the block is movable. Finally, any variables or functions defined in a <define> tag inside of a <create> tag will be associated with the block of that symbol.

Variable	Type	Access	Description
`block.location:column`	integer	read/write	The column the block is in (or near if movable).
`block.location:row`	integer	read/write	The row the block is in (or near if movable).
`block.location:level`	integer	read/write	The level the block is in (or near if movable).
`block.location:x`	real	read/write	The x coordinate of the block, in "pixels".
`block.location:y`	real	read/write	The y coordinate of the block, in "pixels".
`block.location:z`	real	read/write	The z coordinate of the block, in "pixels".
`block.origin:x`	real	read/write	The X coordinate of the origin around which the block rotates, in "pixels".
`block.origin:y`	real	read/write	The Y coordinate of the origin around which the block rotates, in "pixels".
`block.origin:z`	real	read/write	The Z coordinate of the origin around which the block rotates, in "pixels".
`block.bbox:min_x`	real	read only	The minimum x coordinate of the block's bounding box.
`block.bbox:min_y`	real	read only	The minimum y coordinate of the block's bounding box.
`block.bbox:min_z`	real	read only	The minimum z coordinate of the block's bounding box.
`block.bbox:max_x`	real	read only	The maximum x coordinate of the block's bounding box.
`block.bbox:max_y`	real	read only	The maximum y coordinate of the block's bounding box.
`block.bbox:max_z`	real	read only	The maximum z coordinate of the block's bounding box.
`block.vertices`	integer	read only	The number of vertices the block has.
`block.vertex[index]:x`	real	read/write	The x coordinate of vertex[index].
`block.vertex[index]:y`	real	read/write	The y coordinate of vertex[index].
`block.vertex[index]:z`	real	read/write	The z coordinate of vertex[index].
`block.orig_vertex[index]:x`	real	read only	The original x coordinate of vertex[index], before it was modified. ¹
`block.orig_vertex[index]:y`	real	read only	The original y coordinate of vertex[index], before it was modified. ¹
`block.orig_vertex[index]:z`	real	read only	The original z coordinate of vertex[index], before it was modified. ¹
`block.movable`	boolean	read only	Flag indicating if the block is movable.
`block.symbol`	string	read only	The symbol of the block.
`block.name`	string	read only	The name of the block.

Function	Return Type	Description
`block.get_vertices();`		Returns an array of vertices. Array is automatically deallocated.
`vertex_array.set(i,x,y,z);`		Sets coordinates of vertex x,y,z at index i of vertex array when set_vertices() is called.
`block.set_vertices();`		Sets the vertices of the block.
`block.reset_vertices();`		Resets the coordinates of all vertices to their original values.
`block.orient(compass_direction, angle);`		Sets the orientation of the block, by first tipping the block over so that the top of the block faces in the compass direction (which can be one of the following values: "north", "east", "south", "west", "up" or "down"), then rotating the block around the axis pointing in that compass direction. ²
`block.orient(y_angle, x_angle, z_angle);`		Sets the orientation of the block, by first rotating the block around the y axis, then the x axis, then the z axis. ²
`block.rotate_x(angle);`		Rotates the block around the x axis by the given angle.
`block.rotate_y(angle);`		Rotates the block around the y axis by the given angle.
`block.rotate_z(angle);`		Rotates the block around the z axis by the given angle.
Notes: ¹ The orig_vertex array holds the original coordinates of all vertices in a block, as defined in the blockset. Any changes made to the vertices of a block, either via the vertex array, the orient or rotate functions, or the orient attribute of the <param> tag in the 3DML file, are not reflected in the orig_vertex array. The reset_vertices function can be used to reset all coordinates in the vertex array to the coordinates in the orig_vertex array. ² The orient functions start with the original coordinates of all vertices, and then orient the block to a new position. This means that any other changes you've made to the vertices will be lost. If you want to make culmulative changes to the vertices, you should use the rotate functions instead, which are more flexible since you can control the order in which you rotate the block around the x, y and z axes. The orient functions are intended to mimic the behaviour of the orient attribute of the param tag, and hence are rather limited in scope.

last updated Friday January 17 2003