Crusader_Decomp/docs/map_1_spawners_targeted_investigation.md

Map 1 Targeted 0x04D0 Spawner Investigation

Scope

This note closes the specific map-1 question about suspicious 0x04D0 frame-paired monster spawners, especially the cases where nearby frame 0 and frame 1 records point at different DTABLE rows.

Primary evidence used in this pass:

• decompressed cache scene: k:\ghidra\crusader_map_viewer\map_renderer\.cache\scene-cache\remorse\map-1\9ccaa5dabe08947e\scene.json
• extracted pseudocode: MONSTER.slot_0F enterFastArea, MONSTER.slot_0A equip, ITEM.slot_2D
• ScummVM Crusader sources: glob_egg.cpp, actor.cpp, item.cpp, remorse_intrinsics.h, convert_usecode_crusader.h
• live Ghidra instruction windows around 10a0:3889, 10a0:0c40, and 10a0:3d3f

The exact coordinate examples mentioned at the start of the investigation do not appear in this cache hash, so the conclusions below are tied to the decompressed cache currently used by the renderer rather than to an older export or a different build.

Short Answer

• Map 1 really does contain many authored frame-0 / frame-1 0x04D0 pairs.
• Those pairs are not well explained as duplicate placements or viewer noise.
• The nearby-pair match key is QLo = quality & 0xff, not npcNum.
• Frame 0 is the only state checked by MONSTER.enterFastArea.
• In the exact extracted MONSTER.enterFastArea body, the automatic lane is taken when mapNum bit 0x08 is clear, not set.
• Frame 1 is skipped by MONSTER.enterFastArea and remains the strongest practical preview candidate in the currently confirmed auto-enabled map-1 and map-248 pairs.

Verified Usecode Chain

The strongest current chain is:

1. MONSTER.slot_0F (enterFastArea) checks frame == 0 and conditionally routes into MONSTER.equip(...).
2. MONSTER.slot_0A (equip) immediately returns unless the current item is still frame == 0.
3. ITEM.slot_2D scans nearby shape 0x04D0 items, requires a partner with frame == 1, requires the same intrinsic_00EA(...) value on both items, and then calls intrinsic_012F(partner_frame1, source_frame0).
4. intrinsic_012F is the retail create-NPC helper at 10a0:3d3f (Actor::I_createActorCru / Item_Intrinsic12F_CreateNPC).

That is direct evidence that the frame pairing is authored behavior, not just a visual/editor convention.

ScummVM plus the matching retail disassembly split the arguments further:

• the second argument (source_frame0) supplies the DTABLE row through other->getNpcNum()
• the first argument (partner_frame1) supplies facing from item->getNpcNum() & 0x0f
• the frame-1 partner also supplies the difficulty gate from mapNum & 3, the weapon flag from mapNum & 4, the default-activity-1 byte from quality >> 8, and the low-quality unk byte
• the frame-0 source supplies the default-activity-0 byte from quality >> 8 and default-activity-2 from mapNum

That open-source call shape is still useful, but it is no longer strong enough on its own to settle authored spawn identity for every paired 0x04D0 case.

Important Corrections

0x00EA is getQLo, not getNpcNum

An older local parser table still labeled 0x00EA as Item::getNpcNum(void), but stronger sources overrule it:

• ScummVM intrinsic tables map 0x0EA to Item::I_getQLo
• local intrinsic dumps map 10a0:3889 / Int0EA to Item::I_getQLo
• live disassembly at 10a0:3889 masks to the low byte

So the pair-match test inside ITEM.slot_2D is a low-quality-byte comparison, not an NPC-row comparison.

mapNum bit 0x08 needed one more correction

The exact extracted MONSTER.slot_0F body still reads:

• frame == 0 is required
• if (!(a & 8)) spawn MONSTER.equip(...)
• frame == 1 skips that hook

So the safe viewer interpretation stays:

• clear bit 0x08 = automatic enter-area lane enabled
• set bit 0x08 = automatic lane blocked / dormant until another path signals it

Representative Map-1 Cache Pairs

These are concrete decompressed-cache examples from the active hash.

Observer / RoamingSusan pair

• item:186 at 50784, 5888, 0: frame 0, mapNum = 1, npcNum = 6, quality = 1315, preview Observer
• item:187 at the same location: frame 1, mapNum = 10, npcNum = 11, quality = 1315, preview RoamingSusan

Both records share QLo = 35 even though their npcNum values differ.

Observer / ChemSuitGuy pair

• item:635 at 37310, 23102, 0: frame 0, mapNum = 8, npcNum = 6, quality = 1792, preview Observer
• item:636 at the same location: frame 1, mapNum = 7, npcNum = 2, quality = 512, preview ChemSuitGuy

Both records share QLo = 0.

Observer / Guard nearby pair

• item:637 at 37830, 22978, 0: frame 1, npcNum = 4, quality = 2048, preview GUARD
• item:638 at 37846, 22986, 0: frame 0, npcNum = 6, quality = 1280, preview Observer

These are not perfectly colocated, but they are close enough for the viewer's local-pair search and again share QLo = 0 rather than npcNum.

NPC 99 example

• item:14406 near 59864, 35592, 96: frame 0, npcNum = 99

This remains a useful outlier because it shows that odd npcNum values can exist directly on 0x04D0 records. Under the current create-NPC model, a frame-0 npcNum = 99 would mean DTABLE row 99 is the spawn-identity source if that record reaches Actor.createActorCru.

Current Best Model

The safest synthesis from cache, usecode, ScummVM, and live retail disassembly is:

• npcNum still matters because the create-NPC path is DTABLE-backed.
• But the authored pairing between nearby frame-0 and frame-1 0x04D0 records is not keyed by npcNum.
• The pairing key is the low quality byte.
• Frame 0 still owns the verified automatic enterFastArea controller lane.
• Frame 1 is still the required partner state in ITEM.slot_2D.
• But confirmed auto-enabled pairs now fit better if the frame-1 preview is treated as the practical visible-NPC candidate while frame 0 stays the controller-side row.

That explains why map 1 can legitimately contain nearby pairs whose two records name different NPC rows. The pair is not necessarily saying "these are two copies of the same actor". It is more consistent with a split-role authored setup where one 0x04D0 record is the frame-0 controller and the other is the frame-1 paired preview/state row.

Practical Read Of The Map-1 Examples

Under the current model:

• the auto-enabled Observer / RoamingSusan pair is better read as frame 0 controls the lane, but the practical visible-NPC candidate is RoamingSusan
• blocked Observer / ChemSuitGuy and Observer / GUARD pairs still fit a dormant-controller interpretation, so they are not equivalent evidence for the visible actor
• the viewer should stop claiming that frame 0 preview always equals the spawned NPC

So the surprising frame-1 labels are no longer best treated as mere noise or a purely control-side annotation. In the confirmed auto-enabled examples, they are the strongest current practical preview of what actually appears.

Map 248 Follow-Up

Map 248 adds a useful counterexample set because it still contains multiple 0x04D0 records previewing Observer.

Two especially useful stable-ID pairs from the decompressed cache are:

• fixed:4161 at 54656, 56936, 0: frame 1, preview Observer, paired with fixed:4162 frame 0, npcNum = 100, mapNum = 0, same QLo = 63
• fixed:3391 at 59846, 45194, 0: frame 1, preview Observer, paired with fixed:3390 frame 0, npcNum = 134, mapNum = 0, same QLo = 9

Those frame-0 rows matter because the generated Remorse DTABLE used by the renderer currently exposes only rows 0..34. npcNum = 100 and npcNum = 134 do not resolve to known Remorse DTABLE rows at all, while the paired frame-1 rows resolve cleanly to Observer.

There are also several blocked frame-0 Observer rows in map 248 such as:

• fixed:2061 frame 0, preview Observer, mapNum = 8, paired with frame-1 ChemSuitGuy
• fixed:2067 frame 0, preview Observer, mapNum = 8, paired with frame-1 GUARD

That split is important:

• the blocked frame-0 Observer rows fit the dormant-controller interpretation cleanly
• the frame-1 Observer rows paired with auto-enabled frame-0 unknown rows are stronger candidates for the real in-map Observer spawns the user reported

So map 248 does more than merely weaken a blanket claim that frame 0 preview always equals the spawned NPC. It gives a direct contradiction for the old viewer theory:

• the auto-enabled controller row can carry an unresolved out-of-range npcNum
• the paired frame-1 row can still resolve cleanly to the actually reported in-map NPC

Current safest read is narrower:

• frame pairing is definitely real
• QLo still looks like the local match key
• blocked frame-0 rows can clearly be dormant helpers
• auto-enabled confirmed pairs currently line up better with the frame-1 preview as the practical visible-NPC cue
• but the exact which side supplies the final NPC row in all authored cases question still needs one more call-site-level close, because the open-source call signature and the practical map evidence are still not perfectly reconciled

Pair-Class Scan

After the initial targeted examples, a broader cache scan over the active Remorse map-1 and map-248 exports was used to test whether those examples were outliers or a repeatable authored pattern.

For nearest opposite-frame 0x04D0 candidates matched by shared QLo within the renderer's local pair distance:

• map 1 produced 55 auto-enabled mismatched valid pairs, 96 auto-enabled unresolved-controller / resolved-pair cases, and 21 blocked mismatched valid pairs
• map 248 produced 14 auto-enabled mismatched valid pairs, 78 auto-enabled unresolved-controller / resolved-pair cases, and 8 blocked mismatched valid pairs

That matters because it rules out the previous "just a handful of weird examples" escape hatch.

• auto-enabled pairs with different resolved previews are common
• auto-enabled pairs where frame 0 does not even resolve to a valid Remorse DTABLE preview but frame 1 does are also common
• blocked mismatched pairs remain common too, but they fit the dormant-controller interpretation much better than the visible-NPC interpretation

So the current viewer behavior is now intentionally asymmetric:

• auto-enabled paired 0x04D0 previews use a single blue carrier, favoring the practical frame-1 preview side when that side resolves cleanly
• blocked paired 0x04D0 previews use a single red carrier on the dormant frame-0 controller side

That single-carrier rule is what removes the misleading double Observer / RoamingSusan overlays without pretending the underlying create path is fully closed.

Viewer Implications

This pass justifies two concrete renderer behaviors:

• local pair arrows should match nearby opposite-frame 0x04D0 items by shared QLo
• the spawner UI should treat clear mapNum bit 0x08 as auto-enter enabled and set bit 0x08 as dormant / blocked
• paired 0x04D0 previews should render once per pair rather than once per record, using blue for the active carrier and red for dormant controller previews

It does not yet justify a stronger claim that every nearby same-QLo pair is guaranteed to be the runtime pair actually chosen in every scenario. The current overlay should stay local and conservative.

Remaining Uncertainty

• The static Actor.createActorCru argument reading and the practical map evidence are not fully reconciled yet. Map 1 and map 248 now strongly suggest the frame-1 preview is the better viewer-facing NPC cue for confirmed auto-enabled pairs, but the final call-site argument ownership still needs a tighter close in retail disassembly or runtime tracing.
• The user's original coordinates likely came from a different scene export, cache hash, or build, and that mismatch should be kept explicit instead of silently normalized away.
• npcNum = 99 and other sparse/outlier rows still deserve a separate cleanup pass once more map-1 pairs are cataloged.