Crusader_Decomp/docs/map_renderer/trigger-usecode-links.md

Map Viewer Object -> USECODE Links

This note records the current evidence-backed USECODE targets surfaced by the map viewer for pinned editor/controller objects and a small set of non-editor gameplay objects with verified active usecode lanes.

The implementation uses extracted class_event_index.tsv results plus existing controller notes rather than filename guesses. The viewer resolves an exact { className, slot / eventNameHint } pair against the generated usecode cache index and then opens the matching pseudocode body in the USECODE tab.

Stable Viewer Targets

Shape / class	Viewer target	Why this body is the right inspection point
BOX_EW (0x0080)	BOX_EW::use (slot 0x01)	Recovered switch body that dispatches the local QLo link into TRIGGER.slot_20.
0x0011 family-4 usecode egg	Dynamic per QLo: TRIGEGG::hatch, ONCEEGG::hatch, FLOOR1::enterFastArea, MHATCHER::hatch, DOOREGG::hatch, and other authored subtype bodies	The runtime resolves family-4 egg classes as 0x0900 + QLo, so the viewer now opens the exact subtype-selected body instead of treating every 0x0011 as one generic placeholder.
MONITNS (0x0102)	MONITNS::use (slot 0x01)	Existing gameplay notes tie shape 258 / 0x0102 to a live monitor/computer-adjacent use handler, making it a strong non-editor first-view script target.
MONITEW (0x0165)	MONITEW::use (slot 0x01)	Disasm crosswalks shape 0x0165 to the east-west monitor variant, which keeps the same live computer-adjacent use handler family.
PANELNS (0x00A1)	PANELNS::use (slot 0x01)	Verified panel-switch wrapper for the same nearby trigger-helper chain.
PANELEW (0x00A2)	PANELEW::use (slot 0x01)	East-west panel-switch counterpart to PANELNS; nonzero frames with clear map state forward the panel's local QLo into TRIGGER.slot_20 lane 0.
CRUMORPH (0x0318)	CRUMORPH::equip (slot 0x0A)	Recovered control-transfer pad body scans nearby NPCs for a local-QLo control key match, temporarily hands control to the first live hit, and then dispatches TRIGGER.slot_20 lane 0 or 1.
NPCTRIG (0x0363)	NPCTRIG::equip (slot 0x0A)	Crosswalked shape/class match; the compact slot-0x0A body is still the strongest active-event frontier for this trigger family.
CRUZTRIG (0x0365)	CRUZTRIG::gotHit (slot 0x06)	Disasm crosswalks shape 0x0365 to CRUZTRIG, and gotHit is the recovered live body for this trigger/helper family.
VMAIL (0x0367)	VMAIL::slot_0a (slot 0x0A)	Disasm crosswalks shape 0x0367 to VMAIL; slot 0x0A is the active helper body even though its final semantic label is still weaker than the slot number.
CARD_NS (0x031D)	CARD_NS::use (slot 0x01)	Thin wrapper into the downstream SWITCH / TRIGGER path. Regret also exposes cast, but use remains the stable first inspection point.
SPANEL (0x03AA)	SPANEL::use (slot 0x01)	Same local QLo-keyed switch/controller family as PANELNS and CARD_NS.
GENERATR (0x03C1)	GENERATR::gotHit (slot 0x06)	Destroyable generator/controller lane; the recovered body immediately excludes the source item and dispatches TRIGGER.slot_20 lane 0, making it the right first inspection point for power-node objects.
FASTSKIL (0x0120)	FASTSKIL::enterFastArea (slot 0x0F)	Difficulty-gated trigger router, including the verified QLo, QLo + 1, and QLo + 2 remap lane.
SKILLBOX (0x04E3)	SKILLBOX::equip (slot 0x0A)	Corpus-backed skill-gated controller body; this is the active recovered lane, not enterFastArea.
CHEST_NS (0x054F)	CHEST_NS::use (slot 0x01)	The live chest-open handler runs the animation/audio path and the same general FREE-backed content-spawn flow as the east-west chest family.
CHEST_EW (0x0550)	CHEST_EW::use (slot 0x01)	The live chest-open handler runs the animation/audio path and a FREE-backed content-spawn flow, making it a useful general gameplay object target even though it is not editor-centric.
EVENT (0x0361)	EVENT::equip (slot 0x0A)	Large multiplexer body used by the generic event-controller family.
NPC_SPAWNER_04D0 (0x04D0, frame 0)	MONSTER::enterFastArea (slot 0x0F)	Frame-0 spawners participate in the verified MONSTER auto-enter-area lane when map bit 0x08 is clear, so this is now the right first inspection point for authored 0x04D0 placements.
TIMER (0x04C9)	TIMER::enterFastArea (slot 0x0F)	Fast-area timer helper; the first active body arms slot 0x20 from qHi enter/leave flags and the packed mapNum:npcNum delay payload.
SPECIAL (0x04CA)	SPECIAL::enterFastArea (slot 0x0F)	Fast-area phase helper; the active entry body reads mapNum / npcNum as phase bytes and qHi as the delay byte before fanning out through TRIGGER.slot_20 and SPECIAL.slot_21.
TRIGPAD (0x04CD)	TRIGPAD::gotHit (slot 0x06)	Occupancy/surface-gated trigger-pad logic lives in the recovered gotHit body.
NPC_ONLY (0x0366)	NPC_ONLY::gotHit (slot 0x06)	Active hit-driven helper lane; the body gates on an NPC-only actor key, then brackets TRIGGER.slot_20 lane 0 / 1 from the pad itself.
FLAMEBOX (0x0403)	FLAMEBOX::equip (slot 0x0A)	Recovered flame-controller body scans nearby flame helper shapes by shared QLo and can swap helper markers into live flame actors.
SFXTRIG (0x04E2)	SFXTRIG::slot_0a (slot 0x0A)	Disasm crosswalks shape 0x04E2 to the compact event-bearing SFXTRIG helper; slot 0x0A is the stable active body even though a precise semantic label is still weaker than the slot number.
DEATHBOX (0x04E7)	DEATHBOX::slot_0a (slot 0x0A)	The recovered helper body matches death-link QLo and forwards NPC death events into TRIGGER lanes, so opening the helper body is now more useful than leaving the shape unmapped.
BRO_BOOT (0x04FE)	BRO_BOOT::enterFastArea (slot 0x0F)	Verified helper body scans nearby SPANEL items by shared QLo, applies ITEM control slots, and runs the boot animation loop.
STEAMBOX_HAZARD_CONTROLLER (0x0500)	STEAMBOX::equip (slot 0x0A)	Recovered hazard-controller body matches nearby steam helpers by shared QLo and routes them through event 0 / 1 control lanes.
ALARMHAT (0x0561)	ALARMHAT::equip (slot 0x0A)	Local alarm scan that walks nearby 0x04D0 helper items.
ALRMTRIG (0x0581)	ALRMTRIG::equip (slot 0x0A)	Alert relay that selects TRIGGER lanes from map-array and world-alert state.
CMD_LINK (0x04B1, TRIGGER)	TRIGGER::slot_20 (slot 0x20)	High-slot fan-out entry used by nearby controller families; the named low event slots are empty here, so the viewer jumps straight to the first verified active high slot.

Current Rule For TRIGGER

TRIGGER is the one intentional special case.

The extracted class/event tables show no active named slots in the 0x00..0x1f range for TRIGGER, but they do show populated higher slots 0x20..0x2b. Existing renderer notes and exported pseudocode both point to TRIGGER.slot_20 as the shared entry that nearby controller shapes keep spawning when they match on local QLo or phase lane.

That is why the viewer opens TRIGGER.slot_20 for pinned 0x04B1 helpers instead of trying to invent a named event label that the corpus does not support.

TRIGGER.slot_20 is still not fully decoded. The current body is the right landing point for inspection, but several loose or nearly empty branches remain in the recovered pseudocode, especially in the local_04 == 1, local_04 == 2, and parts of the local_04 == 3 fan-out.

Practical Result In The Viewer

• Pinned controller objects and the small set of promoted gameplay objects now expose a USECODE action in the tooltip.
• The action switches the workspace to the USECODE tab.
• The USECODE viewer resolves the exact class/slot target against the generated cache index instead of relying on fuzzy filename search.
• CRUMORPH and NPC_ONLY now also participate in the same cautious local ... -> cmd QLo ... overlay rule used for other TRIGGER.slot_20 controller families, but only for nearby 0x04B1 helpers that actually share the source object's low quality byte.
• 0x0011 usecode-trigger eggs now decode their npcNum nibble-packed X/Y ranges, resolve QLo into the authored family-4 class, open the matching subtype body in the USECODE tab, and draw arrows only for the narrower subtype families whose local target scans are actually recovered.

Actor-Key Family Blocker

• The current static scene/cache export still cannot support trustworthy controller -> actor arrows for the Regret actor-key family.
• The strongest current reason is that the compared value is mutable actor field 0x63, not a stable DTABLE row or an already-exported scene field.
• A direct Regret DTABLE byte check on record offset 0x63 is not enough to close that gap: sampled rows are still zero there, so the actor key is not just a plain NPCDat byte copied into the runtime actor.
• The same recovered corpus shows why the value is unstable: TRIGGER.slot_29 / slot_2B can rewrite actor field 0x63 on nearby matched NPCs, which means the practical link id can change after the map loads.
• Current safest viewer stance is therefore: keep actor-key families named and tooltip-decoded, allow only the already-evidenced local helper arrows, and leave actor-target arrows disabled until a runtime or spawn-time export closes field 0x63 directly.

Known Actor-Key Families

• CRUMORPH (0x0318) compares nearby actor field 0x63 against the pad QLo before transferring control and bracketing TRIGGER.slot_20.
• NPC_ONLY (0x0366) compares the incoming NPC-like source's actor field 0x63 against the pad QLo before bracketing TRIGGER.slot_20 lane 0 / 1.
• WATCHNS / WATCHEW (0x04c6 / 0x04de) have a stronger current local 0x0510 post lane in the viewer, but their deeper watcher body also checks nearby actor field 0x63 against controller QLo.
• THRMBCKN / THRMBCKE (0x0566 / 0x0567 classes) compare nearby Thermatron actor field 0x63 against controller QLo.
• SURCAMNS / SURCAMEW also scan nearby NPCs by actor field 0x63 and controller QLo in their camera/control lane.
• TRIGGER.slot_29 / slot_2B are part of the same ecosystem because one subcommand explicitly rewrites actor field 0x63 on matched nearby NPCs.

0x04F8 remains intentionally outside the USECODE target list for now. The current evidence says it is a destroyable-door helper scanned by DOOR.slot_23, not a proven standalone usecode class the viewer should open directly.

Newly Decoded Field Notes

0x0011 usecode-trigger egg

• The active exported family-4 0x0011 records are proximity/usecode-trigger eggs, not DTABLE NPC spawners.
• mapNum remains the egg id.
• quality & 0xFF is the subtype selector for this family.
• The runtime resolves the usecode class as 0x0900 + QLo.
• Current authored subtype sets are:
  • Remorse: 0, 1, 2, 4, 13 -> TRIGEGG, ONCEEGG, FLOOR1, CHANGER, MISS1EGG
  • Regret: 0, 1, 2, 5, 8, 10, 13, 24 -> TRIGEGG, ONCEEGG, FLOOR1, MHATCHER, CHANGER, DOOREGG, MISS1, VIDEOEGG
• npcNum packs xRange = high nibble and yRange = low nibble.
• Crusader multiplies each nibble by 64 world units and uses a +/-48 Z window for the trigger test.
• TRIGEGG and ONCEEGG route into TRIGGER.slot_20 on hatch/unhatch, so the renderer now draws local arrows to nearby 0x04B1 helpers by shared QLo.
• Regret MHATCHER scans nearby frame-0 0x04D0 helpers whose QLo matches the egg id in mapNum, so the renderer now draws that local helper lane too.
• Regret DOOREGG scans nearby family-1 door objects whose QLo matches the egg id in mapNum, so the renderer now exposes that local door lane.
• Map-13 Remorse CHANGER example fixed:4770 now gives the subtype a concrete local read: egg id 37 (mapNum) sits beside roof tiles whose QLo is also 37, matching the extracted CHANGER::hatch body that destroys nearby roofs keyed by egg id.
• FLOOR1, CHANGER, MISS1*, and VIDEOEGG remain subtype-aware in the tooltip and USECODE target, but they still do not justify a generic local-arrow rule.

0x04C9 TIMER

• The disasm corpus identifies usecode class 1225 as TIMER.
• enterFastArea and leaveFastArea only arm the worker lane; TIMER.slot_20 performs the wait loop and then fans out into TRIGGER.slot_20 with phases 0x80 or 0x81.
• mapNum:npcNum pack the base timer payload as a 16-bit tick count.
• qHi >> 5 selects one of the trim percentages 0, 10, 25, 40, 50, 60, 75, 90, and the worker subtracts that percentage from the packed delay before waiting.
• The low qHi bits act as control flags: bit 0 controls repeat-vs-clear, bit 1 arms on enter-fast-area, bit 2 arms on leave-fast-area, while bits 3 and 4 steer later routing branches inside the worker.

0x04CA SPECIAL

• The disasm corpus identifies usecode class 1226 as SPECIAL.
• enterFastArea / leaveFastArea use mapNum and npcNum as small phase/control bytes rather than DTABLE rows.
• qHi acts as the delay byte used by SPECIAL.slot_21, while QLo remains the local link byte.
• SPECIAL.slot_21 can temporarily add 3 to QLo, route through TRIGGER.slot_20, then restore the original QLo.
• This is enough evidence to promote SPECIAL::enterFastArea as the stable first-view body even though some higher-phase cases still live deeper in slot 0x21.

0x04B1 CMD_LINK

• QLo is the local link id.
• QHi low three bits choose subcommand 0..6, and the upper five bits carry the subcommand argument.
• mapNum low bits decode mode, item-targeting flag, phase lane, and low-priority behavior.
• mapNum high bits plus npcNum build the 11-bit target code used for exact-shape matching or family sentinels.
• nextItem still appears in authored records, but this pass did not recover a stable standalone semantic for it beyond the existing TRIGGER fan-out path.

Editor Catalog Sweep

The viewer catalog currently marks 39 Remorse shapes and 48 Regret shapes as editor objects. The tables below record which entries already have a viewer integration target and which still need examination before they should grow a USECODE link.

Shared Editor Objects

Shape	Catalog name	Status
0x0011	(unnamed)	Integrated: dynamic family-4 USECODE target from QLo, plus local arrows for the recovered TRIGEGG / ONCEEGG, MHATCHER, and DOOREGG lanes.
0x0060	INVISIBLE_WALL_UW	Needs examination for usecode-link integration
0x0061	INVISIBLE_WALL_NS	Needs examination for usecode-link integration
0x0062	INVISIBLE_WALL_EW	Needs examination for usecode-link integration
0x00f1	BROKEN_OVERLAY	Needs examination for usecode-link integration
0x0120	FASTSKIL	Integrated: FASTSKIL::enterFastArea
0x017d	PLACEHOLDER_KEY_CUBE	Needs examination for usecode-link integration
0x0193	SPECIAL_FIRE_WALL	Needs examination for usecode-link integration
0x01b0	LIGHT_BRIDGE_V	Needs examination for usecode-link integration
0x01b1	LIGHT_BRIDGE_H	Needs examination for usecode-link integration
0x0200	NUMBERS	Needs examination for usecode-link integration
0x0361	EVENT	Integrated: EVENT::equip
0x0403	FLAMEBOX	Integrated: FLAMEBOX::equip
0x04b1	CMD_LINK	Integrated: TRIGGER::slot_20
0x04c9	TIMER	Integrated: TIMER::enterFastArea
0x04ca	SPECIAL	Integrated: SPECIAL::enterFastArea
0x04d0	NPC_SPAWNER_04D0	Integrated: MONSTER::enterFastArea for frame-0 placements
0x04e2	SFXTRIG	Integrated: SFXTRIG::slot_0a
0x04e3	SKILLBOX	Integrated: SKILLBOX::equip
0x04e7	DEATHBOX	Integrated: DEATHBOX::slot_0a
0x04fe	BRO_BOOT	Integrated: BRO_BOOT::enterFastArea
0x0561	ALARMHAT	Integrated: ALARMHAT::equip
0x0500	STEAMBOX_HAZARD_CONTROLLER	Integrated: STEAMBOX::equip
0x0581	ALRMTRIG	Integrated: ALRMTRIG::equip
0x05a0	HIDENSEEKR	Needs examination for usecode-link integration
0x05a1	DOOMSDAY_COUNTER	Needs examination for usecode-link integration
0x05b2	MUSIC_CONTROLLER_05B2	Needs examination for usecode-link integration
0x05b3	MUSIC_CONTROLLER_05B3	Needs examination for usecode-link integration
0x05b4	MUSIC_CONTROLLER_05B4	Needs examination for usecode-link integration
0x05b5	MUSIC_CONTROLLER_05B5	Needs examination for usecode-link integration
0x05b6	MUSIC_CONTROLLER_05B6	Needs examination for usecode-link integration
0x05b7	MUSIC_CONTROLLER_05B7	Needs examination for usecode-link integration
0x05b8	MUSIC_CONTROLLER_05B8	Needs examination for usecode-link integration
0x05b9	MUSIC_CONTROLLER_05B9	Needs examination for usecode-link integration
0x05ba	MUSIC_CONTROLLER_05BA	Needs examination for usecode-link integration
0x05bb	MUSIC_CONTROLLER_05BB	Needs examination for usecode-link integration
0x05bc	MUSIC_CONTROLLER_05BC	Needs examination for usecode-link integration
0x05bd	MUSIC_CONTROLLER_05BD	Needs examination for usecode-link integration
0x05be	MUSIC_CONTROLLER_05BE	Needs examination for usecode-link integration

Remorse-Only Editor Objects

No currently unresolved Remorse-only editor rows remain in this note after the NPCTRIG crosswalk promotion.

Regret-Only Editor Objects

Shape	Catalog name	Status
0x00cf	HAND	Needs examination for usecode-link integration
0x01d6	MUTANT_HOOK_CONTROL	Needs examination for usecode-link integration
0x0451	CRAZYEW	Integrated: CRAZYEW::gotHit as a Regret-only NPC wake-up relay; tooltip now treats it as a hit-driven controller rather than a generic editor placeholder.
0x0510	SECRET_DOOR_POST	Integrated as a local arrow target for nearby WATCHNS / WATCHEW controllers that match it by QLo; no separate direct usecode body promoted yet.
0x0548	SECRET_DOOR_SWITCH	Needs examination for usecode-link integration
0x056d	VIDEOBOX	Integrated: VIDEOBOX::equip as the recovered Regret-only gated controller body.
0x05ae	CRAZYNS	Integrated: CRAZYNS::gotHit as a Regret-only NPC wake-up relay; tooltip now treats it as a hit-driven controller rather than a generic editor placeholder.
0x05df	PRESSURE_BARRIER_V	Integrated as a local arrow target for nearby CRYOBOX controllers that match it by QLo.
0x05e0	PRESSURE_BARRIER_H	Integrated as a local arrow target for nearby CRYOBOX controllers that match it by QLo.
0x05e1	CRYOBOX	Integrated: CRYOBOX::equip plus local QLo arrows to nearby 0x05DF / 0x05E0 pressure-barrier faces.

Regret-Only Batch: Watchers, Cryobox, And Wake-Up Relays

• 0x04c6 and 0x04de are no longer anonymous shared editor rows in Regret scenes. The recovered corpus names them WATCHNS and WATCHEW, and both slot_20 bodies scan nearby shape=0x0510 placements before bracketing TRIGGER.slot_20 around their watcher-specific follow-up lane.
• The scene-cache cross-check supports a cautious viewer arrow rule here. Across Regret maps 1, 10, 13, 14, 15, 16, 18, 200, 201, 215, 29, 30, and others, placed WATCHNS / WATCHEW objects repeatedly sit within local helper range of 0x0510 posts and share the same low quality byte even when the raw 16-bit quality differs.
• 0x0510 therefore belongs in the editor as a local secret-door post/helper target, not as an unresolved generic editor placeholder. The recovered watcher body only treats qHi == 0 posts as the text/door-side lane, so the current viewer promotion stays conservative and only adds the local arrow plus tooltip decoding.
• 0x05e1 is now closed as CRYOBOX, not a vague pressure-barrier switch. Its equip body matches nearby 0x05DF and 0x05E0 shapes by shared QLo, then hands off into slot_20 / slot_21 worker lanes that wait on animation state, flip ITEM control slots, and spawn the steam worker path.
• The paired faces 0x05DF and 0x05E0 remain useful human-facing labels as PRESSURE_BARRIER_V and PRESSURE_BARRIER_H, but they no longer belong in the unresolved bucket. In the viewer they are now arrow targets of nearby CRYOBOX controllers instead of unlabeled editor debris.
• 0x0451 and 0x05AE are now closed as CRAZYEW and CRAZYNS. The recovered gotHit bodies are small but concrete: when the incoming hit source is an actor handle (>= 0x00FF), they check NPC.slot_2A and, unless the target is already in activity 12, spawn NPC.slot_2C to wake or re-arm that actor. That is enough to classify them as hit-driven NPC wake-up relays rather than dispensers or volcano-only map art.
• 0x056D is also no longer an unresolved STEAM_COLLISION_SWITCH. The recovered class is VIDEOBOX, and its equip body is a thin global-latch gate that either falls straight into ITEM.slot_21 or runs a short scripted helper loop first. That is enough for a direct usecode-view target even though the higher-level gameplay meaning is still thinner than the WATCH* and CRYOBOX lanes.

Remaining Steps

The next map-viewer USECODE passes should stay evidence-backed and prioritize items that either still appear as generic editor placeholders in the catalogs or already have partial reverse-engineering notes that are not yet promoted into the viewer.

Highest Priority

1. Extend the 0x0011 subtype table beyond the currently promoted TRIGEGG / ONCEEGG, FLOOR1, MHATCHER, DOOREGG, MISS1*, and VIDEOEGG lanes only when the recovered pseudocode justifies a reusable viewer target or arrow rule.
2. Revisit the remaining Regret-only door-side helpers around WATCHNS / WATCHEW, especially 0x0548, to decide whether they form a second stable secret-door lane beyond the now-promoted 0x0510 post targets.
3. Finish the remaining CMD_LINK field write-up: the current tooltip now decodes quality, mapNum, and npcNum, but nextItem still lacks a stable standalone semantic beyond appearing in authored controller records.

Catalog And Viewer Cleanup

1. Sweep the remaining shared editor/controller shapes in the catalog table and promote the next solid names instead of leaving (unnamed) placeholders where the disasm or extracted corpus already gives a stable class anchor.
2. Revisit the 0x05b2-0x05be music-controller cluster and decide whether those shapes belong in the USECODE viewer backlog, a scene-audio note, or both.
3. Recheck the remaining unresolved Regret-only controller shapes (HAND, MUTANT_HOOK_CONTROL, SECRET_DOOR_SWITCH) against the extracted class/event table before adding any direct links.

Gameplay Coverage Extensions

1. Verify whether non-frame-0 0x04d0 placements have a second stable inspection target or should stay documented as paired/helper states only.
2. Revisit helper families that already have partial notes but no viewer promotion yet, especially the invisible-wall/editor-wall lane and any camera/helper markers that forward into event-trigger classes rather than acting as pure geometry.
3. When a family differs by game, keep the stable cross-game viewer target by default and only add game-specific fallback event names after the extracted corpus proves the divergence.

Validation Rules For Future Passes

1. Keep renames grounded in a direct shape/class crosswalk, exported body evidence, or an existing note with clear provenance.
2. After each promotion, rerun the renderer cache build and update this note's sweep tables in the same batch so the backlog stays current.
3. Do not promote callback-holder families like SURCAMNS / SURCAMEW as ordinary active-event objects unless the placed-shape behavior is established, not just the class name.

Current limitation: if a future build changes the active body for a class in one game only, the viewer still prefers the stable cross-game target above and only uses explicit fallback event names where already justified by the extracted corpus.