Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
software:vrgrid:scripting [2019/05/03 23:49]
ptsource
software:vrgrid:scripting [2019/08/20 12:35] (current)
Line 13: Line 13:
 ** Tags **  ** Tags ** 
 </​alert>​ </​alert>​
-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:+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:
 <sxh xml;> <sxh xml;>
 <​define>​ <​define>​
Line 128: Line 128:
 for each item in collection { do this with item } for each item in collection { do this with item }
 </​sxh>​ </​sxh>​
 +<alert type="​information"​ icon="​glyphicon glyphicon-info-sign"​ dismiss="​false">​
 +** Pre-defined objects ** 
 +</​alert>​
 +<​markdown>​
 +vrf
 +----
 +
 +The vrf object holds miscellaneous information about the vrf. It also holds all of the global variables and functions defined in the stand-alone <​define>​ 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.
 +
 +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.
 +
 +
 +`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.
 +
 +math
 +----
 +
 +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.
 +
 +fog
 +---
 +
 +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.
 +
 + 
 +
 +sky
 +---
 +
 +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.
 +
 +
 +atmosphere
 +--------------
 +
 +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).
 +
 +
 +
 +ambience
 +--------------
 +
 +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.
 +
 +
 +
 +orb
 +---
 +
 +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.
 +
 +
 +
 +player
 +------
 +
 +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
 +
 +
 +map
 +---
 +
 +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.
 +
 +vrobj
 +-----
 +
 +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 <​define>​ tag inside of a <​create>​ 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.
 +
 +</​markdown>​
   ​   ​