Hack64 Wiki

User Tools

    Trace: • Yoshi's Story Hacking • Sprite Data

    Site Tools

    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
    0x0100 IA4 4-bit intensity(with alpha) 4
    0x0200 IA8 8-bit intensity(with alpha) 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: by snowboundmage2