Crusader_Decomp/docs/psx/map-viewer-plan.md

PSX Map Viewer And JL-9 Investigation Plan

Scope

• Active target: retail PlayStation SLUS_002.68 already loaded in Ghidra.
• Keep all PSX documentation in docs/psx/.
• Primary objective: get PSX maps loading into the existing map viewer coherently.
• Secondary objective: make PSX graphics export with the correct palette automatically instead of by partial heuristics.
• Tertiary objective: determine whether JL-9 is a real weapon in the PSX build, how it is unlocked or granted, and which sprite/bundle represents it.

Current State

• The detailed architectural write-up now lives in docs/psx/map-rendering.md; keep that file as the long-form reference for storage format, runtime banks, render lanes, and viewer reassembly, and keep this file focused on the active plan and remaining blockers.
• docs/psx/psx.md already closes the boot executable, the broad LSET*.WDL layout, and the likely split between map-like regions and graphics-like regions.
• The earlier region00-first viewer export is now known to be based on a bad assumption: the ~45..59 records it exposes per map are only the small top-level WDL descriptor stream, not the full level content.
• The stronger current model is a multi-section bundle layout: a top-level 0x18-byte dispatch-record table, typed subordinate resource tables rooted at DAT_800758cc/d0/d4/d8, and at least one separate compressed level-state blob that is inflated into DAT_8006769c by FUN_8003b00c(..., 0x3e00, 0x3e00).
• The strongest current graphics source remains post_audio_region_04.
• A first PSX debug scene has already been exported experimentally, but the active workflow is now the renderer-local .cache pipeline rather than site output.
• The active live probe now builds provisional real-art atlases in map_renderer/src/build-psx-cache.js from map_renderer/STATIC_PSX into .cache/psx, .cache/reference-data/psx-remorse, and .cache/scene-cache/psx-remorse/....
• The current verified processed build exposes 62 PSX maps in the live renderer catalog under the runtime-record scene format (4032 atlas-backed shapes, 1925 packed shared atlases after the latest atlas pass).
• The exporter root cause is now clearer: the old five-region post-audio carve was still masking the real visible payload. Loader-sized post_audio_section_00 contains both the small 0x18 root descriptor rows and the dense 24-byte bulk placement rows, so the cache builder now recovers both visible families from that first real section instead of from the guessed region00/region01 split.
• A verified full rebuild now carries region00 + region01 across all 62 maps. LSET1/L0.WDL now emits 1189 items, LSET1/L1.WDL emits 754, and every rebuilt map now reports uniqueZCount > 1 instead of the earlier mostly-flat z = 0 export.
• The next subordinate layers are now structurally split too: DAT_800758d8 is the per-type art/template bank, DAT_800758d0 feeds the simple constructor's local component payload, and DAT_800758cc/d4 feed the compound constructor's state/variant tables. The renderer-side serialization gap is now closed too: the current psx-runtime-record-probe-v6 path exports those banks into stateLayers, and the scene writer preserves them in both scene metadata and mapSource.
• The live viewer now trims the heavyweight stateLayers and decodedRuntimeLayers blobs back out of the interactive runtime scene after load and only reattaches them for scene-JSON export. That keeps the executable-backed research payload reversible without forcing normal pan/zoom interaction to carry the full PSX bank dumps.
• The compound-bank finder is broader now too. When a typed-section-16 bank is not found at a parsed section boundary, the cache builder falls back to an absolute-file scan, which is how the late DAT_800758cc/d0/d4 source candidates now land in the exported scene state.
• The late LSET template bank is now less speculative too. The currently working map-local DAT_800758d8 candidate is not the old "small typed section" guess; on retail LSET1/L9.WDL it decodes cleanly only when the parser treats the late large section as a bank with an embedded +0x38 start, which is now enough to recover real bundle-backed mappings for a first subset of map types.
• The main visible bulk layer is no longer flat. The accepted region01 placements now use the constructor-backed +0x06 byte as provisional z, and LSET1/L0.WDL currently exports 11 distinct structured elevation levels instead of one forced z = 0 plane.
• One renderer-side mismatch is now closed: PSX sprites use authored item.screen rectangles, and the bounding/highlight overlay path now uses those same authored rectangles instead of recomputing a DOS-style wireframe from provisional world coordinates.
• The executable now closes the last projection stage: authored object coordinates land in object fields +0x3c/+0x40/+0x44 as 16.16 fixed-point values, and FUN_80040d44 / FUN_80040f78 project them with screen_x = y - x and screen_y = 2*z - (x + y)/2 before writing the final screen rectangle at +0x20..+0x2e.
• Palette handling is partially grounded by runtime VRAM evidence, but the per-placement override rule is still missing.
• Palette override provenance is now tighter than that older summary: psx_draw_main_visible_object only applies authored override bytes for visible type bands 0x003e..0x00ab and >= 0x00ac, and it reads them from different source-record words (source+0x06 high byte for the earlier band, source+0x0c high byte for the later band). Types below 0x003e do not take that override path in the main visible helper.
• The render-lane split matters for color too, not just visibility. psx_draw_special_visible_queue reuses the same frame/resource submitters as the main visible pass but does not apply the authored palette override byte at all, so any exporter rule that assumes one palette path for all world-facing objects is now too broad.
• The submitters themselves also separate the palette story by resource class. psx_sprite_resource_submit_frame and psx_image_table_submit_frame both consume the same high-byte override token, but they translate it through different CLUT lookup tables depending on the bound resource kind, so the remaining viewer bug is not just which palette index but which palette table for which resource class and render lane.
• The constructor/resource side is narrower now too. Both psx_object_create_simple_record and psx_object_create_compound_record resolve the drawable resource at spawn time from DAT_800758d8 before the object enters the live update loop, so the remaining repeated-wall problem is no longer best framed as a missing late resource allocator. The open bridge is the family-specific post-spawn state/frame route plus the correct lane-aware palette policy.
• The scene/cache naming now uses executable-backed family names (section0_dispatch_roots, section0_constructor_placements) with the old region00/region01 labels kept only as legacy aliases.
• The offline FUN_8003b00c path now exists in the renderer-local exporter and serializes one candidate on-disk compressed source plus the decoded 0x3e00 state buffer into the cache for each map.
• The type-to-art pass is still open. The exporter now scans parsed per-type template-bank payloads for bundle references, and it no longer promotes the disproven scan-order bundle fallback into visible map art. Unverified types stay on placeholders until the executable state/type path yields a real art binding.
• That loader-shaped bank selection is now already paying off in the live cache: map 9 moved from 0 resolved bundle-mapped items to 111 after the template pass switched to the embedded late-section parse, even though unresolved root-dispatch families such as 0x0042 and 0x0049 still need the downstream state/variant path before they can stop using placeholders.
• Current status: the focused PSX exporter is no longer placeholder-driven on map 104. Placements and projection remain structurally correct, and the current cache now resolves all 1002 records to actual PSX bundle art, but many of those bindings are still provisional donor selections rather than final executable-proved family/resource closure.
• A focused art-binding recovery pass is now landed in the cache builder too; see docs/psx/art-binding-recovery.md for the measured recovery note. The exporter now treats many zero-block DAT_800758d8 constructor-placement types as inherited-art candidates instead of dropping directly to placeholders, first via same-map DAT_800758cc script-signature donors and then via a constrained nearest-donor fallback inside the current 0x003e..0x0064 constructor-placement family band.
• That heuristic materially improved the built cache even though it is still provisional rather than executable-proved. The latest rebuild moved the scene set from 58,262 fallback items / 1,714 bundle-mapped items down to 25,038 fallback items / 34,938 bundle-mapped items. Representative maps such as 0, 9, and 43 are now mostly real-art scenes, while map 104 remains the clear outlier with 866 fallback items versus only 136 bundle-mapped items.
• The newest cache slice shows map 104 is failing in a more specific way than “one unresolved type keeps using one bad wall.” The repeated 0x0042 wall cluster currently spans both section0_constructor_placements (u5=0x0020) and section0_dispatch_roots (u5=0x0030, plus smaller 0x0022 outliers), yet all of those records still collapse onto donor map 85 type 0x0040 bundle 0x0009d304 with palette 0. That means the current donor recovery is over-merging at least two authored/runtime roles before the executable-backed family/resource split is proven.
• The viewer/exporter now has a stronger follow-up for that exact failure mode. Provisional donor matches in the unresolved generic family still do not apply as one coarse mixed-role map:type default, but the cache builder now resolves those rows per authored-family plus raw-u5 cohort and emits actual PSX art instead of synthetic fallback atlases. Focused map 104 validation now exports 52 section0_dispatch_roots-art items plus 950 section0_constructor_placements-art items with 0 fallback records, 1 atlas, and 136 shape definitions.
• That no-placeholder pass is intentionally provenance-heavy instead of pretending closure. Scene mapSource rows now preserve mappingSource and optional artCohort, so wrong-art cases can be audited as cohort-* or emergency-global-donor:* matches without reintroducing placeholders into the live renderer.
• The latest six-track Ghidra pass narrows that unresolved split further. 0x0042 does not have a unique descriptor entry; it shares the same generic descriptor object as the wider 0x003e..0x0050 band. For constructor-placement 0x0042, the strongest current path is now explicit: compound spawn wrapper -> psx_object_create_compound_record -> psx_object_advance_state_script -> main-visible refresh/project -> stage-1 draw. For root-dispatch 0x0042, the dominant u5=0x0030 band and smaller u5=0x0022 outliers currently still look like the same broad main-visible runtime role, with 0x0002 acting more like an orientation/extents variant than a separate lane.
• The same pass also closes the submitter side enough to constrain the next art-binding experiment. In both world-facing lanes, draw-time submitter choice is based on the bound resource header kind: kind == 5 uses psx_image_table_submit_frame, otherwise the executable uses psx_sprite_resource_submit_frame. The HUD/overlay lane is now explicitly separated from that rule for viewer purposes: it can route by overlay-slot policy instead of normal world-object kind checks, and psx_draw_clock_digits_overlay is a fixed image-table user rather than evidence for map-object family binding.
• The newest six-track pass tightens the route-state side as well. Constructor and root-dispatch records both hand their authored lane/flags word into obj+0x1c; current best read is 0x0020 = broad world-visible route gate, 0x0002 = orientation/extents-axis behavior, and 0x0400 = stage-2 special-visible selector. That means the current u5=0x0030 versus 0x0022 split is still better treated as same-family main-visible routing with different orientation behavior, while the actual stage-1 versus stage-2 split should now be sampled through obj+0x1c bit 0x0400 instead of inferred from raw u5 alone.
• The selector side is narrower now too. psx_object_select_state_from_transition_table (DAT_80063b4c row indexed by type - 0x1e) is now a concrete per-type selector source ahead of psx_object_select_state_script, and psx_object_update_interaction_transition shows one forced-selector path that drives helper objects to selector 3 unless they are already in 1 or 3. So the next 0x0042 pass should correlate type 0x0042 transition-table output with the later obj+0x94 live script word instead of treating selector 3/4 only as a generic post-spawn mystery.
• The newest follow-up narrows 0x0042 selector recovery again. Type 0x0042 now has its own transition helper, psx_type42_transition_selector_tick, and that helper can dispatch low turning selectors 3/4 before the +0x94-style runtime latch copy. The current DAT_80063b4c row for type 0x0042 mostly yields higher script selectors, so selector 3/4 cases now look more like pre-latch turn/reseat outcomes than direct row literals.
• The exact descriptor slot is now closed too: psx_type_descriptor_table[0x0042] at 0x80063220 points to the shared row 0x800626f8, whose create/update/release callbacks are psx_spawn_compound_record_advance_state_once, psx_object_refresh_main_visible_and_cleanup, and psx_object_release_to_free_list. Both section-0 constructor placements and root-dispatch rows still enter type 0x0042 through that same initial descriptor family.
• The per-type art/cache lane is narrower too. DAT_800758d8 and DAT_800758c8 no longer read as a simple immutable descriptor table plus separate cache; the active helper first seeds DAT_800758d8[type] with the incoming art header, then writes the built resource pointer back to both slots. So the remaining 0x0042 question is still runtime family/resource selection, but the notes should treat the pair as active per-type art state rather than as a permanently raw-versus-cached split.
• The newest follow-up tightens those two lanes again. The live names now reflect the stronger art/cache read: DAT_800758d8 = psx_type_art_active_header_bank and DAT_800758c8 = psx_type_art_built_resource_bank. On the selector side, psx_type42_transition_selector_tick now has one more concrete gate: it first checks psx_object_is_within_view_margin, then can remap a bucket from psx_object_compute_heading_selector_to_focus and dispatch selector 3/4 before the later latch copy. So the next runtime sample should include both the pre-latch dispatch state and the later obj+0x94-style latch, not just one or the other.
• The route-bit writer question also narrowed, but is not fully closed yet. The recovered anonymous islands now prove that 0x0400 is written in the wider nested runtime state machine (psx_object_state_machine_dispatch_tick) and that psx_object_handle_control_pair_0a mutates related policy state plus object-local bit 0x0200, but this batch still did not pin a direct object-local obj+0x1c |= 0x0400 writer for 0x0042. That keeps the next concrete sample focused on runtime state plus object-local flags rather than assuming the stage-2 bit is only an authored u5 literal.
• Step 2 is now landed on the viewer side as well. map_renderer/src/lib/psx-cache.js now exports a per-item runtimeDiagnostic payload in scene version psx-runtime-record-probe-v10, carrying the split the last Ghidra passes converged on: object-local route flags, selector seed/pre-latch hints, exporter-side latched-state candidate, nested-runtime placeholders, resource-kind hints, and a placeholder slot for the live DAT_800675f8 policy word. The immediate next Ghidra work should now fill those channels for representative map 104 0x0042 items rather than redefining the channel model again.
• That first concrete runtimeDiagnostic pass is now done too. item:25/35 (root 0x0022), item:30/31 (root 0x0030), item:85/86 (constructor 0x0030), and control item:53 now form the fixed map 104 sample pack for future 0x0042 checks instead of broad family-level prose.
• The family bridge is explicit now: psx_dispatch_section0_dispatch_roots and psx_dispatch_section0_constructor_placements still converge through the same shared 0x0042 descriptor row into psx_spawn_compound_record_advance_state_once, then the shared constructor/state path. Family identity still matters as an exporter fence, but it is not a different descriptor family.
• runtimeDiagnostic.objectLocalRouteFlags is better grounded too. Constructors directly copy the authored lane word into obj+0x1c, so the exported initialWord values are real initial authored state. For the current sample pack, 0x0022 is authored { 0x0020, 0x0002 }, while 0x0030 is authored { 0x0020, 0x0010 }.
• runtimeDiagnostic.selector also stays justified as a separate channel from the later latch. Spawn-side selector seeding now has a named bridge through psx_transition_spawn_and_seed_selector_from_record, but 0x0042 still uses psx_type42_transition_selector_tick to emit selector 3/4 before the later latch copy.
• runtimeDiagnostic.nestedRuntimeState remains necessary too. The strongest recovered 0x0400 stage-selection write is still nested-state-side, and this pass still did not pin a direct object-local obj+0x1c |= 0x0400 writer for 0x0042.
• runtimeDiagnostic.typePolicy is narrower now as well. DAT_800675f8 is now explicitly psx_type_policy_table_ptr, installed during level load and then read by type-indexed consumers, so the eventual numeric policy word should be treated as type-global within the loaded level rather than as a per-lane value.
• The next follow-up widened the same concrete sample pack in three practical directions: resource identity, frame-state flow, and explicit routing branches. The strongest current read is still that map 104 0x0042 is not yet split by a different descriptor family or an obvious different bind path; the remaining unresolved split is now mostly bound resource identity plus live frame/state token plus object-local 0x0400 at route time.
• The fixed map 104 sample pack should therefore stay frozen for the next pass: root 0x0022 = item:25/35, root 0x0030 = item:30/31, constructor 0x0030 = item:85/86, control 0x0066 = item:53.
• The storage-side section family is tighter now too. The latest pass promotes DAT_80067938 to psx_ctor_placement_section_ptr: a constructor-placement section installed during wdl_resource_bundle_load_by_index whose rows still read as six-halfword 0x0c-stride records [type, x, y, z, selector, u5]. That strengthens the current read that map-object construction is fed from explicit section-pack row families rather than from one opaque monolith.
• Adjacent section-pack pointers are narrower as well. DAT_80067838 is now at least a real level section base in the same install family rather than an unexplained scalar, DAT_80067840 now reads as a resource_bundle_ptr_table with control/opcode-stream consumers, and DAT_800676d8 now reads as level_clut_table, which keeps it on the palette/CLUT side instead of the missing placement/art side.
• The decompressed lane is tighter too. DAT_8006769c is now confirmed again as psx_level_decompressed_state_buffer, written during wdl_resource_bundle_load_by_index, passed to psx_lzss_unpack_into_level_buffer, and then reused by save/runtime snapshot code. Current best read is that it primarily seeds runtime-bank installs and broader session/runtime state rather than acting as one hidden flat item table.
• The 0x80063e54/0x80063e68/0x800675ec control island is now promoted from background curiosity to an active blocker family. 0x800675ec is now psx_marker_channel_runtime_block, with the strongest current field map at +0x34 mode byte, +0x6c mode-step byte, and +0x88/+0x8c short fields that are still the most plausible presentation-adjacent members. That family still needs an explicit struct/table dump before it can be ruled in or out for map-facing 0x0042 divergence.
• Loader ownership is tighter too: psx_load_type_state_banks now reads as the DAT_800758cc/d0/d4 installer only, psx_stream_install_type_runtime_banks is the packed-stream helper that can install all four banks including DAT_800758d8, and the DAT_80067794 header block now reads as save/transition state through psx_snapshot_level_runtime_header_block / psx_apply_level_runtime_header_block, not as the missing 0x0042 art-binding source.
• The old fallback art binding is now positively disproven for map rendering, not just "still unverified": in the live cache, early section0_dispatch_roots types 0x0042 and 0x0049 repeatedly bind to portrait/talk-animation bundles (for example map 0 offsets 0x000B2970 and 0x000D84F4), which confirms the section-0 dispatch rows are generic runtime-object descriptors whose visible art still depends on downstream per-type state/variant selection.
• The executable-side type path is now clearer and named in the live PSX Ghidra database. psx_object_create_simple_record and psx_object_create_compound_record both index the same per-type banks rooted at DAT_800758d8/d0/cc/d4; psx_object_select_state_script selects an active state script from DAT_800758cc, psx_object_advance_state_script at 0x80025d68 interprets sentinel-driven script records, psx_object_lookup_variant_entry resolves a companion entry from DAT_800758d4, and psx_reset_type_runtime_banks_from at 0x80025ce8 is the nearby bank-reset helper that had been misnamed earlier. So the missing map-render rule is not one flat type -> bundle table but a multi-stage runtime selection path.
• The visible render pass is less opaque now too. FUN_80041378 draws in three stages: the sorted visible-object list through FUN_80041458, a second special-visible list through FUN_80041144, and then HUD/overlay/icon primitives through FUN_800416cc. That means the remaining map-viewer gap is still mainly in world-object and special-object families, not in the HUD pass.
• That draw tail is now named more tightly in Ghidra too: FUN_800416cc is now psx_draw_hud_overlay_pass, and its clock/timer child FUN_8004214c is now psx_draw_clock_digits_overlay.
• The next decompilation target is narrower now too: FUN_8002906c is the highest-value follow-up because it is a verified post-construction state reselection path that can overwrite the live script choice from FUN_8003bc1c(obj) >> 2 & 0xf, which is exactly the missing bridge between exported placement selectors and the art-facing DAT_800758d4 variant lookup.
• The stage-2 path is now strong enough to affect renderer planning directly. FUN_80040f78 is the queue-builder for the FUN_80041144 pass: it projects an object just like the main FUN_80040d44 path but appends it to DAT_80078b70 / DAT_80067472 instead of the main DAT_8006ad5c visible list. So a renderer that only models the stage-1 visible list will still miss a real world-facing object lane.
• The broader lifecycle is readable now too. psx_level_session_loop is the outer level-session loop; wdl_resource_bundle_load_by_index performs the actual SPEC_A.WDL + selected LSET*.WDL load and root-record dispatch; psx_world_frame_tick is the normal per-frame world loop; and FUN_80041378 is the top-level draw submission.
• The authored record passes now line up with the viewer model closely enough to use as the current executable ground truth: psx_dispatch_section0_dispatch_roots dispatches the DAT_80067720 0x18-stride family plus the extra fixed-size entries near DAT_80067658, while psx_dispatch_section0_constructor_placements dispatches the DAT_800678f0 0x0c-stride family. Those are the closest executable matches for the current section0_dispatch_roots and section0_constructor_placements viewer families.
• The live-object passes are separated too: psx_run_live_object_type_updates runs the per-type update callback over the linked live object list at DAT_800675ac, psx_run_live_object_behavior_callbacks runs the later per-object behavior callback stored on each object, and psx_update_motion_and_nearby_interactions is the broad world/player motion integrator that sits between behavior updates and draw submission.
• The cull/draw bridge is now explicit too: psx_authored_record_in_view_bounds gates the two authored record-family dispatch passes, psx_world_point_in_view_bounds gates already-instantiated live objects, and FUN_80041458 draws from the final authored screen rectangle while sourcing palette overrides directly from the original record pointer at obj+0xa0.
• Palette override provenance is tighter too: object field +0xa0 is the original authored source-record pointer written by both constructors, so the current override path in FUN_80041458 is reading authored record bytes directly rather than a hidden runtime side table.
• The cache builder now uses that evidence too: shared PSX reference art is keyed by map:type:palette, and scene export applies the authored palette byte when the source record exposes the proven override lane instead of always baking the bundle default palette.
• One narrow renderer-side consequence is now verified in output, not just in notes: the cache builder now applies the executable-backed 0x0050 selector map (0..3 -> frame 0..3) as a temporary fallback, and retail map 9 now exports type=80 state_selector=1 chosen_frame=1 instead of forcing frame 0.
• The renderer-side state parser is stronger too: the current buildTypeStateFrameMaps path no longer treats each DAT_800758cc selector as a flat first-word frame index. It now follows the currently verified sentinel control flow (0xfffe, 0xfffd, 0xfffc, 0xfffb) when building selector-to-frame candidates from the exported state layer.
• The top-level level-loader header is now tighter too. wdl_resource_bundle_load_by_index reads a 0x38 file header whose first nine dwords are section sizes, allocates a separate 0x50 runtime-header block at DAT_80067794, loads one extra non-contiguous blob at DAT_8006767c, and only then optionally inflates the DAT_8006b5d8 source into DAT_8006769c.
• FUN_80039dc4 is now identified as the applier for that DAT_80067794 level runtime-header block, which means the map-viewer export still lacks one executable-backed level metadata lane even after the section-0 and per-type-bank work.
• The current best read on that runtime-header lane is narrower now: because the downstream refresh helper is shared with input/menu paths too, DAT_80067794 looks more like per-level runtime mode/camera/presentation state than a hidden extra placement layer.
• The state-script control flow is tighter too: 0xfffd is the direct in-family jump control, 0xfffc switches to a subsidiary script table entry immediately, and 0xfffb is the scan-forward variant that consumes the next in-band 0xfffd selector before switching.
• The per-type bank provenance is tighter too. psx_load_type_state_banks runs twice before the selected LSET*.WDL opens and twice again after the level-local lanes are loaded, while the standalone late descriptor stream that fills DAT_800758d8 sits between the second pair. So DAT_800758d8 is definitely its own late bank, and the remaining DAT_800758d0/cc/d4 lanes belong to the adjacent state-bank blobs rather than to the decompressed 0x3e00 map-state buffer.
• The unresolved type path is more clearly dynamic than before: psx_object_lookup_variant_entry is called from both constructors and from psx_object_advance_state_script, so a root-dispatch family can change its visible companion bytes after script jumps instead of fixing them only at spawn time.
• The built scene cache now tightens the remaining 0x0042 blocker too. The exported state_selector label is confirmed to be raw word u4, not a derived guess, while lane is raw word u5. A full cache scan found 3944 type=0x0042 placeholders across 61 maps and showed selectors 0..4, with real 3/4 cases on map-4, map-5, map-8, map-45, map-69, and map-85.
• That same cache scan shows lane and selector are not interchangeable. 0x0042 still clusters mostly on lanes 0x0020 and 0x0022, but there are also lane=0x0030 exports with state_selector=0 (for example on map-108). So the next executable-backed pass should treat u4 as the confirmed selector input and u5 as a separate lane/class byte while tracing the post-advance DAT_800758d4 variant lookup.
• The next narrowing pass is now clearer too: the art-facing variant index is not the raw placement selector byte directly. psx_object_select_state_script stores the authored selector in obj+0x9e, but psx_object_lookup_variant_entry indexes DAT_800758d4 with obj+0x94, the current script word. Two runtime paths (psx_object_reselect_state_from_target_vector and psx_type4_reselect_motion_state) can reseat the active script from psx_object_quantize_motion_heading16(obj) >> 2 & 0xf, so at least some live 0x0042 selectors 3 and 4 come from heading-based runtime reselection rather than from the original record alone.
• The newly traced consumer side narrows that further. psx_object_advance_state_script sign-extends the DAT_800758d4 lookup result into obj+0x30/+0x34/+0x38, and the verified downstream consumers of those fields are collision/contact helpers (psx_object_test_overlap_3d, psx_object_update_contact_block_flags, and the target-bounds reads inside the reselection helpers), not the visible draw path. So the practical exporter change is to serialize DAT_800758d4 as signed companion-extents metadata and stop treating it as the leading candidate for the missing final art table.
• That exporter step is now landed in the viewer-side cache path too. buildTypeCompanionExtentsMaps decodes the exported DAT_800758d4 layer as a u32 count + packed 3-byte signed extents table, scene stateLayers now preserve those decoded extents per type/state, and each exported PSX scene item and mapSource row now carries the resolved companionExtents tuple for its chosen live state when one is available.
• That moves the remaining art problem to a more specific place: unresolved families still need a family-specific rule that explains how the live script word at obj+0x94 interacts with the drawable resource at obj+0x10 after post-spawn reselection. The next useful trace should therefore stay close to those family-specific presentation callers instead of spending more time on generic DAT_800758d4 consumers.
• The latest dispatch-table pass narrows that again for 0x0042 and 0x0049: they do not have unique per-type descriptor entries. Both sit inside the same generic descriptor cluster covering 0x003e..0x0050, and their shared descriptor currently resolves to psx_spawn_compound_record_advance_state_once, psx_object_refresh_main_visible_and_cleanup, and the newly named psx_object_release_to_free_list. So the missing art rule is even less likely to be a special-case table fork and more likely to live downstream in generic object state/resource presentation.
• That runtime bridge is now wider and better grounded than it was when psx_type4_reselect_motion_state first became the top target. The newly named cluster around it shows that type-4 delayed interactions can actively rewrite the live script after spawn: psx_type4_update_delayed_interaction (0x80029c20) seeds a forward-probe delay, psx_type4_reselect_motion_state (0x8002906c) either hands off to psx_object_reselect_state_from_target_vector or recomputes heading from motion state before calling psx_object_select_state_script, psx_object_update_nearby_interactions (0x80029478) is the broader non-type-4 nearby-object sweep, psx_object_test_overlap_3d (0x80028298) is the box-overlap predicate, psx_object_update_contact_block_flags (0x800289f0) updates directional contact/block bits, and psx_object_register_contact_pair (0x8002845c) links both objects into the bilateral contact queue.
• The motion-heading piece is now named too. psx_object_reselect_state_from_target_vector (0x80028c94) writes a target-relative motion vector into obj+0x60/+0x64/+0x68, psx_object_quantize_motion_heading16 (0x8003bc1c) wraps the current object motion vector, and psx_quantize_vector_heading16 (0x8003b980) reduces that vector to one of 16 heading buckets before the caller maps it back to a DAT_800758cc script selector. Combined with the already-verified psx_object_advance_state_script -> psx_object_lookup_variant_entry path, this means the art-facing DAT_800758d4 lookup is driven by the current script word at obj+0x94, not directly by the original placement selector stored at obj+0x9e.
• The local render-routing wrappers are named now too, which sharpens the practical exporter story. psx_spawn_compound_record_advance_state_once (0x80013618) and psx_spawn_simple_record_set_active_flag (0x8001372c) are constructor-side wrappers that immediately push new objects into specific live states, while psx_object_refresh_main_visible_and_cleanup (0x80013688) is a compact stage-1 projector/cleanup wrapper and psx_object_advance_state_and_queue_special_visible (0x80013758) is a compact stage-2 wrapper that advances script state and immediately queues through psx_project_object_special_visible_queue. So the executable already contains small dedicated routing helpers for “advance state, then main visible” versus “advance state, then special visible”, not just one monolithic render path.
• The owner-level bridge is named now too: psx_object_integrate_motion_and_route_visible (0x800131a8) integrates per-object motion, refreshes visibility flags, then advances script state and routes the object into either the stage-1 main visible list or the stage-2 special-visible queue. That means the runtime split relevant to the viewer is not a late draw-only distinction; it is already baked into the per-object motion/update step.
• The drawable-resource side is much tighter now too. Both constructors resolve the per-type art bank and store the resulting drawable resource at obj+0x10 before the object enters the live update loop; the current script word at obj+0x94 is then passed straight through psx_resource_frame_origin_x/y, psx_resource_frame_width/height, and finally into psx_sprite_resource_submit_frame or psx_image_table_submit_frame during the stage-1 and stage-2 draw passes. So the renderer now has a much stronger executable-backed chain from type bank -> object resource pointer -> live frame index -> final primitive submission.
• The builder under that constructor-side handoff is named too: psx_create_image_resource_from_descriptor creates the drawable resource from the per-type art descriptor, using image_resource_bind_vram_slot for single-image type-4 resources and image_bundle_load_to_vram for multi-frame type-5 bundles. That means the remaining viewer gap is no longer “where does the object resource pointer come from”; it is the last live state/variant rule that determines which resource/frame combination unresolved families actually present.
• The stage-1 list machinery is named end to end as well: psx_main_visible_list_add, psx_main_visible_list_remove, psx_main_visible_list_rebucket_object, psx_main_visible_list_refresh_from_live_chain, psx_main_visible_list_sort_range, and psx_main_visible_list_get_sorted_slice are the concrete helpers behind the main visible-object pass that psx_draw_world_visible_passes submits before the stage-2 queue.
• The main-visible ordering rule is no longer safely approximated as a flat screenY sort. psx_main_visible_list_get_sorted_slice refreshes only the stage-1 list before psx_draw_world_visible_passes, and psx_main_visible_list_sort_range then walks dependency counters, class buckets, and world-extent tie-breakers before psx_draw_main_visible_object submits frames. A viewer that only projects coordinates and sorts by one screen axis will still miss part of the executable's coherence model even when art binding is otherwise correct.
• The level-load side is part of the same coherence chain too. psx_level_session_loop calls wdl_resource_bundle_load_by_index for the selected SPEC_A.WDL/LSET*.WDL pair, that load path applies level_palette_header_apply, and level_palette_header_apply immediately calls level_palette_upload_cluts. So the runtime CLUT tables consumed later by psx_sprite_resource_submit_frame and psx_image_table_submit_frame are installed during level load before any world-object draw routing begins.
• The remaining repeated-wall outlier is now tighter in cache evidence too. On map 104, the dominant bad cluster is still type=0x0042, and the current scene cache repeatedly shows it binding cross-map-cc-signature-donor:85:0040 with template_type=64, donor_type=64, bundle_offset=0x0009d304, and requested_palette_index=0 resolved_palette_index=0. That means the current visible failure there is not primarily “wrong palette variant picked from a recovered family”; it is still the wrong runtime family/resource presentation rule for that unresolved root-dispatch band.
• The same evidence now sharpens the next repair rule too: keep authored family identity and raw u5 class visible until the executable proves a shared resource path. map 104 currently shows that matching only on donor template/signature is broad enough to merge section0_constructor_placements and section0_dispatch_roots into the same wall art even when their current runtime role is still unproven.
• Practical consequence for the viewer plan: the exported placement selector is now firmly only an input, not a final art choice. The immediate placeholder problem is removed for the focused exporter path, but the next bridge still must model post-spawn interaction/reselection well enough to replace cohort-* and emergency-global-donor:* provenance with tighter executable-backed family/resource/frame rules.
• JL-9 already appears in recovered PSX weapon-name tables, but gameplay availability and sprite identity are not yet closed.

Success Criteria

Map-viewer success

• At least one PSX map loads in the existing viewer with stable world placement, defensible draw order, and recognizable room/layout structure.
• The PSX path reuses the existing viewer pipeline instead of creating a separate one-off viewer.
• Exported scene data preserves enough raw metadata to keep later decomp passes reversible.

Palette success

• Bundle export chooses the same palette family the runtime uses for that placement class.
• At least one tile-heavy scene and one object-heavy scene render with mostly correct colors without manual palette swapping.
• Palette selection logic is encoded in exporter metadata or viewer-side decode rules, not only in prose notes.

JL-9 success

• JL-9 is classified as one of: fully usable weapon, cut/incomplete leftover, menu-only string, or debug-only grant.
• The unlock or acquisition path is identified from executable logic, data tables, or authored content.
• The weapon's sprite or best candidate art bundle is identified and documented.

Workstreams

1. Close the PSX map record format

Purpose: replace the invalid small top-level record stream == whole level assumption with a renderer-fed scene that includes the real bulk map substrate.

Tasks:

1. Revisit the executable loader chain around the LSET*.WDL stream consumer and name the section families loaded into DAT_800678f4, DAT_80067720, DAT_800758cc/d0/d4/d8, DAT_800675f8, and DAT_8006769c.
2. Prove which loaded section is the small top-level object/dispatch list and which section holds the actual bulk map substrate.
3. Recover the format and semantics of the compressed blob that FUN_8003b00c inflates into the 0x3e00 level buffer.
4. Tie one concrete subordinate record family to the constructor inputs that feed object +0x3c/+0x40/+0x44 as 16.16 fixed-point coordinates.
5. Recover the bundle/frame binding rule for map placements well enough to stop relying on broad candidate pairing.
6. Recover the draw-order or layer rule used when multiple map records overlap.
7. Validate the corrected multi-section schema on at least L0.WDL and L1.WDL so the decode is not overfit to one level.
8. Dump the installed section-pack/runtime tables after level load for map 104, especially psx_ctor_placement_section_ptr, psx_type_policy_table_ptr, level_clut_table, and the 0x80063e54/0x80063e68/psx_marker_channel_runtime_block family.
9. Correlate those live table rows against the fixed map 104 0x0042 sample pack (item:25/30/31/35/85/86) before widening any donor or family heuristics again.

Expected output:

• a stable PSX placement schema recorded in docs/psx/
• one exporter that emits scene JSON in the same broad shape as the existing viewer pipeline
• one known-good reference map whose structure is visually recognizable

2. Close palette selection instead of guessing it

Purpose: make exported graphics match the runtime palette path automatically.

Tasks:

1. Continue from the already identified texture draw helpers and the caller path that reads palette override metadata from the object field currently described as +0xa0 in the notes.
2. Determine whether the placement record itself, a second-stage runtime header, or a side table supplies the override palette index.
3. Reconcile the live VRAM row 0xF0 / x=0 success case against the on-disk palette blob so the export path can reproduce the runtime source instead of only matching dumps.
4. Identify whether different bundle modes or resource classes use different CLUT selection rules.
5. Add exporter-side palette metadata that preserves both bundle default palette and resolved placement palette.
6. Validate against at least three anchor assets: one wall/floor-heavy tile set, one object sprite with obvious color identity, and one UI or portrait-like asset.

Expected output:

• a documented palette-selection rule in docs/psx/
• exported PSX atlases or frame PNGs that no longer require manual palette picking for the common solved families
• a short unresolved list only for genuinely exceptional palette cases

3. Integrate the PSX decode into the existing map viewer

Purpose: stop treating PSX as a disconnected experiment and make it a first-class renderer source.

Tasks:

1. Define one PSX scene format version that keeps raw decode fields visible while still fitting the current viewer's atlas-plus-scene model.
2. Export one minimal but real PSX map scene from the solved map schema and load it through the existing viewer path.
3. Compare the rendered result against in-game screenshots, captured VRAM/framebuffer evidence, or clearly identifiable room geometry.
4. Tighten the exporter until one map reads coherently before trying to bulk-export the entire disc.
5. Only after a coherent single-map success, generalize to more LSET maps and add any PSX-specific catalog or loader toggles the viewer needs.

Expected output:

• one coherent PSX map visible in the existing viewer
• one stable exporter path that can be iterated on without forking the viewer architecture

4. Investigate JL-9 as data, logic, and art

Purpose: close the question of whether JL-9 is real and what it corresponds to visually.

Tasks:

1. Locate the PSX weapon-name table and the code/data structure that indexes into it.
2. Identify the item or weapon definition row for JL-9, including ammo type, flags, and any inventory/equipability markers.
3. Trace all code and data references to that row: mission rewards, cheats, debug grants, pickups, shop/loadout flow, or scripted usecode equivalents if present.
4. Check whether JL-9 appears in the pre-alpha build under the same index and whether its surrounding data differs from retail.
5. Identify the sprite by following the weapon/item definition to the bundle/frame or icon resource it uses.
6. Classify the result clearly: shipped and obtainable, shipped but gated/unused, or string/data leftover only.

Expected output:

• a short docs/psx/ note or section that states whether JL-9 is real
• the acquisition or unlock path if one exists
• the best supported sprite or bundle match

Recommended Execution Order

1. Finish map-record closure enough to bind placements to the right art.
2. Replace the current .cache runtime-record probe premise with the corrected multi-section WDL model, then recover the runtime type/resource lookup that can replace the still-provisional u0 -> bundle index rule with real art binding.
3. Get one map loading coherently in the existing viewer.
4. After the viewer path is grounded, use the now-stronger bundle identification flow to close JL-9 sprite identity and availability.

Immediate Next Batch

1. In Ghidra, tighten the section-family naming around DAT_800678f4, DAT_80067720, and the candidate DAT_8006b5d8 source so the current section0_* labels can be promoted from exporter-safe names to exact loader names.
2. Record which helpers read DAT_80067720, which apply the separate DAT_80067794 runtime-header block, and which helpers read the decompressed DAT_8006769c buffer now that the offline decode path is present in the cache.
3. Compare the rebuilt all-map exports against recognizable rooms and decide whether the remaining missing structure now lives mainly in the decoded DAT_8006769c buffer or in still-unrendered subordinate tables.
4. Tighten the raw file mappings for the newly exported runtime-bank layers (DAT_800758d8, DAT_800758d0, DAT_800758cc, DAT_800758d4) so their current section selection is proven rather than heuristic. Current delta: the bank split is stronger now. DAT_800758d8 comes from its own late descriptor stream, while DAT_800758d0/cc/d4 belong to the adjacent psx_load_type_state_banks blobs. The remaining open question is the exact sub-split inside those state-bank blobs, not whether they come from the decompressed level-state lane.
5. Split the remaining art/palette problem by render lane and resource class before widening donor logic again. For each repeated-wall family, determine whether it reaches psx_draw_main_visible_object or psx_draw_special_visible_queue, whether its bound resource at obj+0x10 is sprite-kind or image-table-kind, and whether the authored override byte should be interpreted through the main visible override path at all. Current delta: psx_draw_main_visible_object now proves a banded override rule (0x003e..0x00ab -> source+0x06 high byte, >=0x00ac -> source+0x0c high byte), while psx_draw_special_visible_queue skips that authored override entirely. Current delta: psx_sprite_resource_submit_frame and psx_image_table_submit_frame both accept the same high-byte override token but resolve it through different CLUT tables, so the exporter must stop treating palette selection as a type-only scalar. Current delta: the constructors already bind the drawable resource from DAT_800758d8 before any later state transitions, so the remaining aliasing is not best attacked as a missing late bundle lookup. Current delta: the worst visible outlier on map 104 is still type=0x0042 repeatedly mapped to donor map 85 type 0x0040 bundle 0x0009d304 with palette 0, so the next repair pass should treat it first as a wrong family/resource binding problem, not as a missing alternative palette decode. Current delta: the current donor pass is broad enough to merge section0_constructor_placements u5=0x0020 and section0_dispatch_roots u5=0x0030/0x0022 onto that same donor wall, so the next exporter-safe experiment should keep family plus raw u5 as a hard fence before broadening any cross-map donor reuse further. Current delta: that hard fence is now implemented in the viewer cache builder for provisional generic-family donor matches. The cache now prefers honest placeholders over one shared wrong wall when a single type bucket mixes authored families or u5 classes. Current delta: the new subagent sweep says the next split should not be “invent a new per-type descriptor bucket for 0x0042,” because 0x0042 still shares the generic 0x003e..0x0050 descriptor cluster. The next executable-backed discriminator should be runtime-bank content, state progression, resource kind, and lane/flag behavior instead.
6. Recover an actual family-specific state-to-frame rule from the post-spawn runtime path so the exporter can replace the still-provisional state_selector -> chosen_frame fallback with the live obj+0x94 path used by the submitters. Current delta: the unresolved families are clearly dynamic because psx_object_lookup_variant_entry reruns after psx_object_advance_state_script, psx_object_reselect_state_from_target_vector, and psx_type4_reselect_motion_state; the next verified art-binding pass should therefore sample post-jump state, not only constructor-time selectors. Current delta: the executable's coherent-map path is now ordered as load-time CLUT install -> constructor-side resource bind -> per-frame motion/state advance -> stage-1 or stage-2 visibility routing -> stage-1 dependency sort -> frame submission. Any next exporter shortcut should be checked against that order before being treated as a stable map rule. Current delta: draw-time submitter choice is now explicit too. psx_draw_main_visible_object and psx_draw_special_visible_queue both choose psx_image_table_submit_frame only when the bound resource header kind is 5; otherwise they use psx_sprite_resource_submit_frame. So unresolved 0x0042 still needs runtime resource-kind evidence, not just lane or type labels. Current delta: treat the HUD/overlay lane as a false lead for this specific repair. psx_draw_hud_overlay_pass can route through slot flags rather than the normal world-object kind split, and psx_draw_clock_digits_overlay is forced image-table presentation. Neither should be used to infer 0x0042 world-object art binding. Current delta: the next executable-backed sample should be concrete, not another broad sweep. For map 104, trace at least one constructor-placement type=0x0042 u5=0x0020 case and one root-dispatch type=0x0042 u5=0x0030 case through obj+0x10 resource kind, obj+0x94 live script word, and final world-facing lane so the exporter can decide whether these are truly separate presentation families. Current delta: the concrete sample pack is now fixed. Use item:25/35 as the root 0x0022 control, item:30/31 as the root 0x0030 control, and item:85/86 as the constructor 0x0030 control before widening any art-binding experiment. Current delta: include obj+0x1c in that concrete sample. The next trace should explicitly record whether bit 0x0400 is ever set for representative map 104 0x0042 objects, because that is now the strongest recovered stage-2 selector and is more decisive than raw u5 by itself. Current delta: include the per-type transition-table row in that same sample. For type 0x0042, inspect the DAT_80063b4c row used by psx_object_select_state_from_transition_table and compare its selector outputs against the observed obj+0x9e / obj+0x94 values; that is now the clearest route to explaining selector 3/4 cases without reopening broad donor heuristics. Current delta: do not stop at the latched obj+0x94 value. For representative 0x0042 cases, sample the pre-latch selector dispatch path through psx_type42_transition_selector_tick as well; selector 3/4 can be selected there before the runtime latch copy, so a pure obj+0x94 snapshot can still miss the active turn-state choice. Current delta: treat DAT_800675f8 as policy, not as the main route discriminator. 0x1000 is now best read as nearby-publication suppression after stage-2 routing, 0x0600 as stage-1 ordering class, and 0x2000 as main-visible semitrans policy. The next 0x0042 split still belongs first to obj+0x1c, pre-latch selector behavior, and bound resource kind. Current delta: include the early-gate side in that same sample. psx_type42_transition_selector_tick now clearly checks psx_object_is_within_view_margin before the pre-latch turn/reseat dispatch, so the next runtime sample should log whether the object is even eligible to emit the transient selector before trying to explain a final frame choice. Current delta: keep the 0x0400 question scoped correctly. The latest anonymous-island recovery proves wider runtime-state writes and related policy control, but not yet a direct object-local obj+0x1c |= 0x0400 writer. So the next pass should explicitly separate object-local obj+0x1c, nested runtime state words, and global mode bits instead of folding them into one generic “route flag” bucket. Current delta: treat runtimeDiagnostic.typePolicy.word as a level-global per-type value when you do capture it. The latest pass now closes the table role more tightly than before: DAT_800675f8 is a level-loaded type-policy pointer, not a per-lane word source. Current delta: use the new cache export as the comparison surface. The next batch should target concrete mapSource.items[*].runtimeDiagnostic channels in the generated PSX scene JSON and tie live Ghidra evidence back to those exact fields, especially for representative map 104 0x0042 placeholders. Current delta: the next exporter/runtime correlation should add a stable bound-resource identity plus the live frame/state token used at submission if the current fields are not enough. The concrete 0x0042 sample pack now strongly suggests that 0x0022 versus 0x0030 is not itself the final 64x40 versus 64x64 split. Current delta: the route branch itself is no longer vague. psx_object_integrate_motion_and_route_visible now has an explicit obj+0x1c & 0x0400 stage-2 branch point commented in the live database, so the next runtime capture does not need to hunt for the branch location, only to determine whether the concrete sample items ever carry that bit at the decisive moment.
7. Split section-0 placements into at least four executable-backed presentation classes: main-visible objects with authored palette override, special-visible objects without that override, animated runtime-only objects, and clearly non-map-facing UI/talk assets such as the portrait bundles currently surfacing through fallback art matching.
8. Decode the psx_object_advance_state_script sentinel opcodes (ffff, fffe, fffd, fffc, fffb) well enough to tell when a placement loops, jumps into a subsidiary script, or fires a side-effect helper, because that state-machine branch is now the main discriminator between map-facing art and non-map runtime assets. Current delta: fffe is closed as an audio/effect dispatch through psx_script_dispatch_audio_event, fffd is the direct indexed jump, and fffc/fffb are now separated as the immediate subsidiary-switch versus scan-forward subsidiary-switch pair.
9. Recheck the renderer-side palette export against those executable rules before another broad cache rebuild. In particular, verify that map-scene palette variants only use authored override bytes for the type bands and render lanes where psx_draw_main_visible_object actually consumes them, and keep special-visible families on their resource-default path until a stronger rule is proved.

Current delta: live function coverage is now measurable instead of anecdotal. The active SLUS_002.68 session currently has 1274 local 0x800... functions, 917 named and 357 still anonymous, which puts the practical local naming floor at 71.98% and leaves 28.02% still unresolved. The hottest remaining anonymous pages are currently 0x8002exxx, 0x80030xxx, and 0x80049xxx with 21 unknowns each.

Current delta: one adjacent world/update family is now tighter too. The 0x80023c..2b1.. lane is no longer just a pile of anonymous helpers: psx_object_run_control_opcode now owns the local control-stream switch, case 1 is split into psx_control_move_player_to_point and psx_control_move_object_to_point, case 3 is psx_control_wait_ticks, cases 4/5 are now closed as psx_control_configure_fixed_camera_anchor, case 9 is psx_control_set_facing_direction, and case 2 is grounded as a deferred control-command queue (psx_queue_deferred_control_command -> psx_flush_deferred_control_queue -> psx_apply_deferred_control_command -> dispatch-root/live-object appliers). Case 8 is still not named at the wrapper level, but its direct callee is now closed as psx_spawn_object_compound_effect_variant3, which narrows the remaining uncertainty to the wrapper's timing and motion-side effects rather than the spawned effect itself. 8. In parallel with the map pass, trace the palette-override read path from the known draw helper caller and document which source field feeds the resolved CLUT. 9. Locate the JL-9 weapon entry in the PSX executable tables and log its table index, surrounding weapon names, and all code/data xrefs. 10. Create a short follow-up note in docs/psx/ after the batch rather than burying the result only in Ghidra comments.

Documentation Rule For This Track

• Keep long-form findings in docs/psx/psx.md or another dedicated file under docs/psx/.
• Keep this file as the active plan and update it when a major blocker closes or the execution order changes.
• When JL-9 closes cleanly, give it its own short note under docs/psx/ instead of leaving it as one bullet in a larger map note.