User Tools

Site Tools

Trace: • Sprite Data

Sidebar

Home

Hack64 Wiki

ROM of the Month

Nintendo 64

Other Titles

banjo_kazooie:sprites

Table of Contents

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:

  1. [ ] File size ≥ 4 bytes
  2. [ ] Read and parse frame count and format ID
  3. [ ] If frameCount > 0x0100 → parse as single-chunk
  4. [ ] If ≤ 0x0100 → validate frame table offsets
  5. [ ] Parse each frame header and chunk table
  6. [ ] 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!

banjo_kazooie/sprites.txt · Last modified: 2025/04/12 13:01 by snowboundmage2

Page Tools