====== Sprite Data ======

This page documents the binary sprite format derived from Banjo-Kazooie’s N64 rom. It supports both single-chunk and multi-frame layouts, with support for various pixel formats and chunk-based rendering.

All integers are **big-endian** unless stated otherwise.

----

===== 🢩 Overview =====

This format is used for static or animated sprite graphics in the ROM. Depending on frame count, it can store a simple image or a complex animation.

----

===== 📘 Reference Table =====

==== 🥇 File Header (offsets 0x00–0x03) ====

^ Field       ^ Offset ^ Type       ^ Description                    ^
| Frame Count | 0x00   | `uint16_t` | Number of frames               |
| Format ID   | 0x02   | `uint16_t` | Format identifier              |

==== 🎨 Format ID Mappings ====

^ Format ID ^ Enum     ^ Description                  ^ Bits per Pixel ^
| 0x0001    | CI4      | 4-bit color indexed          | 4              |
| 0x0004    | CI8      | 8-bit color indexed          | 8              |
| 0x0020    | I4       | 4-bit intensity              | 4              |
| 0x0040    | I8       | 8-bit intensity              | 8              |
| 0x0400    | RGBA16   | 16-bit RGBA (5-5-5-1 format) | 16             |
| 0x0800    | RGBA32   | 32-bit RGBA                  | 32             |

----

===== 🖼 Single Chunk Sprite Layout =====

Used if `frameCount > 256` (`0x0100`).

==== Structure ====

^ Field       ^ Offset ^ Type       ^ Description                     ^
| X           | 0x08   | `int16_t`  | X position                      |
| Y           | 0x0A   | `int16_t`  | Y position                      |
| Width       | 0x0C   | `uint16_t` | Width in pixels                 |
| Height      | 0x0E   | `uint16_t` | Height in pixels                |
| Data Offset | ~0x10+ | —          | 8-byte aligned after header     |
| Data Size   | —      | computed   | Width × Height × bpp ÷ 8        |

==== Notes ====
  * No frame table or chunk headers are present.
  * Pixel data begins after a 16-byte header, aligned to the next 8-byte boundary.

----

===== 🎞 Multi-Frame Sprite Layout =====

Used if `frameCount ≤ 256` (`0x0100`).

==== 📂 Frame Table ====

  * Offset: `0x10`
  * Entry size: 4 bytes per frame
  * Each entry contains a **relative** 32-bit offset from the start of the frame data block.

==== 🧱 Frame Data Block ====

Starts at: `0x10 + (frameCount × 4)`

=== Frame Header ===

^ Field       ^ Offset ^ Type       ^ Description          ^
| X           | 0x00   | `int16_t`  | Frame X offset       |
| Y           | 0x02   | `int16_t`  | Frame Y offset       |
| Width       | 0x04   | `uint16_t` | Frame width          |
| Height      | 0x06   | `uint16_t` | Frame height         |
| Chunk Count | 0x08   | `uint16_t` | Number of chunks     |

=== Palette Data (for CI4 / CI8 only) ===

^ Field        ^ Offset             ^ Size       ^ Description                       ^
| Palette Data | aligned after 0x14 | 32 or 512B | 16×2 or 256×2 bytes, depending on format |

=== Chunk Table ===

Each chunk entry is 8 bytes:

^ Field        ^ Offset ^ Type       ^ Description         ^
| Chunk X      | 0x00   | `int16_t`  | Chunk X position    |
| Chunk Y      | 0x02   | `int16_t`  | Chunk Y position    |
| Chunk Width  | 0x04   | `uint16_t` | Width of chunk      |
| Chunk Height | 0x06   | `uint16_t` | Height of chunk     |

  * Pixel data for each chunk follows the chunk table.
  * All data is aligned to the next 8-byte boundary.

----

===== 🧠 Design Rationale =====

=== Format ID and Versatility ===
  * 16-bit format ID allows for clean extensibility.
  * Decoding behavior is format-specific (e.g. CI formats require palettes).

=== Single vs Multi-frame Decision ===
  * A `frameCount > 0x0100` indicates the file is a simple image without a frame table.
  * Keeps parsing logic simpler for single-use graphics.

=== Frame Table Abstraction ===
  * Offsets are relative to the frame data block, not absolute.
  * Allows reorganization and stream-friendly parsing.

=== 8-byte Alignment ===
  * Ensures data structures are aligned in memory.
  * Improves DMA or cache line performance on N64.

=== Chunk-Based Rendering ===
  * Chunks allow tile reuse or sub-rectangles.
  * Efficient layout, supports tilemaps or partial redraws.

=== Optional Palette ===
  * CI4 and CI8 include palettes automatically.
  * Size and format are inferred based on format ID.

----

===== ✅ Validation Checklist =====

Use the following to verify whether a file matches this format:

  - [ ] File size ≥ 4 bytes
  - [ ] Read and parse frame count and format ID
  - [ ] If frameCount > 0x0100 → parse as single-chunk
  - [ ] If ≤ 0x0100 → validate frame table offsets
  - [ ] Parse each frame header and chunk table
  - [ ] Validate alignment and total chunk data sizes

----

===== 📌 Notes =====

  * All integers are stored in **big-endian** format.
  * Offsets in the frame table are **relative** to the frame data section.
  * Data structures and pixel data must be aligned to 8-byte boundaries.
  * CI4/CI8 formats require an internal palette directly after the frame header.

----

''This documentation is a work in progress based on reverse engineering efforts. Contributions welcome!''