104 lines
6.2 KiB
Markdown
104 lines
6.2 KiB
Markdown
# SPLASHPACK Binary File Format Specification
|
||
|
||
All numeric values are stored in little‐endian format. All offsets are counted from the beginning of the file.
|
||
|
||
---
|
||
|
||
## 1. File Header (16 bytes)
|
||
|
||
| Offset | Size | Type | Description |
|
||
| ------ | ---- | ------ | ----------------------------------- |
|
||
| 0x00 | 2 | char | `'SP'` – File magic |
|
||
| 0x02 | 2 | uint16 | Version number (currently **1**) |
|
||
| 0x04 | 2 | uint16 | Number of Exporter descriptors |
|
||
| 0x06 | 2 | uint16 | Number of Texture Atlas descriptors |
|
||
| 0x08 | 2 | uint16 | Number of CLUT descriptors |
|
||
| 0x0A | 3*2 | uint16 | Reserved (always 0) |
|
||
|
||
---
|
||
|
||
## 2. Metadata Section
|
||
|
||
The metadata section comprises three groups of descriptors.
|
||
|
||
### 2.1 GameObject Descriptors (56 bytes each)
|
||
|
||
Each gameobject descriptor stores the transform and mesh metadata for one GameObject.
|
||
|
||
| Offset (per entry) | Size | Type | Description |
|
||
| ------------------ | ---- | ------ | --------------------------------- |
|
||
| 0x00 | 4 | int | **Mesh Data Offset** |
|
||
| 0x04 | 4 | int | X coordinate (Fixed-point) |
|
||
| 0x08 | 4 | int | Y coordinate (Fixed-point) |
|
||
| 0x0C | 4 | int | Z coordinate (Fixed-point) |
|
||
| 0x10 | 36 | int[9] | 3×3 Rotation matrix (Fixed-point) |
|
||
| 0x28 | 4 | uint16 | Triangle count in the mesh |
|
||
| 0x2A | 2 | uint16 | Reserved |
|
||
|
||
### 2.2 Texture Atlas Descriptors (12 bytes each)
|
||
|
||
Each texture atlas descriptor holds atlas layout data and a placeholder for the atlas raw data offset.
|
||
|
||
| Offset (per entry) | Size | Type | Description |
|
||
| ------------------ | ---- | ------ | -------------------------------------------------------- |
|
||
| 0x00 | 4 | int | **Atlas Data Offset Placeholder** |
|
||
| 0x04 | 2 | uint16 | Atlas width |
|
||
| 0x06 | 2 | uint16 | Atlas height (currently always 256, for future-proofing) |
|
||
| 0x08 | 2 | uint16 | Atlas position X – relative to VRAM origin |
|
||
| 0x0A | 2 | uint16 | Atlas position Y – relative to VRAM origin |
|
||
|
||
### 2.3 CLUT Descriptors (12 bytes each)
|
||
|
||
CLUTs are the only data which is stored in the Metadata section.
|
||
For each CLUT (Color Lookup Table) associated with an atlas texture that has a palette:
|
||
|
||
| Offset (per entry) | Size | Type | Description |
|
||
| ------------------ | ---- | ------ | ----------------------------------------------------- |
|
||
| 0x00 | 4 | int | **Clut Data Offset Placeholder** |
|
||
| 0x04 | 2 | uint16 | CLUT packing X coordinate - already in 16 pixel steps |
|
||
| 0x06 | 2 | uint16 | CLUT packing Y coordinate |
|
||
| 0x08 | 2 | uint16 | Palette count (number of valid palette entries) |
|
||
| 0x0A | 2 | uint16 | Reserved (always 0) |
|
||
|
||
---
|
||
|
||
## 3. Data Section
|
||
|
||
The data section contains the actual mesh and atlas raw data.
|
||
|
||
### 3.1 Mesh Data Blocks
|
||
|
||
For each exporter, a mesh data block is written at the offset specified in its descriptor. Each mesh block contains data for all triangles of the associated mesh.
|
||
|
||
#### **Triangle Data Layout (per triangle – 52 bytes total):**
|
||
|
||
| Field | Size | Description |
|
||
| ----------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| **Vertex Coordinates** | 3 vertices × 3 × 2 bytes = 18 bytes | For each vertex (v0, v1, v2): X, Y, Z coordinates (int16) |
|
||
| **Vertex Normal** | 3 × 2 bytes = 6 bytes | Normal vector for vertex v0 (int16: nx, ny, nz) |
|
||
| **Vertex Colors** | 3 vertices × (3 bytes color + 1 byte padding) = 12 bytes | For each vertex (v0, v1, v2): Red, Green, Blue (uint8) plus 1 byte padding |
|
||
| **Texture Coordinates (UVs)** | 3 vertices × 2 bytes = 6 bytes | For each vertex (v0, v1, v2): U and V coordinates (uint8), adjusted by texture packing factors |
|
||
| **UV Padding** | 2 bytes | Padding (uint16, set to zero) |
|
||
| **Texture Attributes** | 2 bytes | The TPage attribute for the given polygon |
|
||
| **Clut X** | 2 bytes | Clut position within VRAM (already predivided by 16) |
|
||
| **Clut Y** | 2 bytes | Clut position within VRAM |
|
||
| **Padding** | 2 bytes | |
|
||
|
||
|
||
|
||
|
||
### 3.2 Atlas Data Blocks
|
||
|
||
For each atlas, a raw texture data block is written at the offset specified in its descriptor
|
||
|
||
- **Raw Texture Data:**
|
||
The atlas data is written pixel by pixel as returned by the pixel packing function. The total size equals
|
||
*(Atlas Width × Atlas Height)* The data is prepared for a DMA transfer to the VRAM.
|
||
|
||
|
||
### 3.3 Clut Data Blocks
|
||
|
||
For each clut, a raw pixel data block is written at the offset specified in its descriptor as an array of `uint16` colors already formatted for the VRAM.
|
||
|
||
---
|