Crash Bandicoot File Formats

This document is intended to contain all the information I have about the file formats used by the original Crash Bandicoot trilogy for the Sony Playstation. This document is not official in any way.

The following basic terminology is used in this document:

PSX

The original Sony Playstation.

Byte

An 8-bit quantity of data. This is the byte size of the PSX.

Word

A 32-bit quantity of data. This is the word size of the PSX.

Intn

An n-bit signed integer.

UIntn

An n-bit unsigned integer.

n...m

Any integer in the range from n to m inclusive, or the range n to m itself.

CID

Chunk ID.

EID

Entry ID.

TBD

Not yet documented.

KB

Kilobyte

A unit equivalent to 1024 bytes.

All of the formats described in this document store their fields in little-endian byte order unless otherwise stated. All signed integer types are two's complement unless otherwise stated.

General Overview

Contained on the game disc are the following files:

• The game executable file
• The SYSTEM.CNF file (Optional)
• An NSD/NSF file pair for each in-game level

The game executable file contains the code that is loaded in and started by the playstation BIOS.

The SYSTEM.CNF file contains settings used to configure the kernel before booting the game itself, as well as the filename of the executable. If SYSTEM.CNF is not present, the playstation will assume a default configuration and the executable filename PSX.EXE.

Each NSD/NSF file pair probably contains all of the data necessary for the game engine to play a specific level. The NSF file is an archive of numerically identified file-like structures (referred to in this document as "entries") organized into a series of 64 KB pages (referred to in this document as "chunks"). The NSD file contains supplementary data used to assist the game engine in accessing the NSF file. This document focuses on these two formats and the formats of the files contained within them.

Format Table

The following formats are described in this document, arranged by type and applicable game:

NSF

NSF files contain the actual game data. Each NSF file is directly broken down into 64 KB pages, referred to in this document as "chunks".

NSF files have no header.

Chunk

Chunks are the top level objects contained in an NSF file. Each chunk is exactly 64 KB in size. Chunks are containers for the second level objects (hereafter referred to as "entries"). Every entry must be aligned on a word boundary.

Every chunk has an identifier based on its position within the NSF file. This chunk ID is calculated as Chunk Offset / 65536 * 2 + 1. Therefore, the first chunk is assigned ID 1, the second ID 3, the third ID 5, etc. This ensures that all chunk ID's have their least significant bit set, allowing the game engine to differentiate between chunk ID's and pointers.

Chunks start with a header of the following format:

Immediately following this structure is Entry Count + 1 Int32's, each of which is an offset relative to the start of the chunk. The first offset marks the start of the first entry in the chunk; the second offset marks the end of the first entry and the start of the second; the third marks the end of the second and the start of the third; etc. The last offset marks the end of the last entry. Note that, although the first entry typically starts immediately after this list of offsets, it is not required to.

The checksum can be calculated with the following C code:

Entry

Entries are the second level objects contained in an NSF file. All entries are containers for the third level objects (hereafter referred to as "items"). Every item must be aligned on a word boundary. Additionally, the length of every item must be a multiple of 4 bytes to ensure the proper alignment of the following item. Any items not otherwise meeting this requirement are padded at the end with null bytes to satisfy the constraint.

Entries all have a common header format, which is:

Immediately following the header is Item Count + 1 Int32's, each of which is an offset relative to the start of the entry. The first offset marks the start of the first item in the entry; the second offset marks the end of the first item and the start of the second item; the third marks the end of the second and the start of the third; etc. The last offset marks the end of the last item.

Every entry is assigned an ID used to refer to the entry from other locations throughout the game files. This ID is a specially-encoded 5-character string, as a 32-bit value with the following bit layout:

The Pointer Identification Bit is used by the game engine to differentiate between EID's and pointers. It must be set for all EID's. The character set used for the characters in the encoding scheme is:

A special EID, 0x6396347F, is the null EID. It is used to refer to nothing instead of a particular entry. Decoded as a string, its value is "NONE!".

NSF Compression

In retail Crash 1, NSF files include a compressed set of copies of the first few (how many? EDIT: at 0x41C in NSD file) chunks that appear in the file. The compressed copies appear at the start of the file, before the usual uncompressed chunks.

Each compressed chunk starts with the following header:

This structure is followed by a compressed string of bytes which, when decompressed, has a length of Length bytes. The compression format is: TBD

This is then followed by Skip unused bytes, followed by 0x10000 - Length uncompressed data bytes, which are appended to the compressed bytes after decompression to form a complete uncompressed chunk.

Compressed chunks are always a multiple of 2048 bytes long. The Skip and Length fields are used to facilitate this.

NSD

TBD. Very similar to Old NSD.

Old NSD

TBD. Very similar to Prototype NSD, but with some added details.

Prototype NSD

TODO: Put a nice diagram here to show how the hash table works

Prototype NSD files are hash tables linking entry ID's to the chunk ID's of their containing chunks. Texture chunks are also included, linking their respective entry and chunk ID's.

The hashing function is easily described in C-style syntax as ((eid >> 15) & 0xFF). To search for an EID in the table, its hash is computed and then used as an index into an initial 256-word table. The resulting value is then used as the starting index to begin a linear search through the following key-value pair list.

Prototype NSD files start with the following structure:

Following this is the key-value pair list, which is Entry Count of the following structure:

Normal Chunk

Normal chunks are the standard chunk type. Any entries that do not appear in a different chunk type appear in a normal chunk.

Sound Chunk

Sound chunks are chunks used to hold sound entries. To facilitate this, sound chunks have a special alignment restriction; every entry must begin 8 bytes after a 16-byte boundary. This causes the audio data to be aligned on a 16-byte boundary (the entry header is 24 bytes). Failure to comply with this alignment specification leads to broken sound effects in-game. (For emulators, this restriction is more lax. See Additional Notes.)

For certain old, unused levels in Crash 1, old sound chunks are used instead.

Old Sound Chunk

Old sound chunks are an older variant of the more commonly seen sound chunks. Old sound chunks appear in the unused "waterfall", "cavern", and similar levels. Old sound chunks contain sound entries just as sound chunks do, and follow the same alignment restrictions.

Speech Chunk

Speech chunks have the same format and alignment restrictions as sound chunks. However, speech chunks contain speech entries instead of sound entries

Wavebank Chunk

TODO: Put a nice diagram here to show how the alignment works.

Wavebank chunks are used to hold wavebank entries. To facilitate this, wavebank chunks have a special alignment restriction; every entry must begin 4 bytes after a 16-byte boundary. This causes the audio data to be aligned 8 bytes after a 16-byte boundary (entry header is 28 bytes, plus 8 bytes for the info section), although why this is necessary, if it even is (IIRC it isn't), I have absolutely no idea.

Texture Chunk

Texture chunks, unlike the other types of chunks, do not contain a list of entries. Instead, the entire 64KB block is treated as a special type of entry, which contains graphical data including textures and color palettes.

Texture chunks have a slightly different header format from other chunks. The format is:

The format of the remaining data is unknown. However, the entire chunk appears to be a 512x128 texture page to be loaded into video memory.

Entity Entry

TBD. Haven't converted this over from the old crash 2-only page layout, so it's still here: T7 Entries.

Code Entry

The first item is TBD

The second item is compiled GOOL bytecode. TBD, some documentation in Additional Notes.

The third item is read-only(?) data used by the GOOL code.

The fourth item, if present, has the following format:

Each array element is an index into the fifth item, which (if present) is a list of the following structure:

The format of the sixth item, if present, is unknown.

Old Model Entry

Old model entries are the Crash 1 version of the model entries. Old model entries always have 2 items, the format of the first of which is:

The second item is a list of Unknown Count 1 64-bit values of unknown purpose.

Old Scenery Entry

Old scenery entries are the Crash 1 version of the scenery entries. Old scenery entries always have 3 items, the format of the first of which is:

TBD

The second item is a list of 3-point polygons, each of which is 64 bits with the following layout:

The "vertex" fields are indexes into the third item, which is a list of vertices. Each vertex is 64 bits with the following layout:

The vertex coordinates are all signed 16-bit values with the lower 3 bits removed. As such, they should be left-shifted by 3 bits and sign-extended before use. The special effects flag indicates whether the vertex should be subject to certain effects in game. These effects vary by level, such as lightning effects for Slippery Climb, flickering light effects in Temple Ruins, red-glowing strobe effects in Cortex Power, illumination effects in Lights Out, and water waving/warping/distortion effects in Up The Creek.

Sound Entry

Each sound entry contains a single sound effect or voice clip which can be played back in-game. A sound entry has a single item, which is raw playstation-format audio. The sample rate is unknown.

For Crash 2 & 3, speech audio is held in speech entries instead.

Speech Entry

Speech entries are identical in format to sound entries, and contain voice clips used during cutscene dialogue and additional dialogue appearing e.g. during boss fights.

Music Entry

Music entries contain data related to the in-game music.

Music entries always have exactly three items. The format of the first item is:

The second item is either a VH file or nothing (empty, no bytes).

The third item is a SEP file containing Track Count tracks.

Wavebank Entry

Wavebank entries are essentially parts of a VB file. Because chunks are 64 KB in size, larger data cannot be fit into them in whole. The VB files used in-game are split into multiple of these entries. They are recombined using the part number from the first item.

Wavebank entries always have exactly two items. The format of the first item is:

The second item is part of a VB file.

Demo Entry

Demo entries contain a series of inputs, and possibly other data, to be played back in "demo mode", which occurs when a player idles on the start menu for a set amount of time. Each demo entry has a single item, which is of unknown format.

Old Documentation

TODO: Reformat this documentation into the newer style.

T4 Entries

T4 entries have an unknown purpose.

The format of T4 entry items is:

T7 Entries

T7 entries contain the individual in-game entities, such as boxes and penguins.

Maybe they also contain the layout of the level, like floors and walls?

T7 entries always have at least 2 items. The format of the first two items is unknown.

The remaining items represent in-game entities.

Entities

Entities are expressed as collections of values (hereafter referred to as "fields") and some other stuff that I haven't figured out yet. The entity header format is:

This header is followed by Field Count of this structure:

The offsets are each relative to 12 bytes after the start of the item, and point to the following structure:

The format and usage of the field data depends on the field type.

2C: Name

Data is an array of characters that forms a null-terminated UTF-8 string. The string is the internal name used to refer to the entity.

It's probably just ASCII instead of UTF-8, but it's best that this be established as the standard now rather than having character encoding fights and incompatibilities later on.

4B: Position

Data is a list of coordinates for the positions used by the entity. Each element in the list has the following structure:

TBD

9F: ID

Data is an Int32. TBD

A4: General Settings

Data is a list of Int32's. TBD

A9: Type

Data is an Int32. The Int32 refers to the type of the entity. E.g. box

Box is 0x22

AA: Subtype

Data is an Int32. The Int32 refers to the variant of the type of the entity. E.g. nitro

For boxes it's:

public enum BoxType : int
{
	TNT = 0,
	Normal = 2,
	Arrow = 3,
	Checkpoint = 4,
	Iron = 5,
	Apple = 6,
	ExclamationMark = 7,
	Life = 8,
	Mask = 9,
	QuestionMark = 10,
	IronArrow = 15,
	Nitro = 18,
	Bodyslam = 23,
	NitroDetonator = 24
}
		

287: Victims

Data is a list of Int16's. Each value is the ID of an entity to be destroyed by this entity in various situations.

Appendix A: PSX Formats

The Playstation has some formats used by many of its games. The formats relevant to crash hacking are (or should be) documented here.

Playstation Textures

Note: This does not describe the playstation TIM file format, only the lower level texture format.

Playstation textures can use the following pixel formats:

• 4-Bit Indexed (16-Color Palette)
• 8-Bit Indexed (256-Color Palette)
• 16-Bit Direct (No Palette)

The 16-bit color format is similar to ABGR1555, and has the following layout:

The transparency control bit is not strictly an alpha component, and its meaning depends on certain settings not (yet) documented here.

Playstation Audio

The Playstation utilizes 3 different audio formats. Of these, only the format used by the SPU is relevant. This format is 4-bit ADPCM or is it? I don't know much about ADPCM.

In this format, audio samples are organized into 16-byte blocks. The first byte is related to decompressing the audio samples contained within the block. The second byte is a set of 8 flags used to control the SPU. The remaining 14 bytes are 28 4-bit ADPCM samples. TBD

Check the links at the bottom of the page for more details.

The command flags are:

SEQ

SEQ files are the playstation analogue of MIDI files.

The format of SEQ files is:

Resolution is equivalent to the "time division" found in a Standard MIDI File header.
Tempo is equivalent to one found in a Tempo MIDI meta event.
Rhythm is the first 2 parameters of the Time Signature MIDI meta event.
Score Data is the actual music data. It is the same format as the score data in a Standard MIDI File.

SEP

SEP files are a format similar to SEQ files, but with multiple scores (or tracks). That is, while SEQ files contain only a single track, SEP files can contain multiple tracks.

SEP files start with a header like so:

Followed by any number of the following structure:

This format has some subtle but important differences from SEQ:

• The version field is Int16 not Int32.
• The version is zero, not one.
• There is an extra Score Length field.
• They both use the same magic number, making it difficult to distinguish them.

Also note that the SEP header does not indicate the number of tracks in the file.

VAB

VAB files are the playstation analogue of DLS files. They contain the audio data and configuration for instruments used to play back SEQ files. A VAB "program" is similar to a DLS "melodic" instrument, and a VAB "tone" is similar to a DLS "region". VAB has no equivalent to a "drum kit", as channel 10 is not given any special treatment by the SEQ player.

A VAB file can contain a maximum of 254 waveforms, 128 programs, and 16 tones per program.

A VAB file is simply a VH file and a VB file concatenated together. Converting VH+VB to VAB is as simple as:

or:

VH

A VH file is the "header" portion of a VAB file.

The VH format starts with the following structure:

This is then followed by 128 of the following structure, each of which defines a program (equivalent to a DLS instrument):

Only the first Program Count of the program definitions describe existing programs. The remaining program definitions assume default values.

After this exists Program Count * 16 of the following structure, each of which defines a tone (equivalent to a DLS region):

Only the first Tone Count (from the associated program definition, not from the main header) of each set of 16 tone definitions describe existing tones. The remaining tone definitions assume default values. Note that Tone Count in the main header does not include the unused tones. That is, Tone Count is not necessarily equal to Program Count * 16. Also note that while programs and tones have zero-based indexes, wave indexes are one-based.

After the tone definitions is a set of 256 UInt16's. The first value and the last value are each reserved and should be set to zero. The inner 254 values define the length in 8-byte blocks (not in bytes) of each waveform as it appears in the VB file. Each wave starts immediately after the one preceding it.

VB

A VB file is the "body" portion of a VAB file.

VB files contain only PSX audio.

Appendix B: Game Files

TBD

Crash 1

TBD

Crash 2

For PAL, there are multiple copies of the warp room; one for each supported language.

• 02 - Warp Room (For PAL, this is the english version)
• 03 - Tiny Tiger
• 06 - Ripper Roo
• 07 - N. Cortex
• 08 - Komodo Bros
• 09 - N. Gin
• 0A - Sewer or Later
• 0C - Night Fight
• 0D - Hangin' Out
• 0E - Snow Go
• 0F - Ruination
• 10 - Piston It Away
• 11 - Snow Biz
• 12 - Rock It
• 13 - Cold Hard Crash
• 15 - Diggin' It
• 16 - Road To Ruin
• 17 - Un-Bearable
• 18 - Crash Dash
• 19 - Hang Eight
• 1A - Pack Attack
• 1B - Crash Crush
• 1C - Intro
• 1D - Bear It
• 1E - Turtle Woods
• 1F - The Pits
• 20 - Air Crash
• 21 - Plant Food
• 22 - Bear Down
• 23 - The Eel Deal
• 24 - Bee-Having
• 25 - Totally Bear
• 26 - Spaced Out
• 27 - Totally Fly
• 28 - 100% Ending
• 29 - Any% Ending
• 2D - Unknown Language Warp Room (PAL only)
• 2E - Unknown Language Warp Room (PAL only)
• 2F - Unknown Language Warp Room (PAL only)
• 30 - Unknown Language Warp Room (PAL only)
• 3B - Game Over Screen
• 3C - Title Screen

Crash 3

TBD

See Also

• A forum thread about this
• A blog post describing some of this information
• A page listing the file numbers for each level
• Andy Gavin's blog posts about the Crash Bandicoot series Includes some technical information
• Code to convert PSX ADPCM to PCM
• Information on MIDI files
• A document detailing the Playstation hardware
• If you can get your hands on the PsyQ documentation, it may be useful.

Additional Notes

PAL seems to have different warp room NSFs for the different languages. They're not just separate speech entries; the entire warproom appears in each file.

Chadderz says the chunk checksum is very poor at detecting errors compared to algorithms such as CRC32. I believe the checksum was not introduced to detect such errors, but rather as a disincentive towards modders. It is only in effect on PAL versions of the games, never on the NTSC versions. Maybe SCEE demanded an anti-modding system be implemented, and the checksum was naughty dog's answer?

On second thought, the checksum may have been a quick debugging-related hack. The code for checksum calculation appears in NTSC games (at least for crash 1), but is never executed. Maybe the PAL versions are actually in some kind of semi-debug mode?

The NSF chunk decompression routine for NTSC-U Crash 1 starts at 0x80013970.

T15 entries for crash 2 and 3 appear in these level types: water (C2), boulder (C2), bee (C2), tomb (C3), dino (C3). Seems to be collision related. Messing with them in tomb levels leads to some walls becoming nonsolid. Deleting them is an instacrash in boulder and water levels, but doesn't crash in bee levels until you go underground (at which point you get a real deal freeze that even stops the music, a very rare occurrence, I've never seen it outside of this situation).

There is no music heard in the crash 1 "prototype". However, some of the NSFs do contain music. 0C and 19 both have what appears to be a pre-retail version of the Jungle Rollers theme. 01 and 09 contain another theme which appears to be "Dance of the Sugar-Plum Fairy" from "The Nutcracker", most likely as a test of the music playback system. This theme is split into two separate SEQs in the SEP file, which should(?) be played in parallel. Very unusual, as typically an entire score will be held within a single SEQ, and the other SEQ will be a separate theme, usually three-mask invul music. Why does the music never play in-game? Is there code to reset the music volume to zero when starting the game? Need to investigate with an emulator and cheat engine or similar. On another note, while many of the level files have no music, most(?) of them have wavebank bodies (no headers without music, though), so they had the instruments but not the music?

Where are the damned audio sample rates stored? Please let it not be directly in the code.

Sound entries don't need to be aligned as strictly for most (all?) emulators. Instead, the only requirement is that the sound data needs to be 8-byte aligned. Perhaps this is a consequence of the SPU addressing memory in 8-byte blocks instead of single bytes.

What do NSD and NSF stand for?

Models:

• Info [xsize,ysize,zsize,texturechunkrefs,...]
• Vertices? [colorcount,...]
• Colors [colors]
• Texture Coordinates
• Empty usually?
• Non-existant usually?

Level Models:

• Info [xoffset?,yoffset,zoffset?,zero?,???,???,???,???,colorcount?,???,???,texturechunkrefs,???,???]
• Vertices [vertices[color4,x12,color2,unknown2,y12]] (vertices are shared between polygons?) (where is z?)
• ???
• ???
• ???
• Colors [colors[r,g,b,???]]

Changing the byte in NTSC-U Road to Ruin NSF at 0x104DDE (held within a T11 entry) makes mask boxes give lives instead? Happened when incremented by one, but seemed to happen when changed to other values as well.

T7 second item is collision data? [xoffset,yoffset,zoffset?,collision-xoffset,collision-yoffset,collision-zoffset?,???,???,...]

Retail NTSC-U Crash 1 loads entry types at 0x80013034 and calls a function based on it.

Temporary table of entry type names until I find a place to put it:

The VAB section is incorrect. There may be unused programs between the valid programs. See The High Road Crash 1 NTSC-U Retail NSF.

Something involving the T11 (GOOL) third item at NTSC-U Retail Crash 1 0x80015A98. EDIT: Whoa man, nevermind. This is some kind of code for turning EIDs into pointers to NSD links between CIDs and EIDs. Also maybe something that loads the associated chunk into memory.

There's a bunch of entry ID's near the end of the NSD file. They're references to T11 entries. The "type" field in an entity is actually an index into this table!

Neither GOOL or GOAL had runtime GC. GOAL had a kind of runtime compaction. Most datastructures (including processes) were fully relocatable and the compactor would bubble up the empty spaces to compact them.

GOOL didn't have true runtime symbols. GOAL did, but the symbol table was global without name spaces. Chunks of symbols were loaded and unloaded with levels however.

What if entry types aren't actually entry types, but rather identifiers for the in-game subsystem the data is associated with. For example, the GOOL subsystem might be the subsystem #11 in the game, and T11 entries are just data associated with the GOOL subsystem. This would explain the gaps in entry types (10 is OPAT, but there are no T10 entries despite there being OPAT-related code in the game, perhaps OPAT has no need for NSF-stored data). This would also explain why speech and sound effects have different entry types (different subsystems for sfx and speech).

Entity field flags:

T11 (GOOL): (these are also referenced in a table in the NSD file, indexed with the entity type)

• Info [entitytype?,???,???,???,entitysubtypestartingindexintofourthitem?,???]
• Code?
• Data?
• State Jump Table? Event Handler Table? [indices]
• State Table? [[???,???,???,???,???,???,???,behavior??]]
• Model/Animation Reference Table? [[???,???,t1ref?,???],...]

Entity type determines what GOOL entry should be used. Is the subtype actually an "initial state" setting?

T11 second item contains legit pieces of code. From the box code in Snow Go:

Crash engine uses psx 1K "scratch pad" at 0x1F800000 as a lookup table for GOOL? See 0x8003A014 in NTSC-U Crash 2 retail. Value at 0x1F80005C is 0x1F800060? This table appears to be copied from 0x8005C514. Also it seems 0x49BE0BE0 marks the beginning of machine code (native MIPS), which must be terminated by the byte string 09 A8 E0 03 00 00 00 00, which is:

(cont.) This is because the handler for opcode 49 is like so:

(cont.) Where $S5 is the GOOL interpreter's instruction pointer. Thus, the GOOL interpreter will resume execution of the bytecode starting immediately after the MIPS NOP.

79 GOOL opcodes (with unofficial names. table is based off NTSC-U retail Crash 2):

GOOL source operand format:

• 00xx xxxx xxxx - S4?
• 01xx xxxx xxxx - S3?
• 100x xxxx xxxx - INT IMMEDIATE?
• 1010 xxxx xxxx - FRAC IMMEDIATE?
• 1011 0xxx xxxx - S7?
• 1011 1xxx xxxx - BOOLEAN IMMEDIATE?
• 110x xxxx xxxx - REMOTE MEMBER?
• 111x xxxx xxxx - POP OR MEMBER?

GOOL destination operand format:

• 0xx xxxx xxxx - S7?
• 10x xxxx xxxx - REMOTE MEMBER?
• 11x xxxx xxxx - PUSH OR MEMBER?

Stuff: (C2 only, C1 probably has different offsets)

• SO - Pointer to object instance?
• *(S0 + 12) - Pointer to entry
• *(S0 + 16) - S4PTR?
• *(S0 + 20) - S3PTR?
• *(S0 + 188) - GOOL Stack Pointer
• *(S0 + 192) - GOOL Instruction Pointer
• *(S0 + 196) - S7?

On the topic of the Crash 2 GOOL RNG:

chadderz121: So I think, it's essentially a shift register doing this: (B0,B1,B2,B3,B4,B5,B6,B7) = (B7+B2+B5,B0,B1,B2,B3,B4,B5,B6)
» Where B0-B3 is A1 and B4-B7 is A2
» *A0 not A2