NAME
bzw - BZFlag world file format
DESCRIPTION
The BZFlag world file format describes a world environment that is used
by the BZFlag game server, bzfs. X BZW file format
The BZFlag world file format describes and environment that includes
the game map, physical world attributes, and automatic world weapons.
The map may contain a variety of "obstacles" like buildings, pyramids,
and meshes. These obstacles make up the world that the BZFlag tanks
will drive around in. Map attributes may be set to create worlds of
various sizes, the default size is 800x800.
Here is small example world:
# simple world containing a box, pyramid, and mesh
world
name Simple World
size 100.0
end
box
position -20 -20 0
size 10 20 10
end
pyramid
position 20 20 0
size 10 10 20
end
mesh
vertex -10 0 0
vertex 10 0 0
vertex 0 10 0
face
vertices 0 1 2
endface
end
The .bzw file is a plain text file with a relatively simple file
format. The format of this text file consists of any number of objects
listed in any order (except that physics, textureMatrix, dynamicColor,
and material must come before they are referenced) separated by
newlines and grouped into blocks of types. The list of world types
consists of:
world
options
waterLevel
dynamicColor
textureMatrix
transform
material
physics
define
group
mesh
meshbox
meshpyr
arc
cone
sphere
tetra
box
pyramid
link
teleporter
base
weapon
zone
Each object is described by placing the type on one line, the word end
on a following line, and a list of attributes for that object, one per
line, in between. The exceptions to the rule are define and face, which
are concluded with enddef and endface. Attributes may be listed in any
order. Attributes have default values, and if that is good enough, the
attribute need not be listed.
Words are always specified in lowercase. Line comments can be specified
by placing a # sign at the start of the line.
For documentation purposes, you can tag each object by adding a name
attribute. There is no set limit to the number of times you may use any
of the objects except for the world, options, and waterLevel objects,
they can only be specified once. The options object contains command
line arguments that are used to configure the server's game mode, but
can not contain server specific options such as -p, -passwd, and -conf.
In the following examples, the values are the defaults.
The World object
Header for the world.
world
name example_world
size 400.0
flagHeight 10.0
end
The Options object
A world file interface for setting command line options for BZFS.
options
-set _tankSpeed 36
-j +r -ms 3
+f GM{5} +f SW{5}
end
The Water Level object
Sets how high the water is, in a matter of units.
waterLevel
name example_waterlevel
height -1.0 # anything below 0 turns it off
end
The Group Definition object
Defines a group, which may include other group instances
This does not place any objects into the world, a group instance must
be used to generate world objects from a group definition.
define <example_groupdef>
# You can add any object to a group definition,
# except for the following types:
# textureMatrix
# dynamicColor
# material
# physics
# links
# weapon
# zone
enddef
The Group Instantiation object
Instantiates a group, and possibly modifies subobjects
group <example_groupdef> # a valid group definition reference
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
# angle degrees about vector n
team 0 # change all base colors within group
tint 1 1 1 1 # hierarchically tints objects within this group
drivethrough # make all subobjects drivethrough
shootthrough # make all subobjects shootthrough
phydrv example_phydrv # reassign any valid physics drivers
matref example_material # set material properties
# (except for the color)
end
The Dynamic Color object
dynamicColor
name example_dyncol
# there are 4 channels that can be modified:
# red, green, blue, alpha
# there are 5 types of commands per channel:
# limits, sinusoid, clampUp, clampDown, sequence
# except for "limits" and "sequence", the commands are repeatable
# if a sequence is used, then clampUps and clampDowns have no effect
# sequences can use three states (0, 1, 2).
# 0 - equivalent to an active clampDown
# 1 - equivalent to no clamps
# 2 - equivalent to an active clampUp
# if both clampUp and clampDown are active, the value is (min+max)/2
# the sinusoid function starts at the max value
# the sum of a channel's sinusoids is clamped between 0 and 1
red limits 0 1 # min/max limits
green sinusoid 0.1 0 0.25 # period, offset, weight
blue clampUp 0.1 0 0.75 # period, offset, width
alpha clampDown 0.2 0.5 0.5 # period, offset, width
red sequence 0.0 0.0 2 0 1 1 2 0 ... # period, offset, list of states
end
The Texture Matrix object
textureMatrix
name example_texmat
scale 0.0 0.0 1.0 1.0 # u/v freqs, u/v scales
spin 0.0 # rotation freq
shift 0.0 0.0 # u/v freqs
center 0.5 0.5 # dynamic u/v center (for spin and scale)
fixedscale 0.0 0.0 # time invariant u/v scale
fixedspin 0.0 # time invariant rotation
fixedshift 0.0 0.0 # time invariant u/v shift
end
Material Properties
Material properties may be set on several types of objects, including
meshes, mesh faces, arcs, cones, spheres, and tetras. Here are the
properties:
material
name example_material
resetmat # restore default values
matref material_name # copy another material's properties
ambient 0.2 0.2 0.2 1.0 # ambient color
diffuse 1.0 1.0 1.0 1.0 # diffuse color (main color)
color 1.0 1.0 1.0 1.0 # synonym for 'diffuse'
specular 0.0 0.0 0.0 1.0 # specular color
emission 0.0 0.0 0.0 1.0 # emission color
shininess 0.0 # shininess (0.0 - 128.0)
texture filename # set working texture
# - non-interlaced PNG
# - http:// or ftp:// hyperlinks can be used (no spaces)
# - BZFlag default texture names can be used (.png not required)
addtexture filename # add texture
notextures # specify that no textures are to be used
notexalpha # don't use the texture's alpha channel
notexcolor # the color is not applied to the texture
# if a texture is specified, but not found, the default texture
# will be used. if the default texture is also not available, then
# the color will be used (untextured)
spheremap # use spherical texture coordinate mapping
texmat -1 # texture matrix (-1 for none)
dyncol -1 # dynamic color (-1 for none)
noradar # do not display on radar (except normal mode)
noshadow # do not render shadows
noculling # do not cull by face winding (double-sided)
nosorting # do not do front-to-back alpha sorting
nolighting # disable lighting
alphathresh 0.0 # alpha thresholding value
groupalpha # sort translucent faces as a group
occluder # faces with this material will occlude
end
The Physics Driver object
physics
name example_phydrv
linear 0.0 0.0 0.0 # x/y/z linear velocities
angular 0.0 0.0 0.0 # rotation freq, x/y coordinates
slide 0.0 # time until max velocity (> 0.0 enables)
death Message goes here.
# the 'death' property requires a non-blank message
end
The Mesh object
mesh
name example_mesh
# Material properties applied to a mesh apply to all faces
# that follow the setting. Mesh faces will alter their own
# properties without affecting the state of the mesh properties.
# The same pattern is used to apply physics drivers.
vertex 100 200 300 # add a vertex (repeatable)
normal 1.0 0 0 # add a normal (repeatable)
texcoord 0.1 0.75 # add a texture coordinate (repeatable)
inside 5.5 4.5 1.2 # add an inside point (repeatable)
outside 0 0 1000 # add an outside point (repeatable)
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
phydrv example_phydrv # assign a physics driver
smoothbounce # ricochets use normals
noclusters # render each mesh face individually
face # start a face (repeatable)
# the front-face winding is counter-clockwise
vertices 1 4 0 3 5 # list of vertices (requires at least three)
normals 2 6 0 4 7 # list of normals (optional)
texcoords 0 3 2 4 9 # list of texture coordinates (optional)
phydrv example_phydrv # assign a physics driver
endface # end the face
#
# This next element can be added to increase the rendering speed
# of the mesh object. If the client is capable of using this data,
# then it is used to draw the mesh instead of the face information.
#
drawInfo
dlist # display list for all material sets
decorative # older clients with not see this mesh
angvel <degrees/sec> # rotation about initial Z axis
extents <minX> <minY> <minZ> <maxX> <maxY> <maxZ>
sphere <x> <y> <z> <radiusSquared>
corner <v> <n> <t> (repeatable)
vertex 0.0 0.0 0.0 (repeatable)
normal 0.0 0.0 0.0 (repeatable)
texcoord 0.0 0.0 (repeatable)
lod (repeatable)
lengthPerPixel <value>
matref <name> (repeatable)
dlist # display list for this material set
sphere <x> <y> <z> <radiusSquared>
points 0 (repeatable)
lines 0 1 (repeatable)
lineloop 0 1 (repeatable)
linestrip 0 1 (repeatable)
tris 0 1 2 (repeatable)
tristrip 0 1 2 (repeatable)
trifan 0 1 2 (repeatable)
quads 0 1 2 3 (repeatable)
quadstrip 0 1 2 3 (repeatable)
polygon 0 1 2 (repeatable)
end # matref
end # lod
end # drawInfo
end # mesh
The Arc object
arc
name example_arc
divisions 16 # number of subdivisions
flatshading # flat shading (smooth is default)
angle 360 # the sweep angle
ratio 1 # (outrad - inrad) / outrad
position 0.0 0.0 0.0
size 10 10 10
rotation 0.0
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
phydrv example_phydrv # assign a physics driver
smoothbounce # ricochets use normals
end
The Cone object
cone
name example_cone
divisions 16 # number of subdivisions
flatshading # flat shading (smooth is default)
angle 360 # the sweep angle
position 0.0 0.0 0.0
size 10 10 10
rotation 0.0
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
phydrv example_phydrv # assign a physics driver
smoothbounce # ricochets use normals
end
The Sphere object
sphere
name example_sphere
divisions 4 # number of subdivisions
flatshading # flat shading (smooth is default)
position 0.0 0.0 10.0
size 10 10 10
radius 10 # sets all size values to this value
rotation 0.0
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
phydrv example_phydrv # assign a physics driver
smoothbounce # ricochets use normals
end
The Tetrahedron object
tetra
name example_tetra
# there must always be 4 vertices
vertex -10.0 -5.0 0.0
vertex +10.0 -5.0 0.0
vertex 0.0 10.0 0.0
vertex 0.0 5.0 10.0
shift 0 0 0 # (repeatable)
scale 1 1 1 # (repeatable)
shear 0 0 0 # (repeatable)
spin angle nx ny nz # (repeatable)
end
The Box object
Adds a simple block.
box
name example_box
position 0.0 0.0 0.0
size 30.0 30.0 9.42
rotation 0.0
end
The Pyramid object
Adds a triangular shaped object.
pyramid
name example_pyramid
position 0.0 0.0 0.0
size 8.2 8.2 10.25
rotation 0.0
end
The Teleporter object
Adds an object that places a tank at another teleporter in a different
area when ran through.
teleporter [name]
# the [name] tag is used for linkage
name example_teleporter
position 0.0 0.0 0.0
size 5.06 4.48 20.16
rotation 0.0
border 1.12
end
The Link object
Adds a route to teleport a tank between two teleporters.
# Teleporter names are terminated with either :f (forward)
# or :b (backwards). The forwards link points to 0 degrees,
# and the backwards link points to 180. Links are made by
# pattern matching the teleporter names. The '*' and '?'
# globbing characters can be used to make multiple matches.
# If there are multiple matches for the "to" link, then the
# destination will be selected randomly between the matches.
# in-game.
# NOTE: bzfs -d -d -d -d will print the linkage table.
link
name example_link
# this will link all teleporters randomly to all other teleporters
from *
to *
end
# or, to link between known teleporters examp_tele1(front) and
examp_tele2(back)
link
name example_realLink
from examp_tele1:f
to examp_tele2:b
end
The Base object
Creates a team base where the corresponding team's flag is stored. The
oncap option will fire a world weapon of the specified type when the
team flag for this base is captured.
base
name example_base
position 0.0 0.0 0.0
size 60.0 60.0 0.0
rotation 0.0
color 0
oncap V
end
The Weapon object
Creates a world weapon, or a weapon fired automatically by the world.
The weapon can either be timed or be event driven. Timed weapons
should use the initdelay and delay fields. Event driven weapons need
to use the trigger option to define what the trigger event is. Valid
trigger events are; OnCap, for flag capture events. OnSpawn, for
player spawn events. OnDie, for player death events. If the weapon is
to be triggered only for a specific team then the eventteam option
should be used with a team number (1 to 4). A eventteam value of -1
will trigger this weapon for any team. -1 is the default eventteam
value.
weapon
name example_weapon
position 0.0 0.0 0.0
rotation 0.0
tilt 0.0
initdelay 10.0
delay 10.0 3.0 5.0 3.0
type V
trigger flagcap
eventteam V
end
The Zone object
Specifies a certain range in the world, and what attributes that range
has.
zone
name example_zone
position 0.0 0.0 0.0
size 1.0 1.0 1.0
rotation 0.0
# where players may spawn
team 0 1 2 3 4
# where flag may spawn
flag GM SW good bad
# dropped team flags will fly to the closest safety zone
safety 1 2 3 4
# attach a flag to this zone (always spawn in this zone)
zoneflag GM 3 # type, count (type can be a team flag, ex: R*)
end
FILE SYNTAX
The symbol '?' means that the item is optional.
The notation {a..b} means that the number of times the item can be
present must be between 'a' and 'b', where '*' mean infinity. ('?' is
equivalent to {0..1})
angle := <float>
2dpoint := <float> <float>
3dpoint := <float> <float> <float>
rgbColor := <float> <float> <float>
alpha := <float>
rgbaColor := rgbColor alpha? | <color_name> alpha?
channel := "red" | "green" | "blue" | "alpha"
(BZWReader.cxx/parseNormalObject)
allObjects :=
"box"
| "pyramid"
| "base"
| "link"
| "teleporter"
| "mesh"
| "arc"
| "meshbox"
| "cone"
| "meshpyr"
| "sphere"
| "tetra"
| "weapon"
| "zone"
| "waterLevel"
| "dynamicColor"
| "textureMatrix"
| "material"
| "physics"
| "transform"
(BZWReader.cxx/BZWReader::readWorldStream)
Note: Blank lines and lines starting with # are discarded.
worldStream :=
"end"
| allObjects
| "define" <group_name>
| "enddef"
| "group" <group_name>
| "teleporter" <name>?
| "options"
| "include" <filename>
| "world"
(ParseMaterial.cxx/parseMaterials)
material :=
object
| "matref" <material_name>
| "resetmat"
| "dyncol" <dynamic_color_name>
| "ambient" rgbaColor
| ("diffuse" | "color") rgbaColor
| "specular" rgbaColor
| "emission" rgbaColor
| "shininess" <float>
| "texture <texture_name>
| "notextures"
| "addtexture" <texture_name>
| "texmat" <matrix_name>
| "notexalpha"
| "notexcolor"
| "spheremap"
| "noradar"
| "noshadow"
| "noculling"
| "nosorting"
| "nolighting"
| "alphathresh" <value>
| "groupalpha"
| "occluder"
| "shader" <shader_name> # NOT IMPLEMENTED
| "addshader" <shader_name> # NOT IMPLEMENTED
| "noshaders" # NOT IMPLEMENTED
(WorldFileObject:.cxx/WorldFileObject::read)
object := "name" <name>
(WorldFileLocation.cxx/readWorldFileLocation::read)
location :=
("pos" | "position") 3dpoint
| "size" 3dpoint
| ("rot" | "rotation") <float>
| "shift" 3dpoint
| "scale" 3dpoint
| "shear" 3dpoint
| "spin" angle 3dpoint
| "xform" <transform_name>
| object
(WorldFileObstacle.cxx/WorldFileObstacle::read)
obstacle :=
"drivethrough"
| "shootthrough"
| "passable"
| location
(CustomArc.cxx/CustomArc::read)
meshbox :=
"divisions" <integer>
| "angle" angle
| "ratio" <float>
| "texsize" <float> <float> <float> <float>
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "flatshading"
| material
| ("top" | "bottom" | "inside" | "outside" | "startside" |
"endside") material
| obstacle
arc :=
"divisions" <integer>
| "angle" angle
| "ratio" <float>
| "texsize" <float> <float> <float> <float>
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "flatshading"
| material
| ("top" | "bottom" | "inside" | "outside" | "startside" |
"endside") material
| obstacle
(CustomBase.cxx/CustomBase::read)
base :=
"color" <integer>
| obstacle
(CustomBox.cxx)
box := obstacle
(CustomCone.cxx/CustomCone::read)
meshpyr :=
"divisions" <integer>
| "angle" <float>
| "texsize" <float> <float>
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "flatshading"
| material
| ("edge" | "bottom" | "startside" | "endside") material
| "flipz"
| obstacle
cone :=
"divisions" <integer>
| "angle" <float>
| "texsize" <float> <float>
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "flatshading"
| material
| ("edge" | "bottom" | "startside" | "endside") material
| obstacle
(CustomDynamicColor.cxx/CustomDynamicColor::read)
dynamicColor :=
object
| channel "limits" <float> <float>
| channel "sinusoid" <float> <float> <float>
| channel "clampup" <float> <float> <float>
| channel "clampdown" <float> <float> <float>
| channel "sequence" <float> <float> ("0" "1" "2"){1..*}
(CustomGate.cxx/CustomGate::read)
teleporter :=
"border" <float>
| "horizontal" # NOT IMPLEMENTED
| obstacle
(CustomGroup.cxx/CustomGroup::read)
group :=
"team" <integer>
| "tint" rgbaColor
| "phydrv" <physics_driver_name>
| "matref" <material_name>
| obstacle
(CustomLink.cxx/CustomLink::read)
teleporter_spec :=
<integer>
| <teleporter_name_with_wilcards> (":f" | ":b")?
link :=
"from" <teleporter_spec>
| "to" <teleporter_spec>
| object
(MeshDrawInfo.cxx/MeshDrawInfo::parseDrawCmd)
drawInfoCmd :=
"points" <integer>+
| "lines" <integer> <integer> <integer>{2}*
| "lineloop" <integer> <integer>+
| "linestrip" <integer> <integer> <integer{2}*
| "tris" <integer> <integer> <integer> <integer>{3}*
| "tristrip" <integer> <integer> <integer>+
| "trifan" <integer> <integer> <integer>+
| "quads" <integer> <integer> <integer> <integer>
<integer>{4}*
| "quadstrip" <integer> <integer> <integer>{2}+
| "polygon" <integer> <integer> <integer> <integer>{3}*
(MeshDrawInfo.cxx/MeshDrawInfo::parseDrawSet)
drawInfoSet :=
"matref" <material_name>
| "dlist"
| "sphere" 3dpoint <float>
| drawInfoCmd
(MeshDrawInfo.cxx/MeshDrawInfo::parseDrawLod)
drawInfoLod :=
"lod"
| "lengthPerPixel" <float>
| drawInfoSet
(MeshDrawInfo.cxx/MeshDrawInfo::parse)
drawInfo :=
"drawInfo"
| "dlist"
| "decorative"
| "angvel" <float>
| "extents" 3dpoint 3dpoint
| "sphere" 3dpoint <float>
| "corner" <integer> <integer> <integer>
| "vertex" 3dpoint
| "normal" 3dpoint
| "texcoord" <float> <float>
| drawInfoLod
(CustomMesh.cxx/CustomMesh::read)
mesh :=
"face"
| face
| "endface"
| "inside" 3dpoint
| "outside" 3dpoint
| "vertex" 3dpoint
| "normal" 3dpoint
| "texcoord" <float> <float>
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "noclusters"
| drawInfo
| material
| obstacle
(CustomMeshFace.cxx/CustomMeshFace::read)
face :=
"vertices" <integer>{3..*}
| "normals" <integer>{3..*}
| "texcoords" <integer>{3..*}
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "noclusters"
| "drivethrough"
| "shootthrough"
| "passable"
| material
(CustomMeshTransform.cxx/CustomMeshTransform::read)
transform :=
"shift" 3dpoint
| "scale" 3dpoint
| "shear" 3dpoint
| "spin" angle 3dpoint
| "xform" <transform_name>
| object
(CustomPhysicsDriver.cxx/CustomPhysicsDriver::read)
physics :=
"linear" 3dpoint
| "angular" <float> 2dpoint
| "radial" <float> 2dpoint # NOT IMPLEMENTED
| "slide" <float>
| "death" <string>
| object
(CustomPyramid.cxx/CustomPyramid::read)
pyramid :=
"flipz"
| obstacle
(CustomSphere.cxx/CustomSphere::read)
sphere :=
"divisions" <integer>
| "radius" <float>
| ("hemi" | "hemisphere")
| "texsize" <float> <float>
| "phydrv" <physics_driver_name>
| "smoothbounce"
| "flatshading"
| material
| ("edge" | "bottom") material
| obstacle
(CustomTetra.cxx/CustomTetra::read)
Note: At most 4 vertices can be specified.
Note2: material will apply to all vertices when specified first,
otherwise like "normals" and "texcoords" they apply to the
previous vertex.
tetra :=
"vertex" 3dpoint
| "normals" 3dpoint
| "texcoords" 2dpoint
| material
| obstacle
(CustomTextureMatrix.cxx/CustomTextureMatrix::read)
textureMatrix :=
"fixedshift" 2dpoint
| "fixedscale" 2dpoint
| "fixedspin" angle
| "fixedcenter" 2dpoint
| "shift" <float> <float>
| "spin" <float>
| "scale" <float> <float> <float> <float>
| "center" 2dpoint
| object
(CustomWaterLevel.cxx/CustomWaterLevel::read)
waterLevel :=
"height" <float>
| material
| object
(CustomWeapon.cxx/CustomWeapon::read)
weapon :=
"initdelay" <float>
| "delay" <float>{1..*}
| "type" <flag_short_name>
| location
(CustomWorld.cxx/CustomWorld::read)
world :=
"size" <float>
| "flagHeight" <float>
| object
(CustomZone.cxx/CustomZone::read)
zone :=
"team" <integer>{1..*}
"flag" ("good" | "bad" | <flag_short_name>){1..*}
| "safety" <integer>{1..*}
| "zoneflag" <flag_short_name> <integer>?
| location
SEE ALSO
bzflag(6), bzadmin(6), bzfs(6)