This reference guide provides the details of the syntax for each of the VRF tags.The code samples provided here are given in an extended form with line breaks between tag properties to make them easy to read. Please note, however, that in VRF you can write tags either way.

One line tags follow this basic syntax:

<tag attribute="value" />

Tags that bound other groups of tags follow this basic syntax:

<tag1 attribute="value">
<tag2 attribute="value" />
</tag1>

The tags that can bound other tags are:

  * <vrf> 
  * <globals> 
  * <design> 
  * <create> 
  * <action> 
  * <imagemap> 
  * <define>

All tags must be bounded by <>. Tags and attributes are not case sensitive, but opening and closing tags must be in the same case.

All values, meaning anything immediately following an equals sign must be surrounded by quotes. Any value that describes an x,y or x,y,z coordinate must be bounded by parentheses . R,G,B color values also must be bounded by parentheses .

To include comments in a VRF file, use the following syntax:

<!-- your comments here -->

Any information bounded in this way will be ignored. Avoid using multiple, consecutive dashes in comments for compliance.

The <vrf> tag. The first and last tags in a VRF file. Everything between these tags is considered to be VRF code described in the VRF format.

<vrf> ... </vrf>´

The <globals> tag. These tags define information which appears before the design section. The globals contains information that applies to the entire VRF code.

<globals> ... </globals>

The <design> tag. These tags surround the design content of the VRF, including the map itself.

<design> ... </design>

The <devel> tag. Used when building a VRF file. If the <devel> tag is present, error messages are displayed, that will help the author find and correct errors in their VRF file, also if the <devel> tag is present the code will be shown using the V key.

<devel />

The <title> tag. The text in the <title> tag is the name of the vrf, and will be displayed in at the bottom of VRGrid.

<title name="name text" />

The <lib> tag. Specifies which set of libraries (i.e., VRI'S, textures, sounds, 3D models and behaviors) are use to display the VRF. It uses an optional required attribute if you want to specify the minimum version of the library for use in the VRF, if the required attribute is used the visitor will get a warning if the version of the library he is using is lower than the required one.

<lib href="url" required="minimum version required"/>

The <map> tag. Dimensions specifies the size of the layers described in the VRF file in units (every unit is the same size, imagine them as wooden cubes placed side-by-side and also stacked to create layers).

<map dimensions="(columns,rows,layers)" />

The <sky> tag. Uses the given texture file (GIF, JPEG or VRI) as the tiled texture for the sky or enclosure. Alternately, a color can be specified to appear in the sky or enclosure, instead of a texture. The brightness parameter sets the light on the sky or enclosure image between 0 and 100 percent (default is 100%).

<sky texture="folder/image.vri -or- URL" color="(red,green,blue)" brightness="brightness%" />

The <fog> tag. Applies fog to entire VRF. Fog color, density, distance in units where the fog starts, and distance in units where the fog ends can all be specified. Default fog values are color=“(255,255,255)”, start=“1”, end=“10”, and density=“50%”. By default, fog is disabled.

<fog color="(red,green,blue)" start="value" end="value" density="density%" />

The <ground> tag. If supplied, VRGrid uses the given image (or color) as the ground plane directly beneath the first layer of the map. An author can then build a map without having to supply a solid floor. To use the default ground texture, include an “empty” ground tag. If not supplied, there will be no ground. Movement through the lowest, groundless layer is hindered, unless units are placed on this level to move over.

<ground texture="folder/image.vri -or- URL" color="(red,green,blue)" />

The <atmosphere> tag. Sets the atmosphere light level and color for the entire VRF. Default is 100% brightness, and white light.

<atmosphere brightness="brightness%" color="(red,green,blue)" />

The <orb> tag. Sets an image to be displayed in the sky such as a sun or moon. Also defines a source position for a directional light that shines from the orb over the entire VRF, and the brightness and color of that light. Href defines a link to a URL and text defines what text will be displayed on mouse roll-over.

<orb texture="folder/image.vri -or- URL" 
position="(turn,tilt)" brightness="brightness%" color="(red,green,blue)" 
href="url" target="target frame" text="text" />

The <ambience> tag. Uses the given WAV file as the ambience sound of the entire VRF. The volume of the sound can be between 0 and 100 percent (default is 100%). The sound can either be played once, looped, or played at random intervals. If playback=“random”, you can specify a range of times in between playbacks. Delay times are measured in seconds, and from the beginning of the sound, rather than the end.

<ambience file="folder/sound.wav -or- URL" volume="volume%" 
playback="looped|random|once" delay="minimum..maximum" />

The <loader> tag. Uses the specified texture in place of any custom textures while the custom textures download.

<loader texture="folder/image.vri -or- URL" />

The <assets> tag. When cloud hosting the VRF file the assets tag sets the include directory for files (i.e., VRI'S, textures, sounds, script imports). This is usefull for sharing files and media between multiple VRF´S.

<assets href="url"/>

The <font> tag. The font tag specifies the custom font used in popups in the VRF. When this tag is not used a default system font is used.

<font name="name-of-font"/>

The <scope> tag. The scope tag positions and hides the cursor. This can be usefull for some designs. The F9 key toggles between this mode as it shows and hides the cursor.

<scope/>

The <view> tag. The view sets the radius viewer distance. Values can be set between 5 and 90.

<view radius="distance"/>

The <create> tag. Every 3D object is assigned a double ASCII character as a unit. For instance, let´s say a full 3D object is assigned to the “##” character. So when you make a wall on the map you might type ## ## ## ## ## which is a wall that is five units wide. The <create> tag allows you to change the textures applied to a 3D object and change some other features of the 3D object, such as the orientation, the lighting (brightness, radius, and color) or the sound (WAV file, volume, radius and playback mode).

<create unit="unit" vrobj="libraryused:3dobjectname">
...
</create>

Below is an example of a <create> tag with all of the possible attributes:

<create unit="unit" vrobj="libraryused:3dobjectname">
<param orient="up|down|north|south|east|west,0|90|180|270"
solid="yes|no" walkable="yes|no" origin="(x,y,z)" />
<side name="name" texture="folder/image.vri -or- URL"
angle="0-359" color="(red,green,blue)"
clarity="clarity%"
style="tiled|scaled|stretched"
projection="top|bottom|north|south|east|west"
faces="0|1|2" solid="yes|no" rect="x1,y1,x2,y2" />
</create>

The <create> tag can also include any or all of the the following tags: <enter>, <exit>,<popup>, <point_light>, <vrf_light>, <sound>, <action>, <define>, and <script>. When used inside the <create> tag, these tags use the same syntax that they use on their own, except that they don't take a location attribute. Avoid using < or & in your vrobj symbols for XML compliance.

The <define> tag. The <define> tag is used to define script variables and functions in your VRF. See Scripting for more details.

<define>
... variables and functions ...
</define>

The <include> tag. The <include> tag makes VRGrid insert the contents of the specified file into the VRF file. This can be useful for sharing common elements between VRF´S. The <include> tag can be used anywhere in the design of a VRF, except inside of <layer>, <define>, <action>, or <script> tags. The included VRF file must start with <include> and end with </include>.

<include href="folder/file.vrf" />

The <layer> tag. Defines the two dimensional map for one floor layer of a VRF. Between the tags, all letters are interpreted as building units for rendering the VRF. The map must be written as a rectangle of characters with all rows equal in length. There is a one-to-one correspondence between the symbol positions in the map and the placement of the 3D objects in the resulting VRF. The number attribute is required the name attribute is optional. It is expected in general that each consecutive level defines a higher floor layer of the VRF.

<layer number="number" name="name">
...rows of units...
</layer>

The <enter> tag. Defines a location where viewers can hyperlink into the VRF from another VRF or webpage. More than one may be defined in a single VRF. There must be at least one enter named “default” in every VRF file. Angle defines what direction the viewer will be facing when entering through this enter (0 to 359 degrees with 0 equal to north, and -90 to 90 degrees to determine whether is looking up or down.) The <enter> tag can be placed anywhere within the design. It is usually placed at the end of the design, after all of the layers have been defined. An enter can also be assigned to a 3D object by placing it inside the <create> tag. It does not take a location attribute if it is placed in the <create> tag.

<enter location="(column,row,layer)" name="name" angle="0-359,-90-90" />

The <exit> tag. A hyperlink to another VRF file. Location defines where in the VRF the link will be placed. The href gives the filename or URL of the destination VRF or other file, with an optional enter name (if omitted the “default” enter will be used). The trigger attribute defines how the link can be activated, either by clicking on it, stepping on it, or both. The text attribute defines the text that will be displayed when the mouse rolls over the link. Like the <enter> tag, the <exit> tag can also be assigned to a 3D object by including it in the <create> tag, or it can be placed in the design on its own, usually at the end of the design or immediately following the layer in which it occurs.

<exit location="(column,row,layer)"
href="folder/desitination.vrf#enter-name"
trigger="click on|step on" text="text"/>

The <action> tag. Defines an action which takes place as a response to a particular trigger. Radius used only for trigger=“step in” or “step out”. Delay is only used for trigger=“timer”. Delay is measured in seconds. If only one delay value is specified, the delay time will remain consistent. If delay is expressed as a range from minimum to maximum times, the delay will be random within those parameters. Action tags can stand alone in the design of the VRF file, or they can be attached to 3D objects inside the <create> tag. Action can also be used in an imagemap with the additional attributes of shape=“rect|circle” and coords=“x1,y1,x2,y2|x,y,radius”.

<action location="(column,row,layer)"
trigger="roll on|roll off|click on|step in|
step out|proximity|timer|location|key down|
key up|key hold" key="keyvalue"
radius="number-of-units" delay="min..max" />
<execute action here />
</action>

The <popup> tag . Popups are 2D images that get displayed on the screen when the user travels within the radius of the location defined. This 2D image can be a texture (animated or still) or a color. The position and size of the popup image on the screen can be specified. Text can also appear on a popup, with a given alignment color and custom font specified with the globals font tag. When text is placed over a texture, the color attribute will define the color of a drop-shadow to make the text more legible. Finally, the brightness of the entire popup can be specified. Popups can be assigned to a location in the map in the design section, or they can be assigned to a specific 3D object in the <create> tag. If used in the <create> tag, the location attribute is not needed. If used in the design, and no location attribute is defined, then the popup will display throughout the entire VRF.

<popup location="(column,row,layer)"
trigger="rollover|proximity|everywhere"
radius="number-of-units"
texture="folder/image.vri -or- URL"
color="(red,green,blue)"
placement="mouse|top-left|top|top-right|
left|center|right|bottom-left|bottom|bottom-right"
size="(width,height)" text="message"
textalign="top-left|top|top-right|left|center|
right|bottom-left|bottom|bottom-right"
textcolor="(red,green,blue)" imagemap="map name"
brightness="brightness%" />

The <imagemap> tag. Defines an imagemap. Imagemaps are images that have areas that contain links to other VRF´S or other documents. Imagemaps can be used in popups only. When creating a rectangular area of an imagemap, the coordinates x1, y1 refer to the top left corner of the rectangle, and x2, y2 refer to the bottom right corner. When creating a circular area of an imagemap, x, y refers to the center of the circle.

<imagemap name="imagemap name">
<area shape="rect|circle"
coords="x1,y1,x2,y2|x,y,radius"
href="destination"
text="your text"/>
</area/>
<action shape="rect|circle"
coords="x1,y1,x2,y2|x,y,radius"
trigger="roll on|roll off|click on|
step in|step out|timer">
</action>
</imagemap>

The <sound> tag. Specifies a sound file that will play in the VRF. Location refers to the placement of the sound in the map or layer. The sound can either be played once, once every time the player enters the specified radius (single), looped continuously, or played at random intervals with the playback attribute. If playback=“random”, you can also specify a range of delay times between playbacks. Delay times are measured in seconds, and are measured from the time that the sound begins, rather than when it ends. Flood=“yes” will cause the sound to fill the specified radius at the specified volume. Radius should only be used if flood=“yes” or playback=“single” or “once”. Rolloff determines how quickly the sound will taper off as you move away from the source. Sounds can also be assigned to specific 3D objects within the <create> tag. If used in the <create> tag, the location attribute is not necessary. Default values are as follows: volume=“100%”, playback=“looped”, delay=“5..10”, radius=“1”,flood=“no”, and rolloff=“1.0”.

<sound file="folder/sound.wav-or-url" name="sound name"
location="(column,row,layer)"
volume="volume%" playback="looped|random|once|single"
delay="minimum..maximum" radius="number_of_units"
flood="yes|no" rolloff="rolloffvalue" />

The <point_light> tag. Defines a light at a specific location in the map that shines in all directions. Location refers to the placement of the light in the map or layer. Position refers to the position of the light within the 256-pixel unitspace. Flood=“yes” will cause the light to fill the radius at the specified brightness. Flood=“no” will create a light that is the specified brightness at the center, and gradually drops off to the atmosphere light level at the far end of the radius. The default value is flood=“no”. Lights can also be assigned to specific 3D objects within the <create> tag. If used in the <create> tag, the location attribute is not necessary.

<point_light style="static|pulsate" location="(column,row,layer)"
position="(x,y,z)" brightness="n%" radius="number_of_units"
flood="yes|no" color="(red,green,blue)" name="light name" 
speed="cycles_per_second"/>

The <vrf_light> tag .Defines a vrf_light at a specified location that shines in a specified direction. Direction is expressed as a pair of angles. The turn angle describes a direction in the horizontal plane, from 0 to 359 degrees, with 0 being north. The tilt angle describes a direction in the vertical plane, from -90 to 90 degrees, with 90 pointing straight up, 0 pointing at the horizon, and -90 pointing straight down. The cone describes how wide the light is in degrees.

<vrf_light style="static|search|revolve" location="(column,row,layer)"
position="(x,y,z)" brightness="n%" radius="number_of_units"
flood="yes|no" color="(red,green,blue)"
direction="(turn,tilt)" cone="angle" name="light name" 
 speed="revolutions_per_second"/>

The <script> tag .Call functions and perform other scripting operations. See Scripting for more information.

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

The <player> tag. Interacts with the view options. The default values for the <player> tag are: move_back=“[up]”, move_back=“[down]”, move_left=“[left]”, move_right=“[right]”, look_up=“a”, look_down=“z”, sidle_mode=“[shift]”, fast_mode=“[ctrl]”, go_faster=“[pad +]”, and go_slower=“[pad -]”.

<player size="(x,y,z)" camera="(x,y,z)" vrobj="unit"
move_forward="key" move_back="key"
move_left="key" move_right="key"
look_up="key" look_down="key"
sidle_mode="key" fast_mode="key"
go_faster="key" go_slower="key" />