EvilEngine/HIP (File Format)

HIP archives, also referred to as HIP/HOP files, are files used by Heavy Iron Studios to store all level data in their Evil Engine games. They are made up of assets, which are the resources and objects used to create levels, characters and menus.

In Scooby-Doo! Night of 100 Frights, all HIP archives use the file extension. SpongeBob SquarePants: Battle for Bikini Bottom introduced the file extension, which has the exact same file format as   but is typically used to store different types of assets. Localized  files were added in The SpongeBob SquarePants Movie and later games to support different languages (,  , 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, The Incredibles: Rise of the Underminer and Ratatouille Prototype. PKR: HIP file version update history Version 1: - baseline Version 2: - Compatible version support information - Asset data checksum - Layer data checksum - Creation/Modification date Version 3: - HIP Layers represent asset memory placement - Layers are not compacted to reduce waste - Loading is based on layers (was by asset) - Added asynchronous loading support

Integers
All integers in HIP archives are unsigned 32-bit (4 bytes long). They are always written in big endian, regardless of platform.

Integers are referred to as  in format descriptions.

Strings
All strings in HIP archives are null-terminated (i.e. end with a NULL byte,  in C/C++). 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, meaning:
 * Strings with an odd length will end with one NULL (hex  ).
 * Strings with an even length with end with two NULLs (hex  ).
 * Empty strings are written as hex.

Strings are referred to as  in format descriptions.

Structure
A HIP archive is stored as a tree of blocks (also known as chunks), where blocks can contain arbitrary data as well as any number of child blocks.

Each block begins with an  human-readable ID that determines what kind of data is present in the block, followed by an   length that is the total amount of bytes taken up by the block's data + child blocks, if any. After the ID and length, the block's data is stored; its format depends on the block ID (see Blocks). Any remaining bytes after the data make up the block's child blocks, which have the same format as normal blocks. Child blocks are parsed repeatedly until the end of the parent block is reached.

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


 * HIPA
 * PACK (Package)
 * PVER (PackageVersion)
 * PFLG (PackageFlags)
 * PCNT (PackageCount)
 * PCRT (PackageCreated)
 * PMOD (PackageModified)
 * PLAT (PackagePlatform) [Not present in Scooby]
 * DICT (Dictionary)
 * ATOC (AssetTableOfContents)
 * AINF (AssetInfo)
 * AHDR (AssetHeader) [Multiple can be present]
 * ADBG (AssetDebug)
 * LTOC (LayerTableOfContents)
 * LINF (LayerInfo)
 * LHDR (LayerHeader) [Multiple can be present]
 * LDBG (LayerDebug)
 * STRM (AssetDataStream)
 * DHDR (AssetDataHeader)
 * DPAK

Assets
Assets are the most important part of HIP archives; they're like the files in ZIP archives. Assets hold all of the raw data for textures, models, sounds, and even objects within a level. Assets also have a name, as well as a unique ID (which is generated from the name using a hash algorithm). The ID is used by the game to find/identify assets. Assets also have a type ID that tells the game how to interpret the asset's raw data. The asset's data is stored at a specified offset in the DPAK block. HIP archives do not use any compression for asset data.

Each asset entry is represented by an AHDR block in HIP archives.

Types
A list of all known asset types can be found here: List of asset types

Layers
Layers are used by HIP archives to group assets of specific types together. Layers have a type ID that specifies what "category" of asset types they contain. For example,  layers contain all of the RWTX assets in a HIP archive,   layers contain all of the MODL assets, and   layers contain many different types of assets (most   files have all their assets in the   layer).

Assets in the same layer have their raw data stored next to each other in the DPAK block. This is mainly done to optimize the memory layout of assets in-game, as well as enforce the order in which assets are loaded (e.g.  layers must be stored before   in order for textures to be applied to models properly).

Each layer entry is represented by an LHDR block in HIP archives.

Types
The following table lists all known layer types and their corresponding type IDs in each game. An empty cell means the layer type is not present in the game.

Layout
HIP archives often contain multiple layers of the same type, usually placed right next to each other. In the vanilla games, assets are distributed across those layers so that each layer has roughly the same number of assets. For example, if a HIP archive has 3  layers and 30 total RWTX assets, each   layer will contain 10 RWTX assets. This was most likely done for multi-threading purposes (loading multiple layers in parallel).

The SpongeBob SquarePants Movie and later games have JSP layer "groups" to support multiple JSPs in one level. These are made up of 3  layers followed by one   layer. JSP layer groups often appear multiple times in a HIP archive. A /  pair will always have the same number of JSP layer groups, even though they are completely empty in   files.

The following tables specify the layout of layers for each game. Each table is sorted by the layers' order of appearance in HIP archives.


 * The Name column is the internal name for each layer type.
 * The Count column is how many times each layer type repeats.
 * The Asset Types column lists what asset types appear in each layer type and whether they mainly appear in,  , or localized   files (e.g.  ).

Blocks
This section contains the format for all known block types in HIP archives. Each section heading is the block's type ID as if it was a human-readable string.

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 compatVersion

subVersion is 2 in all games.

clientVersion is 0x00040006 (4.6) in Scooby, and 0x000A000F (10.15) in all other games.

compatVersion is 1 in all games.

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  flag set (see AHDR flags).

PCRT
This block contains the creation date of the archive. int createdDate string createdDateString

createdDate is the number of seconds since 00:00, Jan 1 1970 UTC, with a timezone offset of UTC-7:00 (Pacific Time).

createdDateString is createdDate as a string, in the format.
 * Www - the day of the week (one of Mon, Tue, Wed, Thu, Fri, Sat, Sun).
 * Mmm - the month (one of Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec).
 * dd - the day of the month
 * hh - hours
 * mm - minutes
 * ss - seconds
 * yyyy - years
 * Example: Thu Sep 02 06:15:46 2004

This is the same format returned by the C standard function. It always ends with a newline character in Scooby.

PMOD
This block contains the latest modification date of the archive. int modifiedDate

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.

language is the archive's target language.

gameName is the archive's target game.

The following table lists all possible values for these variables:

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  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 debugging info for its parent AHDR block. 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 /  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. This was (unfortunately) trimmed to 31 characters (plus the NULL byte) when stored in vanilla HIP files, despite HIP files supporting longer strings, however, the asset ID was calculated from the asset's original name. This means that there are sometimes multiple assets in a HIP file with the same name but different IDs.

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

checksum is the checksum of the asset's data. The algorithm to calculate the checksum is CRC-32/MPEG-2. It's unused by the game.

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.
 * 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.