llamamod/notes/editor-object-schemas.md

Object parameter schemas (strat bytecode analysis)

Registry in code: editor.tools.objects.Schemas (named, typed, documented parameters with ranges, choices and waypoint meaning), statistics of all original instances: src/main/resources/.../editor/tools/objects/type-stats.tsv (TypeStats). Types without a schema fall back to raw values plus "values used in the original levels". Shown in the Inspector section "Object parameters" and checked by the Problems panel (ObjectChecks).

How parameters reach the script

• MAP strat record: count n + index into the parameter pool. The level spawner FUN_0054cfc0 passes a fake stack, FUN_0054bfc0 pops the n values into the new strat's variables 0..n−1 (strat+0xF4 = variable array). So parameter i = variable i of the strat code.
• Values are 20.12 fixed point by convention (0x1000 = 1.0); booleans are 0 / 0x1000, counts and world/chapter numbers n << 12.

Strat VM (FUN_0054d180) – enough to disassemble

Word-coded: op = w & 0xFFFF. op < 0x45: table 0x5796BC, operand = signed high 16 bits, one word. op ≥ 0x45: table 0x578FF4 + op·4 (up to 0x1F6), inline operand words read via the pc. Inline lengths (found by decompiling all 337 handlers with headless Ghidra and following helper calls): 1 word for 0x45 0xA5 0xA6 0xB1 0xB2 0xD0 0xD3 0xD7 0xDB 0x115 0x11C 0x14B 0x14D 0x162 0x167 0x175; 2 for 0xD4 (name: d4 ea rel); 5 for 0x94 and 0xE0 (spawn: FUN_00553170 reads nParams + 4 type fields); 6 for 0x95 (spawn at offset); short 0x0C (event slot) has 2; 0x02/0x03 (debug print: count then items, 0x45/0xEA items have one extra word) are variable. A linear sweep restarted at every d4 name site disassembles all 31 level WADs without desync and hits every MAP strat entry (the entry is the name site). Strings live between strats.

short op	meaning	short op	meaning
04 n / 41 n	push / pop variable n	06 n / 43 n	push / pop global n (0x6D9E8C)
07 n / 40 n	push / pop own property n (FUN_00550E60 / FUN_005509F0)	1C n / 37 n	player property
44 v	push 16-bit constant	14 / 15 / 16	jz / jnz / jmp (pc+4+v·4)
12 / 13 / 2B	jz / jnz / jmp + yield	17	switch (table at pc+4+v·4)

Long ops used for the decoding: 45 push word, 49 add, 4A sub, 4B mul (fixed), 4C div, 4E eq, 4F lt, 53 gt, BC ne, BD/BE ge/le, AF not, B6 and-logical, B7/B8 bit or/and, 50/51 shl/shr, AD/AE sin/cos (table 0x574318), AC floor, BF rand, 16E lerp, 54 set model, 8B radius (+0xFE), 83 +0xD2 (collision radius), A5/A6 set/clear strat flags (0x8000 floor collision, 0x40000 walls), C2 update floor, 73/75/177 waypoint first/next/advance (+0x118 first, +0x120 current; next wraps to the first node), FE move to waypoint, 178 "inside the box of the current and next waypoint (x/z)", 192 level change (pops tribe, world, chapter), B4/8E die, E0/95 spawn. Properties: 16 floor height, 17 floor material, 34–36 x/y/z, 37–39 rx/ry/rz, 3 waypoint first/last bits, 4 waypoint field +26, 6–8 waypoint x/y/z, 9/10 waypoint rx/ry, 41 distance to the player, 61–64 tribe/world/chapter/map, 202 distance to player (squared compare). Camera globals: 47 horizontal distance, 48 height above the target, 29/44 yaw, 36–38 position and 40–42 look-at of cut-scene cameras, 66 camera flag word, 95 progress bits. Patterns: push var i; push 30; mul = seconds → frames; push var; push var; mul; pop var = squared distance (radius).

Decoded types

Confidence: high = code read and behaviour seen in game; medium = code read; low = values only.

Type	Parameters	Waypoints
Coin (high)	p0 snap to floor (drops onto floor, random spin), p1 falls (floor collision flag 0x8000), p2 no shadow	–
Coin5 (high)	p0 snap, p1 falls	–
Health	p0 snap, p1 no shadow, p2 falls	–
HealthFull, HealthGenerator, Wompy	p0 snap, p1 falls	–
Grapes, HealthBanana, ChargeBooster	p0 snap	–
RubyIdol	p0 falls, p1 snap	–
Secret (high)	p0 box mode (player inside the box of the 2 nodes, op 0x178)	box (2 nodes)
CoinLine / CoinCircle (low)	count (counted down), spacing / radius	–
Llama	p0 spawns a helper, p1 unused, p2 camera mode (global 107)	first node = camera start
CheckPointPost (high)	p0 collision radius (+0xD2, 0.2)	1 node = respawn position + yaw (98 of 102)
LevelDoor (high)	tribe, world, chapter of the next level (7,7,7 = world finished); fires on material-16 floor of a tile in its cell (any height; often only in the swap model a RubyIdolDoor/other door object switches to when it opens)	–
CameraSide	p0 height (g48), p1 distance (g47), p2 yaw mode (1 node yaw, 2 node yaw or ±180°), p3 only below node y, p4 flag 0x10000, p10 several boxes, p11 height offset, p12/p13 alt. height/distance	box pairs, node 0 yaw = camera yaw
CameraLift	p0 yaw source (1 object, 2 player), p1 box test on helper strat, p3 smooth (g97), p4 height limit, p5 flag	box
CameraSetDistance	g82, g68, g83, height g48, g73 (each with a flag bit in g66)	–
CameraFocusPoint	radius², min height², max angle, height limit, 3 flags, blend factor	–
CutSceneCameraDirectional	p0 event bit (1..31), p1 mode, p2 wait, p3 disabled, p5 end mode	camera nodes: position, yaw/pitch = view (globals 36–42)
CutSceneTrigger	p0 character (floor snap, g72 counter), p2 radius², p3 event bit (skip if set in g95), p5 height check, p6 bits (1 face player, 2 not skippable)	camera path
ForcePlayerMovement	p0 active, p1 radius², p2 game state, p3 lock, p4 align yaw	target points
ObjectDontDropInBox, FallOffNoHurt	box mode (+ game state)	box
WaterReboundPoints	active	rebound points
RubyIdolDoor	p1 idols needed, p4 sign offset	–
CityGuard family (high)	p0 view range², p1 chase range² (view capped to it), p2 event bit (0 = active at once), p3 wall collision (CityGuard only)	boxes (node pairs), must start inside one – see below
JumpingBeetleBlue, Spider, Bunny	times in seconds (×30), ranges²	patrol path

Guards (CityGuard, CityGuardWithRubyIdol, CowGuard(NoCoin), GorillaGuard, LizardGuard(NoCoin), WarthogGuard)

One compiled template (same code in t1l1m002 unit 20 and the others). Start of the script:

1. if (p2 > 0) { hide; wait until g95 & (1 << (p2−1)); unhide } else wait until playerPtr ≠ 0 – p2 is an event bit: bits of global 95 are set by talking characters (TipoVillage, ChacaVillage), smash statues, LabBigCutscene, LabSlidingDoorPad … with the same number. All village guards have p2 = 0; 4 lab guards wait for an event.
2. Waypoint scan: wpFirst, then pairs (wpNext twice): odd count → debug "Uneven number of WPs" + remove; the start box = first pair whose x/z box (inWaypointBoxXZ, op 0x178, inclusive, fixed point) contains the guard and whose first node has field +0x28 (wpParam, editor unk2) = 0; none → "Guard not in WP box" + remove. So the waypoints are walking areas, not a patrol path: the guard wanders (random turns) inside the current box; when it leaves it, waypointStep(2) looks for another box containing it (boxes with wpParam ≠ 0 only from another such box), else it turns back (clampToWaypointBox). Chasing stays clamped to the boxes; it gives up beyond p1 or when the player leaves. All 41 original guards satisfy this (unit test GuardsTest). The editor: placing a guard gives it one 4×4 box and p2 = 0; ObjectChecks reports an error when the game would remove it and an info for p2 > 0; the Inspector shows the state plus a Box around it button (Guards, Setups.guardBox). Verified in game: CityGuard with its box on a new level (base village 2) appears and attacks the llama; a second one with a 4-node "square path" next to it never appears.

The rest (~150 placed types) shows raw values with the original statistics. Next candidates: Alligator (also box pairs: "Forcing alligator inside first WP box"), PressurePadDoor (bit field), TargetRopePlatform, CataSwingingBlade (speeds/angles), RiverLog. Tooling used (not in the repo): Ghidra script decompiling the handler table, a Python sweep disassembler with an op-name table, "parameter use" context dumps per type.