# Level geometry (TRAK / MAP / STPC / TEXT) – Ein Königreich für ein Lama (PC)

As of: 2026-11-06. Source: groove.exe (Ghidra decompilation `re/groove_decomp.c`, Capstone) +
data analysis of all 34 level WADs. Tools: `tools/geomlib.py`, `tools/geom_export.py`,
`tools/geom_import.py`, `tools/geom_demo.py`, `tools/disx86.py`.
Confidence: **[certain]** = verified from code + data (byte-identical round trip / rendering),
**[likely]** = plausible from data, **[?]** = unknown.

## 1. Overview: which chunk is what

Chunk dispatcher: `FUN_00558xxx` at VA 0x55899e (compares against tag constants, tag read as u32 LE,
e.g. 'CPTS' in the file = 0x53545043).

| Chunk | Loader (VA) | Contents |
|---|---|---|
| WFPC | inline → `DAT_006da330` | u32 feature flags of the level (control MAP/STPC layout) **[certain]** |
| TEXT | 0x4067b0 / 0x406d30 | texture pages (256x256, 16 bit) + texture table (UV rectangles) **[certain]** |
| SMPC / AMPC / SRPC | 0x558d30 / 0x558d70 / 0x545350 | sound (SMPC: 'cvg ' VAG samples; AMPC: 'ambi'/'VABp'; SRPC sound references) – **no geometry** |
| **TRAK** | 0x42aac0 → 0x5563f0 | **world geometry**: tile models (render triangles + collision polygons) → global array `DAT_005846ec` **[certain]** |
| **STPC** | 0x42ab50 | object ("strat") models (same model format), skeletal animations, then strat script data (names like "SinkingStatuePad") **[certain for models]** |
| **MAP** | 0x42ac50 | tile grid: placement of the TRAK models + vertex colours + zone PVS (+ strats/paths/etc., see objects.md) **[certain]** |
| LGHT / LNFO / LGPC | 0x42c180 / 0x42ab10 / 0x558db0 | lights / level info / ? – not geometry |

**The world is a tile system (inherited from Croc):** TRAK contains N "tile" models in local
coordinates (roughly −0.5..0.5 in x/z, but they can stick out up to ±2.4). MAP places them
on a W×H grid (1 unit = 1 cell) with height y and rotation around y. There is **no BSP**;
the spatial partition is the grid itself (cell lists) + a 32-zone visibility table.

## 2. Coordinate spaces [certain]

* **Export space** (= MAP floats "A", = vertex data of TRAK/STPC): **y up**, grid cells lie at
  x ∈ [0,W), **z ∈ (−H, 0]**. The engine draws it with a Direct3D camera, i.e. **left-handed**:
  a right-handed tool shows export-space data mirrored (see editor-render.md).
* **Game space** (MAP fixed point "B", collision, strats): (x, y, −z), 20.12 fixed point (4096 = 1).
  As the game shows it, game space is **right-handed** (y up).
* **File space** (OBJ/glTF of all tools, since 2026-11-07) = game space: right-handed, y up,
  z > 0 in the grid, so Blender shows a level the same way round as the game and a model from
  Blender appears in game as modelled. Converting export ↔ file negates z and reverses the corner
  order (first corner kept: export (0,1,2) ↔ file (0,2,1); `geomlib.to_file/file_order`).
  Used by `geom_export`/`geom_import`/`geom_demo` (`--export-space` = old raw export space, z < 0),
  the editor's Import mesh, OBJ export and glTF export. Verified in game and Blender with an
  asymmetric "F" (`img/editor/handed_*.jpg`, editor-tools-geometry.md).
  The renderer converts B back: pos = (Bx, By, −Bz)/4096, angle = rot·2π/4096.
* Tile transform (local vertex v → world, export space), a = rot/4096·2π:
  `X = x + vx·cos a − vz·sin a ; Y = y + vy ; Z = z + vx·sin a + vz·cos a`
  (verified: 93 % of all tile edge vertices hit a neighbour vertex exactly; the three
  other sign/mirror variants give 65–70 %).
* **Collision data is in game space** (z mirrored relative to the render vertices of the same
  model). Negate nz when decoding (92 % of the reconstructed collision corners lie
  < 0.02 from a render vertex).
* rx/rz of the tiles are 0 in all levels; only rotation around y (in practice 0/1024/2048/3072).

## 3. Model format (TRAK and STPC) [certain]

Fixup functions: TRAK `FUN_005563f0(&ptr, n, &out)` (header 0x84),
STPC `FUN_0041f770(&ptr, n, &out)` (header 0x8c). File layout: **all headers of one call
in a row, then the data of the models in order** (TRAK: one call with n=count;
STPC: n calls with 1 model each → header/data alternating). Pointer fields are 0 in the file
and are set on load.

### Header

| Off | Type | Meaning |
|---|---|---|
| 0x00 | 3×f32 | centre of the bounding box |
| 0x0c | 8×3 f32 | box corners, order (−x−y+z)(+x−y+z)(−x+y+z)(+x+y+z)(−x−y−z)(+x−y−z)(−x+y−z)(+x+y−z). Slightly larger than the vertices (margin not constant, ~0.004–0.014; probably from the original mesh). Used for frustum culling (`FUN_00402840`). |
| 0x6c | u16 | nVerts |
| 0x6e | u16 | nFaces |
| 0x70 | u32 | → verts (file: 0) |
| 0x74 | u32 | → faces (file: 0) |
| 0x78 / 0x7a / 0x7c | 3×u16 | number of collision polygons in 3 groups (code always sums all three; group meaning [?]) |
| 0x7e | u16 | 0 |
| 0x80 | u32 | → collision (file: 0) |
| *STPC only* 0x84 | u16 | = nVerts for rigid models, 0 for skinned models |
| *STPC only* 0x86 | u16 | nBones (skinned models) – preceded in the data by nBones×u16 = vertex count per bone (sum = nVerts, verified) |
| *STPC only* 0x88 | u32 | → bone table (file: 0) |

### Data (in this order)
1. (STPC only) nBones × u16
2. **Vertex** 24 bytes: `f32 x,y,z ; f32 nx,ny,nz` (smoothed normals; lighting comes from MAP vertex colours)
3. **Face** 28 bytes (triangles only):
   `u16 flags ; u16 v0,v1,v2 ; u16 tex ; u16 0 ; f32 nx,ny,nz,d` with n = normalize((v1−v0)×(v2−v0)), d = n·v0
   (verified for all faces). On load `tex` is replaced by a pointer to the texture table entry
   (`DAT_00581154 + tex*20`). The plane is used for backface culling (camera·n − d ≥ ε).
4. **Collision polygon** 32 bytes, nGroupA+B+C of them:
   `u8 type ; u8 material ; 5 × { i8 nx, i8 ny, i8 nz, u8 0, i16 d }`
   * plane 0 = surface, planes 1..4 = edges (normals pointing **inwards**, point inside ⇔ n·p − d ≥ −tolerance).
   * normals ×127 (code multiplies by 32 → 4096 scale), d ×4096 (fixed point) → local coordinates only ±8 units!
   * type bit0 = quad (4 edges), otherwise triangle (3 edges, 5th plane = 0). Bit2 ≈ normal points down (ny<0; ceilings/overhangs) [likely].
   * material: ground type (0 = normal; 0x11/0x12 are ignored depending on WFPC 0x8000000, 0x1e = water/death plane [likely]; the value ends up in the player's ground state).
   * Collision queries: `FUN_004036d0` (floor/ceiling), `FUN_00403ad0` (walls), `FUN_004042f0`, `FUN_004046e0`. Only **the tiles of the grid cell the player stands in** are tested (cell list from MAP), point relative to the tile's B position, rotated by −rot.

### Face flags (u16)
| Bit | Meaning | Confidence |
|---|---|---|
| 0x0008 | new render batch: reload render state (page, blend mode) from this face, draw the previous batch. Sorted by page/state + bit at each change. | certain (code) |
| 0x0010, 0x0800, 0x0020 | UV corner selection (see below) | certain |
| 0x0400 | no backface culling (double-sided) | certain |
| 0x4000 | ignore vertex colours (white) | certain |
| 0x0001, 0x0002 | special render modes (sorting/transparency; together with global flags 0x5f6ee8) | likely |
| 0x8000, 0x1000, 0x2000, 0x0200, 0x0100, 0x0004 | present in the data, the renderer (0x556510) does not evaluate them | ? (probably PS1 leftovers) |

### UVs – the engine has NO free UVs [certain]
Every triangle shows one half of a **texture rectangle** (entry of the TEXT table).
UV rectangle: U0=u0/256, U1=(u1+1)/256, V0=v0/256, V1=(v1+1)/256. With m = flag 0x20 (mirrors U),
a = m?U0:U1, b = m?U1:U0 the corners (v0,v1,v2) get:
* without 0x800: (a,V1) (b,V1) (a,V0)
* 0x800, without 0x10: (a,V1) (b,V1) (b,V0)   ← first half of a quad
* 0x800 + 0x10: (b,V0) (a,V0) (a,V1)       ← second half
(renderer `FUN_00556510` from the line "if ((uVar6 & 0x800) == 0)"). Textures with flag bit0 are
flat colours (u0,u1,v0 = R,G,B). 96 % of world faces have 0x800.

## 4. TRAK chunk [certain]
`u32 n ; n × header(0x84) ; data of model 0..n−1`. All 34 level WADs parse exactly up to the
end of the chunk; `geomlib.build_trak(parse_trak(x)) == x` byte-identical for all levels.
Typically 100–650 models, max. 422 verts / 798 faces per model. Model 0 is, in many levels,
an invisible plane (4 verts, 0 faces, 1 collision polygon, material 0x1e) at y=−2.75 –
the water/fall plane below the islands.

## 5. MAP chunk – geometry parts (loader FUN_0042ac50) [certain]
(Strat/path/zone blocks: see notes/objects.md; only what concerns geometry here.)
Order in the file:

1. `u32 N (tiles), u32 W, u32 H` (grid)
2. **A**: N × `{f32 x, f32 y, f32 z, u32 rot, u32 model, u32 animFlag}` (export space; x,z = cell centre .5).
   Only used to sort into the cell lists: cell = ftol(x − 0.5) − ftol(z + 0.5)·W (ftol truncates; 0x42ad4a,
   constant 0x56e158 = 0.5) = floor(x) + floor(−z)·W for cell-centred tiles (all originals). The player/strat
   cell of the collision tests is x>>12, z>>12 (FUN_004036d0).
3. u32 n + n×u32 (list, referenced by strats)
4. u32 n + n×90 bytes (lights/cameras? – objects.md)
5. u32 n + n×34 bytes (path nodes)
6. **Zone table** 256 bytes = 32 × `{u32 visibility mask, i32 height value}` → `DAT_006da350`
7. **Zone grid** W·H × u32 (zone number 0..31 per cell) → world+0x48
8. **B**: N × `{i32 rx, i32 ry, i32 rz, i32 x, i32 y, i32 z}` 20.12 fixed point, game space (z = −A.z), ry = A.rot.
   **Used for rendering and collision.** A and B are consistent in all levels.
9. **Model index**: N × u32 (= A.model)
10. if WFPC & 0x10000: `u32 n ; n × {u32 cellX, u32 y, u32 cellZ, u32 modelA, u32 modelB}` –
    tile swaps (doors/bridges etc.), entry k belongs to the k-th tile with animFlag≠0.
11. **Vertex colours** per tile i: nVerts(model) × u32 RGBA (0x80 = 1.0, game ×2 with clamp);
    byte3 of the first entry = number of colour sets (0/1 = one; ≥2 → another nVerts×u32 follow,
    the second set is used when `DAT_005865d4==1`). For animFlag tiles the same
    structure follows for modelB. Pointer table world+0x58 (twice as large with WFPC 0x10000000).
12. Rest (u32 n2,n3 + 58-byte strat entries, optional paths (0x200000), view distance (0x10), u16) – objects.md.

`geomlib.build_map_tiles(..., zones='keep', anim=orig)` reproduces all MAP chunks byte-identically.

### Grid / visibility (no BSP) [certain]
* Cell lists: world+0x40 (W·H pointers, linked lists of tile indices), built from A.
* Rendering (`FUN_0042bf40`): rectangle around the camera (view distance) over the grid; for every cell
  all tiles in the list, but **only if bit zone[cell] is set in the mask of the camera zone**
  (`DAT_0058642c` = zonetable[zone[camera cell]].mask, `FUN_0041e020`). Zone 0 has mask 0x1 in the
  village level. → New geometry must get matching zones, otherwise it is invisible.
  `geom_import --zones flat` sets grid=0 and mask(zone 0)=0xffffffff (everything visible).
* Collision: only tiles of the player's cell (see above).

## 6. STPC chunk (objects) [certain up to animations]
`u32 n1 ; n1 × (header 0x8c + data)` static/skinned object models (33 in the village) ;
`u32 n2 ; n2 × animation` (`FUN_0041f8b0`, header 32 bytes: +0 nA (nA×4 bytes), +8 nFrames,
+0xc (0 → nFrames×8 bytes), +0x10 nDelta (frame 0: nDelta×8, otherwise nDelta×2 (+2 if odd)
bytes of compressed vertex deltas), +0x18 nBones (per frame nBones×64 bytes = 4×4 matrix)) ;
if WFPC & 0x100: `u32 n3 ; n3 × {16-byte head (+4 count, +8 → n×8 bytes), models}` ;
then strat data (scripts, names) – not parsed by the loader, referenced from MAP via offsets
(`DAT_006d9dbc+off`). `geom_export --objects` exports the n1 models side by side.

## 7. TEXT – as far as needed for geometry [certain]
`u32 nPal ; nPal×{u32, u32 n, n×u16, n×u8}` ; `u32 nPages ; nPages×{u32 flags, u32 w, u32 h,
(flags&0x80: u32 len + RLE16) | (flags≠0: w·h·2) | w·h}` ; `u32 nTex ; nTex × 8 bytes` ; rest (40 bytes in the village) [?].
Texture entry: `u16 flags, i8 page, i8 page2(-1), u8 u0, u8 u1, u8 v0, u8 v1` (u1/v1 inclusive).
Flags: bit0 flat colour, bit2 1-pixel border, bit3/bit4 width/height ×2, bits 12–14 blend mode, bits 8–10 another mode.
Pixels: ABGR1555 (R = bits 0–4), 0 = transparent. Details: notes/textures.md (other agent).

## 8. Writing new geometry – what must be consistent
Implemented in `tools/geom_import.py` (OBJ → TRAK + MAP tile part, rest of the WAD unchanged):
1. **TRAK**: u32 count; header with correct nVerts/nFaces/nColl; box+centre (for culling,
   recomputed); face planes from vertices; vertex normals. No checksums.
2. **Face texture index** < number of texture table entries; UVs only via rectangle corners (+flags).
   Bit 0x8 at the start of a batch (page/state change, at the latest every 256 faces).
3. **Limits**: ≤ 8000 vertices per model (transform buffer 0x58b0f0..0x5d15f8, 36 bytes/vertex),
   batch output buffer 0x5d15f8 ≈ 4800 vertices; collision d as i16/4096 → collision polygons
   only within ±8 units of the tile origin. u16 indices.
4. **MAP**: keep N in the header, A (floats) and B (fixed point, z negated) identical, model indices
   < TRAK count, tile cells within W×H, **vertex colour block exactly nVerts(model) per
   tile** (otherwise the rest of MAP = strats shifts!), animation block (WFPC 0x10000)
   matching the flags (import sets it to 0 entries), zones (see above).
5. Collision belongs to the cell: a polygon only takes effect if it is in the tile list of the cell
   the player stands in → import enters every polygon into every cell it covers
   (also as a pure collision tile without faces, like original model 0).
6. Total WAD length (wadtool/geomlib rewrite it). No other checksums found.
7. Strats (start point, enemies, camera paths) remain at their old positions (objects.md).

### Tests (without starting the game)
* Round trip TRAK and MAP of all 34 WADs byte-identical.
* Export → import (`--coll-obj`) → export t1l1m001: rendering identical (img/), 26435/26442
  triangles (7 degenerate ones dropped), floor height at 2800 random points: 99 % < 5 mm deviation,
  10 points differ (polygons now also entered in neighbouring cells).
* Independent cross-check: `tools/mapchunk.py` (other agent) parses the generated MAPs completely.
* NOT yet tested in game: demo WADs in $CLAUDE_JOB_DIR/tmp: `demo_add.wad` (original +
  2 blocks + ramp, original zones), `demo.wad` (everything replaced by a floor plate y=0 + blocks).

## 9. Open / unknown
* Meaning of the three collision groups (the sum is always used together) and the complete material list.
* Face flags 0x8000/0x1000/0x2000/0x200/0x100/0x4; exact effect of 0x1/0x2.
* Exact origin of the box margin in the header (recomputing with a 1/128 margin is probably enough).
* Zone table 2nd value (height, `DAT_00586424`) – possibly water/fog height.
* STPC animation: meaning of the nA block and the delta compression in detail (`FUN_0041fa30`).
* Whether the player start point/camera is coupled to geometry (objects.md).

## 10. Tools
* OBJ files of all three tools are file space = game space (section 2); `--export-space` on
  `geom_export`/`geom_import` = the old raw export space (z < 0).
* `geom_export.py WAD OUT [--collision] [--objects] [--export-space]` → level.obj/mtl (UV, vertex colours, one
  object per tile), page_NN.png, collision.obj (groups matNN_grpG), objects.obj, preview_top/persp.png
  (textured software renderer, right-handed camera, always in game space – the same way round as in the
  game, checked against an in-game shot of t1l1m001: `img/geom_preview_handedness.jpg`; before 2026-11-07
  the previews rendered export space and were mirrored). `tools/vorschau/render_level.py` (Blender) reads
  file space and is not mirrored either (checked on the test world, 2026-11-07).
* `geom_import.py BASE.wad MESH.obj NEW.wad [--coll-obj C.obj] [--keep-tiles] [--zones flat|keep] [--default-tex N] [--export-space]`
* `geom_demo.py BASE.wad demo.obj [--plaza]` – example geometry made of texture-tile quads.
* `geomlib.py` – parser/builder (TRAK, STPC models, MAP tile part, TEXT table/pages, collision).