Bundle: Difference between revisions

From Burnout Wiki
mNo edit summary
m (Updated common data type link.)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
  +
{{hatnote|This page is about the original Bundle format, used only during development. For the version used in retail titles, see [[Bundle 2]].}}
{{subpage|Enumerations|text=Enumerations used in the Bundle container.}}
 
   
The Bundle container is the core file format of Burnout Paradise and Criterion's other 7th-gen titles, with the exception of Burnout Revenge (X360). Each Bundle holds one or more resources (assets) and contains information about each resource, such as its size, [[Resource Types (Burnout Paradise)|type]], compression, alignment, and so on.
+
The Bundle container is the core file format used in development builds of Burnout 5/Paradise, Black (Xbox 360), and Black 2 (Xbox 360). It is not used in any retail titles. Each Bundle holds one or more resources (assets) and contains information about each resource, such as its size, type, compression, alignment, and so on.
   
The Bundle format has two major versions: the original, using the <code>bndl</code> magic, and Bundle 2, using the <code>bnd2</code> magic. The first Bundle format underwent at least five iterations during its use from early 2006 to early-mid 2007, but it was never used in a retail game and can only be found in development builds of games such as Burnout Paradise. It was succeeded by Bundle 2, which ultimately saw use in the retail versions of Burnout Paradise (version 2), Need for Speed Hot Pursuit (version 3), and Need for Speed Most Wanted (version 5).
+
The Bundle format underwent at least five iterations during its use from early 2006 to early-mid 2007. At present, only files using Bundle version 3, 4, and 5 have been discovered. It was succeeded by the [[Bundle 2]] container.
 
At present, only files using Bundle version 3, 4, and 5 have been discovered. Those versions, plus Bundle 2 version 2, are described below. For information on later versions, see the [https://needforspeed.miraheze.org/wiki/Bundle Need for Speed Wiki].
 
   
 
= Overview =
 
= Overview =
Bundles are used for nearly every asset in Burnout Paradise, with the only exceptions being the <code>JUNKYARDLIGHTING.DAT</code> text file and <code>STARDATA.DAT</code> binary file (both in the <code>ENVIRONMENTSETTINGS</code> folder), the non-RAM portion of sound assets, and video files. This makes it one of the most important formats to understand when attempting to parse assets.
+
Bundles are used for nearly every asset in Burnout Paradise. This makes it one of the most important formats to understand when attempting to parse assets.
   
While the header contains some valuable data, such as the flags and chunk offsets, the majority of relevant information is in resource entries, which store the ID, uncompressed and compressed size, alignment, relative offset, and type of each resource in each chunk. These also store the import offsets, which enable importing specific data from other resources.
+
While the header contains some valuable data, such as the flags and chunk offsets, the majority of relevant information is in resource entries, which store the size, alignment, offset, and type of each resource in each chunk. These also store the import offsets, which enable importing specific data from other resources.
   
Bundle debug data is also important to understand. Sometimes called Bundle imports, this was originally only available in development builds but shipped with every Bundle in the game in Remastered. Consisting of XML data headed by the <code>ResourceStringTable</code> element, it contains the ID, name, and type name of every resource in a respective bundle. This means that effectively every resource name in the game is known. Despite this, the resource names given by the debug data sometimes do not match the hash when encoded. In some cases, such as with Registry resources, this means the name is hardcoded.
+
Bundle debug data is also important to understand. Sometimes called Bundle imports, it consists of XML data headed by the <code>ResourceStringTable</code> element and contains the ID, name, and type name of every resource in a respective bundle. This means that where debug data is present, every resource name is known. Despite this, the resource names given by the debug data sometimes do not match the hash when encoded. In some cases, such as with Registry resources, this means the name is hardcoded.
   
 
= Memory types =
 
= Memory types =
 
Across all Bundle versions, a common theme is the use of separate data chunks to define what memory type resources are loaded into. These chunks are as follows:
 
Across all Bundle versions, a common theme is the use of separate data chunks to define what memory type resources are loaded into. These chunks are as follows:
   
Bundle:
 
 
# Main Memory
 
# Main Memory
 
# Disposable
 
# Disposable
Line 24: Line 21:
 
# Disposable uninitialized
 
# Disposable uninitialized
   
 
Keep these in mind when viewing the structures.
Bundle 2 V2:
 
# Main Memory
 
# Graphics System
 
# Graphics Local
 
   
  +
= Structures =
Keep these in mind when viewing the specs below.
 
 
= Bundle Layout =
 
 
The original Bundle format's versions were treated more like additions to the previous version. Thus, rather than a full structure for each, only their additions are described here.
 
The original Bundle format's versions were treated more like additions to the previous version. Thus, rather than a full structure for each, only their additions are described here.
   
  +
== CgsResource::BundleHeaderBase ==
== Version 3 ==
 
 
=== Bundle ===
 
=== Bundle ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
 
| 0x0 || 0x4 || char[4] || macMagicNumber || Bundle magic || bndl
 
| 0x0 || 0x4 || char[4] || macMagicNumber || Bundle magic || bndl
 
|-
 
|-
| 0x4 || 0x4 || uint32_t || muVersion || Bundle version ||
+
| 0x4 || 0x4 || uint32_t || muVersion || Bundle version || 3 in base, 4 in V4, 5 in V5
 
|-
 
|-
 
| 0x8 || 0x4 || uint32_t || muResourceEntriesCount || Number of resources in the bundle ||
 
| 0x8 || 0x4 || uint32_t || muResourceEntriesCount || Number of resources in the bundle ||
 
|-
 
|-
| 0xC || 0x28 || Unknown0[5] || || Size and alignment of each chunk ||
+
| 0xC || 0x28 || [[#Size and alignment | Size and alignment]][5] || || Size and alignment of each chunk ||
 
|-
 
|-
 
| 0x34 || 0x14 || uint32_t[5] || || Memory address of each chunk ||
 
| 0x34 || 0x14 || uint32_t[5] || || Memory address of each chunk ||
Line 58: Line 50:
 
| 0x54 || 0x4 || uint32_t || muResourceDataOffset || Resource data offset ||
 
| 0x54 || 0x4 || uint32_t || muResourceDataOffset || Resource data offset ||
 
|-
 
|-
| 0x58 || 0x4 || uint32_t || muPlatform || Platform the bundle was built for || See [[Bundle/Enumerations#Platform|Platform]]
+
| 0x58 || 0x4 || uint32_t || muPlatform || Platform the bundle was built for || See [[#Platform | Platform]]
 
|}
 
|}
   
Line 64: Line 56:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
 
| 0x0 || 0x4 || uint32_t || || Resource data memory address ||
 
| 0x0 || 0x4 || uint32_t || || Resource data memory address ||
Line 70: Line 62:
 
| 0x4 || 0x4 || uint32_t || muImportOffset || Bundle imports offset ||
 
| 0x4 || 0x4 || uint32_t || muImportOffset || Bundle imports offset ||
 
|-
 
|-
| 0x8 || 0x4 || uint32_t || muResourceTypeId || Resource type || See [[Resource Types (Burnout Paradise)|Resource Types]]
+
| 0x8 || 0x4 || uint32_t || muResourceTypeId || Resource type || See [[#ResourceType | ResourceType]]
 
|-
 
|-
| 0xC || 0x28 || Unknown0[5] || mauSizeAndAlignmentOnDisk || ||
+
| 0xC || 0x28 || [[#Size and alignment | Size and alignment]][5] || mauSizeAndAlignmentOnDisk || ||
 
|-
 
|-
| 0x34 || 0x28 || Unknown0[5] || mauDiskOffset || Offsets in bundle || Alignment is unused (always 1)
+
| 0x34 || 0x28 || [[#Size and alignment | Size and alignment]][5] || mauDiskOffset || Offsets in bundle || Alignment is unused (always 1)
 
|-
 
|-
 
| 0x5C || 0x14 || uint32_t[5] || || Memory addresses || Swapped endian
 
| 0x5C || 0x14 || uint32_t[5] || || Memory addresses || Swapped endian
Line 80: Line 72:
   
 
=== Imports ===
 
=== Imports ===
  +
This is not a structure as such; rather, it is <code>uint32_t muImportCount</code> followed by four bytes of padding, then a set of import entries of an amount defined by the aforementioned count.
{| class="wikitable"
 
|-
 
! Offset !! Size !! Type !! Name !! Description !! Comments
 
|-
 
| 0x0 || 0x4 || uint32_t || muImportCount || Number of imports ||
 
|-
 
| 0x8 || || || || Import entries || Aligned 8. See [[#ImportEntry|ImportEntry]] structure
 
|}
 
   
 
=== ImportEntry ===
 
=== ImportEntry ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
| 0x0 || 0x8 || ID || mResourceId || Resource name CRC32 ||
+
| 0x0 || 0x8 || [[Resource ID | ID]] || mResourceId || Resource name CRC32 ||
 
|-
 
|-
 
| 0x8 || 0x4 || uint32_t || muOffset || ||
 
| 0x8 || 0x4 || uint32_t || muOffset || ||
Line 101: Line 86:
 
|}
 
|}
   
=== Unknown0 ===
+
=== Size and alignment ===
This structure contains fields for size and alignment, though alignment sometimes goes unused.
+
This structure contains fields for size and alignment, though alignment sometimes goes unused. Real name is not known.
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
 
| 0x0 || 0x4 || uint32_t || || Size or offset ||
 
| 0x0 || 0x4 || uint32_t || || Size or offset ||
Line 112: Line 97:
 
|}
 
|}
   
  +
== CgsResource::BundleHeaderV4 ==
== Version 4 Additions ==
 
=== Bundle ===
+
=== Bundle (Additions) ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
| 0x5C || 0x4 || uint32_t || muFlags || Bundle flags || See [[Bundle/Enumerations#Flags|Flags]]
+
| 0x5C || 0x4 || uint32_t || muFlags || Bundle flags || See [[#Flags | Flags]]
 
|-
 
|-
 
| 0x60 || 0x4 || uint32_t || || Number of compressed resources ||
 
| 0x60 || 0x4 || uint32_t || || Number of compressed resources ||
Line 128: Line 113:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
| 0x0 || 0x28 || Unknown0[5] || mauUncompressedSizeAndAlignment || ||
+
| 0x0 || 0x28 || [[#Size and alignment | Size and alignment]][5] || mauUncompressedSizeAndAlignment || ||
 
|}
 
|}
   
  +
== CgsResource::BundleHeaderV5 ==
== Version 5 Additions ==
 
=== Bundle ===
+
=== Bundle (Additions) ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Offset !! Length !! Type !! Name !! Description !! Comments
 
|-
 
|-
 
| 0x68 || 0x4 || uint32_t || || || No idea what this does
 
| 0x68 || 0x4 || uint32_t || || || No idea what this does
Line 144: Line 129:
 
|}
 
|}
   
= Bundle 2 Layout =
+
= Enumerations =
=== BundleV2 ===
+
=== Platform ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Name !! Value !! Comments
 
|-
 
|-
  +
| ? || 1 || PC
| 0x0 || 0x4 || char[4] || macMagicNumber || Bundle magic || bnd2
 
 
|-
 
|-
  +
| ? || 2 || Xbox 360
| 0x4 || 0x4 || uint32_t || muVersion || Bundle version ||
 
 
|-
 
|-
  +
| ? || 3 || PlayStation 3
| 0x8 || 0x4 || uint32_t || muPlatform || Platform the bundle was built for || See [[Bundle/Enumerations#Platform|Platform]]
 
|-
 
| 0xC || 0x4 || uint32_t || muDebugDataOffset || Bundle debug data offset || ResourceStringTable XML
 
|-
 
| 0x10 || 0x4 || uint32_t || muResourceEntriesCount || Number of resources in the bundle ||
 
|-
 
| 0x14 || 0x4 || uint32_t || muResourceEntriesOffset || Resource entries offset ||
 
|-
 
| 0x18 || 0xC || uint32_t[3] || mauResourceDataOffset || Resource data offset ||
 
|-
 
| 0x24 || 0x4 || uint32_t || muFlags || Bundle flags || See [[Bundle/Enumerations#Flags|Flags]]
 
 
|}
 
|}
   
=== ResourceEntry ===
+
=== Flags ===
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
! Offset !! Size !! Type !! Name !! Description !! Comments
+
! Name !! Value !! Comments
 
|-
 
|-
  +
| IsCompressed || 0x1 || Resources are zlib compressed
| 0x0 || 0x8 || ID || mResourceId || Resource name CRC32 || Hashed names are all lowercase
 
|-
 
| 0x8 || 0x8 || uint64_t || muImportHash || Dependency name(s) CRC32(s) || Multiple are combined with a bitwise OR
 
|-
 
| 0x10 || 0xC || uint32_t[3] || mauUncompressedSizeAndAlignment || Resource sizes (uncompressed) for each chunk || Has high nibble for alignment; changes between platforms<br>1 << [nibble] equals the memory alignment value
 
|-
 
| 0x1C || 0xC || uint32_t[3] || mauSizeAndAlignmentOnDisk || Resource sizes (compressed) for each chunk || See above
 
|-
 
| 0x28 || 0xC || uint32_t[3] || mauDiskOffset || Resource offsets for each chunk || Relative to the start of the respective chunk
 
|-
 
| 0x34 || 0x4 || uint32_t || muImportOffset || Bundle imports offset ||
 
|-
 
| 0x38 || 0x4 || uint32_t || muResourceTypeId || Resource type || See [[Resource Types (Burnout Paradise)|Resource Types]]
 
|-
 
| 0x3C || 0x2 || uint16_t || muImportCount || Number of imports ||
 
|-
 
| 0x3E || 0x1 || uint8_t || muFlags || ||
 
|-
 
| 0x3F || 0x1 || uint8_t || muStreamIndex || ||
 
 
|}
 
|}
   
=== ImportEntry ===
+
=== ResourceType ===
 
See [[Resource Types (Burnout Paradise) | Resource Types]].
{| class="wikitable"
 
|-
 
! Offset !! Size !! Type !! Name !! Description !! Comments
 
|-
 
| 0x0 || 0x8 || ID || mResourceId || Resource name CRC32 || ImportEntries are appended to the end of resources.
 
|-
 
| 0x8 || 0x4 || uint32_t || muOffset || ||
 
|-
 
| 0xC || 0x4 || || || padding ||
 
|}
 

Latest revision as of 23:03, 13 September 2022

The Bundle container is the core file format used in development builds of Burnout 5/Paradise, Black (Xbox 360), and Black 2 (Xbox 360). It is not used in any retail titles. Each Bundle holds one or more resources (assets) and contains information about each resource, such as its size, type, compression, alignment, and so on.

The Bundle format underwent at least five iterations during its use from early 2006 to early-mid 2007. At present, only files using Bundle version 3, 4, and 5 have been discovered. It was succeeded by the Bundle 2 container.

Overview[edit | edit source]

Bundles are used for nearly every asset in Burnout Paradise. This makes it one of the most important formats to understand when attempting to parse assets.

While the header contains some valuable data, such as the flags and chunk offsets, the majority of relevant information is in resource entries, which store the size, alignment, offset, and type of each resource in each chunk. These also store the import offsets, which enable importing specific data from other resources.

Bundle debug data is also important to understand. Sometimes called Bundle imports, it consists of XML data headed by the ResourceStringTable element and contains the ID, name, and type name of every resource in a respective bundle. This means that where debug data is present, every resource name is known. Despite this, the resource names given by the debug data sometimes do not match the hash when encoded. In some cases, such as with Registry resources, this means the name is hardcoded.

Memory types[edit | edit source]

Across all Bundle versions, a common theme is the use of separate data chunks to define what memory type resources are loaded into. These chunks are as follows:

  1. Main Memory
  2. Disposable
  3. Physical
  4. Uninitialized
  5. Disposable uninitialized

Keep these in mind when viewing the structures.

Structures[edit | edit source]

The original Bundle format's versions were treated more like additions to the previous version. Thus, rather than a full structure for each, only their additions are described here.

CgsResource::BundleHeaderBase[edit | edit source]

Bundle[edit | edit source]

Offset Length Type Name Description Comments
0x0 0x4 char[4] macMagicNumber Bundle magic bndl
0x4 0x4 uint32_t muVersion Bundle version 3 in base, 4 in V4, 5 in V5
0x8 0x4 uint32_t muResourceEntriesCount Number of resources in the bundle
0xC 0x28 Size and alignment[5] Size and alignment of each chunk
0x34 0x14 uint32_t[5] Memory address of each chunk
0x48 0x4 uint32_t Resource IDs offset
0x4C 0x4 uint32_t muResourceEntriesOffset Resource entries offset
0x50 0x4 uint32_t Imports offset
0x54 0x4 uint32_t muResourceDataOffset Resource data offset
0x58 0x4 uint32_t muPlatform Platform the bundle was built for See Platform

ResourceEntry[edit | edit source]

Offset Length Type Name Description Comments
0x0 0x4 uint32_t Resource data memory address
0x4 0x4 uint32_t muImportOffset Bundle imports offset
0x8 0x4 uint32_t muResourceTypeId Resource type See ResourceType
0xC 0x28 Size and alignment[5] mauSizeAndAlignmentOnDisk
0x34 0x28 Size and alignment[5] mauDiskOffset Offsets in bundle Alignment is unused (always 1)
0x5C 0x14 uint32_t[5] Memory addresses Swapped endian

Imports[edit | edit source]

This is not a structure as such; rather, it is uint32_t muImportCount followed by four bytes of padding, then a set of import entries of an amount defined by the aforementioned count.

ImportEntry[edit | edit source]

Offset Length Type Name Description Comments
0x0 0x8 ID mResourceId Resource name CRC32
0x8 0x4 uint32_t muOffset
0xC 0x4 padding

Size and alignment[edit | edit source]

This structure contains fields for size and alignment, though alignment sometimes goes unused. Real name is not known.

Offset Length Type Name Description Comments
0x0 0x4 uint32_t Size or offset
0x4 0x4 uint32_t Alignment

CgsResource::BundleHeaderV4[edit | edit source]

Bundle (Additions)[edit | edit source]

Offset Length Type Name Description Comments
0x5C 0x4 uint32_t muFlags Bundle flags See Flags
0x60 0x4 uint32_t Number of compressed resources
0x64 0x4 uint32_t Compression information offset

Compression Information[edit | edit source]

Offset Length Type Name Description Comments
0x0 0x28 Size and alignment[5] mauUncompressedSizeAndAlignment

CgsResource::BundleHeaderV5[edit | edit source]

Bundle (Additions)[edit | edit source]

Offset Length Type Name Description Comments
0x68 0x4 uint32_t No idea what this does
0x6C 0x4 uint32_t Also no idea what this does

Enumerations[edit | edit source]

Platform[edit | edit source]

Name Value Comments
? 1 PC
? 2 Xbox 360
? 3 PlayStation 3

Flags[edit | edit source]

Name Value Comments
IsCompressed 0x1 Resources are zlib compressed

ResourceType[edit | edit source]

See Resource Types.