VRGrid Scripting

Just as javascript extends the functionality of HTML web pages from static content to dynamic content, VRGrid as its internal scripting engine seo lets take a look at its reference.

The <define> tag .Defines script variables and functions. The <define> tag can be contained by <design> 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>
 

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="number_of_units" 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 }

The vrf object holds miscellaneous information about the vrf. It also holds all of the global variables and functions defined in the stand-alone tag in a vrf.

vrf.title

string

read/write

A string that holds the title of the vrf.

vrf.time:hour

integer

read only

The current hour (0-23).

vrf.time:minute

integer

read only

The current minute (0-59).

vrf.time:second

integer

read only

The current second (0-59).

vrf.time:millisecond

integer

read only

The current millisecond (usually measured since the PC was booted, but the start point should be considered undefined).

vrf.user_can_move

boolean

read/write

Flag indicating whether the user is permitted to move around via the mouse or keyboard.

vrf.user_can_look

boolean

read/write

Flag indicating whether the user is permitted to look around via the mouse or keyboard.

vrf.new_array()

array object

Creates a new array object with no elements.

vrf.free_array(array)

 

Destroys the array object passed in the argument.

vrf.log(string)

 

Writes a string to the log file.

vrf.start()

 

Supplied by the builder of the vrf will be called when the vrf starts, before anything else happens. This function is optional.

vrf.stop()

 

Supplied by the builder of the vrf: will be called when the vrf stops. This function is optional.

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.

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.

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.

The math object provides mathematical functions and constants.

math.pi

real

read only

Holds the constant p.

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.

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

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 vrobjs.

 

fog.endradius

integer

read/write

The ending distance of the fog, in vrobjs.

 

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

sky.brightness

real

read/write

The brightness of the sky, as a percentage (0-100).

sky.color:red

real

read/write

The red component of the sky color (0-255).

sky.color:green

real

read/write

The green component of the sky color (0-255).

sky.color:blue

real

read/write

The blue component of the sky color (0-255).

sky.texture

string

read/write

The URL of the sky texture.

The atmosphere object controls the behaviour of the atmosphere light in a vrf.

atmosphere.brightness

real

read/write

The brightness of the ambient light, as a percentage (0-100).

atmosphere.color:red

real

read/write

The red compoent of the ambient light color (0-255).

atmosphere.color:green

real

read/write

The green component of the ambient light color (0-255).

atmosphere.color:blue

real

read/write

The blue component of the ambient light color (0-255).

The ambience object controls the behaviour of the ambience sound in a vrf.

ambience.file

string

read/write

The URL of the wave file.

ambience.volume

real

read/write

The volume of the sound, as a percentage (0-100).

ambience.playback

string

read/write

The playback mode of the sound, which is one of the following: "looped", "random", "single", "once".

ambience.delay:minimum

real

read/write

The minimum delay between playbacks, in seconds.

ambience.delay:range

real

read/write

The maximum additional delay between playbacks, in seconds.

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

orb.brightness

real

read/write

The brightness of the orb light, as a percentage (0-100).

orb.color:red

real

read/write

The red component of the orb light color (0-255).

orb.color:green

real

read/write

The green component of the orb light color (0-255).

orb.color:blue

real

read/write

The blue component of the orb light color (0-255).

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.position:angle_y

real

read/write

The direction of the orb (0 is north, 180 is south).

orb.texture

string

read/write

The URL of the orb texture.

orb.href

string

read/write

The URL of the orb hyperlink.

orb.target

string

read/write

The target window of the orb hyperlink.

orb.text

string

read/write

The popup text of the orb hyperlink.

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

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:layer

integer

read only

The layer 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

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

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:layers

integer

read only

The number of layers in the map.

map.get_vrobj(column, row, layer)

vrobj object

Returns the fixed or walkable vrobj at the given map location, or null if there is none. A fixed vrobj takes precedence.

map.get_vrobj(unit)

vrobj object

Returns the fixed or walkable vrobj with the given unit.

map.get_vrobjs(column, row, layer)

array object

Returns an array of fixed and walkable vrobjs at the given map location. Array is automatically deallocated.

map.get_vrobjs(unit)

array object

Returns an array of fixed or walkable vrobjs with the given unit. Array is automatically deallocated.

map.set_vrobj(column, row, layer, unit)

 

Places a vrobj with the given unit on the given map location, replacing whatever vrobj may have been there.

map.move_vrobj(column1, row1, layer1, column2, row2, layer2)

 

Moves a vrobj from one map location to another. The original map location becomes empty, and the vrobj that was at the new map location, if any, is replaced.

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

vrobj.location:column

integer

read/write

The column the vrobj is in (or near if walkable).

vrobj.location:row

integer

read/write

The row the vrobj is in (or near if walkable).

vrobj.location:layer

integer

read/write

The layer the vrobj is in (or near if walkable).

vrobj.location:x

real

read/write

The x coordinate of the vrobj, in "pixels".

vrobj.location:y

real

read/write

The y coordinate of the vrobj, in "pixels".

vrobj.location:z

real

read/write

The z coordinate of the vrobj, in "pixels".

vrobj.origin:x

real

read/write

The X coordinate of the origin around which the vrobj rotates, in "pixels".

vrobj.origin:y

real

read/write

The Y coordinate of the origin around which the vrobj rotates, in "pixels".

vrobj.origin:z

real

read/write

The Z coordinate of the origin around which the vrobj rotates, in "pixels".

vrobj.bbox:min_x

real

read only

The minimum x coordinate of the vrobj's bounding box.

vrobj.bbox:min_y

real

read only

The minimum y coordinate of the vrobj's bounding box.

vrobj.bbox:min_z

real

read only

The minimum z coordinate of the vrobj's bounding box.

vrobj.bbox:max_x

real

read only

The maximum x coordinate of the vrobj's bounding box.

vrobj.bbox:max_y

real

read only

The maximum y coordinate of the vrobj's bounding box.

vrobj.bbox:max_z

real

read only

The maximum z coordinate of the vrobj's bounding box.

vrobj.vertices

integer

read only

The number of vertices the vrobj has.

vrobj.vertex[index]:x

real

read/write

The x coordinate of vertex[index].

vrobj.vertex[index]:y

real

read/write

The y coordinate of vertex[index].

vrobj.vertex[index]:z

real

read/write

The z coordinate of vertex[index].

vrobj.orig_vertex[index]:x

real

read only

The original x coordinate of vertex[index], before it was modified. 1

vrobj.orig_vertex[index]:y

real

read only

The original y coordinate of vertex[index], before it was modified. 1

vrobj.orig_vertex[index]:z

real

read only

The original z coordinate of vertex[index], before it was modified. 1

vrobj.walkable

boolean

read only

Flag indicating if the vrobj is walkable.

vrobj.symbol

string

read only

The symbol of the vrobj.

vrobj.name

string

read only

The name of the vrobj.

vrobj.get_vertices();

 

Returns an array of vertices. Array is automatically deallocated.

vertexarray.set(i,x,y,z);

 

Sets coordinates of vertex x,y,z at index i of vertex array when set_vertices() is called.

vrobj.set_vertices();

 

Sets the vertices of the vrobj.

vrobj.reset_vertices();

 

Resets the coordinates of all vertices to their original values.

vrobj.orient(compass_direction, angle);

 

Sets the orientation of the vrobj, by first tipping the vrobj over so that the top of the vrobj faces in the compass direction (which can be one of the following values: "north", "east", "south", "west", "up" or "down"), then rotating the vrobj around the axis pointing in that compass direction. 2

vrobj.orient(y_angle, x_angle, z_angle);

 

Sets the orientation of the vrobj, by first rotating the vrobj around the y axis, then the x axis, then the z axis. 2

vrobj.rotate_x(angle);

 

Rotates the vrobj around the x axis by the given angle.

vrobj.rotate_y(angle);

 

Rotates the vrobj around the y axis by the given angle.

vrobj.rotate_z(angle);

 

Rotates the vrobj around the z axis by the given angle.