Map making by hand

From BZFlagWiki
Revision as of 19:30, 15 February 2017 by Zehra (Talk | contribs) (cleanup)

Jump to: navigation, search
Plywood hammer100x101.gif There is still documentation to be done here!! If you feel up to the task, please have a go at it. Specifically what needs to be added is:
Major re-organization, transform away from "chat" style. Need to reference pages elsewhere on the wiki in place of much of the content which appears to be building up here. Create them if necessary, or see the list here.

Editing by hand is still a common way of creating maps. Although there's a number of GUI options for creating maps such as BZEdit, BZWTools, BZFed, PyBZEdit and IBZEdit. Many map-makers use a basic text-editor. This can be due to the enjoyment of the challenge of creating a map by hand or due to a lack of graphics modeling capability.

Text Editors

Most text-editors designed for coding/programming are more than sufficient for editing bzw files. Although word-processing programs such as Microsoft Word can be used, there are many cheaper (free) and more efficient programs designed specifically for coding. If you are interested in syntax highlighting, look at the forum topic.


  • Notepad
  • PSPad
  • NoteTab
  • Notepad ++ - a tabbed editor based on Scite.


  • TextWrangler
  • TextEdit


  • Command-line editors such as nano, emacs, pico, vim, or ed.
  • GEdit
  • Kate
  • Scite

Editing existing maps

Beginning mapmakers should spend some time studying and making small changes in existing maps to see how things work. In the client, maps can be saved for editing by joining the desired server and choosing: Options>Save World. Maps can also be saved by issuing the /saveworld command. The map should be a simple map when getting started. One may find it easier to create a file in BZEdit and open the resulting file in the text-editor. One can gain experience by also converting map objects into their mesh equivalents such as converting a box into a meshbox or a pyramid into a meshpyramid.

Getting Started

One should become familiar with the BZW syntax before attempting to create a map by hand from scratch or have on hand a reference card. Also knowing the coordinates of where object placement(s) will occur based on the options set. The way world units are oriented in a normal right hand rule coordinate system with positive Z being the "UP" direction. "north" on the in game radar is the positive Y direction in map coordinates. This image shows a typical map, with the origin and axis directions clearly marked out. MapCoordinateSystem.png

The positioning of map objects in the "position" of an object goes as such. The first setting is for the "X" axis with the second being for the "Y" axis and the third being for the "Z" axis. The same applies to the "size" in a world object.

A good way to start learning is to begin with simple world objects and settings:

# Example world with settings and box
# The number sign is not needed for a map to function, but is used for comments.
  size 400 
  -set _tankSpeed 25 
  -ms 5 
  -mp 0,2,0,2,0,2 
  name box1 
  position 0 0 0 
  size 10 10 10 
  rotation 0 

Example map explained

First, it says:

# Example world with settings and box
# The number sign is not needed for a map to function, but is used for comments.

(Note: the # sign is used for comments.)

This is many times added by map editors, but with different comments.(depending on editor)

The next thing is:

  size 400 # Sets the world size to 400 (800 x 800 total)

This is rather self-explanatory. It's the <size> of the <world> (The BZFlag arena).

Next is an <options> section:

  +r   # Enable Ricochet
  -j   # Enable Jumping
  -set _tankSpeed 25  # Sets the tank speed to 25 bzunits/second
  -ms 5  # Sets the maximum shots (per tank) to 5
  -mp 0,2,0,2,0,2  # Maximum of 2 Red Players, 2 Blue Players, and 2 Observers

This allows you to define in the map file certain options that are also available from the command line when you start the bzfs server, or in the optional server config file. Options embedded into a world file will override those input on the command line or in a config file.

The commands listed here are: Ricochet, Jumping, Tank speed, Max Shots, and Max Players. These are rather self explanatory, except for Max Players. Each number represents how many of each of the following team players are allowed in the game (in the order listed): Rogue, Red, Green, Blue, Purple, Observer. Each number defines the max number of players per category.

For more info, see Options Object.

We now come to:

  name box1      # Generally unused
  position 0 0 0 # X Y Z Position
  size 10 10 10  # X Y Z Size (bzunits from the position of the box)
  rotation 0     # Rotation (in degrees)

This is a <box> with a <name> of <box1>. The <position> is 0,0,0 in R3[1]. The rest is pretty self explanatory.

Important: EVERY STATEMENT MUST HAVE AN END. If a statement does not have an end you will get an error.

Basic Definitions

Objects are the basic building blocks of the bzw file. Objects begin with a line declaring the object, some fields describing that object, and a line that closes the object (usually with "end"). Each of these sections of the object is important.
BZFS ignores anything in a line following the #; the line has been "commented out." It is highly recommended that comments be used often, both for the mapmaker and for others that may see the map.
3D Cartesian Coordinate System
In most objects, you will see three numbers after position and size. These numbers are coordinates on a graph. The first number is the x coordinate (left and right) the middle number is the y coordinate (forward and backward) and the third number is the z coordinate (height and depth). Another way of thinking of it is: x = width, y = depth, z = height. (Those accustomed to the Y axis determining height will have to slightly adjust their thinking.)

Optional client setup

There are some options that appear useful when editing a map, especially when editing by hand.

The BZFlag client is capable of displaying a tank's current location for the player at the top right corner, right below the clock. This feature is being activated by executing the "/localset showCoordinates 1" command to the chat line.

Building World Objects

We're getting to the part of building world objects in a map. Most of the objects covered are quite simple to understand and program into a map. The first objects covered are the simple objects. The overview will first deal with boxes then move onto bases and then to pyramids.

See also

Map Editors

BZEdit BZEditWin32 BZFed BZWTools DI-Machine
IBZEdit Modeltool PyBZEdit Wings3D

Map Objects

Arc Base Box Color(BZW) Cone Define DrawInfo
DynamicColor GroundMaterial Group Include Link Linkmaterial Material
Mesh Meshbox Meshpyr Options (object) Physics Pyramid Sphere
Teleporter Tetra TextureMatrix WaterLevel Weapon (object) World (object) Zone

Helpful links