FLATLAND | 3dml tag guide

last updated February 18, 1999

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 mark up language that describes 3 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 v0.9.7
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 we've done here.

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" /> </TAG1>

The tags that can bound other tags are:
<SPOT>, <HEAD>, <BODY>, <CREATE>

All tags must be bounded by <>.

Tags and attributes are not case sensitive, but your files will be easier to read if you capitalize them.

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 surrounded by parentheses( ).

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

Any information bounded in this way will be ignored by Rover.

Required tags in every .3DML file:
<SPOT>...</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.
<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.
<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
<DEBUG/>
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.
<TITLE NAME="name" />
The text in the <TITLE> tag is the name of the world, and will be displayed in at the bottom of the browser window.
<BLOCKSET HREF="url"/>
Specifies which set of 3D blocks (i.e. textures, sounds, models and behaviors) to use to display this spot in the browser.
<MAP DIMENSIONS="(columns,rows,levels)" STYLE="single|double"/>
DIMENSIONS specifies the size of the 3D map described in this 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.
<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 world. 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%).
<GROUND TEXTURE="folder/image.gif -or- URL" COLOR="(red,green,blue)" />
If supplied, the browser uses the given image (or color) as the ground plane directly underneath 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 />
<AMBIENT_LIGHT BRIGHTNESS="brightness%" COLOR="(red,green,blue)"/>
Set 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.
<ORB TEXTURE="folder/image.gif -or- URL" POSITION="(turn, tilt)" BRIGHTNESS="brightness%" COLOR="(red,green,blue)"/>
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.
<AMBIENT_SOUND FILE="folder/sound.wav -or- URL" VOLUME="volume%" PLAYBACK="looped|random" 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 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.
<PLACEHOLDER TEXTURE="folder/image.gif -or- URL"/>
Uses the specified texture in place of any custom textures while the custom textures download.

Tags that can appear in the <BODY> of a 3DML file
<CREATE SYMBOL="symbol" BLOCK="symbol-or-block-name"> </CREATE>
Every 3D block object is assigned a single printable ASCII character as a symbol. For instance, 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 ".#"
Every block is 256 pixels cubed. 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 (expressed as 0, 90, 180, or 270 degree rotation around the y, x, and then z axes), the lighting (brightness, radius, and color) or the sound (wave file, volume, radius and playback mode).
Below is an example of a typical <CREATE> tag:
<CREATE SYMBOL="symbol" BLOCK="symbol-or-block-name"> <PARAM ORIENT="y,x,z" /> <PART NAME="name" TEXTURE="folder/image.gif-or-URL" ANGLE="0-359" COLOR="(red,green,blue)" TRANSLUCENCY="number%" STYLE="tiled|scaled|stretched" /> </CREATE>
The <CREATE> tag can also include any or all of the the following tags: <ENTRANCE>, <EXIT>, <POPUP>, <POINT_LIGHT>, <SPOT_LIGHT>, <SOUND>. 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 when used in the <CREATE> tag.
<LEVEL NUMBER="number" >...rows of building block symbols...</LEVEL>
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.
<ENTRANCE LOCATION="(column,row,level)" NAME="name" ANGLE="degrees"/>
Defines a location where players can hyperlink into this SPOT from another SPOT or Web page. More than one of these can be defined in a single SPOT description. 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-359 degrees, with 0 equal to north) 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.
<EXIT LOCATION="(column,row,level)" HREF="folder/spot.3dml#entrance-name" 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 value is "self". 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.
<POPUP />
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.
Following is an example of a POPUP tag with all possible attributes:
<POPUP LOCATION="(column,row,level)" TRIGGER="rollover,proximity" RADIUS="number-of-blocks" TEXTURE="folder/image.gif -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 use of ImageMaps in 3DML

<IMAGEMAP NAME="imagemap name"> <AREA SHAPE="rect|circle" COORDS="x1,y1,x2,y2 | x,y,radius" HREF="destination URL" TARGET="destination target"/> <AREA ......./> </IMAGEMAP>
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 x2y2 refer to the bottom right corner. When creating a circular area of an imagemap, x,y refers to the center of the circle.

<POINT_LIGHT STYLE="static" LOCATION="(column,row,level)" POSITION="(x, y, z)" BRIGHTNESS="n%" RADIUS = "#_of_blocks" FLOOD="yes|no" COLOR="(red,green,blue)"/>
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" 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.
<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"/>
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)" DIRECTION="(turn1,tilt1)..(turn2,tilt2)" CONE = "angle" SPEED="cycles_per_second" />
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="n%" RADIUS="blocks" FLOOD="yes|no" COLOR="(red,green,blue)" DIRECTION="(turn1,tilt1)..(turn2, tilt2)" 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.