Crusader_Decomp/docs/entity-class-family-split.md

Entity Class Family Split

Purpose

This note breaks the large seg001 Entity lane into a conservative class-family model that can later be promoted in Ghidra or emitted as C++ without pretending that every vtable and helper belongs to one monolithic base class.

Current goal is not full inheritance recovery. Current goal is to identify the safest boundaries between:

• one shared gameplay-entity core layout
• projectile-specific allocation and movement behavior
• debris/corpse variants
• registry/helper surfaces that look adjacent but should not be merged automatically

Core Shared Entity Object

Strongest current common object is the gameplay entity body documented in docs/ne-segment1.md.

Stable shared anchors:

• 0007:3f2f entity_spawn
• 0007:40d4 entity_remove
• 0007:4552 entity_set_position
• 0007:4591 entity_try_place
• 0007:5092 entity_deactivate

Stable shared fields from the current note set include:

• +0x00 vtable pointer
• +0x02 slot index
• +0x04 entity type
• +0x19/+0x1a flags
• +0x3c sprite handle
• +0x45/+0x47/+0x49 world position
• +0x4f/+0x51/+0x53 base position
• +0x54/+0x56/+0x58 previous position

This is the safest current candidate for a future Entity or ActorBase style root.

Candidate Split

1. Entity base gameplay family

Best current scope:

• allocation/spawn and placement
• common position, flags, facing, and sprite ownership
• generic remove/deactivate behavior
• registry-facing slot identity

Best current vtable anchor:

• generic/AI entity vtable 0x29aa

Current caution:

• this family likely includes several behaviorally different actors, but the verified note set still supports one shared base before the split gets more specific.

2. ShotEntity or projectile-derived family

Strong anchors:

• 0007:28ce shot_entity_alloc
• 0007:44a9 shot_entity_free
• 0007:4659 projectile_init_vector
• 0007:4b78 projectile_check_hit
• 0007:4c2e projectile_step_update
• 0007:4d28 projectile_trace_ray
• 0007:51ad projectile_update_tick
• 0007:5a99 projectile_apply_hit

Best current distinct evidence:

• dedicated vtable 0x297e
• extra projectile ownership/target fields through +0x6a..+0xbd
• separate shot sprite handle at +0x3f
• dedicated cleanup path in shot_entity_free

Current safest interpretation:

• projectile objects are not just one mode of the generic entity vtable; they deserve at least one derived-family model with their own ctor/free/update surface.

3. DebrisEntity family

Strong anchors:

• 0007:7490 debris_spawn
• 0007:75ff entity_die

Best current distinct evidence:

• dedicated debris/fragment vtable 0x2a57
• corpse/debris-adjacent vtable pair 0x2a1a and 0x2a33
• death-spawn path uses separate velocity/facing behavior rather than only the generic entity update lane

Current safest interpretation:

• debris should stay separate from ShotEntity; both share movement-style fields but not the same lifecycle intent.

4. CorpseEntity or actor-remnant family

Strong current evidence:

• vtable pair 0x2a1a and 0x2a33
• adjacency to entity_die and debris-spawn behavior

Current caution:

• the notes support a corpse/remnant family, but not yet a crisp split between static remains, actor corpse, and debris fragments.
• keep this as a provisional derived branch until a dedicated caller pass closes object lifetime more tightly.

5. Adjacent but probably separate: dialog/menu object lane

Anchor:

• 0007:2c92 dialog_spawn

Why it should stay separate:

• vtable 0x28b5
• callback registration at 0x39ca
• behavior is UI/dialog-style rather than ordinary gameplay entity movement or projectile logic

Current safest interpretation:

• this object is near the entity notes because it lives in the same broad segment lane, but it should not be promoted under the core gameplay Entity family automatically.

Registry And Helper Surfaces That Should Not Be Mis-modeled

Entity registry vtable 0x2969

Current evidence in docs/ne-segment1.md shows 0x2969 stored at 0x39ca + slot*4 as a registry vtable rather than as the entity instance's primary vtable.

That means:

• do not treat 0x2969 as a normal Entity virtual table
• keep registry or handle-table behavior separate from per-instance inheritance

Pure helpers that should remain free functions for now

Examples:

• snap_entity_to_ground
• spawn_entity_checked
• map_find_spawn_point
• actor_find_in_view

These may operate on entities or produce entities, but current evidence still reads better as subsystem helpers than as obvious instance methods.

Recommended Promotion Order

1. model the shared Entity base layout first
2. split ShotEntity next because its ctor/free/update lane is strongest
3. split debris/corpse branches only after one more caller-side lifetime pass
4. leave dialog/menu object modeling separate from the entity inheritance tree

Source-Emission Guidance

If this family is emitted to provisional C++ later, safest first skeleton is:

• one Entity base struct/class with the stable common layout
• one ShotEntity derived placeholder
• one DebrisEntity derived placeholder
• one unresolved CorpseLikeEntity placeholder if needed
• separate DialogMenuObject class rather than folding it into the gameplay entity tree

Bottom Line

The current evidence strongly supports a shared gameplay entity core, but it does not support flattening generic actor, projectile, debris, corpse, and dialog/menu behavior into one class.

The right near-term move is base first, derived families second, adjacent objects separate.