ZDBSP

ZDBSP is a stand-alone version of ZDoom's internal node builder. Although it has a several features built specifically with ZDoom in mind, ZDBSP is also perfectly capable of building nodes for vanilla Doom engine games too.

It was written with two primary design goals in mind:

• 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.
• 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. Later versions of ZDoom make bleeding a non-issue by running an abbreviated form of the node builder at runtime as polyobjects move, but see the polyobjects section below for historical guidance.

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.

Usage

From your editor

Ultimate Doom Builder comes with configurations for ZDBSP if you just want to use it without thinking about it much, but it also comes with several command-line options if you want to tinker or batch process node building.

Command line examples

• Build nodes for a map that will work with vanilla Doom or any source port:

  zdbsp --zero-reject --map=MAP01 MyWad.wad --output=MyWadWithNodes.wad 
  

• Build nodes for a map, but create an empty REJECT lump instead of one filled with zeroes to save space. This works for ZDoom and any source ports that understand that an empty REJECT is the same as a zero-filled one, but won't work with vanilla Doom:

  zdbsp --empty-reject --map=MAP01 MyWad.wad --output=MyWadWithNodes.wad
  

• Create a map with both regular and GL nodes:

  zdbsp --empty-reject --gl --map=MAP01 MyWad.wad --output=MyWadWithNodes.wad
  

• The output file can be the same as the input file to avoid creating a new file:

  zdbsp --map=MAP01 MyWad.wad --output=MyWad.wad
  

• Leave out the --map option, and ZDBSP will rebuild nodes for every map in a wad. Without a reject option, it also keeps the existing REJECT lump intact:

  zdbsp MyWad.wad --output=MyWad.wad
  

• Go all-in on ZDoom's space-saving node options:

  zdbp --empty-reject --empty-blockmap --compress MyWad.wad --output=MyZDoomWad.wad
  

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. Each one is 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.

Informational

• --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.
• --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 locate the problem.
• --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.

Output control

• --map=MAP or -mMAP
  When you use this option, ZDBSP builds nodes for only 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's what WadAuthor expects the node builder to do.
• --no-prune or -q
  Normally, ZDBSP removes unused sidedefs and sectors from a map as a cleanup step. With this option, ZDBSP leaves them intact instead. However, with or without this option, ZDBSP always removes 0-length linedefs from a map because it's 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.
• --comments or -c
  Write thing, linedef, sidedef, sector, and vertex indices as comments in UDMF maps.

Node control

• --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 has to do twice the work, expect it to take about twice as long to finish.
• --gl-matching or -G
  Like the previous option, this one also makes 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's faster than the previous option when you want to create GL nodes, but the normal nodes may be less "efficient" because they were created from the GL nodes.
• --gl-only or -x
  Only build GL nodes. If a map has regular nodes, they will be removed.
• --gl-v5 or -5
  Normally, v5 GL nodes are only written if the built nodes exceed the limits of v2 GL nodes. This option overrides that decision-making and always writes v5 GL nodes. v5 nodes offer no other benefits over v2 nodes than being able to work with larger maps, so you generally shouldn't need to use this option unless you have some specific reason for wanting v5 nodes.
• --compress or -z
  Write nodes using ZDoom's compressed format. Compressed nodes take up less space than uncompressed nodes, they're the only way to save nodes with more than 65535 segs, and they also have higher vertex precision than normal nodes, reducing the possibility of slime trails. If GL nodes are built, they also use the compressed format. Compressed nodes have their own special format compared to regular Doom nodes. A specification is given below.
• --compress-normal or -Z
  This is exactly like the previous option, except it only applies to normal nodes. GL nodes are written in the standard glBSP format.
• --extended or -X
  Creates extended nodes. This is exactly like --compress, except the resultant nodes aren't also processed through zlib. The underlying data format is the same between the two.
• --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's provided as an option nonetheless.

Node tuning options

• --partition=NNN or -pNNN
  This option controls the maximum number of segs to consider 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. Higher values are also slower than lower 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 are more likely to be used. This can sometimes help to reduce the number of segs in a map. The reasons for preferring axis-aligned splitters are two-fold:
  1. Node bounding boxes fit best when splitters are axis-aligned.
  2. Normal nodes don't store any fractional information for the vertices that segs use, so slime trails may be more likely with diagonal splitters than with axis-aligned ones.

Reject control

• --empty-reject or -r
  When this option is used, ZDBSP writes 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. Because ZDBSP doesn't generate a REJECT table, and the usefulness of having a REJECT is questionable on 21st century machines (except perhaps for very large maps), 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 writes out a full-sized REJECT lump filled with zeros. If you play with