EWTOOLS-QBSP(1)

📦 version 2.0.0~alpha11, in ubuntu stonking

✨ NAME ✨

ewtools-qbsp — compile a Quake BSP file from a MAP source file 💖

And it also goes by qbsp, same energy, same job, bestie 🫶

💫 SYNOPSIS 💫

qbsp [OPTION]... SOURCFILE [DESTFILE]

(okay yes, it says SOURCFILE up there and SOURCEFILE down below — that's literally what the page says, no I will not be fixing it, it's iconic 💅)

🌈 DESCRIPTION 🌈

So qbsp is one of the tools you use to make maps for Quake, the id Software game, and honestly? She's the backbone of the whole operation 😤

You hand her a .map file as input and she hands you back a .bsp file that the Quake engine can actually play. That's the whole vibe check.

And if you don't give her a DESTFILE argument? No stress — she picks the output filename herself by taking the file extension (if there even is one 💀) off the SOURCEFILE and slapping .bsp on the end. Auto-naming queen behavior 👑✨

👑 OPTIONS 👑

okay so here's the whole menu, buckle up bestie, it's a long one 🍓

  • -nofill — doesn't perform outside filling. we're skipping that step entirely ✋
  • -filltype auto | inside | outside — how do we fill this map? from the outside in (that's the lenient one 🫶), from the inside out (that's the aggressive one 😤), or auto and let her decide for herself based on the hull being used.
  • -filldetail [n] — do we fill enclosed pockets of empty space that are surrounded by solid detail? Default is 1 (enabled). so, yes, by default 💅
  • -nomerge — don't do face merging. just... don't 🚫
  • -noedgereuse — don't reuse edges. the page notes this may be useful for debugging software rendering 👀
  • -noclip — doesn't build clip hulls. and heads up, this is only applicable for Q1-like BSP formats.
  • -noskip — doesn't remove faces that use the skip texture 🫣
  • -nodetail — treat all detail brushes as structural. no special treatment for anybody 😌
  • -onlyents — only updates .map entities. that's it, that's the whole job.
  • -verbose ✨
  • -v — print out more .map information 👀
Not me having to tell you this: this switch no longer implies -loghulls. if you want those collision hull statistics you gotta use that one yourself, fr fr.
  • -loghulls — print log output for collision hulls 🪵
  • -logbmodels — print log output for bmodels 🪵
  • -quiet 🤫
  • -noverbose — suppress non-important messages. this is equivalent to -nopercent -nostat -noprogress, so it's a two-for-one situation 🎀
  • -log — write log files. Enabled by default, so you're already doing this bestie 💖
  • -nolog — don't write log files. opting out, valid 💅
  • -chop — adjust brushes to remove intersections if possible. Enabled by default.
  • -nochop — do not chop intersecting brushes. we're leaving them be 😤
  • -chopfragment — always do full fragmentation for chop. go big or go home 🔥
  • -splitsky — doesn't combine sky faces into one large face. one sky, but make it many 🌈
  • -splitspecial — doesn't combine sky and water faces into one large face. the reason you'd want this? it allows for statically lit water 💧
  • -litwater 💧
  • -splitturb — enable lit liquids. this gives you statically lit water in compatible source ports, which still works but renders as fullbright on source ports that don't support it. the only downside is that water faces get split up more, as per -subdivide. Enabled by default ✨
  • -transwater — in Q1 mode, compiles maps for transparent water (lets vis see through liquids 👀). Enabled by default. has no effect in Q2 mode, because in Q2 this is controlled by the mapper, not by us 💅
  • -notranswater — computes portal information for opaque water. no see-through here 🚫
  • -oldaxis — use the original QBSP texture alignment algorithm. Enabled by default.
  • -nooldaxis — use the 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 — force use of the expensive processing for the SolidBSP stage. often results in a more optimal BSP file in terms of file size, at the expense of extra processing time. beauty is pain, and it's also slow 😭
  • -leaktest — makes it a compile error if a leak is detected. no leaky maps on this watch 💀
  • -nopercent — prevents output of percent completion information. you don't need to know how far along we are 🫣
  • -nostat — don't output statistic messages 📊
  • -noprogress — don't output progress messages 🚫
  • -nocolor — don't output ANSI color codes, for when the terminal doesn't recognize colors (e.g. TB). tragic, but understood 💔
  • -q2bsp — target Quake II and the vanilla Q2BSP format, automatically switching to Qbism format if necessary (unless -noallowupgrade is specified). she'll upgrade herself, respectfully 👑
  • -qbism — target Quake II and use Qbism's extended Quake II BSP format 💖
  • -q2rtx — adjust settings to best support Q2RTX. glow-up for the ray tracing girlies ✨
  • -hexen2 — generate a hexen2 bsp. this can be used in addition to -bsp2 to avoid clipnode issues 🧚
  • -bsp2 — create the output BSP file in BSP2 format. this 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).
Deprecated since version 1.0: Use -bsp2 instead. she's retired bestie, let her rest 🙈
  • -allowupgrade — allow formats to "upgrade" to compatible extended formats when a limit is exceeded (e.g. Quake BSP to BSP2, or Quake 2 BSP to Qbism BSP). Enabled by default. glow-up privileges granted 👑
  • -noallowupgrade — opt out of -allowupgrade. no glow-up for you 🚫
  • -hlbsp — create the output BSP file in Half-Life's format. note that the hull size differences prevent this from being generally usable for the vanilla quake gamecode. and this cannot be used in combination with the -bsp2 argument ⚠️
  • -add [mapfile] — the given map file will be appended to the base map. bringing a friend along 🫶
  • -leakdist [n] — space between leakfile points. default 0, which does not write any inbetween points 🕳️
  • -subdivide [n] — use different texture subdivision. default is 240. heads up: lower values will harm framerates. higher values may not be supported. DP+FTEQW+QSS support up to 4080 (unless lightmap scaling is in use), but such values will cause other engines to crash-to-console 💀. use 0 to specify no subdivision.
  • -nosubdivide — disable subdivision. requires a compatible source port. see also -subdivide 👀
  • -lmscale n — change global lmscale (force _lmscale key on all entities). outputs the LMSCALE BSPX lump 📏
  • -software — change settings to allow for (or make adjustments to optimize for the lack of) software support 🖥️
  • -nosoftware — explicitly drop support for software renderers. no software girlies allowed 😤
  • -wadpath <dir> — search this directory for wad files, and the default is cwd. multiple -wadpath args may be used 🫶. this argument is ignored for wads specified using an absolute path.
  • -xwadpath <dir> — like -wadpath, except textures found using the specified path will NOT be embedded into the bsp (equivalent to -notex, but only for textures from specific wads). you should use this for wads like halflife's standard wad files, but q1bsps require an engine extension and players are not nearly as likely to have the same wad version. it's giving compatibility anxiety 😭
  • -path "/path/to/folder" <multiple allowed> — additional paths or archives to add to the search path, mostly for loose files 🗂️
  • -defaultpaths — whether the compiler should attempt to automatically derive game/base paths for games that support it. Enabled by default ✨
  • -nodefaultpaths — opt out of -defaultpaths 🚫
  • -oldrottex — use the old method of texturing rotate_ brushes, where the mapper aligns textures for the object at (0 0 0) 🔄
  • -midsplitsurffraction n — if 0 (the default), use -maxnodesize for deciding when to switch to the midsplit bsp heuristic.

if 0 < midsplitSurfFraction <= 1, switch to midsplit if the node contains more than this fraction of the model's total surfaces. try 0.15 to 0.5. works better than maxNodeSize for maps with a 3D skybox (e.g. +-128K unit maps) 🌌

  • -midsplitbrushfraction n — switch to the cheaper BSP partitioning test if a node contains this % of brushes in the map 🖌️
  • -maxnodesize [n] — switch to the cheap spatial subdivion 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 1024, 0 to disable)
  • -wrbrushes 🖌️
  • -bspx — includes a list of brushes for brush-based collision. this allows for arbitrary collision sizes in engines that support it, currently only FTEQW 👑
  • -wrbrushesonly 🖌️
  • -bspxonly — -wrbrushes combined with the -noclip argument. this is NOT backwards compatible 💀
  • -bmodelcontents — allow bmodels to have contents other than "solid" in Q1 based games, e.g. water in a func_door 💧. this is supported in FTEQW; in winquake, the bmodel will have no collision 😭

Q2 supports this feature natively and this option has no effect.

  • -notriggermodels — for supported game code only: triggers will not write a model out, and will instead just write out their mins/maxs 📐
  • -notex — write only placeholder textures, to depend upon replacements. this avoids inclusion of third-party copyrighted images inside your maps, but is not backwards compatible — it will work in FTEQW and QSS though 💅

note that the textures still need to be available to qbsp 👀

technical details: LUMP_TEXTURES is still written, but each texture within is the dmiptex_t header only (with no texture data following), with offsets all set to 0.

this only has effect in Q1 family games 🎀

  • -missing_textures_as_zero_size — writes missing textures (i.e. ones that qbsp can't find) as 0x0 placeholders 🫣

this is not backwards compatible and will produce .bsp's that crash unsupporting engines. however, it can be useful when you want to run qbsp + light on a map that you are missing the corresponding .wad for.

this only has effect in Q1 family games 🎀

  • -notjunc — alias for -tjunc none 💅
  • -tjunc mwt | none | retopologize | rotate — T-junction fix level, pick your fighter:
    • none — don't attempt to fix T-junctions. this is only for engines or formats that prefer micro-cracks over degenerate triangles. if you don't know what that means, don't set this 🫣
    • rotate — allow faces' vertices to be rotated to prevent zero-area triangles 🔄
    • retopologize — if a face still has zero-area triangles, allow it to be re-topologized by splitting it into multiple fans 🌀
    • mwt — attempt to triangulate faces (along with their T-junction fixes) using a MWT (https://en.wikipedia.org/wiki/Minimum-weight_triangulation) first, only falling back to the prior two steps if it fails 🧠
  • -noextendedsurfflags — bestie, this one straight up refuses to write the .texinfo file, even in the situations where it would normally be needed. it's a debug flag, so like, use it when you're poking at stuff 🙈
  • -omitdetail — detail brushes get entirely left out of the compile. gone. not invited. ghosted 💀
  • -omitdetailwall — same energy, but specifically func_detail_wall brushes get omitted from the compile.
  • -omitdetailillusionary — func_detail_illusionary brushes get omitted from the compile. bye bb 🦋
  • -omitdetailfence — func_detail_fence brushes get omitted from the compile.
  • -convert <fmt> — convert a .MAP into a different .MAP format. the fmt you can pass is:
    • quake — Q1 vanilla map format ✨
    • quake2 — Q2 vanilla map format ✨
    • valve — Valve 220 map format ✨
    • bp — Brush Primitives format ✨
real talk: converting to quake or quake2 might not be able to match the texture alignment from the source map, so like… it can come out a little unaligned, ngl. every other conversion is lossless, so those are the safe ones 💖

the converted map gets saved to <source map name>-<fmt>.map, so no, it does not overwrite your original, you're fine.

  • -includeskip — this one actually emits skip/nodraw faces into the output (the default behaviour is to discard them, so this is the opposite vibe). mainly a Q2RTX thing 👑
  • -threads n — set how many threads to use. by default, qbsp will just attempt to use all available hardware threads, because she's greedy like that 💅
  • -lowpriority — run at a lower priority so there's headroom left for your other processes. this is enabled by default, so she's already being polite to your system 🫶
  • -aliasdef <aliases.def> [...] — adds alias definition files, which can transform entities in the .map into other entities. it's giving remix energy ✨

so like, say your alias definition file (aliases.def) looks like this:

misc_torch1 // source classname
{
"classname" "misc_model" // classname to transform into
"model" "torch1.mdl"
}

misc_torch2
{
"classname" "misc_model"
"model" "torch2.mdl"
}

and your input map file looks like this:

{
"classname" "misc_torch1"
"model" "override.mdl"
}

{
"classname" "misc_torch2"
}

then the following gets output in the .bsp's entity lump:

{
"classname" "misc_model"
"model" "override.mdl" // key/value from map takes precedence
}

{
"classname" "misc_model"
"model" "torch2.mdl" // key/value from alias file
}

notice how the key/value from the map takes precedence over the alias file? that's the whole plot twist 😭

  • -texturedefs "path/to/file.def" <multiple allowed> — path to a texture definition file, which can transform textures in the .map into other textures. and yes, you can pass more than one, multiple allowed, she's flexible 🌈
  • -epsilon n — customize the epsilon value used for point-on-plane checks. tiny number, big consequences, iykyk ⭐
  • -microvolume n — sets the microbrush volume.
  • -outsidedebug — writes a .map after outside filling, showing you the non-visible brush sides. for when you wanna see what's under the hood 🔍
  • -debugchop — writes a .map after ChopBrushes.
  • -debugleak — writes more diagnostic files specifically for debugging leaks. leak girlies this one's for you 😭
  • -debugbspbrushes — saves bsp brushes after BrushBSP to a .map, so you can visualize the BSP splits.
  • -debugleafvolumes — saves bsp leaf volumes after BrushBSP to a .map, so you can visualize the BSP splits. sibling behaviour with the flag above 💅
  • -debugexpand [single hull index] or [mins_x mins_y mins_z maxs_x maxs_y maxs_z] — writes an expanded hull .map for debugging/inspecting hulls and brush bevelling. you can hand it either a single hull index or a full set of mins/maxs values, pick your fighter 🌸
  • -keepprt — avoids deleting the .prt file on leaking maps. she's not throwing away your evidence 🎀
  • -maxedges n — the max number of edges/vertices allowed on a single face before it gets split into another face. 0 means unlimited.
default is 0 for Q2, and 64 for Q1. different defaults, different games, don't @ me ✨
  • -worldextent n — explicitly provide world extents; 0 will auto-detect. default is 0.
  • -forceprt1 — force a PRT1 output file even if PRT2 is actually required for vis. gonna do it anyway 💅
  • -objexport — export the map file as .OBJ models during the various compilation phases. cute lil export bestie 🎀

🌈 GAME PATH SPECIFICATION 🌈

okay so, real talk: to compile a Q2 map, the compilers usually need to be able to find an installation of the game. like, the .map might reference a texture name like e1u1/clip, but qbsp needs to open the corresponding .wal file to look up the content/surface flags (playerclip, etc.) which then get written to the .bsp. she needs to read the receipts 🧚

we use this terminology:

  • basedir — the directory containing the base game (e.g. id1 or baseq2). can be an absolute path, e.g. c:/quake2/baseq2 or c:/quake/id1.
  • gamedir — optional mod directory, e.g. ad or c:/quake/ad. if a gamedir is specified, it will be added to the search path at a higher priority than the basedir 👑

the common cases are:

  • place your .map in <quake2>/baseq2/maps and compile it there — qbsp will auto-detect the basedir/gamedir for you. iconic, no notes 💖
  • for compiling a .map that lives somewhere else, use e.g.:
qbsp -basedir "c:/quake2/baseq2" input.map

or

qbsp -basedir "c:/quake2/baseq2" -gamedir mymod input.map
  • -gamedir "relative/path" or "C:/absolute/path" — override the default mod base directory. if this is not set, or if it is relative, it will be derived from the input file or the basedir if specified.
  • -basedir "relative/path" or "C:/absolute/path" — override the default game base directory. if this is not set, or if it is relative, it will be derived from the input file or the gamedir if specified.
  • -filepriority archive | loose — which types of archives (folders/loose files or packed archives) are higher priority and chosen first for path searching. pick a lane, bestie 🦋

💖 SPECIAL TEXTURE NAMES 💖

the contents inside a brush depend on the texture name(s) you slap onto it. so like, the texture name is the personality of the brush, and it decides the behaviour 💅

by default, brush contents are solid unless they have a special name. 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 — so no chaotic half-water-half-solid brushes, she will catch you 😭

  • *slime
  • *lava
  • * — in all Q1-like games, 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. literally just vibes and asterisks ✨
  • 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. stealth mode activated 👻
  • 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 — so 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 move 🧠

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 — no third options allowed periodt 💅

  • origin — an origin brush (all faces textured with "origin") can be added to a brush entity (but not detail or compiler-internal entities like func_group). doing so causes all of the brushes in the brush entity to be translated so the center of the origin brush lines up with 0 0 0. the entity key "origin" is then automatically set on the brush entity to the original coordinates of the center of the "origin" brush before it was translated to 0 0 0. ✨

in Hexen 2, origin brushes are the native way of marking the center point of the rotation axis for rotating entities.

in Quake, origin brushes can be used to make some map hacks easier to set up that would otherwise require placing brushes at the world origin and entering an "origin" value by hand.

note that, unlike the Hipnotic rotation support in QBSP, using origin brushes does not cause the model bounds to be expanded. (with Hipnotic rotation this was to ensure that the model is not vis culled, regardless of its rotated angle.) origin brushes are useful for more than just rotation, and doing this bounds expansion would break some use cases, so if you're going to rotate a model with an origin brush you might need to expand the bounds of it a bit using clip brushes so it doesn't get vis culled. 🫶

🦋 Half-Life BSP Specific 🦋

if -hlbsp is in use, the following extra texture prefixes are recognized:

  • !slime
  • !lava
  • ! — these act the same as names beginning with * and create liquids.
  • !cur_0
  • !cur_90
  • !cur_180
  • !cur_270
  • !cur_up
  • !cur_dwn — these prefixes generate water with the given current direction:
    • CONTENTS_CURRENT_0 — -9
    • CONTENTS_CURRENT_90 — -10
    • CONTENTS_CURRENT_180 — -11
    • CONTENTS_CURRENT_270 — -12
    • CONTENTS_CURRENT_UP — -13
    • CONTENTS_CURRENT_DOWN — -14

during the BSP process, they act like water with extra modifier flags. 🌊

Note: different from the vanilla HL compiler, we don't generate faces between different CONTENTS_CURRENT_* textured volumes.

✨ EXTERNAL MAP PREFAB SUPPORT 🎀

So this qbsp? It has a whole prefab system, and it runs on a point entity named misc_external_map. The vibe is: every misc_external_map yanks brushes in from an external .map file, slaps on whatever rotations you gave it in the _external_map_angles key, then translates the whole thing over to the origin key of the misc_external_map entity. And then — plot twist — the classname of the misc_external_map gets switched to whatever the mapper put in the _external_map_classname key. (Oh and the origin key gets cleared to 0 0 0 before the .bsp is saved, so it's not still squatting there.)

Your external .map file should contain worldspawn brushes only — though for editing convenience you're allowed to use func_group. Brush entities get merged with the worldspawn brushes during the import 🫶. All worldspawn keys and any point entities? Ignored, sorry bestie. And rn that means the wad key is not handled, so any texture wads the external .map needs? You have to add them to your main map yourself. No cap.

Also lowkey important: you can set other entity keys on the misc_external_map to configure what the final entity ends up being. Like, if you set _external_map_classname to func_door, you can also set a targetname key on the misc_external_map, or literally any other keys that func_door takes. Iconic.

  • _external_map — Names the filename of the .map you wanna import.
  • _external_map_classname — What entity you want that external map to turn into. Internal qbsp entity types like func_detail work, or a regular bmodel classname like "func_wall" or "func_door".
  • _external_map_angles — Rotation for the prefab, in "pitch yaw roll" format. Assume the external map is facing the +X axis, and positive pitch is down. Yaw of 180, for example, would rotate it to face -X. 👑
  • _external_map_angle — The short version of _external_map_angles, for when you just want to specify a yaw rotation.
  • _external_map_scale — Scale factor for the prefab, defaults to 1. Either hand it 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. And the big one: they don't seal the map. (Previous versions did. We don't talk about previous versions.)

So to stay compatible with existing Quake 1 mapping tools, you add detail brushes by making an entity with classname "func_detail". When qbsp reads the map file, it takes any brushes inside a func_detail entity, shoves them into the worldspawn as details, and deletes the func_detail entity. You can use any number of func_detail entities (useful for grouping, fr fr) and all the brushes inside them get added to the worldspawn.

Here's an example entity definition, suitable for adding 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, iykyk):

@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 actually goes in the .map file is just a plain entity with one or more brushes. Like this:

{
"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
}
}

And here's the thing bestie 👀 — when qbsp detects detail brushes, it outputs a modified portal file format with the header PRT2 (the default is PRT1). That portal file carries extra info that vis needs to compute the potentially visible set (PVS) for the map/bsp. So you're also gonna need a vis util that can handle the PRT2 file format. Otherwise it's giving… nothing.

💅 COMPILER-INTERNAL BMODELS 💅

  • func_group — A bmodel that has literally no effect; qbsp just moves the brushes back into the worldspawn entity. The usefulness comes from the ability to set Model Entity Keys on the brushes inside the func_group. Slay.
  • func_detail — Solid detail. Can't be seen inside, splits world faces. Doesn't seal map.
  • func_detail_illusionary — A func_detail variant with no collision (players / monsters / gunfire) and it doesn't split world faces. Doesn't cast shadows unless enabled with _shadow <#bmodel-key-_shadow> "1". Useful for hanging vines 🍓. It still creates BSP leafs, which is unavoidable without a new .bsp file format, so that's just the deal. Intersecting func_detail_illusionary brushes don't clip each other; this is intended to make trees/shrubs/foliage easier with _mirrorinside "1". 🌈
  • func_detail_wall — A func_detail variant that doesn't split world faces. Useful when you want a decoration touching a floor or wall to not split the floor/wall faces (you'll get some overdraw instead, oops). 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. Intersecting func_detail_wall brushes don't clip each other.
  • func_detail_fence — Similar to func_detail_wall, except it's suitable for fence textures and it never clips away world faces. Useful for fences, grates, etc., that are solid and block gunfire. Intersecting func_detail_fence brushes don't clip each other.

🦋 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.

Todo

This is broken since 2.0.0-alpha1. 😭

  • "_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, func_illusionary, func_detail_illusionary, func_detail_fence, etc.) 💖
  • "_chop_order" "n" — Override the order of brushes in the map file, which affects which face "wins" in the CSG phase when there are multiple overlapping coplanar brushes. It's provided since most .map editors don't directly expose the brush order. All brushes are initially 0; setting this to 1 would make a brush appear after anything in the map file, and so clip away coplanar faces from other brushes. For example, you could make a func_group with "_chop_order" "1", and apply it to a light fixture which is coplanar with a floor or ceiling, to ensure the light fixture is visible in-game, without going to the trouble of cutting a hole in the floor/ceiling for it. Main character energy fr fr.
  • "_hulls" "n" — Bitmap ("Flags" type in FGD) that selects for which hulls collision data will be generated. eg. a decimal value of 11 (0b1011) would generate hull 0, hull 1, and hull 3. Faces are computed using data from hull 0, not generating this hull will prevent a bmodel from being rendered, acting as a CLIP brush only active for the specified hulls. Defaults to 0 which will generate clipnodes for all hulls.
  • "_chop" "n" — Set to 0 to prevent these brushes from being chopped; this is an alias for setting _chop_order to 1.
Deprecated since version 2.0.0: Prefer the more flexible _chop_order instead.
  • "_noclipfaces" "n" — Set to 1 to suppress the usual qbsp behaviour where two touching brushes of the same content type will have the touching portion clipped away. This is useful for things that can be seen inside, such as func_detail_illusionary, func_detail_fence, liquids, bmodels, etc. Behaviour is unspecified for coplanar faces; in 0.18 it caused z-fighting, and in 2.0.0-alpha it doesn't currently. 💀

👑 OTHER SPECIAL-PURPOSE ENTITIES 👑

  • func_illusionary_visblocker — For creating vis-blocking illusionary brushes (similar to func_detail_illusionary or "func_illusionary". The player can walk through them.) This gives the same effect as water brushes when the -notranswater flag is used, except the interior of these brushes are saved as CONTENTS_EMPTY. One thing to be aware of: 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 🌈

Besides standard Quake 1 .map files, ericw-tools QBSP is compatible with:

  • Floating point brush coordinates and texture alignments
  • 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)

🗂️ METADATA FORMATS 🗂️

🧊 .wal_json

okay so for Q2 mapping, .wal textures carry metadata that says what the texture's content flags are, what its surface flags are, and its "value" — and all of that gets used only if the mapper doesn't override it in the .map file. like, imagine a lava texture lowkey defaulting to emitting light, having a lava content type, and having a surface warp effect. iconic defaults, honestly. 💅

the final values get baked right into the .bsp, so the game engine literally doesn't need the metadata for anything. it's giving "one and done."

but for ✨increased flexibility✨ we support a JSON metadata format — and it can either override the .wal's metadata, or supply metadata entirely on its own when you're using an image format like .tga instead of .wal.

to use a .wal_json file, drop it in the same directory where the .wal would live. so for example, baseq2/textures/e1u1/water.wal_json would correspond to:

baseq2/textures/e1u1/water.png

🫶 and bestie — all of the values are optional. every single one.

{
    // valid instances of "contents"; either:
    // - a case-insensitive string containing the textual representation
    //   of the content type
    // - a number
    // - an array of the two above, which will be OR'd together
    "contents": [ "SOLID", 8 ],
    "contents": 24,
    "contents": "SOLID",

    // valid instances of "flags"; either:
    // - a case-insensitive string containing the textual representation
    //   of the surface flags
    // - a number
    // - an array of the two above, which will be OR'd together
    "flags": [ "SKY", 16 ],
    "flags": 24,
    "flags": "SKY",

    // "value" must be an integer
    "value": 1234,

    // "animation" must be the name of the next texture in
    // the chain.
    "animation": "e1u1/comp2",

    // width/height are allowed to be supplied in order to
    // have the editor treat the surface as if its dimensions
    // are these rather than the ones pulled in from the image
    // itself. they must be integers.
    "width": 64,
    "height": 64,

    // color to use for lighting bounces. if specified, this
    // is used instead of averaging the pixels of the image.
    "color": [255, 128, 64]
}

👑 AUTHOR 👑

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

🐛 REPORTING BUGS 🐛

bestie if something's cursed, please post bug reports at https://github.com/ericwa/ericw-tools/issues.

and improvements to the documentation are welcome and encouraged — like actually, we want them, no cap. 📝💖

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.

fr fr, "no warranty" is not a vibe — it's a legal fact. respect it. 🙏

and that's a wrap on the whole page, bestie 🎀 this edition of EWTOOLS-QBSP(1) is from Jul 29, 2026, and it's the source/version date you'd normally spot in the footer. go forth and compile something gorgeous 💖✨🦋

📦 where this page comes from