Editing Map making by hand

{{DoDoc|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 [[Special:Allpages|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 [[BZEditWin32|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 [http://my.bzflag.org/bb/viewtopic.php?f=24&t=16037&p=148953 forum topic].
===Windows===
*Notepad
*PSPad
*NoteTab
*[http://notepad-plus-plus.org/ Notepad ++] - a tabbed editor based on Scite.

===Mac===
*TextWrangler
*TextEdit
===Linux===
*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|box]] into a [[Meshbox|meshbox]] or a [[Pyramid|pyramid]] into a [[Meshpyr|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.
[[Image: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.
 world 
   size 400 
 end 
 options 
   +r 
   -j 
   -set _tankSpeed 25 
   -ms 5 
   -mp 0,2,0,2,0,2 
 end 
 box 
   name box1 
   position 0 0 0 
   size 10 10 10 
   rotation 0 
 end 
|}

=== 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:
<pre>
world 
  size 400 # Sets the world size to 400 (800 x 800 total)
end 
</pre>
This is rather self-explanatory. It's the <size> of the <world>.

Next is:
<pre>
options 
  +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
end 
</pre>
This is the <options>.
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)|Options Object]].

We now come to:
<pre>
box 
  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)
end 
</pre>
This is a <box> with a <name> of <box1>.
The <position> is 0,0,0 in R3[https://en.wikipedia.org/wiki/Three-dimensional_space_(mathematics)].
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
: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.
;Comments
: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.
;showCoordinates
: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==
In order to build maps, one must know the world objects used in them.
The table below provides an overview of the map objects which exist in BZFlag.
{|{{Prettytable}}
|-
| {{Hl3}} |'''Map Object''' 
| {{Hl3}} |'''Description'''
|-
|  [[ Arc]] ||  Arc is an object that defines an arc or cylinder in a map.
|-
| [[ Base]] ||  Base is an object which is similar to a box, but defines properties of it being a base for capture the flag style game play modes.
|-
|  [[Box]]  ||   Box is an object which defines a cube structure in a world file.
|-
|  [[Color(BZW)]]  ||  Color is used in a BZFlag world (BZW) as a sub parameter for many parameters, such as materials and dynamic colors.
|-
|  [[Cone]]  ||  Cone object is a BZW object that defines a cone in a BZW world file.
|-
|  [[Define]]  ||  Group Definition, or define, will group a set of objects that can be recalled and duplicated multiple times with the group object.
|-
|  [[DrawInfo]]  ||  DrawInfo allows clients to render the mesh object more efficiently through LODs (Levels of Detail). Drawinfo also allows the ability to create moving objects in a map.
|-
|  [[DynamicColor]]  ||  DynamicColor describes how a color channel will be dynamically updated.
|-
|  [[GroundMaterial]] ||  GroundMaterial is an option for a Material that allows one to set the ground texture. .
|-
|  [[Group]] ||  Group allows one to bring together a number of elements and refer to them as a single object.
|-
|  [[Include]] ||  Include is an option which allows one to specify a second bzw file that will be included in the first bzw.
|-
|  [[Link]]  ||  Link is an object which creates a link (route) between two teleporters.
|-
|  [[Linkmaterial]]  ||  LinkMaterial allows one to set the texture of the teleporter window to anything one would like it to be..
|-
|  [[Material]]  ||  A material is used in a BZFlag world to define a new look for otherwise regular objects, such as meshboxes.
|-
|  [[Mesh]]  || Mesh is an object which defines an arbitrary three dimensional shape.
|-
|  [[Meshbox]]  ||  Meshbox is an update to the original [[Box]] object and supports features such as physics drivers and textures.
|-
|  [[Meshpyr]]  ||  Meshpyr is an object that constructs a specialized mesh that has the geometric appearance of a Pyramid.
|-
|  [[Options (object)]]  ||  Options object is a BZW map structure that defines various options for a server to use when running a map.
|-
|  [[Physics]]  ||  Physics, or Physics Driver, is an object when applied to another object, will affect a tank touching it in some way.
|-
|  [[Pyramid]]  ||  Pyramid is a BZW map structure that defines a polyhedron having a polygonal base and triangular sides with a common vertex in the world.
|-
|  [[Sphere]]  ||  The sphere is an Object that defines a sphere in a map file.
|-
|  [[Teleporter]]  ||  Teleporter is an object which transports the user to another teleporter in a different part of the world.
|-
|  [[Tetra]]  ||  Tetra is an map object which creates a polygon with four vertices.
|-
|  [[TextureMatrix]]  ||  TextureMatrix, or texmat, when applied to a material object, allows you to define how a texture will appear in a material.
|-
|  [[WaterLevel]]  ||  WaterLevel is an object that defines a plane of water that spans the entire map. WaterLevel is deadly to all tanks that cross it.
|-
|  [[Weapon (object)]]  ||  Weapon object is a BZW map structure that defines a fixed weapon effect.
|-
|  [[World (object)]]  ||  World object is a BZW map structure that defines various options for the map.
|-
|  [[Zone]]  ||  Zone is a rectangular BZW map structure for spawn or flag zones.
|}

==See also==
===Map Editors===
{| class="wikitable" style="margin-right: auto; margin-left: 0px;"
| [[BZEdit]]
| [[BZEditWin32]]
| [[BZFed]]
| [[BZWTools]]
| [[DI-Machine]]
|-
| [[IBZEdit]]
| [[Modeltool]]
| [[PyBZEdit]]
| [[Wings3D]]
| 
|}

===Map Objects===
{{Template:Map objects}}

===Helpful links===
* [[Comparison of map editors]]
* [[Comparison of map objects]]
* [[Map FAQ]]
* [[Map making]]
* [[Texturing how to]]
* [[World units]]

[[Category:Tutorials]]
[[Category:Map Making]]
[[Category:Partial Documentation]]