PSX Research

crusader_decompilation_notes.md

@@ -4,7 +4,7 @@ This file is an index. Detailed notes have been split into the `docs/` folder by
 
 Active live analysis target is now `CRUSADER.EXE`. Existing `CRUSADER-RAW.EXE` notes remain in scope as cross-reference evidence and should be cited alongside live NE addresses when they support a rename, variable role, or behavior claim.
 
-Recent verified PSX map-viewer batch: [docs/psx/psx.md](docs/psx/psx.md) and [docs/psx/map-viewer-plan.md](docs/psx/map-viewer-plan.md) now record the latest executable-backed correction to the PSX renderer model. Current best read is that the cache builder still exports executable-named section-0 visible families (`section0_dispatch_roots`, `section0_constructor_placements`), runtime/state layers for `DAT_800758d8`, `DAT_800758d0`, `DAT_800758cc`, `DAT_800758d4`, and one offline `FUN_8003b00c` decode candidate for `DAT_8006b5d8 -> DAT_8006769c`, and packs shared PSX art into `1925` shared atlases instead of the earlier one-atlas-per-shape spread. But the same batch also shows the current fallback art path is wrong at the root: early `section0_dispatch_roots` types such as `0x0042` and `0x0049` currently bind to portrait/talk-animation bundles, so the real remaining blocker is the multi-stage per-type template/state/variant selection path, not just a missing one-step bundle lookup.
+Recent verified PSX map-viewer batch: [docs/psx/psx.md](docs/psx/psx.md), [docs/psx/map-rendering.md](docs/psx/map-rendering.md), [docs/psx/map-viewer-plan.md](docs/psx/map-viewer-plan.md), and the new [docs/psx/art-binding-recovery.md](docs/psx/art-binding-recovery.md) now record both the latest executable-backed renderer findings and the first measured recovery pass against placeholder-heavy PSX scenes. Current best read is that the cache builder still exports executable-named section-0 visible families (`section0_dispatch_roots`, `section0_constructor_placements`), runtime/state layers for `DAT_800758d8`, `DAT_800758d0`, `DAT_800758cc`, `DAT_800758d4`, and one offline `FUN_8003b00c` decode candidate for `DAT_8006b5d8 -> DAT_8006769c`, but it now also treats large zero-block `DAT_800758d8` constructor-placement bands as inherited-art candidates before falling back to placeholders. That donor-based recovery path moved the built cache from `58,262` fallback items / `1,714` bundle-mapped items down to `25,038` fallback items / `34,938` bundle-mapped items, making maps such as `0`, `9`, and `43` mostly real-art while leaving `map 104` as the clearest remaining outlier. The newest pass does not change the earlier `DAT_800758d4` conclusion: `psx_object_advance_state_script` still sign-extends those three bytes into `obj+0x30/+0x34/+0x38` for overlap/contact-style consumers rather than the draw path, and the unresolved blocker still sits later in the live state-to-resource/frame bridge for the remaining constructor-placement families.
 
 Recent verified combat-data batch: [docs/combat-dat.md](docs/combat-dat.md) now documents the shipped `COMBAT.DAT` archive end to end. Current best read is that all local Remorse/Regret variants ship the same `14`-record combat-tactic archive, each record contains a `16`-byte name plus four block offsets and bytecode, and the tactic VM is now grounded both in the live `CRUSADER.EXE` helpers (`Attack_SetupForTacticNo`, `Attack_SetupForBlockNo`, `NPC_Get/SetNPCTacticNo`) and in ScummVM's readable Crusader attack-process implementation. The new note also promotes the per-tactic human-readable catalog, including the midpoint-pressure, marker-shuttle, step-out-shoot, and stationary-chaos families.
 
@@ -38,6 +38,8 @@ Recent map/editor visibility batch: [docs/editor-object-visibility.md](docs/edit
 
 Recent map-viewer trigger batch: [docs/map_renderer/trigger-usecode-links.md](docs/map_renderer/trigger-usecode-links.md) now records the evidence-backed editor/controller-object -> USECODE mapping used by the viewer when opening readable pseudocode from pinned tooltips. Current best read is that the stable viewer targets are `BOX_EW`, `PANELNS`, `CARD_NS`, and `SPANEL` -> `use`; `FASTSKIL` -> `enterFastArea`; `SKILLBOX`, `EVENT`, `ALARMHAT`, and `ALRMTRIG` -> `equip`; `TRIGPAD` and `NPC_ONLY` -> `gotHit`; and the `0x04B1` cmd helper itself -> `TRIGGER.slot_20`, the shared high-slot fan-out lane that nearby controller families keep spawning.
 
+Recent usecode-event vocabulary note: [docs/usecode-event-slots-combine-cast-fast-area.md](docs/usecode-event-slots-combine-cast-fast-area.md) now records a focused evidence pass on the suspicious inherited `combine` / `cast` slot names and the current best meaning of `fast area`. Current best read is that shipped Crusader usecode exposes no recovered `slot_0C` handler bodies at all, while `slot_11 cast` is real but acts as a scripted activation/dispatch lane rather than a classic spell system. The same note also tightens `enterFastArea` / `leaveFastArea` to `authored proximity/activation region` callbacks instead of the older speed-zone-style shorthand.
+
 Recent startup/map-selection batch: [docs/first-mission-map-selection.md](docs/first-mission-map-selection.md) now records the live proof that fresh-game map choice is code-selected rather than read from `CRUSADER.CFG` or another external mission-mapping file. For `CRUSADER.EXE`, the normal fresh-game path still hardcodes map `1`, egg `0x1e` inside `Game_Start`. For `REGRET.EXE`, the same values are hardcoded twice: once in an early `Game_Start` selector and again in the later `FUN_1030_032d` mission-start path that actually controls a real new game. The same note also captures the separate debug `-warp mission` path: it indexes a small executable-embedded mission-to-map word table at `1478:0488` (`0,1,3,5,...,0x1d,0x28`) and then applies `-mapoff`, while the actual map contents remain external in `FIXED.DAT`.
 
 New REGRET startup-flow batch: [docs/regret-game-start.md](docs/regret-game-start.md) now documents the live `REGRET.EXE` `Game_Start` neighborhood more thoroughly. That note promotes `HandleCommandlineArgs`, `Game_RunNewGameFlow`, `Game_DrawCenteredStartupSplash`, `Game_EnterFrontendMenuViewport`, and `Game_RestoreGameplayViewport` in the live database, records the startup-state globals used by the new-game and `-warp` lanes, and explains the current best reason map `1` is set twice in No Regret: two separate live startup entry paths still own their own teleporter literals instead of sharing one final startup-map source.
@@ -114,10 +116,13 @@ Latest F7 overlay follow-up: new note [docs/f7-overlays.md](docs/f7-overlays.md)
 | [docs/remorse-rebuild-abi-notes.md](docs/remorse-rebuild-abi-notes.md) | Working note for rebuild constraints: segmented-memory model, far-call provenance, runtime/toolchain evidence, ABI guardrails, and the split between original-style executable reconstruction and a behaviorally equivalent port |
 | [docs/command-line-parameters.md](docs/command-line-parameters.md) | Consolidated startup/debug argument reference for the retail Crusader executables: live retail `-u` usecode override, the current `-setver` caution, `-debug`, `-asylum`, `-warp`, `-skill`, `-mapoff`, `-egg`, `-demo`, the `-laurie` cross-reference, and the evidence-backed direct-coordinate warp syntax/limits |
 | [docs/psx/psx.md](docs/psx/psx.md) | PlayStation `SLUS_002.68` and disc-resource note: boot/load layout, `LSET`/menu WDL structure, executable-backed map inventory, passcode alphabet/display path, recovered PSX ammo/item/weapon tables, and current unresolved enemy/password-compare gaps |
+| [docs/psx/map-rendering.md](docs/psx/map-rendering.md) | Detailed PlayStation map-rendering architecture note: `LSET*.WDL` storage model, constructor record layouts, runtime banks, state/variant/art bridge, stage-1 versus stage-2 render lanes, visible-list sorting, final primitive submission, and the current best recipe for reconstructing PSX maps in the viewer |
+| [docs/psx/art-binding-recovery.md](docs/psx/art-binding-recovery.md) | Focused PSX viewer recovery note: extraction-versus-render diagnosis, zero-block `DAT_800758d8` constructor-family donor heuristics, measured fallback reduction, representative map stats, and the remaining outlier families/maps |
 | [docs/psx/prealpha.md](docs/psx/prealpha.md) | PlayStation pre-pre alpha `/psx/prealpha/SLUS_002.68` comparison note: reduced disc inventory, retained retail-style `LSET` loader, surviving No Remorse branding, stale `TALK1.XA` and `LoadExec` leftovers, and the current read that this build is closer to an unfinished No Remorse PSX branch than to a visibly rebranded sequel executable |
 | [docs/sprite-node-class-layout.md](docs/sprite-node-class-layout.md) | Focused working note for the `SpriteNode` family: current core layout, destructor and event-dispatch evidence, candidate virtual slots, and a conservative Ghidra modeling plan |
 | [docs/usecode-startup-override.md](docs/usecode-startup-override.md) | Focused retail `-u` deep dive: startup call order, why the override looks like full live-root replacement rather than addition, which event/process/interpreter consumers use that root, and what that implies for future custom usecode experiments |
 | [docs/usecode-roundtrip-ir.md](docs/usecode-roundtrip-ir.md) | ScummVM-to-binary USECODE cross-walk, owner-loaded class-layout and header/event-count reconciliation, conservative IR v0 plan, and the generated class-event/body-window outputs that now ground reversible `_BOOT`, `SURCAM*`, and environmental family decompile artifacts plus repeated-family regression checks |
+| [docs/usecode-event-slots-combine-cast-fast-area.md](docs/usecode-event-slots-combine-cast-fast-area.md) | Focused note on whether inherited event labels `combine` and `cast` are actually live in shipped Crusader usecode, plus the current evidence-backed explanation of `enterFastArea` / `leaveFastArea` as proximity-trigger callbacks |
 | [docs/usecode-pentagram-ghidra-path.md](docs/usecode-pentagram-ghidra-path.md) | Pentagram-derived Crusader USECODE parser plan, proof-of-concept workflow, canonical IR v1 goals, and the Ghidra-side annotation import path |
 | [docs/usecode-tooling-comparison.md](docs/usecode-tooling-comparison.md) | Comparison of Pentagram's converter/disassembler, the local `crusader-disasm` corpus/scripts, and the current workspace parser/pseudocode exporter, with emphasis on assumptions, strengths, and repo-specific differences |
 | [docs/usecode-tool-improvement-plan.md](docs/usecode-tool-improvement-plan.md) | Concrete next-step plan for the local USECODE parser/decompiler, distilled from the Pentagram and `crusader-disasm` comparison into prioritized parser, loop-decoding, intrinsic, trailer, corpus, and runtime-bridge upgrades |