# 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