Fire up your terminal of choice and let's take a look at the main zokumbsp help screen:
ZokumBSP Version: 1.0.9-rc1 (c) 2016-2017 Kim Roar Foldøy Hauge
Based on: ZenNode Version 1.2.1 (c) 1994-2004 Marc Rousseau
Usage: zokumbsp {-options} filename[.wad] [level{+level}] {-o|x output[.wad]}
-x+ turn on option -x- turn off option √ = default
-b[chio=0,1,2,3rsz=0,1,2g=0,1,2] √ - Rebuild BLOCKMAP
c √ - Compress BLOCKMAP.
h - Output BLOCKMAP data as HTML.
i - Id compatible BLOCKMAP. Sets 'o=1n=2' and 'c-s-r-'
o - Offset configuration.
0 = ZenNode 0,0 offset BLOCKMAP.
1 = DooMBSP / BSP 8,8 offset BLOCKMAP.
√ 2 = Best of 36 offset combinations.
3 = Heuristic method to reduce from 65536 offsets.
4 = Best of all 65536 offset combinations.
x,y = Specify specific offsets.
r √ - Remove non-collidable lines from BLOCKMAP.
s - Subset compress BLOCKMAP.
z - Zero header configuration.
0 = No zero header.
√ 1 = Conventional zero header.
2 = Zero footer.
g - Geometry simplification.
√ 0 = No simplification.
1 = Only if same sector.
2 = Also 1-sided lines in different sectors.
b - Build big 32bit BLOCKMAP.
-n[a=1,2,3|q|u|i] √ - Rebuild NODES
a - Partition Selection Algorithm
√ 1 = Minimize splits
2 = Minimize BSP depth
3 = Minimize time
q - Don't display progress bar
u - Ensure all sub-sectors contain only 1 sector
i - Ignore non-visible lineDefs
-r[zfgm] √ - Rebuild REJECT resource
z - Insert empty REJECT resource
f - Rebuild even if REJECT effects are detected
g √ - Use graphs to reduce LOS calculations
m{b} - Process RMB option file (.rej)
-t - Don't write output file (test mode)
level - ExMy for DOOM/Heretic or MAPxx for DOOM II/HEXEN
It's a bit overwhelming for normies like us to take in all at once so let's break it down.
At its most basic, we could use the tool with no options:
zokumbsp C:\doom\mymap.wad
This will crunch through all maps in the file C:\doom\mymap.wad at default settings (the ones with the √), which would be equivalent to:
zokumbsp -bco=2rz=1g=0 -n1 -rg C:\doom\mymap.wad
It's usually a good idea to designate an output wad however, so you can fall back to the original in case of an unforeseen consequence:
zokumbsp C:\doom\mymap.wad -o C:\doom\mymap_2.wad
But maybe we only want to process the boss map:
zokumbsp C:\doom\mymap.wad e1m8 -o C:\doom\mymap_2.wad
Or maybe we want to process e1m1 and e1m5
zokumbsp C:\doom\mymap.wad e1m1+e1m5 -o C:\doom\mymap_2.wad
To turn a function off we put a trailing minus on the argument. For example this would build default blockmap, default nodes, but NOT reject table for e1m8:
zokumbsp -r- C:\doom\mymap.wad e1m8 -o C:\doom\mymap_2.wad
Using a trailing minus on a sub-option will turn off just that sub-option. This command will build default nodes, default reject, and WILL build blockmap but WITHOUT the "remove non-collidable lines" sub-option
zokumbsp -br- C:\doom\mymap.wad e1m8 -o C:\doom\mymap_2.wad
So following those principles, one should be equipped to tackle most any combination of options (I'm not touching m{b} though, dunno what a .rej file even is so fuck that!)
As a final example, let's look at something real world. When a vanilla mapper is really trying to push a map's size/complexity, they can bump into doom's blockmap limit and result in the engine crashing upon loading the map. One of the major features of zokumbsp is some maths sorcery which can reduce the blockmap size, allowing for more geometry to be added by the mapper, and still remain vanilla compatible. One such map struggling to remain within limits is Back To Saturn X map20. Let's use an aggressive blockmap algorithm to see if we can squeeze any more out of the map:
zokumbsp -bo=3 -n- -r- btsx_e2a.wad map20 -o btsx_e2a_m20zokified.wad
ZokumBSP Version: 1.0.9-rc1 (c) 2016-2017 Kim Roar Foldøy Hauge
Based on: ZenNode Version 1.2.1 (c) 1994-2004 Marc Rousseau
Working on: btsx_e2a.wad
MAP20 : GEOMETRY - 8473/8473 lines Reduced to: 100.00% 0.001 secs
* BLOCKMAP - 63894/65508 (97.54%) Compressed: 67.60% 204.043 secs
Saving to btsx_e2a_m20zokified.wad...
1 Level processed in 3 minutes 24.044 seconds - 1 Level needed updating.
So just coming off the map editor which likely compiled automatically with zdbsp or zennode, we don't need to process nodes or reject, we are only interested in that blockmap limit. The option "-bo=3" will take some time to process but we see a 2.5% reduction in the blockmap size, allowing the mapper to fix a few more problems or squeeze in one more secret alcove. With zokum's own study on av, a 21% reduction was achieved with the same options. You can be sure Mutator would have given players 21% more headaches if such optimization was available in 2001!
A bonus example suggested by zokum + btsx godfather dew, was to add subset compression and remove the zero header from the blockmap:
zokumbsp -bo=3sz=0 -n- -r- btsx_e2a.wad map20 -o btsx_e2a_m20_superzokified.wad ZokumBSP Version: 1.0.9-rc1 (c) 2016-2017 Kim Roar Foldøy Hauge Based on: ZenNode Version 1.2.1 (c) 1994-2004 Marc Rousseau Working on: btsx_e2a.wad MAP20 : GEOMETRY - 8473/8473 lines Reduced to: 100.00% 0.001 secs * BLOCKMAP - 53842/65508 (82.19%) Compressed: 73.69% 95.803 secs Saving to btsx_e2a_m20_superzokified.wad... 1 Level processed in 1 minute 35.804 seconds - 1 Level needed updating.
A rather shocking ~18% reduction in blockmap size and still vanilla compatible. However it comes with the caveat of breaking the map in certain major source ports / port versions. The reasons why and recent developments on, are a subject for another article!