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
      

OR

          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. 1
player.move_back string read/write The key(s) for moving back. 1
player.move_left string read/write The key(s) for turning/sidling left. 1
player.move_right string read/write The key(s) for turning/sidling right. 1
player.look_up string read/write The key(s) for looking up. 1
player.look_down string read/write The key(s) for looking down. 1
player.sidle_mode string read/write The key(s) that when held down change turning to sidling. 1
player.fast_mode string read/write The key(s) that when held down causes the player to move at maximum speed. 1
player.go_faster string read/write The key(s) for increasing speed. 1
player.go_slower string read/write The key(s) for decreasing speed. 1

Notes:
1The 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. 1
block.orig_vertex[index]:y real read only The original y coordinate of vertex[index], before it was modified. 1
block.orig_vertex[index]:z real read only The original z coordinate of vertex[index], before it was modified. 1
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. 2
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. 2
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:
1 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.

2 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: January 17, 2003