QBSP(1)

📦 version 0.18.1, in nixpkgs unstable

okay so welcome to qbsp(1), straight out of the General Commands Manual — this is the Quake map compiler, bestie, and we're about to make a .bsp out of a .map like it's absolutely nothing 💖✨

✨ NAME ✨

Compile a Quake BSP file from a MAP source file — that's it, that's the whole main-character job. Map goes in, BSP comes out, everybody claps. 🎀

🎀 SYNOPSIS 🎀

qbsp [OPTION]... SOURCFILE [DESTFILE]

yep, SOURCFILE is spelled like that in the synopsis — it's your source map, no cap. DESTFILE is optional, bestie.

💖 DESCRIPTION 💖

okay so qbsp is a tool used in the creation of maps for the id Software game Quake. It takes a .map file as input and produces a .bsp file playable in the Quake engine. If you don't supply the DESTFILE argument, the output filename gets chosen by stripping the file extension (if any) from SOURCEFILE and appending the .bsp extension. That's the pipeline, fr fr. 🦋

🌸 OPTIONS 🌸

  • -nofill — doesn't perform outside filling. No filling, no stress.
  • -noclip — doesn't build clip hulls. We're skipping the clip-hull arc.
  • -noskip — doesn't remove faces using the skip texture. Those faces stay in the mix.
  • -onlyents — only updates .map entities. Entity-only glow-up, okay?
  • -verbose — prints out more .map information. Chatty era, we love her.
  • -noverbose — prints out almost no information at all. The silent treatment, but productive.
  • -splitspecial — doesn't combine sky and water faces into one large face. They stay separate, periodt.
  • -transwater — computes portal information for transparent water. This is the default, bestie.
  • -notranswater — computes portal information for opaque water. Opaque water gets its portal moment.
  • -transsky — computes portal information for transparent sky. Sky portals, slay.
  • -nooldaxis — use alternate texture alignment algorithm. The default is to use the original QBSP texture alignment algorithm, which required the -oldaxis switch in tyrutils-ericw v0.15.1 and earlier.
  • -forcegoodtree (experimental) — force use of expensive processing for SolidBSP stage. Often results in a more optimal BSP file in terms of file size, at the expense of extra processing time. Experimental, so handle with care ✨
  • -bspleak — creates a .por file, used in the BSP editor.
  • -oldleak — create an old-style QBSP .PTS file. Default is new.
  • -leaktest — makes it a compile error if a leak is detected. Leak = not slay.
  • -nopercent — prevents output of percent completion information. No little percentage guy.
  • -bsp2 — create the output BSP file in BSP2 format. Allows the creation of much larger and more complex maps than the original BSP 29 format.
  • -2psb — create the output BSP file in 2PSB format. This is an earlier version of the BSP2 format, supported by the RMQ engine (and thus is also known as the BSP2rmq or RMQe bsp format). The source text also has the trailing fragment original BSP 29 format). here — we're keeping it, no erasure 💀
  • -leakdist [n] — space between leakfile points. Default is 2.
  • -subdivide [n] — use different texture subdivision. Default is 240.
  • -wadpath <dir> — search this directory for wad files. Default is cwd.
  • -oldrottex — use old method of texturing rotate_ brushes where the mapper aligns textures for the object at (0 0 0).
  • -maxNodeSize [n] — switch to the cheap spatial subdivision bsp heuristic when splitting nodes of this size (in any dimension). This gives much faster qbsp processing times on large maps and should generate better bsp trees as well. From txqbsp-xt, thanks rebb. Default is 1024; 0 disables it.
  • -hexen2 — generate a hexen2 bsp.
  • -wrbrushes — (bspx) includes a list of brushes for brush-based collision.
  • -wrbrushesonly — -wrbrushes combined with -noclip argument. Two-for-one.
  • -notex — write only placeholder textures, to depend upon replacements.
  • -omitdetail — detail brushes are omitted from the compile.
  • -convert <fmt> — convert a .MAP to a different .MAP format. fmt can be: quake, quake2, valve, bp (brush primitives). Conversions to quake or quake2 format may not be able to match the texture alignment in the source map, other conversions are lossless. The converted map is saved to <source map name>-<fmt>.map.

🧚 SPECIAL TEXTURE NAMES 🧚

The contents inside a brush depend on the texture name(s) assigned to it. By default brush contents are solid unless they have a special name. Names beginning with an asterisk are liquids. A prefix of *slime indicates slime, *lava is for lava and anything else beginning with * will have contents as water. 🫶

All faces of a brush must have textures which indicate the same contents. Mixed content types will cause qbsp to print an error and exit. No mixing, bestie — it's giving chaos and qbsp is not here for it.

💅 SKIP 💅

Any surfaces assigned a texture name of skip will be compiled into the bsp as invisible surfaces. Solid surfaces will still be solid (e.g. the player can't walk or shoot through them) but they will not be drawn. Water, slime and lava surfaces can be made invisible using the texture names *waterskip, *slimeskip and *lavaskip respectively. Invisible but still solid? iconic. 💅

🦋 HINT 🦋

Hint surfaces cause a bsp split and portal to be generated on the surface plane, after which they are removed from the final bsp — they are neither visible, nor structural. Strategic placement of hint surfaces can be used by a map author to optimise the PVS calculations so as to limit overdraw by the engine (see also: vis(1)). Big brain map-author energy.

Use a texture with the name hintskip on any surfaces of a hint brush which you don't want to generate bsp splits or portals. All surfaces of a hint brush must use either the hint or hintskip texture name.

🌈 EXTERNAL MAP PREFAB SUPPORT 🌈

This qbsp has a prefab system using a point entity named "misc_external_map". The idea is, each "misc_external_map" imports brushes from an external .map file, applies rotations specified by the "_external_map_angles" key, then translates them to the "origin" key of the "misc_external_map" entity. Finally, the classname of the "misc_external_map" is switched to the one provided by the mapper in the "_external_map_classname" key. (The "origin" key is also cleared to "0 0 0" before saving the .bsp). Obsessed with this little import machine. 🎀

The external .map file should consist of worldspawn brushes only, although you can use func_group for editing convenience. Brush entities are merged with the worldspawn brushes during import. All worldspawn keys, and any point entities are ignored. Currently, this means that the "wad" key is not handled, so you need to add any texture wads required by the external .map file to your main map.

Note that you can set other entity keys on the "misc_external_map" to configure the final entity type. e.g. if you set "_external_map_classname" to "func_door", you can also set a "targetname" key on the "misc_external_map", or any other keys for "func_door".

  • _external_map — Specifies the filename of the .map to import.
  • _external_map_classname — What entity you want the external map to turn in to. You can use internal qbsp entity types such as "func_detail", or a regular bmodel classname like "func_wall" or "func_door".
  • _external_map_angles — Rotation for the prefab, "pitch yaw roll" format. Assuming the external map is facing the +X axis, positive pitch is down. Yaw of 180, for example, would rotate it to face -X.
  • _external_map_angle — Short version of "_external_map_angles" for when you want to specify just a yaw rotation.
  • _external_map_scale — Scale factor for the prefab, defaults to 1. Either specify a single value or three scales, "x y z".

🔥 DETAIL BRUSH SUPPORT 🔥

This version of qbsp supports detail brushes which are similar in concept to Quake 2's detail brushes. They don't seal the map (previous versions did). Lowkey a glow-up.

To be compatible with existing Quake 1 mapping tools, detail brushes can be added by creating an entity with classname "func_detail". When qbsp reads the map file, it will add any brushes included in a func_detail entity into the worldspawn as details and remove the func_detail entity. Any number of func_detail entities can be used (useful for grouping) and all included brushes will be added to the worldspawn.

Here's an example entity definition suitable to add to the .QC files used by BSP Editor:

/*QUAKED func_detail (0.5 0.5 0.9) ?
Detail brushes add visual details to
the world, but do not block visibility.
func_detail entities are merged into
the worldspawn entity by the qbsp compiler
and do not appear as separate entities in
the compiled bsp.
*/

For WorldCraft in .FGD format (untested):

@SolidClass color(128 128 230) = func_detail: "Detail" []

For Radiant in .ENT format:

<group name="func_detail" color="0 .5 .8">
Detail brushes add visual details to the world, but do not
block visibility. func_detail entities are merged into the
worldspawn entity by the qbsp compiler and do not appear as
separate entities in the compiled bsp.
</group>

What should be written to the .map file is a simple entity with one or more brushes. E.g.:

{
"classname" "func_detail"
{
( -176  80  0 ) ( -208  80  0 ) ( -208  48  0 ) COP1_1 0 0 0 1.0 1.0
( -192 -80 64 ) ( -208 -80  0 ) ( -192 -64 64 ) COP1_1 0 0 0 1.0 1.0
( -176 -80  0 ) ( -192 -80 64 ) ( -176 -64  0 ) COP1_1 0 0 0 1.0 1.0
( -16   48  0 ) (  -16  64 64 ) (    0  48  0 ) COP1_1 0 0 0 1.0 1.0
( -16   64 64 ) (  -16  80  0 ) (    0  64 64 ) COP1_1 0 0 0 1.0 1.0
}
}

When qbsp detects detail brushes, it outputs a modified portal file format with the header PRT2 (default is PRT1). This portal file contains extra information needed by vis to compute the potentially visible set (PVS) for the map/bsp. So you will also need a vis util capable of processing the PRT2 file format.

👑 DETAIL VARIANTS 👑

🍓 func_detail_illusionary 🍓

func_detail variant with no collision (players / monsters / gunfire) and doesn't split world faces. Doesn't cast shadows unless enabled with "_shadow" "1". Useful for hanging vines. Still creates BSP leafs, which is unavoidable without a new .bsp file format.

🍓 func_detail_wall 🍓

func_detail variant that doesn't split world faces. Useful for when you want a decoration touching a floor or wall to not split the floor/wall faces (you'll get some overdraw instead.) If it completely covers up a world face, that face will get clipped away, so it's not suitable for fence textures; see func_detail_fence instead.

🍓 func_detail_fence 🍓

Similar to func_detail_wall except it's suitable for fence textures, never clips away world faces. Useful for fences, grates, etc., that are solid and block gunfire.

🔑 MODEL ENTITY KEYS 🔑

  • "_lmscale" "n" — Generates an LMSHIFT bspx lump for use by a light util. Note that both scaled and unscaled lighting will normally be used.
  • "_mirrorinside" "n" — Set to 1 to save mirrored inside faces for bmodels, so when the player view is inside the bmodel, they will still see the faces. (e.g. for func_water, or func_illusionary)

🫶 OTHER SPECIAL-PURPOSE ENTITIES 🫶

💅 func_illusionary_visblocker 💅

okay so this one is for making vis-blocking illusionary brushes — literally the same energy as func_detail_illusionary or func_illusionary, and yes, the player can walk right through them 🫶. It gives the same effect as water brushes when the -notranswater flag is used, except the interior of these brushes is saved as CONTENTS_EMPTY.

⚠️ one thing to be aware of, bestie: if the player’s view is very close to the faces of these brushes, they might be able to see into the void (depending on the engine). Fitzquake family engines have a workaround for this that is enabled if the brushes are textured with a water texture (* prefix). ✨

🌈 MAP COMPATIBILITY 🌈

In addition to standard Quake 1 .map files, ericw-tools QBSP is compatible with:

  • Floating point brush coordinates and texture alignments — decimals are invited to the party 💅
  • Valve’s 220 map format as produced by the Hammer editor 🔨
  • Extended texture positioning as supported by the QuArK editor 🧚
  • Standard Quake 2 map format (leading paths in texture names are stripped and any extra surface properties are ignored) 👑
  • Brush Primitives produce by Radiant editors (normally a Quake 3 format) — iconic, no cap 💖

👑 AUTHOR 👑

  • Eric Wasylishen
  • Kevin Shanahan (aka Tyrann) - http://disenchant.net
  • Based on source provided by id Software and Greg Lewis

😭 REPORTING BUGS 😭

Please post bug reports at https://github.com/ericwa/ericw-tools/issues. Improvements to the documentation are welcome and encouraged — fr fr, docs glow-ups are always accepted 🫶✨

  • Copyright (C) 2017 Eric Wasylishen
  • Copyright (C) 2013 Kevin Shanahan
  • Copyright (C) 1997 Greg Lewis
  • 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.

🦋 SEE ALSO 🦋

light(1) vis(1) bspinfo(1) bsputil(1) quake(6) — go read those too, bestie, the whole Unix family is iconic 💖

💖 source/version: TYRUTILS / TYR_VERSION; date: the manpage footer’s stamp; manual title: QBSP(1) — mwah, go make something slay ✨

📦 where this page comes from