Splashpack format v31¶
Extracted from psxsplash-main/src/splashpack.{hh,cpp} and
godot-ps1/addons/ps1godot/exporter/SplashpackWriter.cs. Keep this in sync when
either side bumps the version.
Authoritative source: the C++ structs with
static_assert(sizeof(...) == N)insplashpack.hh. If this doc disagrees with the code, the code wins.Doc currency: the field tables below detail the v22 baseline. v23-v27 additions (UI 3D models, scene skybox, per-clip audio routing, CDDA track, XA sidecar table) are summarised in the version history at the bottom but not yet expanded into per-field tables — read
splashpack.hhdirectly for the v23+ field layouts. If you bump the format again, please also expand the relevant table here.
File split¶
v20 produces three sibling files. Authoring tools emit all three; the runtime loads each into its respective memory region.
| File | Destination | Contents |
|---|---|---|
scene.splashpack |
Main RAM | Header + scene structures + offsets into the other two |
scene.splashpack.vram |
PS1 VRAM (1024×512×16bpp) | Texture atlas pixels + CLUTs + UI font pixels |
scene.splashpack.spu |
SPU RAM (512 KB) | ADPCM audio data |
Offsets in the main file that point into VRAM/SPU blobs are byte offsets into the respective sidecar file, not absolute addresses.
Endianness¶
Little-endian throughout. The PS1 MIPS CPU is little-endian; writer and loader both assume it.
File header — SPLASHPACKFileHeader (144 bytes)¶
Source: splashpack.cpp ~lines 21–90. static_assert(sizeof(...) == 144).
v21 appended 16 bytes at the end of the v20 header for editor-driven player
rigs (camera offset + avatar attachment). v22 appended a further 8 bytes
for the sequenced-music table (musicSequenceCount + pad_music +
musicTableOffset).
| Offset | Type | Field | Notes |
|---|---|---|---|
| 0 | char[2] |
magic |
"SP" |
| 2 | u16 |
version |
29; loader asserts >= 29 |
| 4 | u16 |
luaFileCount |
|
| 6 | u16 |
gameObjectCount |
|
| 8 | u16 |
textureAtlasCount |
|
| 10 | u16 |
clutCount |
|
| 12 | u16 |
colliderCount |
|
| 14 | u16 |
interactableCount |
|
| 16 | PackedVec3 |
playerStartPos |
Fixed-point GTE coords |
| 22 | PackedVec3 |
playerStartRot |
Euler, fp12 radians |
| 28 | FixedPoint<12,u16> |
playerHeight |
|
| 30 | u16 |
sceneLuaFileIndex |
0xFFFF = none |
| 32 | u16 |
bvhNodeCount |
|
| 34 | u16 |
bvhTriangleRefCount |
|
| 36 | u16 |
sceneType |
0 = exterior (BVH), 1 = interior (rooms) |
| 38 | u16 |
triggerBoxCount |
|
| 40 | u16 |
worldCollisionMeshCount |
Removed in v20; written as 0 for compat |
| 42 | u16 |
worldCollisionTriCount |
Removed in v20; written as 0 for compat |
| 44 | u16 |
navRegionCount |
|
| 46 | u16 |
navPortalCount |
|
| 48 | u16 |
moveSpeed |
fp12 per-frame |
| 50 | u16 |
sprintSpeed |
fp12 per-frame |
| 52 | u16 |
jumpVelocity |
fp12, derived from sqrt(2·g·h) / gteScale |
| 54 | u16 |
gravity |
fp12 per-frame² |
| 56 | u16 |
playerRadius |
fp12 |
| 58 | u16 |
pad1 |
0 |
| 60 | u32 |
nameTableOffset |
→ name table in .splashpack |
| 64 | u16 |
audioClipCount |
|
| 66 | u16 |
pad2 |
0 |
| 68 | u32 |
audioTableOffset |
→ audio table in .splashpack |
| 72 | u8 |
fogEnabled |
0/1 |
| 73 | u8 |
fogR |
|
| 74 | u8 |
fogG |
|
| 75 | u8 |
fogB |
|
| 76 | u8 |
fogDensity |
1–10 |
| 77 | u8 |
pad3 |
0 |
| 78 | u16 |
roomCount |
N+1 when non-zero (sentinel room 0) |
| 80 | u16 |
portalCount |
|
| 82 | u16 |
roomTriRefCount |
|
| 84 | u16 |
cutsceneCount |
|
| 86 | u16 |
roomCellCount |
|
| 88 | u32 |
cutsceneTableOffset |
|
| 92 | u16 |
uiCanvasCount |
|
| 94 | u8 |
uiFontCount |
|
| 95 | u8 |
uiPad5 |
0 |
| 96 | u32 |
uiTableOffset |
|
| 100 | u32 |
pixelDataOffset |
→ pixel-data table for CLUTs/atlases |
| 104 | u16 |
animationCount |
|
| 106 | u16 |
roomPortalRefCount |
|
| 108 | u32 |
animationTableOffset |
|
| 112 | u16 |
skinnedMeshCount |
|
| 114 | u16 |
pad_skin |
0 |
| 116 | u32 |
skinTableOffset |
|
| 120 | PackedVec3 |
cameraRigOffset |
v21+. Player-local PSX units; runtime rotates by yaw. |
| 126 | PackedVec3 |
playerAvatarOffset |
v21+. Mesh-origin to player-origin offset, player-local. |
| 132 | u16 |
playerAvatarObjectIndex |
v21+. Which gameObject auto-tracks player; 0xFFFF = none. |
| 134 | u16 |
pad_rig |
0 |
| 136 | u16 |
musicSequenceCount |
v22+. Number of sequenced-music entries (capped at 8). |
| 138 | u16 |
pad_music |
0 |
| 140 | u32 |
musicTableOffset |
v22+. → MusicTableEntry[] in .splashpack, 0 if no sequences. |
Post-header layout (main .splashpack)¶
Written in this order by PSXSceneWriter.Write() and read linearly by
SplashPackLoader::LoadSplashpack():
Header (144 bytes)
├── LuaFile[] — luaFileCount × sizeof(LuaFile)
├── GameObject[] — gameObjectCount × sizeof(GameObject)
├── SPLASHPACKCollider[] — colliderCount × 32 bytes
├── SPLASHPACKTriggerBox[] — triggerBoxCount × 32 bytes
├── BVHNode[] — bvhNodeCount × sizeof(BVHNode) (if exterior)
├── TriangleRef[] — bvhTriangleRefCount × sizeof(TriangleRef)
├── Room data — if interior scene (rooms, portals, cells, refs)
├── Interactable[] — interactableCount
├── Nav regions — navRegionCount + navPortalCount
├── Cutscene table — pointed to by cutsceneTableOffset
├── Animation table — pointed to by animationTableOffset
├── Skinned mesh table — pointed to by skinTableOffset
├── UI table — canvases + fonts, pointed to by uiTableOffset
├── Audio table — clip headers (data lives in .spu), at audioTableOffset
├── Music table — MusicTableEntry[] + PS1M blobs, at musicTableOffset (v22+)
├── Name table — null-terminated strings, at nameTableOffset
├── Pixel data table — TPage + CLUT offsets into .vram, at pixelDataOffset
└── Per-object triangle streams — referenced by GameObject.polygonsOffset
Fixed-layout sub-structures¶
SPLASHPACKCollider — 32 bytes¶
| Offset | Type | Field |
|---|---|---|
| 0 | i32×3 |
minX, minY, minZ (fp12 AABB min) |
| 12 | i32×3 |
maxX, maxY, maxZ (fp12 AABB max) |
| 24 | u8 |
collisionType |
| 25 | u8 |
layerMask |
| 26 | u16 |
gameObjectIndex |
| 28 | u32 |
padding |
SPLASHPACKTriggerBox — 32 bytes¶
| Offset | Type | Field |
|---|---|---|
| 0 | i32×3 |
minX, minY, minZ |
| 12 | i32×3 |
maxX, maxY, maxZ |
| 24 | i16 |
luaFileIndex (−1 = no script) |
| 26 | u16 |
padding |
| 28 | u32 |
padding2 |
SPLASHPACKTextureAtlas¶
| Type | Field | Notes |
|---|---|---|
u32 |
polygonsOffset |
Offset into .splashpack (triangle stream for this atlas) |
u16 |
width |
Texels |
u16 |
height |
Texels |
u16 |
x |
VRAM column |
u16 |
y |
VRAM row |
SPLASHPACKClut¶
| Type | Field |
|---|---|
u32 |
clutOffset |
u16 |
clutPackingX |
u16 |
clutPackingY |
u16 |
length |
u16 |
pad |
MusicTableEntry — 24 bytes (v22+)¶
| Offset | Type | Field | Notes |
|---|---|---|---|
| 0 | u32 |
dataOffset |
Byte offset of the PS1M blob in the .splashpack. |
| 4 | u32 |
dataSize |
Size of the PS1M blob in bytes. |
| 8 | char[16] |
name |
Null-padded; truncated by writer to 15 chars + null. Lua resolves via Music.Find(name) / Music.Play(name). |
The PS1M blob's internal layout (header + channel table + event stream)
is documented separately in docs/sequenced-music-format.md.
Coordinate conversions (writer side)¶
SplashEdit runs in Unity coordinates (left-handed, Y-up, meters) and converts on write:
- Position:
psxCoord = round(metricCoord * 4096 / gteScaling)as i16. Y is flipped:(x, -y, z). - Rotation: Euler XYZ in radians → fp12 via
rad * 4096 / (2π). - Speed / gravity: meters-per-second → per-frame at 30 fps → fp12.
- Jump height: converted to initial vertical velocity with
v = sqrt(2·g·h) / gteScaling.
All fp12 fields are stored as u16 with range 0–65535; the writer has overflow
guards that log an error but write a clamped value, so corrupt scenes fail at
export-time, not runtime.
Version history (as of v27)¶
- v10: audio clips
- v11: fog config
- v12: cutscenes
- v13: UI canvases + fonts
- v16: trigger boxes
- v17: animations
- v18: skinned meshes
- v20: three-file split (main / vram / spu)
- v21: editor-driven player rig —
cameraRigOffset+playerAvatarOffset playerAvatarObjectIndexappended to the header (+16 bytes). Runtime reads aCamera3Dchild ofPS1Playeras the third-person offset and aMeshInstance3Dchild as the auto-tracked avatar.Camera.SetModeLua API flips between first- and third-person at runtime.- v22: sequenced music —
musicSequenceCount+pad_music+musicTableOffsetappended to the header (+8 bytes). Music section is an array of 24-byteMusicTableEntryrows pointing at PS1M blobs. Format documented indocs/sequenced-music-format.md. Runtime adds aMusicSequencerclass on top ofAudioManager(with voice reservation so dialog can't steal music notes). - v23: UI 3D-model widgets — per-canvas
UIModelEntry[]table with per-instance mutable runtime state. Renderer composes a HUD pass for these on top of the main scene. Seesplashpack.hh:34for layout. - v24: scene skybox — full-screen textured quad with optional tint and
rotation. Header gains
skyEnabledflag + sky descriptor block. Seesplashpack.hh:204. - v25: per-
AudioClipRoutebyte (0=SPU, 1=XA, 2=CDDA, 3=Auto). Authoring side picks intent; build pipeline resolves to a concrete backend. SeePS1AudioClip.cs:94andsplashpack.hh:95. - v26: per-
AudioClipcddaTrackbyte for CDDA-routed clips so Lua code doesn't have to know which physical disc track a song landed on. 0 = unset. Seesplashpack.hh:114. - v27: XA sidecar table —
xaClipCount+xaTableOffsetin the header, with per-XA-clip(name, sidecarOffset, sidecarSize)rows pointing into the per-scenescene.<n>.xafile. RuntimeXaAudioBackend(xaaudio.cpp) drives Form-2 disc streaming viapsyqo::CDRomDevice::Actionfor SETMODE 0x24 → SETLOC → READS. Seesplashpack.hh:120. - v31: static-mesh vertex-pool format. Per-object mesh storage
shrinks from
Tri[polyCount](52 B per triangle, vertices expanded ×3) to aMeshBlobheader (4 B: u16 vertexCount + u16 triCount) followed byVertex[vertexCount](12 B each: 6 B pos + 2 B uv + 4 B color, fields reordered for natural alignment) andFace[triCount](20 B each: 3 × u16 indices + 6 B face normal + 2 B tpage + 4 B CLUT XY + 2 B pad). Vertices are deduplicated by(pos, post-expander uv, color)— 50–55% smaller in typical manifold meshes; ~32% smaller in worst-case zero-reuse meshes. Skinned meshes keep the legacyTri[]layout: their per-tri-vertex bone-indices array can't pool across triangles that share a vertex but assign different bones, and the savings would be smaller anyway given the boneIndices overhead. Renderer expands a Tri on the stack viaexpandTri(verts, face)per-iteration; no in-RAM Tri[] is held. Hard cutover: v30 splashpacks no longer load. - v30: skin-animation pose compression. Per-bone-frame storage
shrinks from 24 B
BakedBoneMatrix(9 int16 row-major rotation + 3 int16 translation, fp12) to 14 BBakedBonePose(4 int16 quaternion + 3 int16 translation, fp12) — a ~42% reduction on every clip. The renderer's working buffer (lerpedBones[]) stays in matrix form; an inlineposeToMatrix()decoder runs once per bone at frame swap. Linear interpolation between adjacent frames still happens in matrix space (consistent with prior behavior; matrix lerp isn't slerp-correct but the per-frame error is imperceptible at 30 fps clip rates and the cost saving is worth it). Format change is inside the skin section — header layout and every other section stay byte-compatible with v29. Hard cutover: v29 splashpacks no longer load (loader hard-assertsversion >= 30). - v29: sound macros + sound families (Phase 5 Stage A). Header gains
four u16 counts (
soundMacroCount,soundMacroEventCount,soundFamilyCount,familyClipIndexCount) + four u32 table offsets — total +24 bytes, header now 224 B. Records:SPLASHPACKSoundMacroRecord(24 B): inline 16-byte name,firstEventIndex+eventCountslice into the macro-event table,maxVoices,priority,cooldownFrames.SPLASHPACKSoundMacroEventRecord(8 B):frame(local to macro),audioClipIndex,volume,pan,pitchOffset(i8 semitones).SPLASHPACKSoundFamilyRecord(28 B): inline 16-byte name,firstClipIndex+clipCountslice into the familyClipIndices table, pitch/volume/pan jitter ranges,flags(bit 0 = avoidRepeat),priority,cooldownFrames.- familyClipIndices: flat u16 array; each family's slice lists
the AudioClips indices it draws variants from.
Stage A scaffold: counts/offsets emit as zero, runtime parses but
doesn't dispatch. Stage B wires
SoundMacroSequencer/SoundFamilyruntime systems and the Lua dispatch path. Seesplashpack.hhfor ground-truth field layouts.
- v28: scene-wide instrument bank for sequenced music. Header gains
instrumentCount/regionCount/drumKitCount/drumMappingCount(u16 each) plus four u32 table offsets — total +24 bytes, header now 200 B. Records:SPLASHPACKInstrumentRecord(16 B):firstRegionIndex+regionCount+programId+ mix + voice budget + default ADSR.SPLASHPACKRegionRecord(16 B):audioClipIndex,rootKey,keyMin/keyMax,velocityMin/velocityMax,tuneCents, mix, optional ADSR override.SPLASHPACKDrumKitRecord(8 B):firstMappingIndex+mappingCount+midiChannel.SPLASHPACKDrumMappingRecord(8 B):midiNote+audioClipIndex+ per-drum mix +chokeGroup+priority. Stage A scaffold: counts/offsets emit as zero, runtime loads the fields but doesn't dispatch through them. Stage B/C of Phase 2.5 will populate the bank from author-sidePS1Instrument/PS1DrumKitand wire the runtime resolution chain. Seesplashpack.hh:73.
When porting the writer to Godot¶
- Match struct sizes bit-for-bit. Add a test that hashes an empty-scene splashpack against a known-good SplashEdit empty-scene splashpack.
- Preserve writer order — the loader is a linear cursor walk in places; offsets only cover the jump tables.
- Preserve padding fields exactly. Zeroing them is fine; skipping them is not.
collisionMeshCount/collisionTriCountare dead fields kept for binary compat. Write zeros.- When SplashEdit bumps to vN+1, read its
PSXSceneWriter.csdiff and mirror here. UpdateCLAUDE.mdand the version-check tests.