bzw(5)
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 800×800.
- Here is small example world:
# simple world containing a box, pyramid, and meshworldname Simple Worldsize 100.0endboxposition -20 -20 0size 10 20 10endpyramidposition 20 20 0size 10 10 20endmeshvertex -10 0 0vertex 10 0 0vertex 0 10 0facevertices 0 1 2endfaceend
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:worldoptionswaterLeveldynamicColortextureMatrixtransformmaterialphysicsdefinegroupmeshmeshboxmeshpyrarcconespheretetraboxpyramidlinkteleporterbaseweaponzone
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. worldname example_worldsize 400.0flagHeight 10.0endThe Options object
A world file interface for setting command line options for BZFS. options
endThe Water Level object
Sets how high the water is, in a matter of units. waterLevelname example_waterlevelheight -1.0 # anything below 0 turns it offendThe 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>
enddefThe Group Instantiation object
Instantiates a group, and possibly modifies subobjects group <example_groupdef> # a valid group definition referenceshift 0 0 0 # (repeatable)scale 1 1 1 # (repeatable)shear 0 0 0 # (repeatable)spin angle nx ny nz # (repeatable)
team 0 # change all base colors within grouptint 1 1 1 1 # hierarchically tints objects within this groupdrivethrough # make all subobjects drivethroughshootthrough # make all subobjects shootthroughphydrv example_phydrv # reassign any valid physics driversmatref example_material # set material properties
endThe Dynamic Color object dynamicColorname example_dyncol
red, green, blue, alpha
limits, sinusoid, clampUp, clampDown, sequence
repeatable
red limits 0 1 # min/max limitsgreen sinusoid 0.1 0 0.25 # period, offset, weightblue clampUp 0.1 0 0.75 # period, offset, widthalpha clampDown 0.2 0.5 0.5 # period, offset, widthred sequence 0.0 0.0 2 0 1 1 2 0 … # period, offset, list of statesendThe Texture Matrix object textureMatrixname example_texmatscale 0.0 0.0 1.0 1.0 # u/v freqs, u/v scalesspin 0.0 # rotation freqshift 0.0 0.0 # u/v freqscenter 0.5 0.5 # dynamic u/v center (for spin and scale)fixedscale 0.0 0.0 # time invariant u/v scalefixedspin 0.0 # time invariant rotationfixedshift 0.0 0.0 # time invariant u/v shiftendMaterial Properties Material properties may be set on several types of objects, including meshes, mesh faces, arcs, cones, spheres, and tetras. Here are the properties:materialname example_materialresetmat # restore default valuesmatref material_name # copy another material’s propertiesambient 0.2 0.2 0.2 1.0 # ambient colordiffuse 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 coloremission 0.0 0.0 0.0 1.0 # emission colorshininess 0.0 # shininess (0.0 – 128.0)texture filename # set working texture
addtexture filename # add texturenotextures # specify that no textures are to be usednotexalpha # don’t use the texture’s alpha channelnotexcolor # the color is not applied to the texture
spheremap # use spherical texture coordinate mappingtexmat -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 shadowsnoculling # do not cull by face winding (double-sided)nosorting # do not do front-to-back alpha sortingnolighting # disable lightingalphathresh 0.0 # alpha thresholding valuegroupalpha # sort translucent faces as a groupoccluder # faces with this material will occludeendThe Physics Driver object physicsname example_phydrvlinear 0.0 0.0 0.0 # x/y/z linear velocitiesangular 0.0 0.0 0.0 # rotation freq, x/y coordinatesslide 0.0 # time until max velocity (> 0.0 enables)death Message goes here.
endThe Mesh object meshname example_mesh
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 driversmoothbounce # ricochets use normalsnoclusters # render each mesh face individuallyface # start a face (repeatable)
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 driverendface # end the face
drawInfodlist # display list for all material setsdecorative # older clients with not see this meshangvel <degrees/sec> # rotation about initial Z axisextents <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 setsphere <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 # matrefend # lodend # drawInfoend # meshThe Arc object arcname example_arcdivisions 16 # number of subdivisionsflatshading # flat shading (smooth is default)angle 360 # the sweep angleratio 1 # (outrad – inrad) / outradposition 0.0 0.0 0.0size 10 10 10rotation 0.0shift 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 driversmoothbounce # ricochets use normalsendThe Cone object conename example_conedivisions 16 # number of subdivisionsflatshading # flat shading (smooth is default)angle 360 # the sweep angleposition 0.0 0.0 0.0size 10 10 10rotation 0.0shift 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 driversmoothbounce # ricochets use normalsendThe Sphere object spherename example_spheredivisions 4 # number of subdivisionsflatshading # flat shading (smooth is default)position 0.0 0.0 10.0size 10 10 10radius 10 # sets all size values to this valuerotation 0.0shift 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 driversmoothbounce # ricochets use normalsendThe Tetrahedron object tetraname example_tetra
# there must always be 4 verticesvertex -10.0 -5.0 0.0vertex +10.0 -5.0 0.0vertex 0.0 10.0 0.0vertex 0.0 5.0 10.0shift 0 0 0 # (repeatable)scale 1 1 1 # (repeatable)shear 0 0 0 # (repeatable)spin angle nx ny nz # (repeatable)endThe Box object
Adds a simple block. boxname example_boxposition 0.0 0.0 0.0size 30.0 30.0 9.42rotation 0.0endThe Pyramid object
Adds a triangular shaped object. pyramidname example_pyramidposition 0.0 0.0 0.0size 8.2 8.2 10.25rotation 0.0endThe 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 linkagename example_teleporterposition 0.0 0.0 0.0size 5.06 4.48 20.16rotation 0.0border 1.12endThe 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. linkname example_link
# this will link all teleporters randomly to all other teleportersfrom *to *end
# or, to link between known teleporters examp_tele1(front) and examp_tele2(back) linkname example_realLinkfrom examp_tele1:fto examp_tele2:bendThe 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. basename example_baseposition 0.0 0.0 0.0size 60.0 60.0 0.0rotation 0.0color 0oncap VendThe 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. weaponname example_weaponposition 0.0 0.0 0.0rotation 0.0tilt 0.0initdelay 10.0delay 10.0 3.0 5.0 3.0type Vtrigger flagcapeventteam VendThe Zone object
Specifies a certain range in the world, and what attributes that range has. zonename example_zoneposition 0.0 0.0 0.0size 1.0 1.0 1.0rotation 0.0
# where players may spawnteam 0 1 2 3 4
# where flag may spawnflag GM SW good bad
# dropped team flags will fly to the closest safety zonesafety 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" (BZWReader.cxx/BZWReader::readWorldStream)- Note: Blank lines and lines starting with # are discarded.
- worldStream :=
-
"end" (ParseMaterial.cxx/parseMaterials)- material :=
-
object (WorldFileObject:.cxx/WorldFileObject::read)- object := "name" <name>
(WorldFileLocation.cxx/readWorldFileLocation::read)- location :=
-
("pos" | "position") 3dpoint (WorldFileObstacle.cxx/WorldFileObstacle::read)- obstacle :=
-
"drivethrough" (CustomArc.cxx/CustomArc::read)- meshbox :=
-
"divisions" <integer> - arc :=
-
"divisions" <integer> (CustomBase.cxx/CustomBase::read)- base :=
-
"color" <integer> (CustomBox.cxx)- box := obstacle
(CustomCone.cxx/CustomCone::read)- meshpyr :=
-
"divisions" <integer> - cone :=
-
"divisions" <integer> (CustomDynamicColor.cxx/CustomDynamicColor::read)- dynamicColor :=
-
object (CustomGate.cxx/CustomGate::read)- teleporter :=
-
"border" <float> (CustomGroup.cxx/CustomGroup::read)- group :=
-
"team" <integer> (CustomLink.cxx/CustomLink::read)- teleporter_spec :=
-
<integer> - link :=
-
"from" <teleporter_spec> (MeshDrawInfo.cxx/MeshDrawInfo::parseDrawCmd)- drawInfoCmd :=
-
"points" <integer>+ (MeshDrawInfo.cxx/MeshDrawInfo::parseDrawSet)- drawInfoSet :=
-
"matref" <material_name> (MeshDrawInfo.cxx/MeshDrawInfo::parseDrawLod)- drawInfoLod :=
-
"lod" (MeshDrawInfo.cxx/MeshDrawInfo::parse)- drawInfo :=
-
"drawInfo" (CustomMesh.cxx/CustomMesh::read)- mesh :=
-
"face" (CustomMeshFace.cxx/CustomMeshFace::read)- face :=
-
"vertices" <integer>{3..*} (CustomMeshTransform.cxx/CustomMeshTransform::read)- transform :=
-
"shift" 3dpoint (CustomPhysicsDriver.cxx/CustomPhysicsDriver::read)- physics :=
-
"linear" 3dpoint (CustomPyramid.cxx/CustomPyramid::read)- pyramid :=
-
"flipz" (CustomSphere.cxx/CustomSphere::read)- sphere :=
-
"divisions" <integer> (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 (CustomTextureMatrix.cxx/CustomTextureMatrix::read)- textureMatrix :=
-
"fixedshift" 2dpoint (CustomWaterLevel.cxx/CustomWaterLevel::read)- waterLevel :=
-
"height" <float> (CustomWeapon.cxx/CustomWeapon::read)- weapon :=
-
"initdelay" <float> (CustomWorld.cxx/CustomWorld::read)- world :=
-
"size" <float> (CustomZone.cxx/CustomZone::read)- zone :=
-
"team" <integer>{1..*}
See Also
bzflag(6), bzadmin(6), bzfs(6)