View source for BSPX

{{goldsrc topicon}}{{Quake topicon}}{{quake2 topicon}}{{quake3 topicon}}
{{non-valve engine|engine|Some information is only relevant for Id Tech, but BSPX as a whole is useful for GoldSrc mods using custom renderers. All known information related to BSPX is presented to be thorough, as custom renderers aren't limited to BSP30.}}
'''BSPX''' is a standard for adding new lumps to {{Idtech2|4.1}}, {{idtech3|4.1}}, and {{goldsrc|4.1}} [[BSP]] files, which are used to add additional features to be used by source ports or [[custom renderer]]s without breaking vanilla compatibility. As BSPX lumps are placed at the end of the BSP file, they are not loaded by vanilla engines, so a BSP with BSPX lumps is backwards compatible.
== Structure ==
<source lang=c>
typedef struct {
	char lumpname[24]; // up to 23 chars, zero-padded
	int fileofs;  // from file start
	int filelen;
} bspx_lump_t;
typedef struct {
	char id[4];  // 'BSPX'
	int numlumps;
	bspx_lump_t lumps[1];
} bspx_header_t;
</source>

== Lumps ==
{{todo|More info; see {{fte|2}} and [[Ericw-tools]] source codes}}
=== <tt>DECOUPLED_LM</tt> === 
"Decouples" [[lightmap (GoldSrc)|lightmap]] scale, alignment, and rotation from those of [[texel]]s.

Compile with [[ericw-tools]] using {{code|_world_units_per_luxel}} KV in [[worldspawn]] or {{code|-world_units_per_luxel #}} in QBSP, wherein # is the luxel scale (like in {{hammer4|2|addtext='s}} [[Hammer Face Edit Dialog|face edit window]]).

The 2023 {{quake2|4.1}} remaster uses {{mono|DECOUPLED_LM}} with a luxel scale of 8 on all maps except for the Quake II 64 maps.

Unnecessary and possibly incompatible with Quake III's BSP format and derivatives, which store lightmaps as pages in the BSP file (or externally) instead of paginating at load time, and has no direct correlation between texel size and luxel size. Q3Map2 and some games support {{code|-lightmapsize}} switch to use external TGA lightmaps, but for vanilla Quake III, use the {{code|q3map2_lightmapsize}} parameter in the given material; see [http://sgq3-mapping.blogspot.com/2009/01/using-hi-resolution-external-lightmap.html explanation].

=== <tt>LIGHTGRID_OCTREE</tt> ===
An {{w|octree}}-formatted 3D grid of RGB888 color values{{confirm}}, used by dynamically lit models instead of being lit based upon the nearest (worldswawn) lightmap luxel or light_environment entity. 

This is used by all non-N64 maps in the 2023 {{quake2|4.1}} remaster. 
{{important|Does not store any directionality; consider implementing a variant that stores 6 values per point (like Source's [[ambient cube]]s) or stores an additional vector indicating direction (like GoldSrc's light_environment).}}
Unnecessary with Quake III's BSP format and derivatives, which already contain lightgrids.

=== <tt>LIGHTING_E5BGR9</tt> ===
Used for [[HDR]] [[lightmaps]]. Functions similarly to the [[BSP_(Source)#Lighting|RGBE8 lightmaps]] in {{src|2}}, but with an additional bit of precision per color instead of having the exponent be 8 bits.

Behavior may be inconsistent between different compilers and renderers when used in conjunction with DECOUPLED_LM.

=== <tt>ENVMAP</tt> ===
Defines where cubemaps are found (does not store the cubemaps themselves). Can be generated (alongside <tt>SURFENVMAP</tt>) from {{code|env_cubemap}} entities by loading the BSP in {{fte|4.1}} and running the {{code|mod_findcubemaps}} console command. 

The following FGD entry represents the expected syntax (note that it is different from {{src}}'s {{ent|env_cubemap}} syntax):
<source lang=c>
@PointClass color(0 0 255) iconsprite("sprites/editor/env_cubemap.spr") = env_cubemap : 
	"An entity that creates a sample point for the Cubic Environment Map."
[
	size(choices) : "Cubemap Size" : 0 : "Resolution of the cubemap." =
	[
		0   : "Default"
		1   : "1x1"
		2   : "2x2"
		4   : "4x4"
		8   : "8x8"
		16  : "16x16"
		32  : "32x32"
		64  : "64x64"
		128 : "128x128"
		256 : "256x256"
	]
]
</source>
In the compiled lump, each envmap reference is stored much the same way:
<source lang=c>
struct
{
	vec3_t origin;
	int cubesize;
} envmaps[];
</source>

=== <tt>SURFENVMAP</tt> ===
Used alongside <tt>ENVMAP</tt> lump to store what cubemap index each brush surface should use.
Pretty simple:
<source lang=c>
struct
{
	unsigned int envmapindex;
} persurface[];
</source>

=== <tt>BRUSHLIST</tt> ===
Store actual brush information for collision, like {{quake2|4.1}}, {{quake3|4.1}}, and {{src|4.1}}, allowing for arbitrary hull sizes. This also bypasses max clipnode limits without requiring an upgraded format such as [[BSP2]].

Struct for each [[bmodel]] is like so:
<source lang=c>
struct {
	unsigned int ver = 1;
	unsigned int modelnum;		//inline model number. 0 for world, obviously.
	unsigned int numbrushes;	//size of following array.
	unsigned int numplanes;		//total count. for validation.
	struct
	{
		vec_t mins;
		vec_t maxs;
		signed short contents;
		unsigned short numplanes;
		{
			vec3_t 	normal;
			float 	dist;
		} planes[numplanes];
	} brush[numbrushes];
} permodel[];
</source>
Contents are stored as a signed short, matching the existing [[BSP flags (Quake and GoldSrc)#Contents types|runtime contents values]]. Axial planes are not stored, but rather inferred based upon their normal, distance, and the brush's mins and maxs.


Only practical for clipnode-based formats like [[BSP29]], [[BSP30]], and [[BSP2]] ([[BSP38]] and derivatives store this information already).

=== <tt>ZIP_PAKFILE</tt> ===
A [[ZIP]] file, used like {{Src}} [[BSP (Source)#Pakfile|BSP's pakfile lump]]. For best compatibility, should be {{w|Deflate}} or uncompressed, and should be the last lump in the BSP.

The name of this lump is theoretical; the only {{idtech2|2}} source port which supports zip files embedded in the BSP is {{fte|2}}, which just looks for concatenated zip files, regardless of if they are formatted as a proper lump.

=== <tt>RGBLIGHTING</tt> ===
Equivalent to the 24-bit lightmap lump from a [[BSP30]]. Used as an alternative for external [[LIT]] files when using [[BSP29]] or monochromatic [[BSP2]], while maintaining a 8-bit monochromatic fallback for {{quake|1}} engines that don't support this lump.

Only practical for {{quake|2}} and {{hexen2|2}} engines; {{goldsrc|2}}, {{quake2|2}}, and {{Quake3|2}} map files store 24-bit true color lightmaps already.

=== <tt>VERTEXNORMALS</tt> ===
Stores [[vertex normal]] data for brushes, necessary for accurate [[smoothing]] when using real-time light sources instead of prebaked lightmaps. Surfaces that are shaded smooth should have the surface flag 0x00000800 set in their texinfo entry; surfaces without that flag are flat-shaded.

=== <tt>FACENORMALS</tt> ===
Used by ericw-tools instead of the VERTEXNORMALS lump.
{{todo|How does it work? Does it work for the same purpose, or is it less precise?}}

=== <tt>LIGHTINGDIR</tt> ===
"Deluxemaps", designed for use with [[normal map]]ped surfaces that have lightmaps. Effectively a normal map which is stored like the lightmaps. 
{{warning|This can "result in some ugliness if there's shadows"{{sic}}, to quote lead FTE dev Spike. If creating your own lightmap compilers, consider taking a page out of Source's book, and create a derivative of the DECOUPLED_LM lump containing separate lightmaps for each of the three [[normal]] directions.}}

Behavior may be inconsistent between different compilers and renderers when used in conjunction with DECOUPLED_LM.

=== <tt>LMSTYLE16</tt> ===
Upgrade to the deprecated LMSTYLE lump, supporting up to 65k lightstyles. The number of styles per-face is variable (inferred via lump size vs surface count). These two changes make it suitable to be used even without LMSHIFT.

== Deprecated Lumps ==
These BSPX lumps have been deprecated by newer BSPX lumps. 

=== <tt>LMSHIFT</tt> ===
{{modernDeprecated|Deprecated by {{mono|DECOUPLED_LM}}.}}

Defines lightmap scale for each surface. Renderers supporting this lump must support 256x256 (really 255x255) lightmaps, instead of only the usual 16x16 (really 15x15).

Unnecessary and possibly incompatible with Quake III BSPs and derivatives.

=== <tt>LMOFFSET</tt> ===
{{modernDeprecated|Deprecated by {{mono|DECOUPLED_LM}}.}}

Required when using LMSHIFT to maintain compatibility with engines/renderers that do not support LMSHIFT.

=== <tt>LMSTYLE</tt> ===
{{modernDeprecated|Deprecated by {{mono|LMSTYLE16}}.}}
Stores the 4 lightstyle indices for each surface; only makes sense when used in conjunction with LMSHIFT.

== External links ==
* [https://github.com/fte-team/fteqw/blob/1f9f3635f0aef3b2eed6b40e35fcf6223c6ad533/specs/bspx.txt BSPX spec] in {{fte|2}} repo

[[Category:GoldSrc Technical]]