Call of Duty 2: d3dbsp

The .d3dbsp structure, Call of Duty 2's variant on the well-known BSP format, is rather difficult to decipher. Since it's a binary file you can't simply read it. A hexadecimal editor is the best tool in this case.

I am still deciphering it myself, I will post anything I happen to get known of regarding the file format.

Be sure to read here and here before you even try to decipher it. Knowing what the technique is that BSP formatted maps use, could be handy as well.

Every number ending with an 'h' indicates its a number using the hexadecimal count system. For other numbers one can assume the decimal count system is used.

Numbers are stored in little-endian. The endianness describes the order in which a sequence of bytes are stored in computer memory. Little-endian is an order in which the "little end" (least significant value in the sequence) is stored first.

Header

The file starts with 2 DWORDS: the header 'IBSP' indicating this is a BSP file originally designed by ID software and the version number 4 (4h).

Then there is an array, filled with DWORD pairs, indicating the lump's offset and length respectively. The array ends with 2 empty (zero) DWORDs. Each lump that has size 0 in the list is simply not filled / not used.

 Note: there can be a difference of number of lumps per map. If a map has a leak
(no solid skybox or not everything is IN the skybox) the bsp only has 24 lumps (or even 23 if light is not
compiled). The bsp description yet only supports the 37-lumps version (a valid map).

Lumps

A BSP is organized in several sections, called lumps. Each lump stores data with different functionality. It's a data unit containing sub-sections, or better: entries. Every entry is a binary representations of something, a plane for instance. Such a plane is stored as a normal vector (3 floats) and a distance (1 float). The length of the datatype "float" is 4 byte (DWORD), so the size of one plane entry is 4 DWORDs (4*4 = 16 bytes).

Lump[0] - Textures

Texture information is 72 bytes long per texture. The first 64 bytes are used for the texture name. Then we have an DWORD for flags, and another DWORD for content flags.

struct
{
    char texture[64];
    int  [2];
};

Flags:

Surface type:
-------------
         -          - <error> (asset manager will fail)
0x00000000 0x00000001 <none>
0x01600000 0x00000001 asphalt
0x00100000 0x00000001 bark
0x00200000 0x00000001 brick
0x00300000 0x00000001 carpet
0x00400000 0x00000001 cloth
0x00500000 0x00000001 concrete
0x00600000 0x00000001 dirt
0x00700000 0x00000001 flesh
0x00800000 0x00000002 foliage
0x00900000 0x00000010 glass
0x00a00000 0x00000001 grass
0x00b00000 0x00000001 gravel
0x00c00000 0x00000001 ice
0x00d00000 0x00000001 metal
0x00e00000 0x00000001 mud
0x00f00000 0x00000001 paper
0x01000000 0x00000001 plaster
0x01100000 0x00000001 rock
0x01200000 0x00000001 sand
0x01500000 0x00000001 snow
0x01400000 0x00000020 water
0x01500000 0x00000001 wood

Surface properties:
-------------------
0x00000000 0x00000080 missileClip
0x00000000 0x00002000 bulletClip
0x00000000 0x00010000 playerClip
0x00000000 0x00000200 vehicleClip
0x00000000 0x00020000 aiClip
0x00000000 0x00000400 itemClip
0x00000000 0x00000041 canShootClip
0x00000000 0x00001000 aiSightClip
0x00000001 0x00000001 noFallDamage
0x00002000 0x00000001 noSteps
0x00000010 0x00000001 noImpact
0x00000020 0x00000001 noMarks
0x00000000 0x80000000 noDrop
0x00000002 0x00000001 slick
0x00000008 0x00000001 ladder
0x02000000 0x01000001 mantleOn
0x04000000 0x01000001 mantleOver
0x00000000 0x00000001 noLightmap
0x00020000 0x00000001 noDynamicLight
0x00040000 0x00000001 noCastShadow
0x00000080 0x00000001 noDraw
0x00000000 0x00000001 noFog
0x00000000 0x00000001 drawToggle
0x00000004 0x00000800 sky
0x00000000 0x00000001 radialNormals
0x00000000 0x00000004 nonColliding
0x00004000 0x00000000 nonSolid
0x00000000 0x20000001 transparent \__ (two entries
0x00000000 0x28000001 transparent /    added to lump)
0x00000000 0x08000001 detail
0x00000000 0x10000001 structural
0x80000000 0x00000000 portal
0x00000000 0x00000001 occluder
         -          - origin (no lump entry)

Combinations (examples):
------------------------
0x00000000 0x00002080 missleClip & bulletClip
0x00000000 0xb0000000 noDrop & transparent & structural
0x00000000 0x90000000 noDrop & structural
0x00000004 0x20000800 transparent & sky \__ (two entries
0x00000004 0x28000800 transparent & sky /    added to lump)
0x01400088 0x00000020 water & noFog & noDraw & ladder

These flags can be set in AssMan, nonetheless some Radiant functions influence them as well, e.g.

"Make Weapon Clip" on a wood-textured brush

0x01500000 0x00000001 \__ usual wood flags
0x01500000 0x00002080 /   first flag like wood, second flag missleClip & bulletClip

Note: the brush lost its collision (less planes in lump 4 etc.)

Lump[1] - World Lightning

Contains most of the pre-processed lightning. Not present if compiled without lightning, otherwise a multiple of 4.096 KB.

Without: World geometry is rendered overbright

Lump[2] - Light Volume

Precalculated (sun)light in the 3d space of the playable area, also called light grid.

Without: a lot less light influence and a little rainbow colors on entities (e.g. players)

Lump[3] - Model Lightning

Base (sun)light for model entities (xmodel)

Without: static models show up very dark

Lump[4] - Planes

Each plane is defined by 4 DWORDs, 3 for the normal vector and 1 for the offset of the origin. Planes are faces with infinite length, we suspect they have to do with the rendering system.

struct
{
    float normal[3];
    float distance;
};

Lump[5] - Brushsides

under investigation

Without: CMod_LoadBrushes: bad side count

Lump 5 and 6 are used for the collision map, however the second column seems to hold texture id's.

Two columns, first either distance or plane id:

• float distance - plane parallel to x, y or z axis
• ushort plane_id - skew plane

Example:

 0 |    -128        2
 1 |     -64        2
 2 |      64        2
 3 |     128        2
 4 |    -128        2
 5 |     -64        2
 6 |     128        0
 7 |     192        0
 8 |    -192        0
 9 |    -128        0
10 |       0        0
11 |       8        0

Second column is a texture id, texture lump:

0 | dawnville2_wartorn_brick07                                      0x00200000 0x00000001
1 | dawnville2_wood_boards01                                        0x01500000 0x00000001
2 | dawnville2_wood_boards01                                        0x01500000 0x00002080

Lump[6] - Brushes

under investigation

Without: no collision with brush geometry. Footage (Xfire)

Brushsides index, two columns (2 ushorts?)

• First column:

Amount of brushsides, start id can be calculated (sum_of_previous_amounts - 1)
For end id, add the entry value to the start id (sum_of_previous_amounts - 1 + amount_of_brushsides)

   6    2
   6    0

• Second column:

Might be texture id, perhaps one of the applied textures as default.
If more than one texture is mapped to the brush, it may get overwritten (brushsides lump texture id).

Lump[7] - Faces

It's like the missing link between the triangles (lump 9) and vertices (lump 8). It refers to both of them defining the texture per triangle, giving the offset in the vertex lump to which the numbers in lump 9 point to (ID's in lump 9 point to vertex as in: offset + ID, offset is given in this lump). Also offset in triangles lump is given.

Without: LoadMap: funny lump size in (*.d3dbsp)

Lump[8] - Vertices

Every vertex is 17 DWORDs long (98 bytes). First 3 DWORDs define the position (x y and z). Next 3 DWORDs define the normal vector of the vertex (x y and z) (WHY?!), then a DWORD which defines the colour (BGR) and the opacity (A). Then 2 DWORDs which have to do with texture shifting, and 2 more DWORDs for something yet unknown. At the end we have 6 DWORDs having to do with texture alignment (rotation?).

struct
{
    float position[3];
    int   normal[3];    
    char  bgr[3];
    char  a;
    float shift[2];
    float [2];
    float [6];
};

Lump[9] - Triangles

former Faces

A face is made up of 3 vertexes, giving a triangle.

struct
{
    int vertex_id[3];
};

Lump[22] - unknown

Without: game crashes with application error

Lump[23] - Bounding Boxes?

Assumed to be the Skybox.

Lump[25] - Nodes

Without: Map has no Nodes

Lump[26] - Leafs

Without: Map has no Leafs

Lump[29] - unknown

Without: no visible changes, might be sort of leaftree / bsp whatnot

Lump[30] - Player Terrain Collision?

Without: terrain retains collision, but player can't move smoothly on the ground. It's easy to get stuck or float around. Still okay where terrain is very even. Footage (Xfire)

Lump[31] - unknown

Without: game crashes with application error

Lump[32] - unknown

Without: no visible changes, bsp ?

Lump[33] - unknown

Without: game crashes with application error

Lump[34] - unknown

Without: game crashes with application error

Lump[35] - unknown

Without: Map with no models

Possibly "rigid groups of world geometry": Quake3 - Model Lump

Lump[36] - VIS

Present if VIS (portalling) has been calculated during the compile process.

Without: /r_singlecell 1 still shows the portals, forced VIS?

Lump[37] - Entities

The entities lump is readable and stored (almost) the same way described in the .MAP file structure.

Couple entity types in this lump got a "model" key/value pair with a star and a number (*n), causing Radiant to crash and the compiler to ignore the whole block. You also have to remove certain other things as long as the necessary data has been decompiled as well:

• model *n
• fx
• script_exploder
• trigger
• gndLt (optional, ignored by Radiant)

Furthermore, you need to recreate the skybox, as there will likely be leaks in the ground caused from caulk/clip/... textured geometry. It's not visible in game as you know and therefore not stored in the usual lumps for vertices, triangles and so on. But it has collision, and the collision data is either stored in the brush or terrain collmap lumps. Note that many models are clipped using invisible textures as well. If no collmap file is present for a model, create one or it will lack collision after compile. A decompiler would have to reconstruct the collision map to avoid this.

struct
{
    char entities[];
};

Web Links

• Binary Space Partitioning
• BSP Format
• BSP (File Extension)
• BSP for Dummies
• Unofficial Quake3 Map Specs
• Quake Documentation v3.4
• Quake 2 BSP File Format
• Call of Duty 2: Map File Format
• Understanding Vis and Hint Brushes (Portalling)
• Quake BSP Renderer
• Quake Glossary
• Endianness

Made by CoDEmanX and Daevius