EWTOOLS-BSPUTIL(1)

📦 version 2.0.0~alpha11, in ubuntu stonking

okay so bestie, welcome to EWTOOLS-BSPUTIL(1) — that's the section 1 man page from the ericw-tools manual, and we are about to become unreasonably good at poking at Quake BSP files. 💖

✨ NAME ✨

  • ewtools-bsputil — utility for working with Quake BSP files 🦋
  • bsputil — utility for working with Quake BSP files 🦋

(yes it's the same thing twice, they're giving "same energy, different name", iconic honestly)

🌸 SYNOPSIS 🌸

bsputil [OPTION]... BSPFILE

💅 DESCRIPTION 💅

bsputil is a small utility for in-place manipulation of Quake BSP files. that's the whole vibe. it goes in, it messes with your .bsp, it says nothing, it leaves. no cap. ✨

🎀 OPTIONS 🎀

  • --scale x y z — scales the .bsp by the given scale factors. this one is experimental, so heads up: only a few entity properties actually get edited:
    • origin
    • lip
    • height
  • --replace-entities ENTFILE — swaps the .bsp's entity lump out for the contents of ENTFILE. girl, that's it, that's the whole trick. 💫

📝 Todo 📝

  • apparently this can handle BSPFILE being a path to a .MAP file, and update one map file given the entities in a second, ENTFILE. allegedly. 🙈
  • Move this functionality to maputil <>?
  • --convert FORMAT — converts the input .bsp to one of the given formats:
    • bsp29
    • bsp2
    • bsp2rmq
    • hexen2
    • hexen2bsp2
    • hexen2bsp2rmq
    • hl
    • q2bsp
    • qbism
lowkey important: this is a "container" conversion only, so most conversions will not be usable. it changes the box, not what's inside it. the way that matters!! 😭
  • --extract-entities — pulls the entity data out of BSPFILE and makes a plain text .ent file. the output filename is generated from BSPFILE by stripping the .bsp extension and adding the .ent extension. it names itself, we love a self-sufficient queen. 👑
  • --extract-textures — pulls the texture data out of BSPFILE and makes a Quake WAD file. the output filename is generated from BSPFILE by stripping the .bsp extension and adding the .wad extension. same energy, different extension. 🎀
  • --replace-textures WADFILE — replaces any textures in BSPFILE with the updated versions from WADFILE.
Note: a warning will be issued if any texture sizes don't match between BSPFILE and WADFILE. so like, read your warnings bestie. ⚠️
  • --check — loads BSPFILE into memory and runs a set of tests to check that all internal data structures are self-consistent. currently the tests are very basic, and not all warnings will result in errors from all versions of the Quake engine. also this option is not targeted at level designers — it's meant to help with development of the qbsp tool and to check that a "clean" bsp file is generated. it's a dev tool, iykyk. 🔥
  • --modelinfo — prints some information on all models in the .bsp. simple. elegant. slay.

📝 Todo 📝

  • Deprecated in favour of the .json export of bspinfo <>. 💀
  • --findfaces x y z nx ny nz — finds faces with the given x, y, z coordinates inside the face, and the face having the given normal nx, ny, nz. six numbers, one scavenger hunt. 🔍
  • --findleaf x y z — prints the leaf at the given coordinates. short and sweet fr fr. 🍓
  • --settexinfo facenum texinfonum — changes the texinfo of a given face. facenum in, texinfonum in, face changed. 💅
  • --decompile — decompiles BSPFILE to BSPFILE.decompile.map. hex code out, map file in. 🦋
  • --decompile-geomonly — decompiles BSPFILE to BSPFILE.decompile.map without texturing. geometry only, no glow-up. ✨
  • --decompile-ignore-brushes — decompiles BSPFILE to BSPFILE.decompile.map without using the Q2 brushes lump. bye brushey. 👋
  • --decompile-hull N — decompiles only the given hull number to BSPFILE.decompile.hullN.map. one hull, one file, no extras. 💖
  • --extract-bspx-lump LUMPNAME OUTFILENAME — writes the BSPX lump LUMPNAME to OUTFILENAME. 🫶
  • --insert-bspx-lump LUMPNAME INFILENAME — reads INFILENAME and inserts it as a BSPX lump LUMPNAME in BSPFILE. the reverse of the last one, we love a matching set. 🌈
  • --remove-bspx-lump LUMPNAME — removes LUMPNAME from BSPFILE. gone, deleted, uninvited from the group chat. 💀
  • --svg — Writes a top-down SVG rendering of BSPFILE. art. aerial view realness. ⭐

👑 AUTHOR 👑

  • Kevin Shanahan (aka Tyrann) — <http://disenchant.net>
  • Eric Wasylishen
  • Based on source provided by id Software

three absolute legends, fr fr. 🫶

😭 REPORTING BUGS 😭

please post bug reports at <https://github.com/ericwa/ericw-tools/issues>.

Improvements to the documentation are welcome and encouraged — yes really, they want your help, come through bestie. 💌

  • Copyright (C) 2017 Eric Wasylishen
  • Copyright (C) 2013 Kevin Shanahan
  • Copyright (C) 1997 id Software
  • License GPLv2+: GNU GPL version 2 or later <<http://gnu.org/licenses/gpl2.html>>.

this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law. (that's the dramatic part and it's real, not vibes.) 🧚

okay that's the whole page bestie, sourcing done, we ate and left no crumbs. 🌸 one last thing: this beauty is dated Jul 29, 2026, so mark your calendar, mwah 💅✨

📦 where this page comes from