EvilEngine/HIP (File Format)

HIP archives, also referred to as HIP/HOP files or packages, are container files used by Heavy Iron Studios in their 5 RenderWare games covered on this wiki. They are used to store assets, which are the resources and objects used to create levels, characters and menus for the games.

In Scooby-Doo! Night of 100 Frights, all HIP archives use the file extension .HIP. SpongeBob SquarePants: Battle for Bikini Bottom introduced the file extension .HOP, which has the exact same file format as .HIP but is typically used to store different types of assets. Each level and some global scenes (such as player data) are stored as .HIP/.HOP pairs in BFBB and subsequent games, and the rest of the HIP archives just use .HIP (boot.HIP, font.HIP, etc.).

File Format

There are three known revisions of the HIP archive format: the first one used in Scooby-Doo! Night of 100 Frights, a second one used in SpongeBob SquarePants: Battle For Bikini Bottom and a third one which is used in The SpongeBob SquarePants Movie, The Incredibles and The Incredibles: Rise of the Underminer.

A HIP archive is stored as a hierarchical structure of blocks. Each block has a 4-byte ID and length, and can contain data as well as child blocks. The ID is typically human-readable and can be read as a 4-byte ASCII string, although it's technically read as an int in BFBB's source code. The length determines how many bytes the entire block takes up, including both its data and child blocks. The header is stored as follows:

int blockID
int blockLength

Following the header, any block-specific data is stored, followed by any child blocks.

Overall Structure

The basic block hierarchy common to all HIP archives is as follows:

• HIPA
• PACK
  • PVER
  • PFLG
  • PCNT
  • PCRT
  • PMOD
  • PLAT (Not present in Scooby)
• DICT
  • ATOC
    • AINF
    • AHDR+ (Multiple can be present)
      • ADBG
  • LTOC
    • LINF
    • LHDR+ (Multiple can be present)
      • LDBG
• STRM
  • DHDR
  • DPAK

Layers

Layers are used by HIP archives to group assets of specific types together. For example, TEXTURE layers contain all of the RWTX assets in a HIP archive and MODEL layers contain all of the MODL assets. All assets in a HIP archive have their data grouped together by layer inside the DPAK block, with padding in between each asset's data as well as in between each layer. DPAK explains more about how padding and alignment of assets and layers works.

TODO: list all known type IDs

Strings

All strings in HIP archives are null-terminated, i.e. end with a 0 byte (\x00). They do not have a character count at the beginning. All strings are padded at the end so that their length is a multiple of two bytes. This means that all strings will have either one or two 0s at the end. Empty strings are simply stored as two 0s.

Strings are referred to as string in the Block format descriptions.

Endian

HIP archives are stored as big endian in all versions of each game.

Blocks

This section contains the format for each block described in Overall Structure. Each section heading refers to the block's 4-byte ID.

HIPA

This block contains no data or child blocks. It is used to mark the start of the file, and the ID can serve as a magic number to identify the file's type.

PACK

This block contains no data but it does contain child blocks: PVER, PFLG, PCNT, PCRT, and PMOD, as well as PLAT in every game past Scooby Doo: Night of 100 Frights. This block is used to group together various metadata about the archive.

PVER

This block contains information about the archive version.

int subVersion
int clientVersion
int compatible

TODO: document all possible values

PFLG

This block contains archive flags. It is unused by the game.

int flags

• In all games, this value always includes 0x2E in the flags. Its meaning is unknown.
• In BFBB, every file except font2.HIP has some extra flags:
  • 0x290000 is used in GC US hips
  • 0x2A0000 is used in Xbox hips
  • 0x2C0000 is used in PS2 hips
  • 0x510000 is used in GC mn-pal/mnu3.HIP and mn-pal/mnu3.HOP
  • 0x02000000 is used in all BFBB hips except font2.HIP

PCNT

This block contains counts of specific things, only the first 2 are used by the game.

int assetCount
int layerCount
int maxAssetSize
int maxLayerSize
int maxXformAssetSize

assetCount determines how many assets are in the HIP archive and thus how many AHDR blocks should be present.

layerCount determines how many layers are in the HIP archive and thus how many LHDR blocks should be present.

maxAssetSize is the largest asset size in bytes out of all assets in the archive.

maxLayerSize is the size in bytes of the layer that takes up the most space in the DPAK block, minus the padding bytes at the end.

maxXformAssetSize is the largest asset size in bytes out of all assets specifically with the READ_TRANSFORM flag set (see AHDR flags).

PCRT

This block contains the creation date of the archive.

time_t createdDate
string createdDateString

time_t is stored as a 4-byte int and originates from C/C++. In HIP archives, it is the number of seconds since 00:00, Jan 1 1970 UTC, with a timezone offset of UTC-7:00 (Pacific Time).

createdDateString always ends with a newline character ('\n', '\x0A') in Scooby.

PMOD

This block contains the latest modification date of the archive.

time_t modifiedDate

See PCRT for a definition of time_t.

PLAT

This block contains information about the specific game, platform, language, etc. the archive was built for. It's not present in Scooby. The format differs between BFBB and its subsequent games:

BFBB:

int platformID
string platformName
string region
string language
string gameName

TSSM, Incredibles, ROTU:

int platformID
string language
string region
string gameName

platformID is a 4-byte ID referring to which platform the archive was built for.

platformName is a human-readable string corresponding to the platformID.

region is the archive's target region, either NTSC or PAL.

language is the archive's target language.

gameName is the archive's target game. This is always "Sponge Bob" in BFBB and "Incredibles" in TSSM, Incredibles, and ROTU.

TODO: list all possible values for everything

DICT

This block serves as a "dictionary" for all the assets and layers in the HIP archive. It contains no data and 2 child blocks: ATOC and LTOC.

ATOC

This section holds all the asset entries for the HIP archive. It contains no data and a AINF child block followed by a variable number of AHDR child blocks. The number of AHDR blocks should match the assetCount value found in PCNT. All AHDR blocks together form a list and is sorted by the id value found within each block when building the HIP archive.

AINF

This block is unused by the game.

int ainf

This value is always 0.

AHDR

This block defines an entry for an asset. It contains some data followed by an ADBG child block.

int id
int type
int offset
int size
int plus
int flags

id is the asset's unique 4-byte ID, which is calculated by the asset's name using a variation of the BKDR hash algorithm, described here.

type is the asset's 4-byte type ID, which is typically human-readable and can be read as an ASCII string if preferred. All known type IDs can be found here.

offset is the starting position of the asset's data, relative to the beginning of the file.

size is the length in bytes of the asset's data.

plus is the amount of padding bytes present between the end of the asset's data and the next asset in the layer's data. It's calculated from the alignment value in the ADBG block. The last asset in each layer has a plus value of 0.

flags is a bitfield of settings which specifies how the asset's data is stored and how it should be handled by the game:

• 0x1 - SOURCE_FILE - The asset's data was sourced from an external file. The filename/path can be found in the ADBG child block.
• 0x2 - SOURCE_VIRTUAL - The asset's data was created within the level editor Heavy Iron used. The filename in ADBG is empty.
• 0x4 - READ_TRANSFORM - The asset's data is stored in a special format which needs to be "transformed" by the game into a runtime-specific format. This applies to all RenderWare assets, such as MODL, which is stored as a .dff file and needs to be transformed into an "RpClump" (RenderWare object) at runtime.
• 0x8 - WRITE_TRANSFORM - The asset's data needs to be transformed from a runtime-specific format into a special binary format, likely used by Heavy Iron's level editor.

ADBG

This block defines debug-specific info for its parent AHDR block. None of this is used by the release builds of any games, but Heavy Iron left it in anyways, and thank goodness for that.

int alignment
string name
string filename
int checksum

alignment is the multiple of bytes that the asset's data aligns to. This value can be -1 (or any negative value), which means it uses the "default" alignment value for the asset's specific type ID. The default alignment value for each asset type can be found in .LIP/.LOP files in BFBB and Scooby (either 16 or 32 for most types).

name is the asset's name, which also determines the asset's ID.

filename is the asset's source filename if the SOURCE_FILE flag is set in the parent AHDR block.

checksum is the checksum of the asset's data. The algorithm to calculate the checksum is currently unknown, but it's unused by the game anyways.

LTOC

This section holds all the layer entries for the HIP archive. It contains no data and a LINF child block followed by a variable number of LHDR child blocks. The number of LHDR blocks should match the layerCount value found in PCNT.

LINF

This block is unused by the game.

int linf

This value is always 0.

LHDR

This block defines an entry for a layer. It contains some data followed by an LDBG child block.

int type
int assetCount
int[assetCount] assetIDs

type is the layer's type ID, which determines what types of assets are stored within this layer. Multiple layers can have the same type ID, which means that assets will be divided evenly between those layers. Layers lists all known type IDs.

assetCount is the number of assets in this layer.

assetIDs is a list of all the assets' IDs. The order of IDs in this list determines the order that the assets' data will be stored in DPAK.

LDBG

This block is unused by the game.

int ldbg

This value is always -1 (0xFFFFFFFF).

STRM

This block organizes all of the data for the assets in the HIP archive. It contains no data and 2 child blocks: DHDR and DPAK.

DHDR

This block is unused by the game.

int dhdr

This value is always -1 (0xFFFFFFFF).

DPAK

This block contains all asset data, grouped by layer.

Each layer is aligned to a fixed size which depends on the target platform:

• GameCube: 32 bytes
• PS2/Xbox: 2048 bytes

Each asset is aligned to the alignment value specified by their corresponding ADBG block.

In order to align assets and layers, padding bytes are used. All padding bytes have the value 0x33.

• All assets, except for the last asset in each layer, have padding bytes after them. The plus value in each asset's AHDR block is set to the amount of padding bytes used.
• All layers, including the last one, have padding at the end. The maxLayerSize value in PCNT does not include the amount of padding bytes used.

If there are 0 assets (assetCount in PCNT is 0), this block contains no data. Otherwise:

int paddingAmount
char[paddingAmount] padding
char[] data

There is padding between the start of the block and the beginning of the asset data. The amount of padding is calculated from the fixed layer alignment size (described above), minus the first 4 bytes which is reserved for paddingAmount. It specifies how many padding bytes will follow.

Tools

HipHopFile is a library which can be used to work with HIP files.

External links

• xhipio.cpp - BFBB's source code for reading basic blocks and values from HIP archives
• xpkrsvc.cpp - BFBB's source code for reading all assets and layers from BFBB-specific HIP archives