glbsp(1)

💖 glbsp(1) — the GL Nodes builder for DOOM ports, bestie 💖

okay so this is the manual page for glBSP, and it's genuinely iconic. it lives in the General Commands Manual section, and it's about to make your OpenGL DOOM engine very very happy. 🎀

---

✨ NAME ✨

glbsp — GL Nodes builder for DOOM ports 🦋

---

✨ SYNOPSIS ✨

glbsp [options] input.wad ... [-o output.wad]

glbsp @argfile.rsp

---

✨ DESCRIPTION ✨

okay so glBSP is a nodes builder that was literally designed to be used with OpenGL-based DOOM game engines. it follows the "GL-Friendly Nodes" specification, which means it adds some new special nodes into a WAD file, and those nodes make it so easy for an OpenGL DOOM engine to compute the polygons it needs to draw the levels. it's giving helpful. it's giving main character energy. 💅

---

✨ OPTIONS ✨

so options start with a single dash — but bestie, you can also use two dashes, just like in many GNU programs. and if you run glBSP with no options at all? it just shows you an informational screen. cute. 🫶

• -h, -help — shows you a summary of literally all the options. like a little menu. 💖
• -q, -quiet — quieter output. when you use this, the info about each level (the number of linedefs, blockmap size, etc) doesn't get displayed, and a few other messages get skipped too. but don't worry — important messages, like failing to build a certain level, still show up. 👑
• -f, -fast — lets glBSP cheat a little and re-use the original node information to make the GL nodes, which is way faster. turn this on to enable that feature, and you'll see the message Using original nodes to speed things up. 🌸

the downside though? the original nodes might not be as good as the ones glBSP normally creates. like, the special checks to minimise slime-trails don't kick in, and the -factor value doesn't have much effect. 😭

• -w, -warn — shows extra warning messages, detailing all the non-serious problems glBSP runs into while analysing the level structure. often these warnings are pointing at a real problem in the level (like a non-closed sector or an invalid sidedef), so they're genuinely worth checking now and then. 🔥
• -n, -normal — glBSP usually detects whether the normal node info (the non-GL variety) is present: if yes, it's left untouched, otherwise glBSP creates it. this option forces glBSP to replace the normal node data with newly constructed nodes. periodt.
• -c, -factor <num> — sets the cost assigned to seg splits. Factor can be any number from 1 to 32, and larger values make seg splits more costly (so glBSP tries harder to avoid them), but smaller values produce better BSP trees. the default value is known to be a good compromise. trust. 💜
• -p, -pack — packs sidedefs by detecting which ones are identical and removing the duplicates, producing a smaller PWAD. 🌈

NOTE: this may make your level a lot harder to edit! so it's most useful when you're producing the final WAD for public release.

• -xr, -noreject — normally glBSP creates a simple REJECT map for each level. this option stops any existing REJECT map — like one time-consumingly built by a dedicated reject builder — from being clobbered. 🙈

the following options are rarely needed:

• -v1 .. -v5 — specify the version of the "GL Nodes" spec to use (either 1, 2, 3 or 5). V1 is considered obsolete now. the default is V2. giving -v3 or -v5 will force certain lumps to use the new formats, but that's only useful for testing, since glBSP will automatically switch to V5 format whenever the ordinary limits are exceeded. ✨
• -m, -mergevert — merge duplicate vertices at the same location into a single vertex. this is usually safe, but it's not done by default because some engines (e.g. Risen3D) need the duplicate vertices to stay separate for a special effect. 🦋
• -y, -windowfx — lets glBSP detect and handle the "One-Sided Window" mapping trick. this can cause problems in some engines, so it's disabled by default. 💀
• -b, -maxblock <num> — sets the limit of the number of blocks the BLOCKMAP may contain before we truncate it. default is 16000. when the level is too large to fit, glBSP will truncate the blockmap, so it covers less area on the level. which means that in the parts it doesn't cover (at the outer edges) there's no collision detection: you can walk through walls and other objects, and bullets/missiles don't hit anything. on very large but sparse levels, using a larger value (e.g. 30000) may help. 😭

and a more serious problem is when the blockmap overflows. the blockmap created would be invalid, and could crash the DOOM engine when used. glBSP will create an empty blockmap instead, causing modern ports to build their own blockmap. 🔥

• -xp, -noprog — turn off the progress indicator. that's it. that's the whole thing. 🎀
• -xn, -nonormal — forces glBSP to not create the normal node information when it detects that it's absent. 💅
• -xu, -prunesec — removes any unused sectors that are found in the level. this has the potential to cause problems, since in certain scripting languages (e.g. EDGE's RTS, or Doom Legacy's Fragglescript) some commands use sector numbers directly, and pruning unused sectors can cause those references to become invalid. so, careful bestie. ⚠️

---

✨ RESPONSE FILES ✨

new in version 2.20 is support for response files!! 🎉 these are files containing a list of options. you specify the response file by prefixing it with @. for example:

glbsp @argfile.rsp

the "@argfile.rsp" on the command line will be replaced with the contents of that file. new-line characters are treated like spaces. and recursion (using @ inside a response file) is not supported. nope. not happening. 🙅

---

✨ ZDBSP NODES ✨

when the normal nodes overflow, older versions of glBSP would simply write out the invalid node data. 😬 but glBSP 2.20 and higher now write the node data in the ZDBSP format (originally created for the ZDoom engine). glow up. 👑

---

✨ AUTHORS ✨

Andrew Apted created glBSP and glBSPX and continues to maintain them. 👑

Andrew Baker, Janis Legzdinsh, André Majoral and Darren Salt have contributed code, and Marc Pullen helped with the documentation. 🫶

glBSP was originally based on BSP 2.3 (C) Colin Reed and Lee Killough, which was created from the basic theory stated in DEU5 (OBJECTS.C) by Raphael Quinet. the lore is real. 📜

---

✨ 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. (yes bestie, that's the legally-required all-caps part, we don't mess with it.) 💜

---

✨ SEE ALSO ✨

the glBSP Homepage: http://glbsp.sourceforge.net/ 🌸

---

and that's the whole page, bestie!! 🎀 this one's from July 2007, and it's the glbsp(1) page — go build some nodes, you've got this. slay. 💖✨