About ZDBSP

ZDBSP is a stand-alone version of ZDoom's internal node builder. This node builder was written with two design goals in mind:

  1. It must be fast. The original node builder was just going to be used to fix map errors in ZDoom. After adding GL nodes support, ZDoomGL also started using it as a preprocessing step for any maps without existing GL nodes. In both cases, the node builder needed to be quick in order to minimize the time the user was forced to wait before playing a map.
  2. Polyobject bleeding must be minimized. The node builder was tested with the standard Hexen maps and several user maps, and it has been able to prevent bleeding on all properly-formed maps. (Note that it is impossible to prevent polyobject bleeding in all circumstances. See the polyobjects section below for rules you should follow for best results.)

Using ZDBSP with WadAuthor

First, copy zdbsp.exe to your WadAuthor directory. Then start WadAuthor and choose "Options..." from its Tools menu. Select the "Files" tab and choose "External" for Node Building. This activates the Command text box so that you can type text into it. Copy and paste any of the following into it based on what you want to do.

Create a map that can be played with Doom or any source port:

zdbsp -R -m$_Mapname $_Wadfile -o$_Wadfile

Create a map that will only be played with ZDoom. This will be ZDoom-only because it creates a zero-length REJECT lump. ZDoom is smart enough to know that a zero-length REJECT lump is the same thing as a REJECT lump filled with zeros, so you can save space:

zdbsp -r -m$_Mapname $_Wadfile -o$_Wadfile

Create a map with both regular and GL nodes so that ZDoomGL does not need to build GL nodes:

zdbsp -rg -m$_Mapname $_Wadfile -o$_Wadfile

ZDBSP command line options

ZDBSP supports several command line options to affect its behavior. If you forget what they are, you can view a quick summary of them by running ZDBSP without any options. They are also listed below in more detail than the listing ZDBSP provides. Note that these options are case-sensitive, so -r is not the same thing as -R. You can use either the long form of an option or the short form depending on your preference.

--help
Displays a summary of all ZDBSP's command line options, as if you had run ZDBSP without any options.
--version or -V
Displays ZDBSP's version number.
--map=MAP or -mMAP
When you use this option, ZDBSP will only build the nodes for one map in a wad instead of rebuilding the nodes for every map contained in the wad. MAP should be the map's full name (e.g. MAP01 or E1M1)
--output=FILE or -oFILE
Normally, ZDBSP creates a new wad named tmp.wad. You can use this option to make it write to a different file instead. In the case of WadAuthor, this is used to make ZDBSP overwrite the original file with the new one, because that is what WadAuthor expects the nodebuilder to do.
--no-prune or -q
When you use this option, ZDBSP will not remove unused sidedefs or sectors from a map. ZDBSP will always remove 0-length linedefs from a map even when you use this option because it is possible for them to make the game crash under certain circumstances. Moreover, ZDoom will itself remove 0-length linedefs and rebuild the nodes if it finds any.
--no-nodes or -N
This option causes ZDBSP to take the node information from the old wad file and write it to the new wad file. I can't think of any reason why you would want to do this, but it is provided as an option nonetheless.
--gl or -g
This option causes ZDBSP to build two sets of nodes for a map: One set of regular nodes and one set of GL nodes. Because ZDBSP is doing twice the work, it will take twice as long to finish.
--gl-matching or -G
Like the previous option, this one will also make ZDBSP generate GL nodes. However, it will only build one set of nodes and then strip the extra GL information from them to create the normal nodes. Because of this, it is faster than the previous option when you want to create GL nodes, but the normal nodes will generally be less efficient because they were created from the GL nodes.
--empty-blockmap or -b
This option writes a zero-length BLOCKMAP to the wad. As of this writing, ZDoom is the only port that will detect this and build the BLOCKMAP itself.
--empty-reject or -r
When this option is used, ZDBSP will write a zero-length REJECT to the wad. As of this writing, ZDoom is the only port that supports this. A zero-length REJECT is the same thing as a reject filled with zeros. Since ZDBSP does not generate a REJECT table, and the usefulness of having a REJECT is questionable, you should always use this option if you intend for the map to be played solely with ZDoom.
--zero-reject or -R
This option is similar to the previous one, except ZDBSP will actually write out a full-sized REJECT lump filled with zeros. If you play with ZDoom, this is just wasted space, but other ports and Doom itself require a full-sized REJECT lump to work.
--no-reject or -E
This option makes ZDBSP copy the REJECT lump from the old wad to the new wad unchanged. However, if it detects that the old REJECT is the wrong size for the number of sectors in the map, it will be removed as if you had used the --empty-reject option.
--no-polyobjs or -P
This option disables ZDBSP's polyobject detection code. If you are building nodes for a map without polyobjects, you might be able to save a fraction of a second from the build time by using this option, but there is generally no reason to use it.
--no-timing or -t
If you don't care how long it takes to build nodes, use this option and ZDBSP won't tell you.
--warn or -w
Displays extra warning messages that ZDBSP might generate while building GL nodes. The nodes will still be usable if warnings occur, and warnings are not unlikely. If you have strange display problems with GL nodes, turning on the warning messages may help you locate the problem.
--partition=NNN or -pNNN
This option controls the maximum number of segs that will be considered for splitters at each node. The default is 64. By increasing it, you might be able to generate "better" nodes, but you get diminishing returns the higher you make it. High values are also slower than low ones.
--split-cost=NNN or -sNNN
This option adjusts how hard ZDBSP tries to avoid splitting segs. The default value is 8. By increasing this, ZDBSP will try harder to avoid splitting segs. If you decrease it, ZDBSP will split segs more frequently. More splits mean the BSP tree will usually be more balanced, but it will also take up more room.
--diagonal-cost=NNN or -dNNN
This option controls how hard ZDBSP tries to avoid using diagonal splitters. The default value is 16. A higher value means that diagonal splitters will be more likely to be used. This can sometimes help to reduce the number of segs in a map. The reason avoiding diagonal splitters is important is because normal nodes do not store any fractional information for the vertices that segs use, so you are more likely to see slime trails with diagonal splitters than with horizontal or vertical splitters.
--view or -v
Under Windows, this displays a viewer that will let you inspect a map's subsectors, nodes, and REJECT. To scroll the map around, drag it with your right mouse button. The viewer was created to assist with debugging with the GL nodes. It is not very user-friendly nor is it bug-free. In fact, if you try to build nodes for more than one map with this option, there is a good chance ZDBSP will crash.

Polyobjects

One of ZDBSP's most important features is that it tries very hard to avoid polyobject bleeding. To make this feature work, however, you must design your maps properly. You do this be ensuring that your polyobjects are always shown inside a convex sector. This is referring to the area where the polyobjects appear in the game, not where they appear in an editor. If you do not know what convex means, think of triangles, squares and circles. They are all convex. If you have a sector shaped like the letter C, that is not convex.

Ironically, an example of what not to do is in Hexen's MAP01. The polyobject doors at the very start of that map do not appear in a convex area. ZDBSP has been tuned so that they will display properly with the default options, but you should not count on this for your own maps.

If ZDBSP has to split a linedef around a polyobject's display area, it will print a message indicating where this happened so that you can inspect the area and fix it. For example, when you use ZDBSP on hexen.wad, it outputs these warnings for MAP01:

   Split seg 929 (-1176,1312)-(-1088,1312) of sector 265 on line 572
   Split seg 931 (-1088,1312)-(-1000,1312) of sector 265 on line 573

The important pieces of information here are the coordinates of the segs that were split and the lines those segs were made from. In this case, both lines 572 and 573 were split. Because they surround a polyobject's display area, ideally they should not be split, so you need to look at the map in an editor to determine what made them split. This happens because the area is not convex, so you need to look for a line in the same "loop" that, if you made it longer, could cross the line that was split. In this example, lines 575 and 579 are responsible for splitting line 572, and lines 576 and 578 are responsible for splitting line 573. You can fix the error by reworking the area so that it is convex, either by moving lines 575, 579, 576, and 578, or by adding additional lines to separate each half into four convex pieces.

Below are some illustrations. The areas where the two polyobjects appear have been highlighted.

This first image shows the area as it appears in hexen.wad, unmodified. Note that neither side is convex, so ZDBSP will need to split each side into two subsectors. The extra subsectors have been highlighted in a brighter color to illustrate how ZDBSP splits them.
The Original Area

In the next image, the lines have been moved to make each side convex.
Convex Areas made by Moving Lines

In the final image, new two-sided lines have been added to make each polyobject's display area rectangular. Unlike the line-moving method above, this does not alter the area's appearance. Notice that this looks a lot like the way ZDBSP split them in the first image. The difference is that by adding the extra lines yourself, you have control over how the split is done and ZDBSP does not need to guess about the best way to make the area convex.
Convex Areas made by Adding Lines

Unfortunately, if you use WadAuthor, ZDBSP's output window will not normally appear long enough for you to actually read it. You can get around this by adding the -m option to the zdbsp command line that WadAuthor uses (see the Using ZDBSP with WadAuthor section). Then its output will stay around until you close the ZDBSP viewer.

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You can also find a copy of the license as the file COPYING in the source distribution.