VRF Tutorial

VRF is a full compliance XML based language used to build for representing interactive 3D and 2D with VR support. It includes its own scripting language for software design, and a format support for 3D models. VRF allows you to build a 3D environment without doing any 3D modeling. You can integrate many kinds of media right into a VRF, including sound, animation, 2D graphics, and text. Building 3D environment is actually very similar to building in the real world using familiar pieces such as simple wooden blocks or even two-by-fours from the local lumberyard. In VRF, there are sets of predefined 3d objects that you can put together to build a house, or a waterfall, or anything you desire. A VRF file has 2 major sections: the globals and the design. The globals is the section where you set attributes for the entire 3D environment, such as the map layers dimensions, atmosphere light and sound, the sky texture, etc. The design is the section where you can customize your 3d objects, and where you create your actual global map. The map layers are the heart of a VRF file, where you use different kinds of 3d objects (represented by double ASCII characters) to build a 3D environment. Each unit typically occupies a space of 256 x 256 x 256 (pixels). Units are arranged into a grid pattern to create each horizontal layer of a VRF. Layers are stacked on top of each other to create multi-layers VRF´S. This tutorial will take you step-by-step through the process of creating a VRF. After you have completed your first one, you may wish to use more advanced VRF features.

Before you begin the tutorial, there are two things you will need to do:
  • Download and install the VRGrid application
  • Get a free Github account since this tutorial will use Github for hosting
Getting Started

After creating a Github account create a repository. In your Github profile page go to “Repositories” then “New” and fill in the form. After your repository as been created we need to create a static host adress for it, to do that enter your repository you will have a “master” branch we will create a “gh-pages” branch. So select the “Branch” button and you will see “Find or create a branch” type in gh-pages and create. After that you also will have a Github https adress for that repository. To see your repository web adreess go to the repository “Settings” and you will find it under “Github Pages” “ You shoud see “Your site is published at "https://yourusername.github.io/yourrepositoryname/"”. That will be your web adress from now. Thats it and you are all set to go, from now on we will use the “gh-pages” branch of the repository to make and edit our files. If you want to use a standard code editor you can also you'll want to use software that displays all ASCII characters in monospacing and can do column editing. PTSource Developer Platform as support and syntax highlighting for VRF files. But in this tutorial we will only use the Github web editor. Se let´s start.

In the “gh-pages” branch of you repository create a new file named myfirstvrf.vrf

Go ahead and type the following lines in that file to get started :

<vrf>
<globals>
</globals>
<design>
</design>
</vrf>
Everything in a VRF file must be bounded by the <vrf> and </vrf> tags.

The <globals> part of the VRF

The <globals> part of the VRF contains several XML tags that apply to the entire VRF.

The <title> tag. The <title> tag holds the title of the VRF. The title text will be displayed at the bottom of VRGrid.

Put the following code between the <globals> tags in your VRF file:

<title name="My VRF Test" />
The <lib> tag. The <lib> tag lets VRGrid know what library of 3d objects and textures to use to display the VRF. The first time VRGrid encounters a new library, the library is downloaded and cached. The next time VRGrid encounters the same library, VRGrid will check if it is cached before attempting to download it.

Put the following code between the <globals> tags in your VRF file:

<lib href="https://ptsource.github.io/VRGrid/libs/basic.vlib"/>

The <map> tag. The <map> tag tells VRGrid what size your VRF is going to be. VRF´S are measured in units, (columns, rows, levels). When you are building a VRF, remember that whenever you change the dimensions of your map by adding new layers, columns,or rows, you will have to change the dimensions in the <map> tag as well.We are going to make a VRF that is 9 units wide, 9 units long, and 1 unit high.

Put the following code between the <globals> tags in your VRF file.

<map dimensions="(9,9,1)" />

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.

Put the following code between the <globals> tags in your VRF file:

<assets href="https://ptsource.github.io/VRGrid/assets/" />
The <sky> tag .The <sky> tag sets an image to be used as the background for your VRF. This texture will appear anywhere there aren't any units visible. If you don't put a ceiling on your VRF, the texture defined in the <sky> tag will appear in the sky. If you leave any holes in your walls or floors, then the <sky> texture will be seen there. If you prefer, you can set a color for the sky rather than a texture. The color is expressed by red, green, and blue values between 0 to 255. For example, pure red would be expressed as color=”(255,0,0)“, pure blue is color=”(0,0,255)“, and pure green would be color=”(0,255,0)“. All other colors can be expressed as combinations of red, green, and blue. You can also set the brightness of the sky in the <sky> tag. Brightness is expressed as a whole number percentage. If you don't specify brightness, the default level is 100%. If you leave out the <sky> tag altogether, the background will default to the sky texture specified in the library. Remember, if your image file isn't in the same folder as your VRF file, then you also need to specify the path to your image: <sky texture= “folder/image.vri -or- URL” /> the file must be located in a sub-folder of the path defined in the assets tag.

Put the following code between the <globals> tags in your VRF file:

<sky texture="images/clouds.gif" brightness="90%" />

The <ground> tag. The <ground> tag specifies a texture (or color) to be used on the ground plane of your VRF. If you use the <ground> tag, then you won't have to supply a solid floor of 3d objects in your map. The ground will be the same dimensions as your map. If your map is 5 units by 8 units, then your ground will be that same size as well. You can specify either a texture or a color with which to fill the ground plane. If you leave the <ground> tag out, there will be no ground plane displayed in your VRF, and you will have to supply a solid floor made of 3d objects in order to keep your visitors from falling endlessly through virtual space. If you want to use the default ground texture specified by the library, then simply include an empty <ground> tag in your VRF file: <ground />.

Put the following line of code between the <globals> tags in your VRF file:

<ground texture="images/dirt.gif" />

The <atmosphere> tag. The <atmosphere> tag has two attributes: brightness and color. Brightness defines how bright your VRF will appear to be in areas where you haven't placed any other lights. Brightness is expressed as a whole number percentage. If you set your atmosphere light relatively low, say around 50%, then you will have more room to play with lighting effects later. If you don't need that kind of flexibility, go to globals and set brightness at or close to 100%. The color attribute allows you to specify what color the light is in your VRF. Brightness defaults to 100%, if not otherwise specified. Color defaults to white, or (255,255,255).

Put the following code between the <globals> tags in your VRF file:

<atmosphere brightness="100%" />

The <ambience> tag. The <ambience> tag specifies a sound file that will play throughout your VRF. The ambience sound will be heard at the same volume throughout the entire VRF. The sound can either be 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. For example, if your sound is 5 seconds long, playback=“random”, and delay=“5..10”, then sometimes the sound will play back to back, (as the length of the sound file is the same as the minimum delay time), and no more than 5 seconds will ever elapse between when the sound ends and when it begins again. (The maximum delay time, 10 seconds, minus the length of the sound itself, 5 seconds, leaves a maximum silence of 5 seconds.) The default values for these attributes are volume=“100%”, playback=“looped”, delay=“5..10”.

Put the following code between the <globals> tags in your VRF file:

<ambience file="sounds/waves.wav" volume="65%" playback="looped" />

The <devel> tag. <devel> is an optional tag you can use to get more information about errors in your VRF. VRGrid by default ignores these errors as much as possible but if you include the <devel> tag you will get more information that will help you to locate and correct errors, also when the <devel> tag is avalible the code will be shown using the “V” key. So if you want to use the <devel> tag add the following line of code in your <globals> tag:

<devel />

The complete xml globals code for this tutorial should look like this:

<vrf>
<globals>
<title name="My VRF Test" />
<lib href="https://ptsource.github.io/VRGrid/libs/basic.vlib"/>
<assets href="https://ptsource.github.io/VRGrid/assets/" />
<map dimensions="(9,9,1)" />
<sky texture="images/clouds.gif" brightness="90%" />
<ground texture="images/dirt.gif" />
<atmosphere brightness="100%" />
<ambience file="sounds/waves.wav" volume="65%" playback="looped"/>
<devel />
</globals>
<design>
</design>
</vrf>  

The <design> part of the VRF

The <design> tag. The design of a VRF file is where you finally get to make the map itself. There are five main activities that are handled in the <design> tags are:

  1. Customizing 3d objects
  2. Creating the map
  3. Creating popups
  4. Assigning image maps
  5. Assigning enters and exits

First we will create a simple map and an enter. The map is made up of individual layers that act just like stories of a building. Each layer in a VRF must have the same number of rows and columns. If you need to add extra rows or columns to a VRF you have already been working on, you will need to add those rows or columns to every layer in the VRF. Each layer in a VRF is bounded by the <layer>…</layer> tags. The <layer> tag has just one attribute: number, number=“1” refers to the bottom layer of a VRF, just like floors of a building. Any character between the <layer> tags will be interpreted as a unit. All units occupy the space of a cube with 256 pixels in every dimension (256 x 256 x 256).

For this first map we will use just two kinds of 3d objects. You can find a complete list of 3d objects reference in the VRGrid menu under “Libraries”. We will use :

  • The full 3d object ”##“ The full 3d object is a solid cube, filling up the entire 256 x 256 x 256 unit space.
  • The empty unit ”..“ Nothing but virtual thin air. The empty unit is just a place holder that keeps your maps looking like easy-to-read grids.

Put the following code between the <design> tags in your VRF file:

<layer number="1">
     ## ## ## .. .. .. ## ## ## 
     ## .. .. .. .. .. .. .. ##
     ## .. .. .. .. .. .. .. ## 
     ## .. .. .. .. .. .. .. ## 
     ## .. .. .. .. .. .. .. ##  
     ## .. .. .. .. .. .. .. ##  
     ## .. .. .. .. .. .. .. ## 
     ## .. .. .. .. .. .. .. ##  
     ## ## ## ## ## ## ## ## ## 
</layer>

The <enter> tag . You must always specify at least one ennter for your VRF. The enter doesn't look like anything, it is just the place in the VRF where your visitors will first land. The <enter> tag has three attributes: location, name, and angle. An <enter> tag can be placed anywhere within the <design> tag. Some prefer to put their <enter> tags immediately following the layer in which they occur, others prefer to keep all of their <enter> tags together just before the closing </design> tag after all of the layers have been defined. In this tutorial we will keep them together at the end of the <design>. Our first VRF will only have one layer and one enter. The location is specified as an (x,y,z) coordinate, measured in units (with 1,1,1 being in the top left (or northwest) corner of the bottom layer.) The name attribute allows you to name each enter, so that you can refer to them later. They act sort of like targets in HTML. Every VRF must have one enter named “default”. The angle attribute defines what direction your visitors will be facing when they enter the VRF. The angle parameter has 2 values, turn and tilt, specified in whole number degrees. The first value specifies what direction (north, south, east, west, or somewhere in between) your visitors will face. Possible values range from 0 to 359. The second value specifies whether they will be looking up or down, with possible values of -90 to 90. The default value is “0,0” which will leave your visitors facing north, and parallel to the horizon. A value of “90,0” will set your visitors facing directly east, “180,45” will leave them facing south, and 45 degrees up into the “air”, etc.

Put the following code after the </level> tag in your VRF file:

<enter location="(5,8,1)" name="default" angle="0,0" />

Congratulations! You now have a fully functioning VRF! Save your Github file “myfirstvrf.vrf” in your Github repository and open VRGrid, type “G” or select “Open VRGrid URL” from the “File” menu and paste : "https://yourusername.github.io/yourrepositoryname/myfirstvrf.vrf". You will find yourself in a room with 4 walls and no ceiling. You should see your sky texture overglobals, and the ground texture underfoot. You will also see the sky texture in the open space in the wall in front of you. Go to the edge and look over.

The complete xml code for this VRF should look like this :

<vrf>
<globals>
<title name="My VRF Test" />
<lib href="https://ptsource.github.io/VRGrid/libs/basic.vlib"/>
<assets href="https://ptsource.github.io/VRGrid/assets/" />
<map dimensions="(9,9,1)" />
<sky texture="images/clouds.gif" brightness="90%" />
<ground texture="images/dirt.gif" />
<atmosphere brightness="100%" />
<ambience file="sounds/waves.wav" volume="65%" playback="looped"/>
<devel />
</globals>
<design> 
<layer number="1">  
     ## ## ## .. .. .. ## ## ## 
     ## .. .. .. .. .. .. .. ##
     ## .. .. .. .. .. .. .. ## 
     ## .. .. .. .. .. .. .. ## 
     ## .. .. .. .. .. .. .. ##  
     ## .. .. .. .. .. .. .. ##  
     ## .. .. .. .. .. .. .. ## 
     ## .. .. .. .. .. .. .. ##  
     ## ## ## ## ## ## ## ## ## 
</layer>  
<enter location="(5,8,1)" name="default" angle="0.0" />
</design>
</vrf>

As you can see it´s easy to get your show on the road, you can find all 13 tutorial files in VRGrid Github repository here VRGrid Github as well in you VRGrid menu under “Tutorial and Samples” just load them in VRGrid an type “V” to view all the code, full samples are also included.