Cidb

2026-10-04T16:16:30Z

Adoky: initial cidb information

'''CIDB''' is the collision-data container embedded in many Link's Awakening room-model '''BFRES''' files. It stores one or more triangle meshes, each with raw per-triangle surface IDs and a serialized PhysX R-tree used for broad-phase collision queries.

This page documents the current state of reverse engineering, not an official specification. Fields are labelled **verified** only where they have been decoded from the retail RomFS and exercised by round-trip checks.

== Location in BFRES ==
CIDB is embedded rather than stored as a separate regular ROMFS file.

1. Open a room model in "region_common/map".

2. Search for the ASCII magic CIDB (43 49 44 42).

3. The lossless container ends at the BFRES relocation-table offset stored in the BFRES header at `0x18`. The CIDB magic must occur before that relocation table.

== Conventions ==
Unless a table says otherwise, integer and float fields are little-endian.
{| class="wikitable"
|+
!Type
!Meaning
|-
|<code>u8</code>, <code>u16</code>, <code>u32</code>
|unsigned integer, little-endian
|-
|be_u32
|unsigned 32-bit integer, big-endian
|-
|f32
|IEEE-754 single-precision float, little-endian
|-
|be_f32
|IEEE-754 single-precision float, big-endian
|}
Raw CIDB vertices use `(X, Y, Z)`. `X` and `Z` form the floor plane; `Y` is the vertical/gravity axis.

== CIDB container ==
All decoded map containers start with this little-endian header.
{| class="wikitable"
!Offset
!Type
!Description
|-
|<code>0x00</code>
|<code>char[4]</code>
|Magic: <code>CIDB</code>
|-
|<code>0x04</code>
|<code>u32</code>
|Header size. Observed value: <code>0x10</code>.
|-
|<code>0x08</code>
|<code>u32</code>
|Unknown. Observed as <code>0</code> in the sampled map files.
|-
|<code>0x0C</code>
|<code>u32</code>
|Section count. Observed as <code>5</code>.
|-
|<code>0x10</code>
|<code>u32[section_count]</code>
|Offsets of CIDB sections, relative to the CIDB start.
|}
The exact meaning of every container section has not been established. The safe way to find collision is to search the CIDB payload for <code>NXS\x01MESH</code>, not to assume a particular section number.

== NXS/MESH collision record ==
Every decoded collision mesh starts with the eight-byte magic <code>4E 58 53 01 4D 45 53 48</code> (<code>NXS\x01MESH</code>). The mesh's variable data immediately follows this 28-byte header.

=== Outer descriptor and contact-code table ===
In the retail CIDBs examined so far, an <code>NXS\x01MESH</code> record is immediately preceded by a 0x2C-byte outer descriptor. This is not merely alignment data:
{| class="wikitable"
!Descriptor-relative offset
!Type
!Established meaning
|-
|<code>+0x04</code>
|<code>u32</code>
|NXS/MESH payload length, beginning at the following <code>NXS</code> magic.
|-
|<code>+0x08</code>
|<code>u32</code>
|Byte length of the following material/contact-code table; divisible by four.
|-
|<code>+0x10</code>
|<code>u32</code>
|Still not fully named; observed values include <code>0xFFFFFF01</code> and <code>0xFFFFFF02</code>.
|}
The contact-code table begins at <code>nxs_offset + descriptor[+0x04]</code> and consists of <code>descriptor[+0x08] / 4</code> little-endian <code>u32</code> values. The table is followed by padding until the next CIDB descriptor. It is part of the CIDB, not BFRES render-material metadata or a value invented by the executable at load time.

For example, TownWell mesh 1 serializes the four words <code>0x00000029, 0x00000017, 0x0000004B, 0x0008000B</code> directly after its NXS payload. Its material-table-index <code>1</code> resolves to <code>0x17</code>, the observed shallow water contact code. The high bits are meaningful state bits in at least some entries, so tools must preserve every full <code>u32</code> unchanged.
{| class="wikitable"
!Offset
!Type
!Description
|-
|<code>0x00</code>
|<code>char[8]</code>
|Magic: <code>NXS\x01MESH</code>
|-
|<code>0x08</code>
|<code>u32</code>
|PhysX mesh serialization version. Observed value: <code>0x0E</code>.
|-
|<code>0x0C</code>
|<code>u32</code>
|PhysX midphase ID. Observed value: <code>0</code>, consistent with the following <code>RTRE</code> R-tree midphase.
|-
|<code>0x10</code>
|<code>u32</code>
|PhysX serialization flags. <code>0x07</code> = material-index array + face-remap array + <code>u8</code> indices; <code>0x0B</code> = material-index array + face-remap array + <code>u16</code> indices.
|-
|<code>0x14</code>
|<code>u32</code>
|Vertex count (<code>V</code>).
|-
|<code>0x18</code>
|<code>u32</code>
|Triangle count (<code>T</code>).
|-
|<code>0x1C</code>
|<code>f32[3 × V]</code>
|Vertex positions in raw <code>(X, Y, Z)</code> order.
|}

=== Triangle index width ===
The retail map archive has two observed index forms:
{| class="wikitable"
!Condition observed
!Triangle index type
!Bytes per triangle
|-
|<code>V <= 255</code>
|<code>u8[3]</code>
|3
|-
|<code>V > 255</code>
|<code>u16[3]</code>
|6
|}
Triangle indices follow the vertex array and are ordered <code>[a, b, c]</code>. The reader verifies that all indices are below <code>V</code>. Collision is one-sided; a custom floor must have its normal facing raw <code>+Y</code>, and a wall's normal must face the playable volume.

=== Per-triangle material-table indices ===
The triangle-index array is followed by exactly <code>T</code> little-endian <code>u16</code> values. Entry <code>i</code> belongs to triangle <code>i</code>.

<code>surface_ids_offset = 0x1C + (V * 12) + (T * 3 * index_width)</code>

<code>surface_id[i] = u16(surface_ids_offset + i * 2)</code>

These values are PhysX <code>PxMaterialTableIndex</code> entries: per-triangle indices into the CIDB mesh's immediately following <code>u32</code> contact-code table. They are not BFRES render-material names and are not, by themselves, a global gameplay material enum. A complete scan of the retail map archive found values <code>0</code> through <code>10</code>.

This is why the same raw value can legitimately result in different footsteps in two rooms: the mesh stores an index, while each CIDB mesh serializes its own contact-code table. The runtime resolves a hit's triangle material index through that per-mesh table.

The field order and flags match the public PhysX 3.4 triangle-mesh serializer, which writes <code>mMaterialIndices</code> as a <code>u16</code> array, and its shape material resolver, which obtains the hit triangle's material index then resolves it through the shape material array.

'''Material name table (48 entries, index = <code>low6</code>).''' Built by a static initialiser at <code>0xE5099C</code> into a bss table at <code>0x1CC1C40</code> (40-byte entries), so it does not exist as a literal in the file. Index: name.
{| class="wikitable"
!Idx
!Name
!Idx
!Name
!Idx
!Name
!Idx
!Name
|-
|0
|GRASS
|12
|MARBLE
|24
|SWAMP
|36
|SAND
|-
|1
|GRASS
|13
|MARBLE
|25
|MARBLE
|37
|SAND
|-
|2
|TURF
|14
|STONE
|26
|CARPET
|38
|DIRT
|-
|3
|GRASS
|15
|MUD
|27
|WOOD2CR
|39
|DIRT
|-
|4
|GRASS
|16
|MARBLE
|28
|CARPET
|40
|GRASS
|-
|5
|SAND
|17
|STONE
|29
|STONE
|41
|DIRT
|-
|6
|GRAVEL
|18
|STONE
|30
|STONE
|42
|DIRT
|-
|7
|DIRT
|19
|CARPET
|31
|MUD
|43
|DIRT
|-
|8
|DIRT
|20
|MARBLE
|32
|DIRT
|44
|SAND
|-
|9
|WOOD
|21
|WATER
|33
|CARPET
|45
|DIRT
|-
|10
|WOOD3HO
|22
|SWAMP
|34
|STONE
|46
|DIRT
|-
|11
|STONE
|23
|WATER
|35
|CARPET
|47
|WATER
|}

ZeldaMods (Link's Awakening) - User contributions [en]

Cidb