Crusader_Decomp/docs/entity-dispatch-entry-class-layout.md

# EntityDispatchEntry Class Layout

## Purpose

This note is the first focused class-layout working paper for the Remorse C++ lift.

It takes the broad `EntityDispatchEntry*` inventory entry and narrows it into a base/derived object model that can later be pushed into Ghidra as class namespaces, instance structs, vtable structs, and method ownership.

The goal is not to claim a final C++ API. The goal is to lock down the pieces that are already stable enough to support later implementation work.

## Why This Family Goes First

`EntityDispatchEntry` is the strongest current pilot family because it already has:

- a clear constructor-style base init path
- multiple derived constructor variants
- explicit owned state and word-list teardown
- stable field groups with known offsets
- repeated virtual-slot dispatch through known offsets
- strong caller evidence across scheduler, runtime-state, palette, and startup/display lanes

That makes it the best place to prototype the full later workflow:

- class namespace creation
- method ownership
- instance-struct typing
- vtable typing
- base/derived split
- later C++ skeleton emission

## Candidate High-Level Model

Current best working split:

- `EntityDispatchEntryBase`
- `EntityDispatchEntryTimed` or `EntityDispatchEntryPeriodic` for the `0x3aa6` timing/period variant
- `EntityDispatchEntryRuntimeState` for the later `000d:7e00/8078` runtime-state owned-buffer family

This should stay a working model, not a hard rename, until the class work lands in Ghidra.

## Base Constructor Surface

### `0008:ba00` `entity_dispatch_entry_init`

Current best read:

- optional allocate/init path for a `0x32`-byte base object
- stamps base vtable/list-link state using `0x3b06`, `0x2d10`, and `0x3afe`
- zeroes core state fields
- seeds the group/layer byte through `entity_set_group_id`

This is the strongest current candidate for the base constructor-style init method.

### Derived constructor variants

#### `0008:cefb` `entity_dispatch_entry_ctor_vtbl_3ad2`

- allocates if null
- reinitializes through `entity_dispatch_entry_init`
- sets vtable `0x3ad2`
- sets flag `0x100` at `+0x16`
- zeroes extension words `+0x32/+0x34`

#### `0008:d214` `entity_dispatch_entry_ctor_vtbl_3aa6`

- allocates `0x40` bytes if null
- reuses `0008:cefb`
- sets vtable `0x3aa6`
- sets flag `0x200` at `+0x16`
- zeroes fields `+0x38..+0x3e`

#### Related alloc/init helpers

- `0004:ea00 entity_dispatch_entry_alloc_type_0f5e`
- `0004:eb1f entity_dispatch_entry_ctor_0f3a_with_cache_reset`

These look more like subtype-specific factory/create helpers than pure base constructors, but they still belong in the family map.

## Destroy / Release Surface

### Base-owned word-list destruction

#### `0008:dbec` `entity_word_list_destroy`

- resets vtable to `0x2d10`
- frees list storage if present
- optionally frees object when destroy flag bit `1` is set

This is the clearest current destructor-style path on the base object.

### Runtime-state release

#### `000d:8078` `entity_dispatch_entry_release_runtime_state`

- frees paired owned buffers
- updates shared hold/owner propagation through `g_active_dispatch_entry_farptr`
- destroys embedded word-list members

This reads as the release/destructor path for the runtime-state derived family rather than for the whole base type.

## Current Base Layout

This table is a working layout, not a finished header.

| Offset | Current name | Confidence | Current meaning |
|---|---|---|---|
| `+0x00` | `type_or_kind` | Medium | Constructor/factory helpers stamp type words such as `0x0f3a`, `0x0f5e`, or `0x051e` here in some subfamilies. Base-vtable interpretation remains separate. |
| `+0x02` | `slot_index_or_count` | Medium | Used as entry slot/index in several wrappers; also used as count in the base word-list family, so exact role may vary by subtype or overlay. |
| `+0x04` | `source_type` | High | Written by `entity_set_source_type`. |
| `+0x06` | `event_type_or_list_ptr_lo` | Medium | Written by `entity_set_event_type_checked`, but also participates in word-list storage in the list-owning variant. This is likely one of the current overlay collisions to resolve later. |
| `+0x08` | `group_id_byte` | High | Low 5-bit group/layer value managed by `entity_set_group_id`. |
| `+0x0a/+0x0c/+0x0e/+0x10` | `link_or_state_words` | High | Cleared by `entity_dispatch_entry_unlink`; belong to link/extent/target/reset state. |
| `+0x12/+0x14` | `target_farptr` | High | Managed by `entity_flag20_*_target` helpers. |
| `+0x16` | `flags1` | High | Holds bits `0x10`, `0x20`, `0x100`, `0x200`, `0x4000`, and other subtype/state gates. |
| `+0x18` | `flags2` | High | Holds bits `0x40`, `0x80`, `0x100`, `0x400`, `0x1000`; used by unlink, periodic, and refresh paths. |
| `+0x1e/+0x28` | `embedded_dispatch_or_word_list_members` | Medium | Many callsites treat these as subobject or vtable-dispatch bases. Exact split still needs a dedicated subobject note. |
| `+0x24/+0x26`, `+0x2e/+0x30` | `optional_member_ptrs` | Medium | Checked before freeing both embedded word-list members. |
| `+0x32/+0x34` | `extension_words_a` | High | Zeroed by the `0x3ad2` constructor variant; also used by later runtime/VM helper flows. |
| `+0x36/+0x38/+0x3a` | `period_or_schedule_words` | Medium | Written by `entity_set_update_period_and_reschedule`; clearly timing-related in the periodic variant. |
| `+0x3c/+0x3e` | `accumulator_words` | High | Used by `entity_periodic_accumulate_and_dispatch`. |
| `+0x40` | `hold_token` | High | Shared/borrowed hold byte in startup/display and runtime-state families. |
| `+0x41/+0x42/+0x44` | `runtime_state_flags` | High | Initialized by `entity_dispatch_entry_init_runtime_state`. |
| `+0x46/+0x48` | `owned_buffer_a` | High | Runtime-state owned work/palette-like buffer. |
| `+0x4a/+0x4c` | `owned_buffer_b` | High | Second runtime-state owned buffer. |
| `+0x49` | `file_family_selector` | High for the seg126 subtype | Local selector state in startup/display transition family. Likely subtype-specific, not general base meaning. |
| `+0x5b` | `state_flags` | High for the seg126 subtype | State-machine bits in the `000c` startup/display lane. Likely subtype-specific overlay. |
| `+0x520` | `selected_resource` | Medium | Loaded file/resource object in the transition-file-family subtype. |

## Important Layout Caveat

This family is almost certainly not one flat struct with universally stable semantics at every offset. Current evidence already shows subtype overlays:

- base scheduler/dispatch-entry state
- word-list-owning variants
- periodic/timer variants
- startup/display transition variants
- runtime-state/palette-backed variants

So the safest future Ghidra modeling strategy is:

1. create a minimal `EntityDispatchEntryBase`
2. create derived or overlay structs for subtype-specific tails
3. avoid prematurely forcing every offset into one monolithic universal class layout

## Candidate Method Map

### Strong base methods

| Address | Current function | Candidate method role |
|---|---|---|
| `0008:ba00` | `entity_dispatch_entry_init` | `InitBase()` |
| `0008:bbb6` | `entity_set_source_type` | `SetSourceType()` |
| `0008:bc27` | `entity_set_event_type_checked` | `SetEventTypeChecked()` |
| `0008:bca8` | `entity_set_group_id` | `SetGroupId()` |
| `0008:bd53` | `entity_dispatch_entry_unlink` | `Unlink()` |
| `0008:be05` | `entity_increment_group_id` | `IncrementGroupId()` |
| `0008:c01d` | `entity_refresh_dispatch_state` | `RefreshDispatchState()` |
| `0008:bfb2` | `entity_clear_status_bits_from_flags` | `ClearStatusBitsFromFlags()` |
| `0008:bf8e` | `entity_call_update_vfunc14` | `CallUpdateSlot14()` |
| `0008:beee` | `entity_run_flagged_handlers` | `RunFlaggedHandlers()` |

### Pair/link/target helpers

| Address | Current function | Candidate method role |
|---|---|---|
| `0008:c7f1` | `entity_pair_update_link_slot_a` | `UpdateLinkSlotA()` |
| `0008:c890` | `entity_pair_update_link_slot_b` | `UpdateLinkSlotB()` |
| `0008:c92f` | `entity_pair_sync_a` | `PairSyncA()` |
| `0008:ca18` | `entity_pair_sync_b` | `PairSyncB()` |
| `0008:c9ee` | `entity_pair_mark_and_sync_a` | `MarkAndPairSyncA()` |
| `0008:cad7` | `entity_pair_mark_and_sync_b` | `MarkAndPairSyncB()` |
| `0008:cb2c` | `entity_flag20_clear_and_update_target` | `ClearFlag20AndUpdateTarget()` |
| `0008:cb5c` | `entity_flag20_set_and_init_target` | `SetFlag20AndInitTarget()` |

### Periodic/timed subtype methods

| Address | Current function | Candidate method role |
|---|---|---|
| `0008:cefb` | `entity_dispatch_entry_ctor_vtbl_3ad2` | `ConstructVtable3AD2()` |
| `0008:d214` | `entity_dispatch_entry_ctor_vtbl_3aa6` | `ConstructVtable3AA6()` |
| `0008:d313` | `entity_periodic_accumulate_and_dispatch` | `TickPeriodic()` |
| `0008:d3e6` | `entity_set_flag2000_and_update_active_counters` | `EnableActiveCounters()` |
| `0008:d433` | `entity_clear_flag2000_and_update_active_counters` | `DisableActiveCounters()` |
| `0008:d27e` | `entity_set_update_period_and_reschedule` | `SetUpdatePeriodAndReschedule()` |

### Word-list-owning subtype methods

| Address | Current function | Candidate method role |
|---|---|---|
| `0008:da00` | `entity_word_list_set_0408_terminated` | `SetWordList0408Terminated()` |
| `0008:dba3` | `entity_word_list_free_existing` | `FreeWordList()` |
| `0008:dbec` | `entity_word_list_destroy` | `Destroy()` |
| `0008:dc38` | `entity_word_list_ensure_contains` | `EnsureWordListContains()` |
| `0008:dcab` | `entity_word_list_append_unique` | `AppendUniqueWord()` |
| `0008:ddaf` | `entity_word_list_remove_value` | `RemoveWordValue()` |
| `0008:deea` | `entity_word_list_get_at` | `GetWordAt()` |
| `0008:df1b` | `entity_word_list_set_at` | `SetWordAt()` |
| `0008:dfa1` | `entity_word_list_find_unflagged_by_id10` | `FindUnflaggedWordById10()` |

### Runtime-state subtype methods

| Address | Current function | Candidate method role |
|---|---|---|
| `000d:7e00` | `entity_dispatch_entry_init_runtime_state` | `InitRuntimeState()` |
| `000d:8078` | `entity_dispatch_entry_release_runtime_state` | `ReleaseRuntimeState()` |

## Candidate Virtual Surface

The current evidence does not justify a fully named vtable yet, but some slot use is already real:

- `+0x14` = update callback slot used by `entity_call_update_vfunc14`
- `+0x28` = callback slot used by the periodic and proximity-style dispatch helpers
- embedded subobject/member surfaces at `+0x1e` and `+0x28` are also dispatched through helper wrappers in `far-call-targets.md`

Recommended future vtable note shape:

| Slot offset | Current best role | Evidence quality |
|---|---|---|
| `+0x14` | update/refresh callback | High |
| `+0x28` | periodic/dispatch callback | High |
| others | unknown/default stubs | Low |

## Safe Future Ghidra Modeling Steps

When manual class work starts, the safest order for this family is:

1. create class namespace `EntityDispatchEntry`
2. move only the strong base methods first
3. create minimal `EntityDispatchEntryBase` struct with the stable fields through `+0x18`
4. create subtype overlay structs for word-list, timed, and runtime-state tails
5. create a small provisional vtable for only the verified slots

Do not start by forcing one complete 0x520-byte monolithic class.

## Questions To Close Later

- whether `+0x00` should be modeled as a literal `kind` field in all variants or only in some factory-built subtypes
- exact ownership split between the base object and the embedded surfaces at `+0x1e` and `+0x28`
- whether the seg126 startup/display subtype is truly part of the same inheritance family or only shares a lower-level dispatch-entry substrate
- final base-size versus subtype-size boundaries once class namespaces exist in Ghidra

## Immediate Next Documentation Value

The next best companion note after this one is a slot-focused `SpriteNode` virtual table note, because that gives a second family with a cleaner explicit virtual surface and helps calibrate how aggressive the first Ghidra class conversion should be.