docs/re-notes/sprites.md

Sprite System

WA.exe uses a custom .spr format for paletted animated sprites. The DD_Display object manages a 1024-slot sprite table, loading sprites from .dir archive files via the GfxDir subsystem.

DD_Display Sprite Storage

DD_Display contains four arrays for sprite management:

Byte Offset	Size	Description
+0x0008	4096 (1024 × u32)	sprite_palette[1024] — palette ID (1-3) per slot
+0x1008	4096 (1024 × Ptr32)	sprite_ptrs[1024] — Sprite object pointer per slot
+0x311C	12 (3 × Ptr32)	gfx_dirs[3] — GfxDir pointer per palette
+0x3530	12 (3 × u32)	sprite_counts[3] — loaded sprite count per palette

Sprite IDs range from 1 to 1023. Bit 0x800000 on the ID signals "already loaded" and causes LoadSprite to return immediately with success.

Sprite Object (0x70 bytes)

Vtable: 0x66418C. Created by ConstructSprite (0x4FAA30), populated by ProcessSprite (0x4FAB80).

Offset	Size	Type	Name	Source
0x00	4	Ptr32	vtable	ConstructSprite
0x04	4	Ptr32	context_ptr	ConstructSprite (ECX param)
0x08	2	u16	_unknown_08	wkJellyWorm
0x0A	2	u16	fps	wkJellyWorm
0x0C	2	u16	width	wkJellyWorm, ProcessSprite
0x0E	2	u16	height	wkJellyWorm, ProcessSprite
0x10	2	u16	flags	wkJellyWorm, ProcessSprite
0x12	2	u16	frame_count	ProcessSprite (can be overwritten)
0x14	2	u16	header_flags	ProcessSprite (from .spr raw+8)
0x16	2	u16	max_frames	wkJellyWorm, ProcessSprite
0x18	2	u16	_unknown_18
0x1A	2	u16	_unknown_1a
0x1C	4	u32	scale_x	ProcessSprite (negative frame count)
0x20	4	u32	scale_y	ProcessSprite (negative frame count)
0x24	4	u32	is_scaled	ProcessSprite (1 if scaled, 0 otherwise)
0x28	4	Ptr32	frame_meta_ptr	SpriteFrame* array
0x2C	4	Ptr32	secondary_frame_ptr	0x4000 flag in header_flags
0x30	2	u16	secondary_frame_count
0x32	2	u16	_pad_32
0x34	4	Ptr32	display_gfx	DisplayGfx vtable (0x664144)
0x38	40	[u8; 0x28]	_unknown_38
0x60	4	Ptr32	raw_frame_header_ptr	ProcessSprite
0x64	4	Ptr32	bitmap_data_ptr	ProcessSprite
0x68	4	Ptr32	palette_data_ptr	ProcessSprite
0x6C	4	u32	_unknown_6c

SpriteFrame (0x0C bytes)

Per-frame metadata, pointed to by Sprite::frame_meta_ptr. One entry per animation frame.

Offset	Size	Type	Name
0x00	4	u32	bitmap_offset
0x04	2	u16	start_x
0x06	2	u16	start_y
0x08	2	u16	end_x
0x0A	2	u16	end_y

Source: wkJellyWorm Sprites.h::SpriteFrame.

Sprite Vtable (0x66418C, 8 entries)

Slot	Address	Name
0	0x4FAA80	Destructor
1	0x4FAAD0	Unknown
2	0x4FB5C0	Unknown
3	0x4FE550	Unknown
4	0x4FE2F0	Unknown
5	0x4FE9C0	Unknown
6	0x5613D0	CTask common stub
7	0x5613D0	CTask common stub

Key Functions

LoadSprite (0x523400)

__thiscall on DD_Display, RET 0x14 (5 stack params). Loads a sprite into the DD_Display sprite table.

Parameters:

1. palette (1-3) — which GfxDir palette to use
2. sprite_id (1-1023) — slot index
3. size_override — packed DWORD: low16 = width override, high16 = height override (0 = no override)
4. file_archive — PC_FileArchive*
5. filename — const char* sprite filename

Returns: 1 on success, 0 on failure.

Flow:

1. If sprite_id & 0x800000, return 1 (already loaded)
2. Validate palette in [1,3] and gfx_dirs[palette] is non-null
3. Validate sprite_id in [1,1023]
4. Call vtable[0x20] to check if sprite already exists at this slot
5. Allocate sprite memory via WA_MallocMemset (0x53E910)
6. Call ConstructSprite (0x4FAA30) to initialize
7. Call LoadSpriteFromVfs (0x4FAAF0) to load data
8. Store sprite pointer at this[sprite_id + 0x402] (byte offset +0x1008)
9. Store palette at this[sprite_id + 2] (byte offset +0x8)
10. Increment sprite_counts[palette]
11. Apply size_override to sprite +0x16 (width) and +0x18 (height) if non-zero

ConstructSprite (0x4FAA30)

__usercall — EAX = sprite pointer, ECX = context pointer. Initializes a freshly allocated 0x70-byte sprite struct: sets vtable to 0x66418C, DisplayGfx vtable at +0x34, zeroes all data fields.

LoadSpriteFromVfs (0x4FAAF0)

__usercall — EAX = filename string, ECX = PC_FileArchive pointer, 2 stack params (sprite pointer, GfxDir pointer). Tries GfxDir::FindEntry (0x566520) for a cached entry first; on miss, calls GfxDir::LoadImage (0x5666D0) to read from the archive. Allocates a buffer for raw sprite data, then calls ProcessSprite (0x4FAB80).

ProcessSprite (0x4FAB80)

__usercall — EAX = sprite pointer, 1 stack param (raw data pointer from .spr file). Parses the .spr binary format and populates the Sprite struct fields. See the .spr File Format section below.

DrawSpriteGlobal (0x541FE0)

__thiscall + EAX = y_pos (usercall). 4 stack params: layer, x_pos, sprite_id, frame. Enqueues a draw command (type 4) to the rendering queue. World-space coordinates.

DrawSpriteLocal (0x542060)

Identical to DrawSpriteGlobal but enqueues command type 5. Screen-space coordinates.

DestroySprite (0x4FAA80)

__thiscall, sprite vtable slot 0. Frees sprite resources.

.spr File Format

Binary format parsed by ProcessSprite (0x4FAB80). Data layout:

Offset  Size     Field
+0x00   4        (unused / magic)
+0x04   4 (u32)  data_size — added to global counter at 0x7A0864
+0x08   2 (u16)  header_flags → sprite+0x14
+0x0A   2 (u16)  palette_entry_count
+0x0C   3 × N    palette entries (3 bytes each, likely RGB)
...     varies   frame metadata (SpriteFrame, 0x0C bytes each)
...     varies   bitmap pixel data

Special flags:

• 0x4000 in header_flags: secondary frame table present before the primary frames. Count at first word after palette, followed by 0x0C-byte entries.
• Negative frame count (bit 15 set in the frame count word at the frame header): high 7 bits → scale_x, low 7 bits → scale_y. Actual frame_count set to 1. Scale values stored at sprite +0x1C and +0x20 as (value << 16) >> 5.

Global Counters

Four u32 globals tracking total sprite resource usage, accumulated by ProcessSprite:

Address	Description
0x7A0864	Total sprite data bytes loaded
0x7A0868	Total sprite frame count
0x7A086C	Total sprite pixel area (sum of frame w×h)
0x7A0870	Total palette entries × 3

GfxDir System

Sprites are stored in .dir archive files loaded by the GfxDir subsystem:

• GfxHandler::LoadDir (0x5663E0): Loads a .dir archive. Reads "DIR\x1A" header (0x1A524944), parses 0x1000-byte entries, performs pointer relocation.
• GfxDir::FindEntry (0x566520): Looks up a cached entry by name.
• GfxDir::LoadImage (0x5666D0): Reads image data from archive, returns through vtable with 0x0C-byte descriptor (vtable 0x66A1C0).

Sources

• Ghidra decompilation of LoadSprite, ConstructSprite, ProcessSprite, DrawSpriteGlobal
• wkJellyWorm Sprites.h / Sprites.cpp — struct layout, function hooks, calling conventions
• Runtime analysis via OpenWA validator DLL