PSX Art-Binding Recovery

Scope

Active target: retail PlayStation SLUS_002.68 feeding the renderer-local cache pipeline in Crusader-Map-Viewer/map_renderer.
Goal of this pass: stop treating the current unreadable PSX output as a renderer-only problem and measure whether placeholders are mainly caused by extraction-time art binding failures.
This note records the first pragmatic recovery pass that replaces large placeholder bands with real bundle-backed art while keeping the result auditable in exported scene metadata.

Root Cause Summary

The current unreadable output was primarily an extraction-side problem, not a front-end draw bug.
Before this pass, the built .cache/scene-cache/psx-remorse set carried 58,262 fallback placeholders versus only 1,714 bundle-mapped items.
The fallback concentration was overwhelmingly in section0_constructor_placements (94.5% of fallback items), not in the smaller section0_dispatch_roots family.
The hottest unresolved types were 0x0042, 0x0041, 0x0047, 0x0045, 0x003f, 0x004b, 0x0046, 0x0044, 0x0048, and 0x004a.
Those types already appeared in the exported DAT_800758d8 art-template layer in many maps, but almost all of their rows were blockSize = 0 and therefore had no direct payload dwords to match against bundle offsets.
The neighboring state banks were still populated: DAT_800758cc carried valid script tables for the same types, while DAT_800758d0 stayed empty for this family and DAT_800758d4 remained on the runtime-bounds side.
That combination strongly suggests inherited or aliased presentation for these constructor-placement families rather than a literal absence of art.

Implemented Recovery Rule

The cache builder now resolves PSX art in three stages instead of dropping directly from "no direct DAT_800758d8 payload" to a placeholder:

Use the direct non-zero DAT_800758d8 row when a type has a real local template payload and bundle match.
If the type lives in the unresolved zero-block constructor-placement family, look for a same-map donor type whose DAT_800758cc script blob is identical and whose DAT_800758d8 row resolves to a real bundle.
If no exact script-signature donor exists, fall back to the nearest resolved same-map donor inside the current constructor-placement family band (0x003e..0x0064).

The exporter keeps this explicit instead of pretending the rule is fully solved:

mappingSource now records whether the art came from a direct template, a cc-signature-donor:xxxx, or a generic-family-donor:xxxx path.
templateTypeId and donorTypeId are preserved in exported mapSource rows.
The unresolved type still uses its own DAT_800758cc selector-to-frame map; only the bundle source is borrowed.

Measured Effect

Two measured rebuilds mattered in this pass.

First donor pass

Added donor reuse for the original generic family band.
Totals moved from 58,262 fallback / 1,714 bundle-mapped to 37,054 fallback / 22,922 bundle-mapped.

Representative maps:

map 0: 1078 / 111 -> 340 / 849
map 9: 664 / 111 -> 197 / 578
map 43: 707 / 97 -> 196 / 608
map 64: 1194 / 161 -> 736 / 619
map 104: 909 / 93 -> 894 / 108

Extended donor band

Extended the same heuristic through the next zero-block constructor-placement band up to 0x0064.
Final measured totals after rebuild: 25,038 fallback / 34,938 bundle-mapped.

Representative maps after the extended pass:

map 0: 66 fallback / 1123 bundle-mapped
map 9: 42 fallback / 733 bundle-mapped
map 43: 9 fallback / 795 bundle-mapped
map 64: 160 fallback / 1195 bundle-mapped
map 104: 866 fallback / 136 bundle-mapped

So the first practical conclusion is straightforward: the exporter was the main blocker for most maps, and a constrained donor heuristic can replace a large fraction of placeholders with real graphics without touching the viewer runtime.

No-Placeholder Cohort Pass

A second follow-up pass replaced synthetic fallback atlas generation with cohort-aware donor resolution keyed by authored family plus raw u5 lane before the older coarse type default is consulted.
The exporter still prefers direct local DAT_800758d8 payload matches first, but when a type bucket is mixed-role or otherwise unresolved it now resolves each cohort separately instead of collapsing the whole map:type bucket into one donor or one placeholder.
Focused validation on map 104 now rebuilds as 1002 real-art items with 0 fallback items, 1 atlas, and 136 shape definitions. Scene sourceCounts are now 52 section0_dispatch_roots-art plus 950 section0_constructor_placements-art.
The scene JSON also now preserves mappingSource and optional artCohort on each mapSource row, so provisional cohort and emergency donor matches stay auditable after placeholders are removed.
This is still not the final executable-proof binding rule. The focused cache is now placeholder-free, but many rows still resolve through cohort-* or emergency-global-donor:* provenance and should be treated as provisional PSX art recovery rather than as final family/resource closure.

Remaining Unresolved Mass

The cache is still not fully closed. 25,038 fallback items remain across 62 maps.
The remaining fallback distribution is still concentrated in section0_constructor_placements.
Current top fallback-heavy types after the donor pass are 0x0042, 0x005a, 0x005b, 0x005c, 0x0047, 0x0059, 0x005d, 0x005e, 0x0062, and 0x0063.
0x0042 remains the single largest unresolved type even after the heuristic pass.
map 104 is the most obvious current outlier: it still sits at 866 fallback items versus only 136 bundle-mapped items, so the next recovery pass should treat it as the best stress case rather than relying only on the now-mostly-readable early maps.

Those counts are now historical rather than current for the focused map 104 export. They remain useful as the baseline that motivated the cohort pass, but the immediate blocker has shifted from “remove placeholders” to “replace provisional donor provenance with tighter executable-backed cohort/resource rules.”

Practical Interpretation

The donor heuristic is good enough to prove that many placeholders were caused by missing extraction-time inheritance logic.
It is not strong enough to count as the final executable-backed rule for the unresolved families.
The remaining gap still sits where the earlier Ghidra work already pointed: somewhere between the constructor-side art/resource creation lane and the live post-spawn state/resource/frame reselection path.

Palette Lock-In Rule

The PSX exporter must not treat mode 1 bundle header palette index +0x14 as the rendered 256-color selector.
The current dump-grounded rule is narrower and stronger: the known-good visible family decodes against one contiguous 256-entry lookup table equivalent to live VRAM row 0xF0, x=0.
In extractor terms, that behaves like the first 16 adjacent 16-color CLUTs flattened into one 256-entry palette. That is the rule now encoded in map_renderer/src/lib/psx-cache.js for mode 1 bundles.
The old bundle-header palette index is still preserved in exported scene metadata as defaultPaletteIndex, but it is diagnostic provenance, not the primary rendered selector.
mode 2 stays on the earlier per-bundle/per-usage palette-index path. This lock-in applies specifically to the current mode 1 family proven by the VRAM dump.
If a future pass proves a wider runtime CLUT-row formula, update this note and the exporter together in one change. Do not silently reintroduce mode 1 -> bundle header palette index as a fallback rule.