Crusader_Decomp/docs/sprite-node-class-layout.md

SpriteNode Class Layout

Purpose

This note captures the current class-level read of the SpriteNode family so later Ghidra class work can move quickly and conservatively.

Compared with EntityDispatchEntry, this family has a cleaner explicit virtual/event-dispatch surface and a more bounded ownership model. That makes it an excellent second pilot for class lifting.

Current Best Class-Level Read

SpriteNode is a tree-based render/UI node family with:

• child-chain ownership
• accumulated position and bounds propagation
• dirty-state tracking
• central event dispatch through a small virtual surface
• destructor ownership over child nodes and global focus state

This already looks much closer to an ordinary C++ object family than many gameplay-side structures.

Strongest Evidence Anchors

Destructor

000b:326e sprite_node_destroy

Current best read:

• destructor-style path
• sets vtable ptr to 0x501a
• clears global focus pointer [0x4fd0:0x4fd2] if self
• releases child nodes
• frees object memory through mem_free

This is the strongest current single proof that SpriteNode should be lifted as an owned object family.

Event dispatch

000b:3ab2 sprite_node_dispatch_event

Current best read:

• large event dispatch switch
• checks event types 2/4/8/0x100
• updates global focus pointer at [0x4fd0:0x4fd2]
• dispatches through virtual slots +0x14, +0x18, +0x20, +0x24

This is the strongest current proof of a stable virtual method surface.

Dirty/update family

• 000b:3380 sprite_node_is_dirty
• 000b:33a6 sprite_node_mark_dirty
• 000b:40ee sprite_node_update_and_dispatch

These show that node state changes and redraw/update dispatch are methods on the same family, not just free helper functions wandering across unrelated data.

Recursive tree helpers

• 000a:b988 sprite_node_get_or_traverse
• 000b:358d sprite_tree_accumulate_pos
• 000b:3a00 sprite_tree_sum_x_offset
• 000b:3a35 sprite_tree_sum_y_offset

These are strong evidence for a child-linked tree object with inherited coordinate accumulation.

Candidate Layout

This layout is intentionally conservative.

Offset	Current name	Confidence	Current meaning
+0x19/+0x1b	child_or_next_ptr	High	Child-chain pointer pair used by recursive traversal and offset accumulation.
+0x21	local_x_offset	High	Summed by sprite_tree_sum_x_offset / accumulate helpers.
+0x23	local_y_offset	High	Summed by sprite_tree_sum_y_offset / accumulate helpers.
+0x29	dirty_flags	High	Checked by sprite_node_is_dirty; manipulated by mark/update paths.
+0x17e	redraw_flag	Medium	Cleared by sprite_clear_redraw_flag; likely a subtype or larger-object field tied to one SpriteNode family variant.

Layout Caveat

The current notes likely mix a compact core SpriteNode with one or more larger derived UI/display objects. The evidence for +0x17e strongly suggests there are bigger family members or wrapper objects in the same virtual ecosystem.

So the safe future modeling strategy is:

• define a small SpriteNodeBase
• keep larger UI/display fields in derived or sibling structs until more offsets are closed

Candidate Method Map

Strong instance methods

Address	Current function	Candidate method role
000b:326e	sprite_node_destroy	Destroy()
000b:3380	sprite_node_is_dirty	IsDirty()
000b:33a6	sprite_node_mark_dirty	MarkDirty()
000b:3ab2	sprite_node_dispatch_event	DispatchEvent()
000b:40ee	sprite_node_update_and_dispatch	UpdateAndDispatch()
000a:b988	sprite_node_get_or_traverse	GetOrTraverse()

Strong family-local helpers that may remain free/static

Address	Current function	Why it may stay non-method
000b:3a00	sprite_tree_sum_x_offset	Pure recursive accumulation helper; method status depends on later decompile readability.
000b:3a35	sprite_tree_sum_y_offset	Same as above.
000b:330c	sprite_tree_dispatch_wrapper	Looks like a pure thunk wrapper rather than a meaningful source-level method.
000b:3362	sprite_tree_unwind_check	Stack-segment guard helper; probably not worth presenting as a class method.

Candidate Virtual Slot Map

DispatchEvent now gives a materially tighter slot map than the earlier placeholder A/B/C/D read.

Slot offset	Current best role	Evidence
+0x04	event 1 handler	DispatchEvent routes event code 1 here directly
+0x08	event 2 handler	same dispatcher
+0x0c	event 4 handler	same dispatcher
+0x10	event 8 handler	same dispatcher
+0x14	event 0x10 handler	same dispatcher
+0x18	event 0x20 handler	same dispatcher
+0x1c	event 0x40 self handler	called after the dispatcher walks child nodes for the same event
+0x24	event 0x100 handler	same dispatcher
+0x34	child-broadcast event 0x40 slot	used on child nodes during the 0x40 walk, not on the root dispatch object itself

The seg091 default-slot helpers are also useful evidence:

• 000a:7b44, 000a:7b49, 000a:7b53, 000a:7b4e, 000a:7b78, 000a:7b7d, 000a:7b30, 000a:7b3f, 000a:7b35, 000a:7b3a
• 000a:7b58 returns zero and behaves like a default no-op boolean slot
• 000a:7b5f is a forwarding trampoline slot

These likely belong to one or more shared/default node vtables and should be preserved as vtable evidence even if they never become pretty source-level methods.

Ownership And Global State

Focus/global state

Global focus pointer [0x4fd0:0x4fd2] is updated in the dispatch family and cleared in the destructor.

That gives the family a real interaction with global UI focus/state, but the key point for class work is simpler:

• focus ownership is tied to the node family itself
• this is not just an arbitrary free helper changing global UI state

Child ownership

The destructor and recursive sum/traverse helpers strongly suggest real child ownership or at least managed child linkage.

That means later class modeling should preserve a node/tree mental model rather than flattening everything into stand-alone display items.

Candidate Ghidra Modeling Plan

When class authoring begins, the safest sequence for this family is:

1. create class namespace SpriteNode
2. move Destroy, IsDirty, MarkDirty, DispatchEvent, UpdateAndDispatch, and GetOrTraverse first
3. create minimal SpriteNodeBase struct with the stable offsets around +0x19, +0x21, +0x23, and +0x29
4. create provisional vtable with slots +0x14, +0x18, +0x20, +0x24
5. keep recursive tree helpers outside the class until decompiler output shows they benefit from becoming methods

Live Ghidra Authoring Status

Verified first live SpriteNode batch landed on 2026-04-08.

• Created class owner Remorse::SpriteNode in the active CRUSADER.EXE database.
• Re-anchored the strongest old 000b: method batch into the live 1360: segment by preserved offset delta from 000b:326e -> 1360:046e.
• Created minimal live datatypes /Remorse/SpriteNodeBase and /Remorse/SpriteNodeVtable from the current safest note anchors.
• /Remorse/SpriteNodeBase currently names only the bounded field block that is directly supported by the live method batch:
  • +0x19 = child_or_next_farptr
  • +0x21 = local_x_offset
  • +0x23 = local_y_offset
  • +0x29 = dirty_flags
• /Remorse/SpriteNodeVtable is still the earlier minimal shell in-session, but the live DispatchEvent read now supports a deeper slot map than the first authoring batch encoded:
  • direct self dispatch uses +0x04, +0x08, +0x0c, +0x10, +0x14, +0x18, +0x1c, and +0x24
  • child broadcast during event 0x40 uses child slot +0x34
• Moved the first bounded method set under the class owner with short provenance comments:
  • 1360:036a -> Create (best current constructor-style anchor; still keep the higher-wrapper caveat visible)
  • 1360:046e -> Destroy (older note anchor 000b:326e)
  • 1360:0580 -> IsDirty (older note anchor 000b:3380)
  • 1360:05a6 -> MarkDirty (older note anchor 000b:33a6)
  • 1360:0955 -> GetOrTraverse (best current live anchor for older note anchor 000a:b988)
  • 1360:0cb2 -> DispatchEvent (older note anchor 000b:3ab2)
  • 1360:12ee -> UpdateAndDispatch (older note anchor 000b:40ee)
• The live decompiler now makes the core family surface much easier to navigate directly in-session:
  • Create now exists live as the current safest constructor-style anchor: it allocates 0x34 bytes when this is null, stamps the 0x501a SpriteNode vtable, initializes the child-link/core offset fields, and links the incoming parent/child lane.
  • Direct callers now narrow the subtype story materially: the current call set is dominated by GumpCreate_* and adjacent UI wrapper constructors, which supports treating Create as the compact shared base-node constructor used by higher-level gump/display objects rather than as a one-off derived leaf.
  • Destroy restores the 0x501a base vtable, clears the global focus pointer when this owns it, releases child linkage, and optionally frees self.
  • IsDirty and MarkDirty read and mutate the +0x29 dirty-state lane exactly as the note predicted.
  • GetOrTraverse now exists live as the best current 000a:b988 re-anchor: it recursively walks the child-linked subtree, adjusts the incoming query coordinates by the local offsets, and returns either the matched child node or the default sentinel through the out pointer.
  • DispatchEvent updates the global focus pointer at 0x4fd0:0x4fd2 and now ties concrete event codes to concrete slot offsets: 1/2/4/8 -> +0x04/+0x08/+0x0c/+0x10, 0x10/0x20 -> +0x14/+0x18, 0x40 -> child +0x34 then optional self +0x1c, and 0x100 -> +0x24.
  • UpdateAndDispatch now clearly shows the IsDirty / MarkDirty / recompute / child-walk sequence instead of staying as an anonymous seg1360 helper.
• The SpriteNode family is therefore no longer note-only. What remains open is narrower now: chiefly whether Create should remain the family's public constructor-style entry or later be split into a higher derived/UI wrapper and a smaller base-node constructor once more callers and subtype evidence land, plus the deeper vtable-slot and subtype-layout questions.

Open Questions

• whether the current Create signature itself can be cleaned up further now that its caller set points to a shared compact base-node constructor used by higher-level gump wrappers
• exact root vtable address or addresses for the main SpriteNode family
• whether the +0x17e redraw flag belongs to a derived display node rather than the compact base node
• whether the recovered event-code map can now be promoted from raw event-code labels to prettier semantic slot names without overfitting UI behavior too early
• whether sprite_tree_accumulate_pos should become a class method, a static helper, or a separate geometry utility

Immediate Follow-Up Value

The most useful next companion work after this note is not more sprite detail by itself. It is the rebuild-ABI note, because once the first few class families are documented this well, the next real risk is drifting away from the original memory and calling-convention model before any code is emitted.