|
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 v1.5.1
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>
<ACTION>, <IMAGEMAP>
- 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:
<!--your comments here-->
Any information bounded in this way will be ignored by Rover.
Basic structure of
a .3DML file:
<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.
<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)" 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 rollover.
<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.
<PLACEHOLDER
TEXTURE="folder/image.gif -or- URL"/>
Uses the specified texture in place of any custom textures while the custom
textures download.
<STREAM
NAME="stream_name" WMP="url-for-WMP-stream" RP="url-for-RP-stream"/>
Specifies a streaming media file to use for both Windows Media Player and for RealPlayer.
<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
<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, the lighting (brightness, radius, and color) or the sound
(wave 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">
<PARAM ORIENT="up|down|north|south|east|west,0|90|180|270" SOLID="yes|no"/>
<PART NAME="name" TEXTURE="folder/image.gif-or-URL"
ANGLE="0-359"
COLOR="(red,green,blue)"
TRANSLUCENCY="number%"
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>, <SPOT_LIGHT>, <SOUND>,
<ACTION>. 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.
<LOAD
TEXTURE="folder/image.gif"/>
<LOAD SOUND="folder/sound.wav"/>
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.
<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="0 - 359,-90 - 90"/>
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,
and -90 - 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.
<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.
<ACTION
LOCATION="(column,row,level)" TRIGGER="roll on|roll off|click on|step
in|step out|proximity|timer|location" RADIUS="number-of-blocks" DELAY="min..max"/>
<REPLACE SOURCE="symbol|(column,row,level)" TARGET="(column,row,level)"/>
</ACTION>
Defines an ACTION which takes place as a response to a particular TRIGGER.
REPLACE is the only action that is currently available. RADIUS is 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.
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. 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".
<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. If used
in the BODY, and no LOCATION parameter is defined, then the POPUP will
display throughout the entire spot.
Following is an example
of a POPUP tag with all possible attributes:
<POPUP LOCATION="(column,row,level)"
TRIGGER="rollover,proximity|everywhere"
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%" />
ImageMaps
<IMAGEMAP NAME="imagemap name">
<AREA SHAPE="rect|circle"
COORDS="x1,y1,x2,y2 | x,y,radius"
HREF="destination URL"
TARGET="destination target"/>
<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>
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.
<SOUND
FILE="folder/sound.wav-or-url"
LOCATION="(column,row,level)"
VOLUME="number%"
PLAYBACK="looped|random|once|single"
DELAY="minimum..maximum"
RADIUS = "#_of_blocks"
FLOOD="yes|no"
ROLLOFF="1.0"/>
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" ROLLOFF="1.0"
<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.
|