Crusader_Decomp/docs/remorse-class-candidate-inventory.md

# Remorse Class Candidate Inventory

## Purpose

This note is the working inventory for the first C++-oriented class lift in Remorse.

It is intentionally narrower than a full source plan. The goal here is to identify the object families that already have enough verified evidence to justify explicit class modeling in Ghidra later, even before the MCP layer grows class-authoring endpoints.

Until MCP can create namespaces, move methods, and build typed vtable/struct layouts directly, this note should act as the canonical queue for manual class-upgrade work.

## Selection Rules

A family belongs here only if at least some of the following are already true in the current notes:

- a constructor-style allocator/init path exists
- a destructor, teardown, or release path exists
- one or more stable vtable roots or slot dispatches are known
- instance fields have repeatable meanings across multiple methods
- the family has enough caller context to separate instance methods from generic helpers

Families that are only `callback-shaped` or `object-like` but still lack a safe subsystem label can stay here at lower confidence. They are still useful because they tell us where later class tooling must preserve ambiguity.

## Confidence Scale

- High: enough evidence to start class namespaces, instance structs, and method ownership now
- Medium: class-like enough to inventory and maybe type, but higher-level naming or ownership is still partially open
- Low: strong object mechanics, but subsystem naming or field ownership is still too ambiguous for broad lifting

## Inventory

| Candidate family | Confidence | Current best class-level read | Core evidence | Ctor / create evidence | Dtor / release evidence | Vtable evidence | Size / layout evidence | Immediate lift value |
|---|---|---|---|---|---|---|---|---|
| `EntityDispatchEntryBase` | High | Base dispatch-entry object used by scheduler/event and transition/runtime-state families | `entity_dispatch_entry_init`, repeated field writes, list ownership, flag/state helpers | `0008:ba00 entity_dispatch_entry_init` alloc/init path for `0x32` bytes; variant allocators in `0004:ea00`, `0008:cefb`, `0008:d214` | `0008:dbec entity_word_list_destroy`; `000d:8078 entity_dispatch_entry_release_runtime_state` for runtime-state flavor | base/root vtables `0x3b06`, `0x2d10`, `0x3afe`; derived vtables `0x3ad2`, `0x3aa6`; slot dispatch at `+0x14`, `+0x28` | stable fields at `+0x02`, `+0x04`, `+0x06`, `+0x08`, `+0x0a..+0x18`, `+0x32..+0x3e`, plus runtime-state tail | Strongest pilot family for the first full class-model pass |
| `EntityDispatchEntryRuntimeState` | High | Runtime-state / palette-backed derived dispatch entry with owned buffers and hold-state propagation | runtime-state init/release pair, palette-entry emission families, owner-byte propagation through `g_active_dispatch_entry_farptr` | `000d:7e00 entity_dispatch_entry_init_runtime_state`; several `dispatch_entry_create_*_palette_state*` helpers build this family | `000d:8078 entity_dispatch_entry_release_runtime_state` frees owned buffers and updates hold-state propagation | inherits dispatch-entry behavior; runtime-state users dispatch through vtable slot `+0x08` after waits | owned fields `+0x41/+0x42/+0x44`, paired buffers at `+0x46/+0x48` and `+0x4a/+0x4c` | Excellent second step after the base dispatch-entry type |
| `SpriteNode` | High | Tree-based UI/render node with child links, dirty-state propagation, event dispatch, and destructor ownership | recursive tree helpers, event switch dispatch, dirty/update family, destructor | constructor not yet explicitly named in current notes, but object-init helper and repeated sprite-node ownership patterns are strong | `000b:326e sprite_node_destroy` releases child nodes and frees self | event dispatch through vtable slots `+0x14/+0x18/+0x20/+0x24`; many default vtable stubs identified in seg091 | repeated fields at `+0x19/+0x1b`, `+0x21`, `+0x23`, `+0x29`; global focus pointer interaction at `0x4fd0:0x4fd2` | Strong candidate because virtual surface is already visible and bounded |
| `Entity` | High | Base gameplay entity / actor-like object with multiple derived vtables for generic, shot, corpse, and debris behaviors | stable NE entity layout, repeated lifecycle helpers, projectile/debris subfamilies | `0007:3f2f entity_spawn`; `0007:435e shot_entity_alloc`; `0007:7490 debris_spawn`; `0007:2c92 dialog_spawn` is adjacent but likely separate family | `0007:40d4 entity_remove`; `0007:5092 entity_deactivate`; `0007:44a9 shot_entity_free` for projectile flavor | vtables `0x29aa`, `0x297e`, `0x2a1a`, `0x2a33`, `0x2a57`, plus registry vtable `0x2969`; multiple virtual-slot helper wrappers in raw notes | strong instance layout from `+0x00` through `+0xbd` in `ne-segment1.md` | Central long-term class family, but should probably be split into base + derived subfamilies |
| `DialogMenuObject` | Medium | Small UI/dialog object family sharing one vtable and event-notify wrappers | `dialog_spawn`, menu/cursor event notify wrappers, UI update callback | `0007:2c92 dialog_spawn` allocates object and stamps vtable `0x28b5` | no standalone destructor named yet in current notes | vtable `0x28b5`; `cursor_event_notify_*`, `menu_event_notify_*`, and `ui_update_callback` all behave like method wrappers | enough to establish family ownership, but layout is still thin | Good compact pilot if a smaller UI-oriented family is preferred |
| `WatchEntityController` | Medium | Global controller/watch/camera object with explicit virtual dispatch and startup/display involvement | global object at `0x2bd8`, dispatch wrapper, create-global path, startup/display callsites | `0007:ba00 watch_entity_controller_create_global` delegates to `0007:ba45 watch_entity_controller_create`, stamps type `0x2c2b`, stores global object | no direct destructor identified in current notes | repeated dispatch through vtable slots `+0x24`, `+0x2c`, and `+0x30` | global-object ownership clearer than field layout; seed row at `0x2be4` into callback table | Worth inventorying now because it will benefit immediately from namespace/method grouping |
| `EntityVmRuntime` | High | Main VM runtime object that owns owner-resource helper, cached slot/value state, and category-base setup | creation/load path is structurally stable and repeatedly cross-checked against extracted usecode evidence | `000d:44df entity_vm_runtime_init_from_path_if_configured`; `000d:4c99 entity_vm_runtime_create` | destroy path not fully named in the snippets here, but owner-resource destroy is known and runtime state/save-load consumers are well constrained | not a classic gameplay vtable family in the current notes, but method-style ownership and object fields are stable | object size and field zones strongly implied by `+0x10c/+0x10e`, `+0x117/+0x119`, `+0x1315/+0x1317` and related runtime state | Major lift target because VM readability is a blocker for recompilable source |
| `EntityVmOwnerResource` | High | File-backed helper owned by VM runtime that indexes source tables and materializes owner rows | helper object shape and per-entry loader contract are already tight | `000d:7000 entity_vm_runtime_owner_resource_create` allocates helper/object tables | paired destroy helper `000d:70fd entity_vm_runtime_owner_resource_destroy` is documented in related notes | helper method-table uses slots `+0x04` size-query and `+0x0c` materialization callback | helper-owned count `+0x14`, far-pointer table `+0x10`, paired word table `+0x18`, owner rows stride `0x0d` | One of the cleanest non-gameplay object families for typed struct work |
| `EntityVmContext` | Medium | Per-slot/per-entity VM context object built from runtime and owner-resource data | create/setup/load helpers already have clear ownership, but broader dispatch semantics are still active work | `000d:46ec entity_vm_context_create_from_slot_index` and related masked-create wrappers | no single destroy method is highlighted in the current note set used here | context-side dispatch and busy-state updates through virtual or callback-like method surface at least on the context object | stable fields include `+0x32/+0x34`, `+0xd6/+0xd8`, `+0x102`, `+0x10c/+0x10e`, `+0x11b/+0x11d`, `+0x123` | Important for VM readability, but should follow runtime and owner-resource typing |
| `CacheBackendObject` | Medium | Small backend/cache loader object with DOS file-handle state and method table | constructor and callback roles are already explicit | `0009:5600 cache_backend_object_init` allocates `0x20` bytes and seeds method-table state | no explicit destructor named in current note slice | backend callback roles at `+0x34` and `+0x0c` are verified in cache lookup/load path | concrete `0x20`-byte size; fields at `+0x08`, `+0x0c`, `+0x10`, `+0x14`, `+0x16`, `+0x18`, `+0x1c` | Good contained family for early datatype work |
| `PresentationCallbackBroker` | Low | Video/presentation-state callback broker rooted at `0x4588` | init/teardown/callback slot evidence is real, but subsystem naming remains intentionally conservative | `runtime_callback_object_init_once` family is documented, but not all constructor details are fully promoted here | `runtime_callback_object_teardown_once` and finalize path are explicit | vtable slots `+0x04`, `+0x08`, `+0x0c` all have live evidence | global state at `0x4588/0x458c/0x4590/0x4594/0x4595/0x45a6`; payload fields from caller objects at `+0x12d/+0x12f`, `+0x74f/+0x751` | Useful as a typed broker object later, but not a good first namespace/class pilot |
| `UsecodeDebuggerBreakState` | Medium | Dormant debugger-state object retained in retail binary | clear constructor and method expectations, but retail instantiation path is missing | `1408:0000 usecode_debugger_break_state_create` allocates and initializes the object | no direct destroy path highlighted in current notes | breakpoint gate callbacks through object vtable during `1408:0053` flow | internal tables and state exist, but field map is not yet summarized into one layout note | Good archival class candidate even if not a current gameplay priority |

## Recommended Modeling Order

If the goal is to make later class-authoring work fast and low-risk, the best order is:

1. `EntityDispatchEntryBase`
2. `EntityDispatchEntryRuntimeState`
3. `SpriteNode`
4. `EntityVmOwnerResource`
5. `CacheBackendObject`
6. `WatchEntityController`
7. `Entity`
8. `EntityVmRuntime`
9. `EntityVmContext`
10. `PresentationCallbackBroker`

This order prioritizes bounded families with visible constructors, derived variants, or explicit method tables before the larger gameplay and VM surfaces.

## First Pilot Candidates

### Best pilot: `EntityDispatchEntryBase`

Why it is the safest first full class lift:

- constructor variants are already named
- derived vtable variants are known
- multiple field groups have stable semantics
- destroy/release behavior is present
- it directly exercises the exact MCP features later needed: namespace creation, struct typing, method ownership, and vtable slot labeling

### Smallest bounded pilot: `CacheBackendObject`

Why it is attractive:

- explicit `0x20` size
- explicit create path
- explicit method-table callback roles
- smaller ambiguity surface than gameplay entities or the VM runtime

### Best UI-oriented pilot: `SpriteNode`

Why it is valuable:

- clear virtual event surface
- tree ownership and destructor logic already exist
- likely to benefit quickly from readable class/derived-method naming

## Per-Family Documentation Tasks

For each inventory entry, later class-upgrade work should produce the same minimum artifacts:

1. candidate namespace/class name
2. constructor and destructor list
3. instance-size estimate or known size
4. vtable root(s) and known slots
5. field map grouped by confidence
6. caller ownership notes
7. explicit `keep as free function` list for helpers that should not become methods

## Immediate Follow-Up Notes Worth Writing Later

- dedicated `EntityDispatchEntry` class-layout note with base/derived split
- dedicated `SpriteNode` virtual-slot table note
- dedicated `EntityVmRuntime` / `EntityVmOwnerResource` layout note
- dedicated `Entity` family split note covering base entity, projectile, debris, and corpse variants

## Current Rule Until MCP Catches Up

Do not rely on automatic class listings from the live MCP tools as the class-recovery source of truth. The current output is still noisy and does not reflect the actual game object families well enough for disciplined C++ lifting.

Use this inventory plus the linked evidence notes as the authoritative queue for future class-authoring work.