3DML Tag Guide

This reference guide provides the details of the syntax for each of the 3DML tags. A thorough description of the blocks available can be found in the Blockset Guides. These guides are designed to be used in conjunction with the 3DML Tutorial, which gives step-by-step instructions on how to build a spot. It is advisable to complete the tutorial first.

3DML is a markup language that describes three-dimensional spaces (called spots) that are viewable with the Flatland Rover. Wherever possible, 3DML syntax is identical to or as similar to HTML syntax as possible. In some cases, however, we chose to make things a little different from HTML in order to retain XML compliance.

This guide is current for Rover version 3.4.

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 3DML you can write tags either way, as long, one line tags, or with line breaks as used in this reference.

General Rules About 3DML 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" />

The tags that can bound other tags are:

          <spot>, <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. This reference uses lowercase tags and attributes for consistancy.

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 3DML file, use the following syntax:

          <!-- your comments here -->

Any information bounded in this way will be ignored by Rover. Avoid using multiple, consecutive dashes (--) in comments for XML compliance.

Basic structure of a 3DML file

The <spot> tag

          <spot version="current_version_number"> ... </spot>

The first and last tags in a 3DML file. Everything between these tags is considered to be a spot described in the 3DML format. The version parameter specifies the oldest version of Rover the spot was designed for. As of the writing of this reference, the current version number is 3.4.

The <head> tag

          <head> ... </head>

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

The <body> tag

          <body> ... </body>

These tags surround the body content of the spot description, including the map itself.

Tags that can appear in the head of a 3DML file

The <debug> tag

          <debug warnings="yes|no" />

Used when building a 3DML file. If the <debug> tag is present, Rover will display error messages that will help the author find and correct errors in their 3DML file. It is recommended that the <debug> tag be removed before publishing your 3DML file to the Web.

The warnings attribute controls whether or not warnings (non-fatal errors) will be reported. Rover 3.4 is designed to be much more verbose in it's warnings, so it's helpful to be able to turn them off at times. The default is "yes".

The <title> tag

          <title name="name text" />

The text in the <title> tag is the name of the spot, and will be displayed in at the bottom of the browser window.

The <blockset> tag

          <blockset href="url" />

Specifies which set of blocks (i.e., textures, sounds, models and behaviors) to use to display this spot in the browser.

The <map> tag

          <map dimensions="(columns,rows,levels)"
          style="single|double" />

Dimensions specifies the size of the map described in the 3DML file in units of blocks (every block is the same size; imagine them as wooden cubes placed side-by-side and also stacked to create levels). Style determines whether single or double character symbols will be used to represent blocks in the map and in create tags.

The <sky> tag

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

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

The <fog> tag

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

Applies fog to entire spot. Fog color, density, distance in blocks where the fog starts, and distance in blocks 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 may or may not be rendered in a spot, depending on the 3D graphics card of the computer.

The <ground> tag

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

If supplied, Rover uses the given image (or color) as the ground plane directly beneath the first level 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:

          <ground />

If not supplied, there will be no ground. Movement through the lowest, groundless level is hindered, unless blocks are placed on this level to move over.

The <ambient_light> tag

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

Sets the ambient light level and color for the entire spot. Default is 100% brightness, and white light. Colored light will only be visible when Rover is running on 3D acceleration hardware.

The <orb> tag

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

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 spot, and the brightness and color of that light. Color will only be seen on 3D acceleration hardware. Href defines a link to a URL and text defines what text will be displayed on mouse roll-over.

The <ambient_sound> tag

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

Uses the given WAV file as the ambient sound of the entire spot. 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.

The <placeholder> tag

          <placeholder texture="folder/image.gif -or- URL" />

Uses the specified texture in place of any custom textures while the custom textures download.

The <onload> tag

          <onload href="url" target="target_name" />

Launches the specified URL as soon as the spot is loaded. This is useful for displaying information in another frame or window along with your spot.

Tags that can appear in the body of a 3DML file

The <create> tag

          <create symbol="symbol" block="symbol-or-block-name">

Every 3D block object is assigned a single ASCII character as a symbol. For instance, let's say a full block is assigned to the "#" character. So when you make a wall on the map you might type ##### which is a wall that is five blocks wide. Double-character symbols may also be used, if style="double" in the <map> tag. When using double-character symbols, each default single-character symbol is preceeded by a ".". So the default double-character symbol for a full block is ".#". The <create> tag allows you to change the textures applied to a block object and change some other features of the block, such as the orientation, the lighting (brightness, radius, and color) or the sound (WAV file, volume, radius and playback mode).

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

          <create symbol="symbol" block="symbol-or-block-name">
          -or - (angle_x,angle_y,angle_z)"
          solid="yes|no" movable="yes|no" origin="(x,y,z)"
          scale="(scale_x,scale_y,scale_z)" />
          <part name="name" texture="folder/image.gif-or-URL"
          angle="0-359" color="(red,green,blue)"
          faces="0|1|2" solid="yes|no" 
          rect="x1,y1,x2,y2" />

The <create> tag can also include any or all of the the following tags: <entrance>, <exit>, <param>, <popup>, <point_light>, <spot_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

          ... variables and functions ...

The <define> tag is used to define RoverScript variables and functions in your spot. See RoverScript Reference for more details.

The <import> tag

          <import href="folder/file.3dml" />

The <import> tag makes Rover insert the contents of the specified file into the 3DML file. This can be useful for sharing common elements between spots. The <import> tag can be used anywhere in the body of a spot, except inside of <level>, <define>, <action>, or <script> tags. The imported 3DML file must start with <import> and end with </import>.

The <load> tag

          <load texture="folder/image.gif" />
          <load sound="folder/sound.wav" />

The <load> tag forces Rover to load the specified file. Normally, Rover will load textures and sounds in the order in which they appear in the 3DML file. Using the <load> tag, you can force Rover to load images or sounds in a different order.

The <level> tag

          <level number="number">
                   ...rows of block symbols...

Defines the two dimensional map for one floor level of a spot. Between the tags, all letters are interpreted as building blocks for rendering the spot. 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 blocks in the resulting spot. The number attribute is optional. It is expected in general that each consecutive level defines a higher floor level of the spot.

The <entrance> tag

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

Defines a location where players can hyperlink into this spot from another spot or Web page. More than one may be defined in a single spot. There must be at least one entrance named "default" in every 3DML file. Angle defines what direction the viewer will be facing when she enters through this entrance (0 to 359 degrees with 0 equal to north, and -90 to 90 degrees to determine whether she 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 levels have been defined. Some authors prefer to put them immediatley following the level in which they occur. An entrance can also be assigned to a block by placing it inside the <create> tag. It does not take a location attribute if it is placed in the <create> tag.

The <exit> tag

          <exit location="(column,row,level)"
          trigger="click on|step on" text="text"
          target="destination name" />

A hyperlink to another 3DML file. Location defines where in the spot the link will be placed. The href gives the filename or URL of the destination spot or HTML page, with an optional entrance name (if omitted the "default" entrance 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. Target names the frame or window in which the link will open, just as it does in HTML. The default target of a 3DML file is "_self"; the default target of any other file is "_blank". Like the <entrance> tag, the <exit> tag can also be assigned to a block by including it in the <create> tag, or it can be placed in the body on its own, usually at the end of the body or immediately following the level in which it occurs.

The <action> tag

          <action location="(column,row,level)"
          trigger="roll on|roll off|click on|step in|
          step out|proximity|timer|location|key down|
          key up|key hold|start" key="keyvalue" partname="name-of-part"
          radius="number-of-blocks" delay="min..max" />
          <replace source="symbol|(column,row,level)"
          target="(column,row,level)" />
          <spin angles="(angle_x,angle_y,angle_z)" active="yes|no />
          <nospin />
          <orbit source="(column,row,level)|symbol"
          distance="(x,y,z)" speed="" active="yes|no" />
          <move pattern="pattern_code" active="yes|no" />
          <ripple style="waves|raindrops" force="value"
          droprate="droprate%" damp="damp%" />

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 body of the 3DML file, or they can be attached to blocks 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".

Key values for the key parameter include:

          a b c d e f g h i j k l m n o p q r s t u v w x y z
          1 2 3 4 5 6 7 8 9 0
          - = ~ ! @ # $ % ^ * ( ) _ + : " ? ; ' , . /
          [shift]  [ctrl]  [alt]   [space]   [backspace] [enter] [insert]
          [delete] [home]  [end]   [page up] [page down] [up]    [down]
          [left]   [right] [pad 0] [pad 1]   [pad 2]     [pad 3] [pad 4]
          [pad 6]  [pad 7] [pad 8] [pad 9]   [pad +]     [pad -] [pad *]
          [pad /]  [pad .] [none]

Replace defines a block to be replaced by another. Target defines the location of the block that will be replaced. Source specifies the block that will take the place of the specified target. If no target is specified, then the source will replace the block which holds the <action> tag.

Spin rotates a block x,y,z degrees per second. Use <nospin /> to stop this action on a block.

Orbit makes one block spin around another block, like the moon orbits the earth. The source is the symbol of the block that this block should orbit. The distance is the number of pixels away the block should orbit in the x, y and z directions. The speed is the how many radians to travel per second.

Move gives a block a set of instructions to follow over time. These instructions are made up of mini commands:

Example: <move pattern="(sp,100,100,100), (mv,80,0,0), (mv,0,80,0), (mv,-80,0,0),(mv,0,-80,0)(lp)" />

This moves a block in a repeating square pattern.

Ripple makes water effects on the surface of a block. Style is the type of water effect, either rain or waves. Force is the number of pixels to change the surface (randomized by both rain and water). Droprate is how often to cause a raindrop or a wave. Damp is how much to soften the effect over time, the less this amount the longer the ripples travel. Default values are style="raindrops", force="15.0", droprate="25%", and damp="85%".

The <popup> tag

          <popup location="(column,row,level)"
          texture="folder/image.gif -or- URL"
          size="(width,height)" text="message"
          textcolor="(red,green,blue)" imagemap="map name"
          brightness="brightness%" />

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 and color. 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 body section, or they can be assigned to a specific block in the <create> tag. If used in the <create> tag, the location attribute is not needed. If used in the body, and no location attribute is defined, then the popup will display throughout the entire spot.

The <imagemap> tag

          <imagemap name="imagemap name">
          <area shape="rect|circle"
          href="destination URL"
          target="destination target"/>
          <area ... />
          <action shape="rect|circle"
          trigger="roll on|roll off|click on|
          step in|step out|timer">

Defines an imagemap. Imagemaps are images that have areas that contain links to other 3DML spots or HTML pages. 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.

The <sound> tag

          <sound file="folder/sound.wav-or-url" name="sound name"
          volume="volume%" playback="looped|random|once|single"
          delay="minimum..maximum" radius="#_of_blocks"
          flood="yes|no" rolloff="rolloffvalue" />

Specifies a sound file that will play in the spot. Location refers to the placement of the sound in the map. 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 blocks 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".

The <point_light> tag

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

Defines a static light at a specific location in the map that shines in all directions. Location refers to the placement of the light in the map. Position refers to the position of the light within the 256-pixel blockspace. 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 ambient_light level at the far end of the radius. The default value is flood="no". Colored light will only be visible on 3D acceleration hardware. Lights can also be assigned to specific blocks within the <create> tag. If used in the <create> tag, the location attribute is not necessary.

          <point_light style="pulsate" location="(column,row,level)"
          position="(x,y,z)" brightness="min%..max%"
          radius="#_of_blocks" flood="yes|no" name="light name"
          color="(red,green,blue)" speed="cycles_per_second" />

Defines a point_light that constantly pulses from the minimum brightness to the maximum brightness. If speed="2", the light will go from the minimum brightness to the maximum and back again 2 times per second.

The <spot_light> tag

          <spot_light style="static" location="(column,row,level)"
          position="(x,y,z)" brightness="n%" radius="#_of_blocks"
          flood="yes|no" color="(red,green,blue)"
          direction="(turn,tilt)" cone="angle" name="light name" />

Defines a static spot_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.

          <spot_light style="search" location="(column,row,level)"
          position="(x,y,z)" brightness="n%" radius="blocks"
          flood="yes|no" color="(red,green,blue)"
          cone="angle" speed="cycles_per_second" name="light name" />

Defines a searching spot_light that moves from direction 1 to direction 2 and back again at the specified speed.

          <spot_light style="revolve" location="(column,row,level)
          position="(x,y,z)" brightness="brightness%" radius="blocks"
          flood="yes|no" color="(red,green,blue)"
          direction="(turn1,tilt1)..(turn2,tilt2)" name="light name"
          cone="angle" speed="revolutions_per_second" />

Defines a rotating spot_light that passes through directions 1 and 2 at the specified number of revolutions per second.

The <script> tag

Call functions and perform other scripting operations. See RoverScript Reference 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="#_of_blocks" key="keyvalue">
          ... script ...

The <player> tag

          <player size="(x,y,z)" camera="(x,y,z)" block="block name"
          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" />

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 -]".

Last updated: January 15, 2003