VRF Tag Guide

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. VRF files are XML files with custom syntax tags, it uses full XML compliance.

General Rules About VRF Tags

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>
  • <head>
  • <body>
  • <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 XML compliance.

Basic structure of a VRF file

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

<vrf> ... </vrf>´

The <head> tag. These tags define a block of information which appears before the body section. The header acts as it does in HTML, containing information that applies to the entire XML code.

<head> ... </head>

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

<body> ... </body>

Tags that can appear in the head of a VRF file

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

<debug />
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.

<lib href="url" />
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,levels)" />
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 <ambient_light> tag. Sets the ambient light level and color for the entire VRF. Default is 100% brightness, and white light.
<ambient_light 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 <ambient_sound> tag. Uses the given WAV file as the ambient 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.
<ambient_sound 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 <stream> tag . Specifies a streaming reality media file to use. Reality media files are generated with the VREncoder from MP4, FLV, MPG or 3GP files.
<stream name="stream_name" rmurl="url-for-rm-stream" />
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"/>

Tags that can appear in the body of a VRF file

The <create> tag. Every 3D object is assigned a double ASCII character as a symbol. 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 symbol="symbol" block="symbol-or-block-name">
...
</create>
Below is an example of a <create> tag with all of the possible attributes:
<create symbol="symbol" block="symbol-or-block-name">
<param orient="up|down|north|south|east|west,0|90|180|270"
solid="yes|no" movable="yes|no" origin="(x,y,z)" />
<part name="name" texture="folder/image.vri -or- URL"
angle="0-359" color="(red,green,blue)"
translucency="translucency%"
style="tiled|scaled|stretched"
projection="top|bottom|north|south|east|west"
faces="0|1|2" solid="yes|no" stream="stream_name"
rect="x1,y1,x2,y2" />
</create>
The <create> tag can also include any or all of the the following tags: <entrance>, <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 block 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 <import> tag. The <import> 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 <import> tag can be used anywhere in the body of a VRF, except inside of <layer>, <define>, <action>, or <script> tags. The imported VRF file must start with <import> and end with </import>.
<import 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 optional. It is expected in general that each consecutive level defines a higher floor layer of the VRF.
<layer number="number">
...rows of unit symbols...
</layer>
The <entrance> 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 entrance named “default” in every VRF file. Angle defines what direction the viewer will be facing when entering through this entrance (0 to 359 degrees with 0 equal to north, and -90 to 90 degrees to determine whether is looking up or down.) The <entrance> tag can be placed anywhere within the body. It is usually placed at the end of the body, after all of the layers have been defined. An entrance 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.
<entrance location="(column,row,level)" name="name" angle="0-359,-90-90" />