Crusader_Decomp/docs/map_renderer/egg-identification.md

# Egg Identification Investigation

## Goal

Add a reliable egg browser to the map renderer and clarify what the game means by an egg "ID".

## Short Answer

- Fresh-game startup is hardcoded to map `1`, egg `0x1e`.
- That startup egg is not read from `CRUSADER.CFG` or another external mission map.
- For Crusader teleport eggs, the destination number that gameplay matches against is the low byte of the item `quality` field.
- The broader egg families use different payload fields depending on egg type, so the renderer should not assume that every egg-family item uses the same number source.

## Fresh-Game Default Start Egg

The existing reverse-engineering note in [docs/first-mission-map-selection.md](k:/ghidra/Crusader_Decomp/docs/first-mission-map-selection.md) already establishes the startup path:

- normal new game calls `Teleporter_CreateProcessDirect(1, 0x1e, 1)`
- the controlling call site is in `Game_Start`
- this is a code-selected default, not a config-file mapping

That means the known first-map spawn uses teleport egg id `0x1e` on map `1`.

## ScummVM Crusader Egg Model

The ScummVM Crusader engine in `engines/ultima/ultima8` maps Crusader egg families as follows:

- family `3` = `SF_GLOBEGG`
- family `4` = `SF_UNKEGG` (usecode trigger egg)
- family `7` = `SF_MONSTEREGG`
- family `8` = `SF_TELEPORTEGG`

Relevant files:

- [shape_info.h](k:/misc/scummvm/engines/ultima/ultima8/gfx/shape_info.h)
- [item_factory.cpp](k:/misc/scummvm/engines/ultima/ultima8/world/item_factory.cpp)
- [egg.cpp](k:/misc/scummvm/engines/ultima/ultima8/world/egg.cpp)
- [egg.h](k:/misc/scummvm/engines/ultima/ultima8/world/egg.h)
- [monster_egg.h](k:/misc/scummvm/engines/ultima/ultima8/world/monster_egg.h)
- [monster_egg.cpp](k:/misc/scummvm/engines/ultima/ultima8/world/monster_egg.cpp)
- [teleport_egg.h](k:/misc/scummvm/engines/ultima/ultima8/world/teleport_egg.h)
- [teleport_egg.cpp](k:/misc/scummvm/engines/ultima/ultima8/world/teleport_egg.cpp)
- [current_map.cpp](k:/misc/scummvm/engines/ultima/ultima8/world/current_map.cpp)

One structural detail matters here: generic trigger eggs and teleport eggs inherit from `Egg`, but `MonsterEgg` is its own `Item` subclass instead of an `Egg` subclass. That helps explain why Crusader monster eggs do not line up perfectly with the generic egg-field conventions.

## Which Field Holds The Number?

There is not one universal answer for every egg-family item.

### Teleport eggs

Teleport eggs are the important case for spawn/start locations.

ScummVM uses:

- `TeleportEgg::getTeleportId()` = `(_quality & 0xFF)`
- `MainActor::teleport(mapNum, teleport_id)` to move to a destination egg
- `CurrentMap::findDestination(id)` to find a teleport egg target with matching low-byte quality

It also distinguishes two teleport egg roles:

- `frame != 1` = active teleporter trigger
- `frame == 1` = destination marker

So for renderer purposes, the gameplay-relevant teleport egg id is the low byte of `quality`, not `mapNum`.

### Generic/usecode eggs

ScummVM's generic egg intrinsics expose:

- `Egg::I_getEggId()` -> `getMapNum()`

So family `4` eggs use `mapNum` as their generic egg id in the engine interface.

Current Crusader viewer work now closes one additional family-4 detail for the `0x0011` placements used as usecode-trigger eggs:

- `quality & 0xFF` is the subtype selector for the authored family-4 usecode class.
- The runtime resolves that class as `0x0900 + QLo`.
- The currently verified authored subtype sets are:
	- Remorse: `QLo 0, 1, 2, 13` -> `TRIGEGG`, `ONCEEGG`, `FLOOR1`, `MISS1EGG`
	- Regret: `QLo 0, 1, 2, 5, 8, 10, 13, 24` -> `TRIGEGG`, `ONCEEGG`, `FLOOR1`, `MHATCHER`, `CHANGER`, `DOOREGG`, `MISS1`, `VIDEOEGG`
- `npcNum` does not behave like a DTABLE row here.
- `xRange = (npcNum >> 4) & 0x0f`
- `yRange = npcNum & 0x0f`
- Crusader multiplies those range nibbles by `64` world units.
- The runtime trigger check also uses a `+/-48` Z window.

That is why the renderer now treats `0x0011` as a proximity/usecode-trigger egg with a projected footprint overlay, a subtype-aware USECODE landing point, and only the narrower local-arrow rules that are actually justified by the recovered subtype body.

### Monster eggs

ScummVM's monster egg accessor exposes:

- `MonsterEgg::I_getMonId()` -> `getMapNum() >> 3`

That is a separate meaning from teleport ids.

There is an important Crusader-specific wrinkle for renderer work:

- the generic ScummVM `MonsterEgg` model stores monster shape in `quality & 0x7FF` and activity in the low three bits of `mapNum`
- but exported No Remorse `0x024F` frame `0` monster eggs often have `quality = 0` and still carry non-zero `npcNum` values that line up with useful DTABLE rows
- concrete exported examples include Remorse map 69 (`npcNum = 2` and `npcNum = 6`) and Remorse map 2 (`rawNpcNum = 5`)
- No Remorse frame `1` `0x024F` entries also exist, but the checked cases were zeroed placeholders with no useful `npcNum`, `mapNum`, or `quality` payload
- exported No Regret `0x024F` currently diverges earlier: its shape definition resolves to `family: 0`, `kind: terrain` rather than `family: 7`, `kind: egg`, so the renderer should not assume that Remorse monster-egg semantics carry over unchanged

So the renderer keeps two interpretations side by side for family `7` eggs:

- the egg-family label remains `monster id = mapNum >> 3`, matching the engine intrinsic surface
- the NPC preview for evidence-backed `0x024F` frame `0` eggs comes from `npcNum`, because that field matches observed spawn identity better than the zero-heavy `quality` field in current Remorse exports

### Glob eggs

Glob eggs expand glob contents using the item `quality` value as the glob reference.

## Renderer Decision

The new map-renderer egg UI treats all egg-family items as eggs, but labels each one with the field that matches its ScummVM family behavior:

- family `8`: teleport id = `quality & 0xFF`
- family `4`: egg id = `mapNum`
- family `7`: monster id = `mapNum >> 3`
- family `3`: glob id = `quality`

That keeps the viewer useful for teleport/start-point work without flattening all egg families into one misleading scheme.

For the NPC preview overlay, the renderer now makes one additional evidence-backed exception:

- `0x024F` frame `0` monster eggs with a non-zero `npcNum` get the same DTABLE-backed blue NPC preview as `0x04D0` spawners

That exception is intentionally narrower than the generic egg browser labels. It reflects the currently verified Remorse data, not a blanket claim that every family `7` egg in every game uses `npcNum` as its authoritative spawn row.

## Current Cross-Game State Of `0x024F`

- No Remorse: exported shape definition resolves to `family: 7`, `kind: egg`, and scene items produce `egg.type = monster-spawn`
- No Regret: exported shape definition currently resolves to `family: 0`, `kind: terrain`, and scene items do not produce egg metadata

That is the strongest current reason to keep the new monster-egg preview support scoped to the evidence-backed Remorse path instead of enabling it globally for both games.

## Weapon Room `250`

The current renderer catalog data already contains egg-oriented notes that include `250` in the known egg-id lists for Crusader egg shapes, which is consistent with the user-observed convention that egg `250` is the weapons room/test room marker.

Those catalog references are evidence for the workflow and UI, but the renderer should still treat them as conventions layered on top of the raw egg-family decoding above.

## Non-Egg Teleporter Carriers

Not every authored teleporter in the exported maps is itself an egg-family item.

- Both retail games use shape `0x01DB` (`TELEPORTER_LIGHTS`) as a non-egg teleporter helper even though the exported shape definition is terrain-like rather than family `8` egg content.
- Current renderer scene exports show both frame `1` and some frame `0` `0x01DB` placements carrying small low-byte `quality` values that line up with real teleport-destination eggs.
- Verified No Remorse examples include map `13`, where frame `1` `0x01DB` items carry `quality & 0xFF = 14` and the map also contains teleport-destination egg `14`, and map `3`, where one frame `1` `0x01DB` carries low-byte `16` and the map contains teleport-destination egg `16`.
- Verified No Regret examples now include map `3` frame-`1` matches (`quality 4 -> destination egg 4`, `quality 2 -> destination egg 2`, `quality 9 -> destination egg 9`) plus the remaining frame-`0` telepad helpers (`quality 27 -> destination egg 27`, `quality 28 -> destination egg 28`), map `5` (`quality 78 -> destination egg 78`), map `10` (`quality 39 -> destination egg 39`, `quality 49 -> destination egg 49`), map `11` (`quality 19/20/21 -> destination eggs 19/20/21`), and map `15` (`quality 22 -> destination egg 22`).

That evidence is strong enough for link-arrow visualization, but it is intentionally narrower than the family `8` egg rule above:

- the renderer now treats frame `0` and frame `1` `0x01DB` placements as teleporter link sources for arrow rendering when they carry an integer destination id in `quality`
- the link key is the low byte of `quality`
- the destination side still comes from real teleport-destination eggs
- this does not yet claim that every `0x01DB` placement or every non-egg teleporter helper in Crusader uses the same schema

## TELEPAD Hardcoding

The current best executable-side explanation for `0x01DB` behavior comes from the checked Crusader usecode disassembly corpus, not from the generic ScummVM egg model.

- `Usecode class 475 (01DB TELEPAD)` is a real authored telepad class in `crusader_disasm.txt`.
- `TELEPAD::gotHit` reads the pad's `quality` into local `theQual` with `Item::I_getQuality`.
- `quality == 0xFF` is treated as inert and exits without a teleport.
- `quality` in the low range `1..0x1d` uses the actor's current map together with the quality value as the egg id, then spawns `TELEPAD::ordinal20` to perform the move.

That means the simple viewer rule for `0x01DB` is not arbitrary UI inference. It matches a real quality-driven telepad dispatch lane.

The same `TELEPAD::gotHit` body also contains explicit hardcoded remaps and special cases rather than one universal `quality -> same-map egg` rule:

- `0x1e -> map 0x28, egg 0x1e`
- `0x1f -> map 0x45, egg 0x45`
- `0x20 -> map 0x04, egg 0x10`
- `0x21 -> map 0x03, egg 0x11`
- `0x23 -> map 0x29, egg 0x1e`
- `0x64 -> map 0x05, egg 0x64`
- `0x65 -> map 0x05, egg 0x65`
- `0x82 -> map 0x19, egg 0x82`
- `0x83 -> map 0x19, egg 0x83`
- `0x84 -> map 0x19, egg 0x82`
- `0x85 -> map 0x19, egg 0x83`
- `0xd7/0xda/0xdb/0xdc -> map 0x05` with matching egg ids

`TELEPAD::ordinal20` then confirms the actual move mechanism:

- the normal lane calls `MainActor::I_teleportToEgg(...)`
- same-map and cross-map forms both appear
- map `0x28` and map `0x29` have extra hardcoded presentation/cutscene handling around the jump process, including `R01`, `B01`, `wec`, `1d`, and `14a` movie names

So the current safest renderer claim is:

- frame `0` and frame `1` `0x01DB` placements are useful cross-game teleporter-link sources when low-byte `quality` matches a real destination egg
- but the full authored gameplay semantics of `TELEPAD` include a hardcoded quality switch with special map-specific behavior, not just generic destination-egg matching

## Elevator Helpers

The checked usecode corpus also closes one separate same-map elevator lane used by visible elevator car objects rather than by egg-family source triggers.

- `Usecode class 542 (021E ELEVATOR)` reads `Item::I_getQLo` and `Item::I_getQHi` from the elevator object itself.
- For same-map moves, `ELEVATOR::gotHit` dispatches `ELEVATOR::ordinal20` with destination egg ids derived from the low quality byte.
- The verified same-map cases are `QLo 1..0x0f -> egg 1..0x0f` and the explicit special case `QLo 0x10 -> egg 4`.
- `QLo 0x11` and `QLo 0x12` are cross-map special cases in the checked body, so the viewer does not currently draw same-map arrows for those values.
- `ELEVATOR::ordinal20` later confirms that the move itself is still a `MainActor::I_teleportToEgg(...)` hop using the caller-supplied egg id and map.

Scene evidence lines up with that lane in No Remorse map `1`:

- `shape:542` quality `0x0101` sits near destination egg `2`, which matches a source platform that teleports to egg `1`.
- `shape:542` quality `0x0202` sits near destination egg `1`, which matches the return platform that teleports to egg `2`.
- the same authored pattern repeats for the other nearby elevator pairs, including `0x0105 -> egg 5` from the far endpoint and the local return platform `0x0206 -> egg 6` beside destination egg `5`.

So the public renderer now treats same-map `shape:542` frame-`0` placements as elevator-link sources when their checked `QLo` values map to a local destination egg id.

## Current Elevator Gap

- No Regret map `3` destination egg `102` does not sit on the same currently verified `ELEVATOR` (`shape:542`) or `LIFT` (`shape:307`) lanes.
- Current scene exports for that map show no nearby `shape:542` or `shape:307` objects at all.
- A nearby editor/helper record `item:1056:fixed:1201:0:41758:33694:0` carries `mapNum 102`, but there is not yet enough executable-side evidence to promote that into a viewer arrow rule.
- The map renderer therefore leaves egg `102` unresolved for now instead of hardcoding a speculative elevator source pattern.

## Adjacent Editor Objects: `0x04E3` And `0x04B1`

These two shapes came up during egg-browser work because they sit near teleporter/elevator/trap authoring patterns, but the current evidence says neither one should be folded into the egg model.

### `0x04E3` frame `0`: `SKILLBOX`

The recovered Crusader usecode corpus has a direct class label here:

- `Usecode class 1251 (04E3 SKILLBOX)`
- the recovered handler is `SKILLBOX::func0A(sint16)`

That body is difficulty-sensitive rather than egg-like.

- it reads `Game::I_getDifficultyLevel()`
- it branches on the object's `frame`
- for `frame == 2`, it reads `Item::I_getQLo(item)`, temporarily adjusts that low-quality byte by difficulty, dispatches `TRIGGER::ordinal20`, then restores the original `QLo`
- for the other frames, it chooses between trigger lane `0` and trigger lane `1` based on a difficulty threshold derived from `frame + 2`
- when `Item::I_getMapArray(item)` is nonzero, the same lane choice is made but with `0x80` added to the dispatched trigger selector

That gives the current best read of the family:

- `frame 0` = difficulty gate that flips at difficulty level `2`
- `frame 1` = difficulty gate that flips at difficulty level `3`
- `frame 2` = special skill-routing form that rewrites `QLo` per difficulty before dispatch

For the specific target in this pass, `0x04E3` frame `0` is therefore best read as a hidden difficulty gate or skill-route selector, not as a teleporter egg, generic egg id carrier, or NPC spawner.

Scene-cache evidence supports that split.

- across cached maps, `0x04E3` appears mostly as `frame 2`, then `frame 1`, with relatively few `frame 0` records (`64` in cached Remorse scenes and `25` in cached Regret scenes)
- `frame 2` payloads cluster strongly by `QLo`, which matches the recovered `Item::I_getQLo(...)` access
- `frame 0` payloads are much more heterogeneous, which fits a gate/controller role better than a simple numeric spawn id
- many dominant `frame 2` records reuse the same `npcNum/mapNum` pairs such as `208/134`, while the low byte of `quality` still varies meaningfully; that makes the low byte look like the authored control value and the other bytes look more like secondary metadata

What helps in the editor:

- label `0x04E3` as `SKILLBOX` instead of generic `Editor Object`
- show `quality` split into `QLo` and `QHi`
- for `frame 0` and `frame 1`, show a small derived note describing the difficulty switch point
- for `frame 2`, show the resolved difficulty lanes explicitly: `diff1 -> QLo`, `diff2 -> QLo + 1`, `diff3+ -> QLo + 2`
- keep `npcNum` and `mapNum` visible, but treat them as raw helper metadata rather than as DTABLE or egg ids

### `0x04B1` frame `0`: trigger/link controller

`0x04B1` still does not have as clean a recovered class label as `SKILLBOX`, but the current usecode evidence already points in one direction.

- an earlier trigger pass found `TRIGGER.slot_20` iterating nearby `shape=0x04B1` items
- that trigger lane compares `Item.getQLo(item)` against a base link id
- it then branches on `Item.getMapNum(item)` flag bits before dispatching additional trigger logic

This pass also re-confirmed that `0x04B1` is grouped with controller/helper shapes rather than with actor payload objects.

- recovered control code such as `ELEVATOR::gotHit` explicitly scans nearby authored helper shapes and includes `0x04B1` in that control-side whitelist
- that keeps `0x04B1` in the same ecosystem as trigger/elevator helper markers rather than DTABLE-driven spawn objects

The currently recovered `cmd` text is not yet a stable class name. It appears as a local variable name in recovered usecode exports, which fits a command/controller interpretation, but that is still weaker evidence than the `SKILLBOX` label above.

Scene-cache evidence strengthens the controller model.

- cached Remorse scenes overwhelmingly use `0x04B1` as `frame 0`
- cached Regret scenes use `0x04B1` across a much wider frame spread (`0` through `10` in the current cache)
- for Remorse `frame 0`, the most common low-byte values are small channel-like numbers such as `1`, `2`, `3`, `5`, `6`, `10`, `20`, `30`, `31`, `40`, `50`, and `60`
- the full `quality` word often changes while the low byte stays on the same small channel number, which is exactly what the earlier `Item.getQLo(...)` trigger evidence would predict
- the frequently repeated `npcNum/mapNum` pairs like `208/134` do not line up with a useful NPC-row interpretation and should stay raw for now

Current best read:

- `0x04B1` frame `0` is a command/link helper used by trigger-style controller logic
- `quality & 0xFF` is the strongest current candidate for the authored link or command id
- `mapNum` is not a destination map; its low bits are routing flags and its high bits contribute to the decoded target shape
- `npcNum` is not a DTABLE row here; it is the low byte of the decoded target selector used by `TRIGGER.slot_21`

The recovered TRIGGER body now gives a more concrete field split for `0x04B1` itself:

- `QLo` = current link id matched against the upstream trigger chain
- `QHi` = subcommand selector in the low three bits, plus a small argument in the upper bits
- `mapNum & 0x03` = command mode
- `mapNum & 0x04` = route into the item-targeting TRIGGER lanes instead of the NPC-triggering side
- `mapNum & 0x08` = phase gate (`set -> phase 0 / 0x80`, `clear -> phase 1 / 0x81`)
- `mapNum & 0x10` = low-priority/deferred execution bucket
- `((mapNum & 0xE0) * 8) + npcNum` = decoded target search shape or sentinel target code

The executable-side read is now concrete enough to say more than "it probably triggers something": several `QHi` subcommands are visibly specific.

- subcommand `0` is a helper-dispatch lane: it walks nearby `0x0476` helpers with the same `QLo` and forwards the upper-bit argument into `FREE.slot_30` using the helper's packed payload fields
- subcommand `1` is a direct target-mutation lane whose exact effect depends on mode: the recovered paths can write `QHi`, write `QLo`, call `equip`, set `frame`, or run a timed `TRIGGER.slot_22 -> DOOR.slot_21` pulse on matched targets
- subcommand `2` is no longer just a placeholder in the editor readout: in the direct item-targeting body it resolves to a frame-set lane using the upper-bit argument as the frame value
- subcommands `4` and `5` are verified link rewrites, adding to or subtracting from the active `QLo` before the controller continues scanning
- subcommand `6` is a create-and-drop lane: it again resolves payload through nearby `0x0476` helpers, creates the target item, copies `Q`, moves it to the helper coordinates, and unequips/drops it

The strongest new practical result is that some authored `0x04B1` records can now be resolved to concrete nearby target shapes instead of staying purely abstract.

- Remorse map `10` contains `0x04B1` items with decoded target shape `0x04D0`, and several of those have nearby same-`QLo` `0x04D0` helper matches.
- The same map also contains `0x04B1` items resolving to decoded target shapes `0x0476` and `0x04E3`, each with local same-`QLo` matches.
- Example authored records include `mapNum=134, npcNum=208 -> target shape 0x04D0`, `mapNum=135, npcNum=118 -> target shape 0x0476`, and `mapNum=134, npcNum=227 -> target shape 0x04E3`.

That still does not mean every `0x04B1` record is fully solved. Some target codes still decode to shapes that need more map-side correlation, and the NPC-triggering versus item-targeting paths do not use every subcommand in exactly the same way. But the object is now clearly more than a generic relay: it is a compact local trigger program that encodes phase, priority, target domain, target shape, link rewrites, and several concrete operation lanes in the standard item fields.

What helps in the editor:

- relabel `0x04B1` from generic `Editor Object` to something like `Trigger Link Controller` or `Cmd Link`
- show `QLo` and `QHi` separately, with `QLo` emphasized
- decode `mapNum` into phase lane, priority, targeting mode, and high-bit target-shape contribution instead of only showing it raw
- decode `npcNum` as the low byte of the target selector
- show the derived target shape or sentinel family code directly in the tooltip
- list nearby same-`QLo` exact-shape candidates when the decoded target shape can be resolved in the current map
- do not attach DTABLE/NPC preview logic to this family
- keep a same-`QLo` highlight/filter action, because that remains the strongest local linkage field even after the target-shape decode

The practical egg-browser outcome is that both shapes are adjacent to egg workflows, but neither one should currently be decoded as an egg-family object. `0x04E3` looks like a difficulty/skill gate, and `0x04B1` looks like a trigger-link controller.

## More Editor Helpers

The next helper batch follows the same pattern: these are controller-side authored objects that sit near eggs, doors, hazards, or alarm setups, but they should stay in their own helper bucket instead of being collapsed into one generic editor-object schema.

### `0x0361` frame `0`: `EVENT`

This one now has a direct recovered class label too.

- `Usecode class 865 (0361 EVENT)`
- recovered body: `EVENT::equip`

`EVENT::equip` is a large event multiplexer rather than a single-purpose marker.

- it immediately reads `link = Item.getQLo(arg_06)`
- it branches on the incoming `event` number
- several branches dispatch `TRIGGER.slot_20`
- other branches touch camera state, audio, NPC actions, doors, and nearby `NUMBERS` helpers

Current best read:

- `0x0361` is a generic scripted event controller/helper
- `QLo` is the strongest authored linkage field currently visible in the recovered body
- `QHi` is used by at least some counter-style branches, so it is worth surfacing too
- `frame 0` should be treated as one authored placement of that broader event family, not as a special egg/NPC record

What helps in the editor:

- override placeholder-style catalog names with `EVENT`
- emphasize `QLo` and `QHi`
- describe it as a generic event controller, not a visible prop

### `0x0500` frame `0`: `STEAMBOX`

This helper also has a direct class label.

- `Usecode class 1280 (0500 STEAMBOX)`
- recovered body: `STEAMBOX::equip`

The recovered handler has two visible controller lanes.

- for `event == 0`, it scans nearby steam-family shapes and matches them by `Item.getQLo(...)`
- for `event == 1`, it scans nearby `shape=0x03A9` items, again matched by `QLo`
- matching items then dispatch into `STEAMBOX.slot_20` or `STEAMBOX.slot_21`

Current best read:

- `0x0500` is a steam hazard/control relay, not a generic placeholder cube
- `QLo` is the authored channel/link id
- `frame` matters on nearby controlled shapes more than on the controller itself

What helps in the editor:

- label it `STEAMBOX`
- show `QLo/QHi` with `QLo` emphasized as the steam channel
- keep the role text focused on nearby steam/hazard linkage

### `0x0561` frame `0`: `ALARMHAT`

This family was already partially documented in the dedicated alarm note, and the extracted body matches that earlier read.

- `Usecode class 1377 (0561 ALARMHAT)`
- recovered body: `ALARMHAT::equip`

The visible structure is local alarm-state control.

- `frame 0` scans nearby `shape=0x04D0` helpers and targets their `frame 0` state
- nonzero frames gate on `Item.isOnScreen(arg_06)` and nearby actor-family presence before scanning the same `0x04D0` family

Current best read:

- `0x0561` is a local alarm-state driver
- it is meant to flip or arm nearby `0x04D0` controller/spawner objects
- `frame 0` is the simple always-check local alarm form; nonzero frames add extra activation conditions

What helps in the editor:

- label it `ALARMHAT`
- add a frame note calling out `frame 0` as the direct local alarm lane
- keep `npcNum`/`mapNum` raw instead of forcing a DTABLE interpretation onto this helper itself

### `0x0581` frame `0`: `ALRMTRIG`

This one is compact and comparatively clean.

- `Usecode class 1409 (0581 ALRMTRIG)`
- recovered body: `ALRMTRIG::equip`

The whole handler is an alert-state relay.

- it checks `Item.getMapArray(arg_06)`
- it checks `World.getAlertActive()`
- it dispatches `TRIGGER.slot_20` with lane `0`, `1`, `0x80`, or `0x81`

Current best read:

- `0x0581` is an alert/alarm trigger relay
- the important authored split is `mapArray == 0` versus nonzero
- the second split is world alert state inactive versus active

What helps in the editor:

- label it `ALRMTRIG`
- show the `mapNum`/`mapArray` byte in hex because it behaves like a flag lane selector here
- describe the four resulting trigger lanes explicitly

### `0x04F8` frame `0`: destroyable-door helper

This shape still lacks a clean No Remorse class label in the recovered tables, but the door-side behavior is already concrete enough to expose in the editor.

- `DOOR.slot_23` iterates nearby `shape=0x04F8` items after the door damage path
- it matches them by `Item.getQLo(deathBox) == Item.getQLo(arg_06)`
- it dispatches `TRIGGER.slot_20` on lane `0` when `Item.getMapArray(deathBox) == 0`
- otherwise it dispatches the `0x80`-offset lane

Current best read:

- `0x04F8` is a door-side helper that lets authored doors become destroyable and then forward into trigger logic
- `QLo` is the local door/link key
- the map-array byte chooses the normal trigger lane versus the `+0x80` variant

That is strong enough to support an editor-facing role hint even though the final class/name provenance is still incomplete.

### `shape_04e3` / `0123only`

The workspace did not yield an exact `0123only` string hit in the current source, catalogs, or extracted usecode artifacts.

Current safest read:

- there is no evidence yet that `0123only` is a separate helper family from `0x04E3`
- the only strong recovered identity for `shape 0x04E3` is still `SKILLBOX`
- treat `0123only` as an external nickname or pending label until a real source hit turns up

So the editor integration should continue to show `SKILLBOX` for `0x04E3` and avoid promoting `0123only` to a canonical name.

### `0x0120`: `FASTSKIL`

This shape is a second skill-family controller, but it is not the same object as `SKILLBOX`.

- `Usecode class 288 (0120 FASTSKIL)`
- recovered handler: `FASTSKIL::enterFastArea()`

The recovered body is short enough to read directly.

- it waits `5` ticks before doing anything
- it only runs the main lane while `Item::I_getMapArray(item) == 0`
- for `frame == 2`, it reads the current `QLo` as a base skill/link id and dispatches `TRIGGER::ordinal20` lane `0` through three difficulty lanes: `diff1 -> QLo`, `diff2 -> QLo + 1`, `diff3+ -> QLo + 2`
- for the non-`frame 2` forms, it does not rewrite the link id; instead it compares difficulty against `frame + 2` and dispatches `TRIGGER::ordinal20` lane `0` below that threshold and lane `1` at or above it

That makes the current best read:

- `0x0120` is a fast-area skill gate/controller, not a generic editor cube
- `frame 0` flips at difficulty `2` (`diff1 -> lane 0`, `diff2+ -> lane 1`)
- `frame 1` flips at difficulty `3` (`diff1/2 -> lane 0`, `diff3+ -> lane 1`)
- `frame 2` is the explicit skill-routing form that remaps the downstream trigger `QLo` by `+0/+1/+2`

For editor arrows, the strongest conservative rule is the same local controller rule already used for other trigger sources, but with the frame-`2` rewrite made explicit.

- `FASTSKIL` can point to nearby `0x04B1` controller helpers when they live in the same local trigger cluster
- for `frame 0` and `frame 1`, the relevant local link key is the source item's current `QLo`
- for `frame 2`, the relevant local link keys are `QLo`, `QLo + 1`, and `QLo + 2`, matching the recovered difficulty lanes
- one concrete Remorse map `13` example is especially strong: a `FASTSKIL` placement and a `0x04B1` controller helper sit at the same coordinates `(35390, 20894)` with matching raw quality `283` / `QLo 27`

This still needs to stay conservative.

- broader scene sweeps do not justify treating every nearby `0x04B1` as a `FASTSKIL` target
- the renderer should therefore stay on the existing local-distance plus explicit `QLo` lane rule instead of inventing a wider object-class relationship
- the tooltip should explain the frame-specific trigger lane or `QLo` rewrite directly so the object reads as a trigger program rather than as another anonymous skill box

## Switch And Helper Follow-Up

This pass tightened several of the still-generic switch/helper shapes that sit next to egg workflows.

### `0x00A1` frame `0`: `PANELNS`

This one now has a direct recovered class label.

- `Usecode class 161 (00A1 PANELNS)`
- recovered handler: `PANELNS::use()`

The body is small and consistent with a plain directional wall panel switch.

- if `frame == 0`, the handler returns immediately
- if `Item::I_getMapArray(item) != 0`, the handler also exits without firing
- otherwise it plays SFX `0xAC` and dispatches `TRIGGER::ordinal20` with lane `0`

Current best read:

- `0x00A1` frame `0` is the idle/inactive visual state of a panel switch family
- the important authored controller key is still downstream `QLo`, because the spawned `TRIGGER` path uses that link namespace rather than `mapNum` or `npcNum`
- sampled Remorse scene caches show nearby same-`QLo` `0x04B1` controller helpers often enough to support editor arrows as a local-assistance layer

### `0x031D` frame `0`: `CARD_NS`

This one also closes cleanly from the recovered usecode corpus.

- `Usecode class 797 (031D CARD_NS)`
- recovered handler: `CARD_NS::use()`

`CARD_NS::use()` is only a thin wrapper. It immediately spawns `SWITCH::ordinal21` on the source item.

`SWITCH::ordinal21` is the more useful body for editor work.

- it reads `Item::I_getQLo(item)` and passes that to `MainActor::I_hasKeycard(...)`
- if the switch is already in `frame 4`, it routes straight into `TRIGGER::ordinal20` lane `0`
- otherwise, with the right card and no alert-state block, it flips to `frame 4`, plays the authorization SFX lane, then dispatches `TRIGGER::ordinal20` lane `0`
- the denied path eventually dispatches `TRIGGER::ordinal20` lane `1`

Current best read:

- `0x031D` frame `0` is a locked north/south keycard switch
- `QLo` is the keycard id and the strongest local link field for controller arrows
- same-map same-`QLo` `0x04B1` matches appear in sampled Remorse scenes, so the renderer can expose them as editor-helper arrows without claiming that the switch talks directly to those helpers in one hardcoded object-only lane

### `0x03AA` frame `0`: `SPANEL`

This shape now has both a direct class label and a second helper-side link path.

- `Usecode class 938 (03AA SPANEL)`
- recovered handler: `SPANEL::use()`

The direct switch body is simple.

- it exits when `mapArray != 0`
- otherwise it conditionally plays SFX `0xAF` for the early-map lane
- it then dispatches `TRIGGER::ordinal20` lane `0`

That closes the same switch-style controller story as `PANELNS`, with `QLo` remaining the practical local link key through the downstream `TRIGGER` chain.

`SPANEL` also appears on the target side of another helper family.

- `BRO_BOOT::enterFastArea()` scans nearby `shape 0x03AA` items
- it compares them by shared `QLo`
- depending on the active mission/global branch, it applies `ITEM::ordinal23` or `ITEM::ordinal24` to those matching `SPANEL` items

Current best read:

- `0x03AA` frame `0` is a switch panel source in the trigger/controller ecosystem
- it is also a helper target for `BRO_BOOT`
- broader exported-scene sweeps now show repeated local same-`QLo` `BRO_BOOT -> SPANEL` matches on Remorse maps `9`, `10`, `11`, `21`, `23`, `160`, and `246`, so the renderer can now expose that helper lane conservatively too

### `0x0366` frame `0`: `NPC_ONLY`

The earlier placeholder label is now closed.

- `Usecode class 870 (0366 NPC_ONLY)`
- recovered handler: `NPC_ONLY::gotHit(uword, word)`

The body is a gated trigger pad rather than a generic editor helper.

- it rejects the hit unless the incoming actor/reference resolves to an NPC-like source
- it reads `Actor::I_GetNPCDataField0x63_00B(actor)`
- it reads `Item::I_getQLo(item)` from the pad and requires those values to match
- with `mapArray == 0` and the occupancy checks satisfied, it flips to `frame 1`, waits briefly, and dispatches `TRIGGER::ordinal20` lane `0`
- once the actor is no longer satisfying the occupancy lane, it restores `frame 0` and dispatches `TRIGGER::ordinal20` lane `1`

Current best read:

- `0x0366` frame `0` is an idle NPC-only trigger pad
- `QLo` is the author-selected NPC-group key, but the executable compares it against actor field `0x63`, not against the scene-export `npcNum` or a simple DTABLE row
- current scene exports do not expose that actor-side field directly, so there is not yet enough evidence to draw trustworthy `NPC_ONLY -> actor` arrows in the renderer
- a follow-up scene-cache sweep also failed to produce a convincing generic `NPC_ONLY -> 0x04B1` helper pattern; shared-`QLo` local matches look incidental rather than like a dedicated authored link lane

That means the safe editor improvement here is naming and field emphasis, not a target-arrow rule yet.

### `0x0403` frame `0`: `FLAMEBOX`

This shape now has a direct class label and a usable local arrow rule.

- `Usecode class 1027 (0403 FLAMEBOX)`
- recovered handler: `FLAMEBOX::equip(sint16)`

The recovered body has two nearby-helper lanes keyed by shared `QLo`.

- event `0` scans nearby flame-family shapes `0x043A`, `0x043B`, `0x050A`, and `0x0518`
- event `1` scans nearby flame editor/helper shapes `0x0438` and `0x0439`
- both lanes compare helper items by `Item::I_getQLo(...) == Item::I_getQLo(flamebox)`
- the event-`1` lane can replace the helper marker with an animated flame actor and then spawns the flame process

Scene-cache checks on Remorse map `1` line up with that lane strongly enough to expose in the editor.

- `FLAMEBOX qlo 24` at `(61310,60830)` has nearby helper `shape 0x0438` at `(61886,60798)`
- `FLAMEBOX qlo 7` at `(60350,49406)` has nearby helper `shape 0x050A` at `(59938,49294)`
- `FLAMEBOX qlo 21` at `(59166,5214)` has nearby `shape 0x0439` matches at `(58814,5790)` and `(59166,5790)`

Current best read:

- `0x0403` frame `0` is a local flame controller
- `QLo` is the authored flame channel id
- editor-helper arrows from `FLAMEBOX` to nearby same-`QLo` flame helper shapes are evidence-backed and now justified

### `0x04E7` frame `0`: `DEATHBOX`

The existing `npc death` nickname was directionally right but incomplete. The recovered class name and caller path now narrow the object down.

- `Usecode class 1255 (04E7 DEATHBOX)`
- recovered helper body: `DEATHBOX::func0A(sint16)`
- recovered caller path: `NPCDEATH::ordinal20` scans nearby `shape 0x04E7` items directly

The strong executable-side lane is in `NPCDEATH::ordinal20`.

- it iterates nearby `DEATHBOX` items
- it compares the incoming death-link value against `Item::I_getQLo(deathBox)`
- if `Item::I_getMapArray(deathBox) == 0`, it dispatches `TRIGGER::ordinal20` lane `0` from the helper item
- otherwise it reads `QHi` and `npcNum` from the helper, can create a keycard with frame `QHi - 1`, can override that keycard's `QLo` from helper `npcNum`, and then dispatches the `0x80` trigger lane

That makes the current best editor-facing read:

- `0x04E7` is an `NPCDEATH` helper/controller, not just a raw death marker
- `QLo` is the death-link match key
- `QHi` carries drop/helper mode information, including the verified keycard lane for values `1..4`
- `npcNum` can act as a secondary payload for the spawned keycard helper path

Current limitation:

- the static scene export does not yet expose the originating NPC death-link values directly enough to draw reliable `DEATHBOX -> source NPC` arrows
- some maps do show local same-`QLo` `0x04B1` helpers near `DEATHBOX`, but the recovered executable path is still clearest as `NPC death event -> DEATHBOX -> TRIGGER`, and a broader follow-up sweep did not justify promoting `DEATHBOX -> 0x04B1` into a generic arrow rule

### `0x04FE` frame `0` / frame `1`: `BRO_BOOT`

This shape is no longer mysterious, even though its local authored targets are not yet consistently visible in sampled scenes.

- recovered class label: `BRO_BOOT`
- recovered handlers include `BRO_BOOT::enterFastArea()` and `BRO_BOOT::leaveFastArea()`

`BRO_BOOT::enterFastArea()` does three important things.

- it branches on a mission/global state lane (`global [001F 01]` in the recovered output)
- it scans nearby `shape 0x03AA` items and compares them by shared `QLo`
- it applies `ITEM::ordinal23` or `ITEM::ordinal24` to those matching `SPANEL` items, then runs its own boot-style frame animation loop

The broader scene cache now supports that link well enough for a renderer overlay.

- follow-up exported-scene sweeps found repeated local same-`QLo` `BRO_BOOT -> SPANEL` matches across Remorse maps `9`, `10`, `11`, `21`, `23`, `160`, and `246`
- one concrete Remorse map `10` example has `SPANEL` item `4538` at `(21018, 13406)` with a nearby `BRO_BOOT` at `(20968, 13784)`, both carrying `QLo 50`

Current best read:

- `0x04FE` is a scripted helper tied to nearby `SPANEL` items, not a free-form generic editor object
- frame `0` and frame `1` are boot-sequence animation states, not independent target ids
- `QLo` is the local authored linkage field for the helper-to-`SPANEL` lane

Current renderer stance:

- this is strong enough to relabel the family as `BRO_BOOT`
- the exported-scene sweep is now broad enough to justify a generic local `BRO_BOOT -> SPANEL` arrow layer based on shared `QLo` plus local distance

### `0x0080` frame `0`: `BOX_EW`

This one closes as another switch-family trigger source.

- `Usecode class 128 (0080 BOX_EW)`
- recovered handler: `BOX_EW::use()`

The recovered body is compact but useful.

- if `mapArray != 0`, it exits without firing
- `frame 0` plays the switch SFX and dispatches `TRIGGER::ordinal20` lane `1`
- nonzero frames dispatch `TRIGGER::ordinal20` lane `0`

The map-side correlation is strong enough to promote a conservative helper-arrow rule, but only for the idle switch state.

- sampled exported scenes show repeated local same-`QLo` `BOX_EW frame 0 -> 0x04B1` matches, including co-located pairs on Remorse map `9`
- the same broader sweep did not justify treating nonzero `BOX_EW` frames as the same generic cmd-link source lane

Current best read:

- `0x0080` is the `BOX_EW` switch family
- `QLo` remains the practical authored controller key for nearby helper scans
- the renderer can safely expose `BOX_EW frame 0 -> nearby 0x04B1` arrows when local distance and `QLo` both match

### `0x04CD` frame `0`: `TRIGPAD`

This family now has a direct class label, but not a new helper-arrow rule.

- `Usecode class 1229 (04CD TRIGPAD)`
- recovered handler: `TRIGPAD::gotHit(...)`

The recovered body behaves like a heavier floor trigger.

- it gates on occupancy and surface checks before the pad arms
- with `mapArray == 0`, it waits briefly, dispatches `TRIGGER::ordinal20` lane `0`, and later dispatches lane `1` as the condition clears
- the same body also loops across nearby elevator-family items and can call `ELEVAT` control slots in that path

Current best read:

- `0x04CD` is a real trigger-pad class, not a generic editor placeholder
- it belongs in the trigger/helper ecosystem, but its executable behavior is broader than a simple `QLo -> cmd-link` switch
- the wider exported-scene sweep did not justify promoting a generic local `TRIGPAD -> 0x04B1` arrow rule, so the safe editor improvement is labeling plus tooltip decoding only

### `0x033A` frame `0`: `NUMBERS`

This family still does not have a cleaner recovered usecode class label than the catalog-facing name, but the scene role is much less ambiguous now.

- exported scenes show `0x033A` as tiny glyph-sized frames, typically `10x16` or `12x16`
- those items repeatedly cluster beside larger sibling shapes such as `0x0501`, `0x0502`, `0x0503`, `0x0505`, and `0x0507`
- the same map-side checks do not make it look like another trigger or cmd-link helper family

Current best read:

- `0x033A` is best treated as a number/readout display helper family
- the renderer should label it clearly so editor users can spot display clusters
- current evidence does not justify helper arrows from `NUMBERS`

## Editor Helper Arrow Overlay

The renderer now exposes a separate nested toggle under `Show editor-only elements` called `Show editor helper arrows`.

That overlay is intentionally narrower than the existing verified teleport/elevator arrow layer. It only draws local helper relationships that have direct usecode support and an evidence-backed authored key:

- `ALARMHAT (0x0561) -> nearby 0x04D0` helpers, using the recovered local alarm scan behavior
- `STEAMBOX (0x0500) -> nearby steam-family targets`, matched by shared `QLo`
- `0x04F8 -> nearby destroyable door-family targets`, matched by shared `QLo` and local placement
- `BRO_BOOT (0x04FE) -> nearby SPANEL targets`, matched by shared `QLo`
- `PANELNS (0x00A1)`, `CARD_NS (0x031D)`, and `SPANEL (0x03AA) -> nearby 0x04B1` controller helpers when they share the same local `QLo`
- `BOX_EW (0x0080) frame 0 -> nearby 0x04B1` controller helpers when they share the same local `QLo`
- `FLAMEBOX (0x0403) -> nearby flame helper shapes`, matched by shared `QLo`
- `EVENT (0x0361)` and `SKILLBOX (0x04E3) -> nearby 0x04B1` controller helpers when they share the same local `QLo`
- `FASTSKIL (0x0120) -> nearby 0x04B1` controller helpers on the same local trigger lanes, with `frame 2` also exposing the recovered `QLo + 1` and `QLo + 2` difficulty variants
- `ALRMTRIG (0x0581) -> nearby 0x04B1` controller helpers by the same lane byte, as a weaker relay-style visualization rather than a claimed final object identity
- `0x04B1 -> nearby exact decoded target shapes` when the TRIGGER field split resolves to a concrete target shape and local same-`QLo` candidates exist

Two newly decoded families stay intentionally out of the arrow layer for now.

- `TRIGPAD (0x04CD)` is now named and decoded in tooltips, but the broader scene sweep did not justify a generic `TRIGPAD -> 0x04B1` helper rule
- `NUMBERS (0x033A)` looks like a display/readout marker family rather than a trigger/controller source, so it stays label-only

The important constraint is that these arrows are editor-assistance overlays, not canonical gameplay graphs. They are meant to expose likely local controller lanes without pretending that every helper object participates in one global id namespace.

## Live Ghidra Notes

The live `CRUSADER.EXE` Ghidra database now also has comment-backed notes at `1020:029e` and `1020:02d0` documenting the startup teleporter precedence that matters for map/egg overrides:

- if the X override remains `-1`, startup stays on the teleporter/egg path
- even when X/Y/Z coordinates are present, a nonnegative `-egg` override still wins and routes through `Teleporter_CreateProcessDirect`

That executable-side note is adjacent to the broader teleporter system rather than to `0x01DB` specifically, but it closes one important runtime rule for interpreting teleport-id driven startup behavior.

## Outcome For The Feature

The egg browser added to the renderer now:

- lists every egg-family item in the loaded map
- shows the decoded id appropriate to that egg family
- can center the camera on a chosen egg and pin-select it
- can draw zoom-stable id labels over eggs in the viewport

## Remaining Uncertainty

Two things are still worth keeping in mind:

- family `7` Crusader handling is still marked in ScummVM as partly suspicious because those records can also behave container-like
- `250 = weapons room` is a strong workflow convention, but this investigation did not add a new executable-side proof beyond the catalog evidence and known reverse-engineering notes