llamamod/notes/objects.md

MAP chunk & objects (strats) – "Ein Königreich für ein Lama" (PC)

Source: groove.exe, MAP loader FUN_0042ac50, strat spawn FUN_0054cfc0 → FUN_0054bfc0, strat VM FUN_0054d180, chunk dispatcher at 0x558960. Tools in ../tools/. All 34 original MAPs are read completely by mapchunk.parse() (0 bytes left over) and written back byte-identically by mapchunk.build().

Terms

• Tile = placed geometry model from TRAK (the level "construction kit", 1x1 grid).
• Strat = object/script instance (enemy, coin, door, player …). The strat code (bytecode, u32 words) and the object models live in STPC; MAP only contains instances with an offset into STPC. There is no type ID – the type is the code address. Type names are in the code: opcode 0xd4, 0xea, s32 rel → name = C string at (address after rel) + rel. strats.py resolves this.
• Coordinates: world y points up. Tiles store float x, y, z with z negative; strats/fixed point (20.12, 4096 = 1.0) store z positive (= −tile.z). Angles: 4096 = 360°. Floor tiles (flat model, vertex y = +0.25) → objects stand at tile.y + 0.25 (confirmed on player/checkpoints/coins).

MAP layout (all little endian) — confidence: high (from loader + roundtrip)

WFPC (u32 flags, global 0x6da330) controls optional blocks.

#	Block	Format
1	Header	u32 nTiles, u32 W, u32 H (grid size in cells)
2	Tiles	nTiles × {f32 x, f32 y, f32 z, u32 rotY(0/1024/2048/3072), u32 model, u32 hasAlt}
3	Parameter pool	u32 n, n × u32 (strat parameters, referenced by strats via index)
4	Zones ("Environment")	u32 n, n × 90 bytes (see below)
5	Waypoints	u32 n, n × 34 bytes {u32 next(≠0: next entry belongs to the same chain, 0 = end of chain), u32, u16 rx, u16 ry, u16 rz, s32 x, y, z (fixed, z positive), u32, u32}
6	Region table	32 × {u32 flags, u32 value} (→ 0x6da350)
7	Region grid	W×H × u32 region index (0..31) per cell, row = z cell
8	Tiles fixed	nTiles × 6 u32 {rx=0, rotY, rz=0, x·4096, y·4096, −z·4096} – exactly derivable from block 2
9	Tile models	nTiles × u32 TRAK model index (= field 5 of block 2)
10	Alt models (WFPC&0x10000)	u32 n, n × 5 u32; n = number of tiles with hasAlt≠0, in tile order; field 4 = alternative TRAK model (e.g. door open/closed, stMapreplace)
11	Vertex colours	per tile: nv(TRAK model) × u32 RGBA (byte 3 = frame count F); if max F>1: (F−1)×nv more u32; then the same for the alt model, if present. Colour is ×2 (clamped to 255)
12	Strats	u32 nStrats, u32 poolExtra, nStrats × 58 bytes (see below)
13	Paths (WFPC&0x200000)	u32 n; each: u32 nsub; each sub: u16 cnt, u16 flags; cnt × {u32,u32,[u32 if WFPC&0x4000000],u16 type,u16} – not used in any original level
14	(WFPC&0x10)	u32 (default 200; size of a 0x48 buffer)
15		u16 (→ mapobj+0xc, meaning open)

Cell assignment of a tile: col = int(x−0.5), row = −int(z+0.5), index col + row·W (linked list per cell). Tiles outside 0..W−1 / 0..H−1 write into foreign memory.

Strat entry (58 bytes) — mapchunk.STRAT = '3H3iIIi4Iiih'+'H'

Off	Type	Field	Confidence
0	u16 ×3	rotation x, y, z (4096=360°; x/z almost always 0)	high
6	s32 ×3	position x, y, z fixed 20.12 (z positive)	high
18	u32	code offset in STPC (= object type)	high
22	u32	number of parameters n	high
26	s32	index into parameter pool (−1 if n=0); parameters are pushed onto the strat stack	high
30	u32	number of strat variables (from the compiler, constant per type)	high
34	u32	number of 16-byte slots (collision/sub-objects; constant per type)	medium
38	u32	type flags (0x8000/0x80000/0x40000 = collision/physics block; constant per type)	medium
42	u32	extra memory (&0x3fffffff, mostly 0..3; constant per type)	medium
46	s32	waypoint index (block 5) or −1	high
50	u32	always 0	–
54	u16	flags; bit 1 (2) = do not create at level start	high
56	u16	always 0	–

poolExtra (second u32 in the strat header) = max. simultaneous strats − 30 (the engine allocates poolExtra+30 slots of 0x154 bytes). Must be ≥ number of strats + dynamically spawned ones.

Zones (90 bytes, 0x5c in memory) — confidence medium

u32 cellX, cellY, cellZ, s32 x,y,z (fixed), u32 ?, u32 rot?, u32 flags(+0x20; bit 8 = start zone → DAT_00584644), u32, u32 ptr offset in STPC (0=none), u32, u32, u32, u16, u32 fog near/far (+0x3c/+0x40), u32 ×2 (+0x44/+0x48), u32 colour (e.g. 0x404040), u32 colour, u16, u16, u32 music ID (+0x58; FUN_00546b70). Camera/fog/music areas; not light sources (those are in LGHT).

Player, checkpoints, exit

• Player start = position/rotation of the strat instance Llama (exactly 1× in every running level; type fields nvars 78, flags 0x248000). Special levels: river (t1l3*) = KuscoAndPachaTogetherOnATree, roller coaster (t1l7m001/3/5) = RollerCoaster, t1l2m003 = LlamaChase.
• Checkpoints = CheckPointPost (spawns CheckPointHead), variant CheckPointBox.
• Exit = LevelDoor (1×/level), special cases VillageEndDoor, EndGameDoor.
• Always present: CheatTeleport, Wompy (function not checked), CutSceneTrigger.

Object types

Complete table type × level (instance counts): strat_types_table.md (generated with tools/strat_table.py <wads>). Summary:

• in practically all levels: Coin, CutSceneTrigger, CutSceneCameraDirectional, LevelDoor, Secret, Llama, CheatTeleport, ChargeBooster, Wompy, CheckPointPost, Coin5, CameraSide, Health, HealthFull, SmashPot, RubyIdol, Grapes, HealthGenerator, RubyIdolDoor …
• ~300 types in total, ~200 more only spawned internally (splinters, ropes, effects).
• Every level has its own compiled strat code + models in STPC. A type can only be placed in levels whose STPC contains it (strats.py level.wad --all lists all named strats in the code, including ones never placed directly). The code contains absolute STPC offsets (e.g. spawn stubs b2 <abs> e0 …), so STPC cannot be moved without relocating. Taking types from other levels = merging STPC (+ TEXT indices) → laborious, not for now.
• "Spawn stub" entries (e.g. SmashPot): MAP points to a small piece of code push X; spawn(abs target, nvars, …); end → strats.py reports Name(spawn).

Rules for writing a new MAP

1. Keep tile blocks 2/8/9/11 in parallel (same count/order); derive block 8 from 2; block 9 = field 5 of 2; vertex colour length exactly = Σ nv(model)·frames (+alt).
2. Alt block: count = tiles with hasAlt≠0, same order. Simply append new tiles at the end (strats can replace tiles by index – stMapadd/stMapreplace – so do not reorder existing indices).
3. All tiles within 0..W × 0..H (z negative!). Region grid has W·H entries.
4. Strat: code offset must be a strat start in this STPC; copy nvars/slots/flags/extra from the original type; append parameters to the pool, set index/count; waypoint −1 or a valid index (some types need waypoints, otherwise "removing strat").
5. Increase poolExtra if there are more strats.
6. WFPC flags determine which optional blocks must be present – do not change them.

Tools

• mapchunk.py – parse/build (identical roundtrip for all 34 MAPs), vcol_split per tile.
• map_dump.py level.wad [--strats --tiles --lights]
• strats.py level.wad [--all] – types with instance counts, code offsets, type fields.
• strat_table.py wads_dir – type×level table.
• stpcwalk.py – roughly walks STPC (models → animsets → [WFPC&0x100 block] → strat code).
• make_testlevel.py src.wad dst.wad [--name …] [--spacing 3] [--floor-model N] [--keep-original] – finds a free grid area, lays a floor plate from copies of the most common flat floor tile (t1l1m001: TRAK model 12), places one instance per type (parameters from the original) on a 6-unit grid, the player at the edge, and a parkour (6 stepping plates +0.5 with gaps, coins) leading to a goal platform with a LevelDoor. Skipped: Camera*/CutScene*/ Force*/Trigger. Test (not checked in game): T1L9M001 → 1753 tiles, 36 strats, 27 types.

Other chunks (dispatcher 0x558960)

• WFPC: u32 feature flags (→ 0x6da330), e.g. 0x18410690.
• INFO/VERS: u32 1 each (ignored).
• NAME: u32 + level name.
• TRAK: tile models (u32 n, n×0x84 header, then data; header+0x6c u16 nVert, +0x6e nFace(0x1c), +0x78/7a/7c count of 0x20 primitives). Face+8 u16 = index into the TEXT texture list.
• STPC: u32 n models (each 0x8c header directly + data), u32 n animsets (0x20 header + data), [WFPC&0x100: extra models], then strat code up to the end of the chunk.
• LGHT: u32 n; per light u8 type, u8 r, u8 g, u8 b (×2), type 1/2/…: more u32 (direction/position, z negated). FUN_0042c180.
• LNFO: 2 u32 (→ 0x5ff070, 0x5ff060), e.g. 55, 2.
• LGPC: u32 n(+1), u32 m, u32; then (n+1)·m × u32 sizes, followed by the blobs. FUN_00558db0.
• FONT: 256 × 4 u16 (glyph rectangles). SPRT: u32 (list if WFPC&0x100000).
• SMPC / AMPC / SRPC: sound banks ("cvg" samples / "ambi" ambient / references), FUN_00545350.
• 'GRIM' (not seen in level WADs): FUN_00437b40.