Burnout Wiki:Format documentation specification
All technical documentation of formats used by the Burnout games should use the same key layouts, maintaining consistency across the wiki. This is both for improved readability for viewers and easier editing for contributors.
General
Choosing a data type
Much of the time, the exact data type of a field is unknown even when its meaning and purpose are clear. A 4-byte integer could be signed or unsigned and it could be an int, int32_t, long, DWORD, or any number of other types. In these cases, fixed-width data types as defined in the C++ header stdint.h should be used. Where the sign is unclear, choose the unsigned variant of the type.
In cases where the type is truly unknown (e.g., it cannot be discerned whether it is a float or integer), a single question mark may be displayed to mark it as such.
Endianness
The byte order, or endianness, of hexadecimal values displayed on the wiki should always be big endian. If they are little endian as they are on PC, PS2, and Xbox, they should be converted (byteswapped).
Unused columns
Columns defined here should never be removed, even when empty. This is a compromise between readability and editability; adding columns, especially in large tables, can be very tedious and time-consuming.
Sections
Formats should be documented with at least the top-level section Structures. Unions, Typedefs and Enumerations are optional top-level sections. Other top-level sections may be added as necessary.
Generally, individual structures, unions, typedefs, and enumerations are third-level sections while variants (such as 32 and 64 bit) are fourth-level. While this page structure is preferred, it is not a strict requirement; all lower-level sections may be chosen at the editor's discretion.
Sections should be named the full name of the type with all namespaces included, e.g., BrnVehicle::GraphicsSpec. If the full name is unknown, use a name relevant to its purpose. Never title a section "unknown" unless the content's purpose is truly unknown.
Page names
Page names should be plain English versions of the official format name, e.g., the page for GenericRwacWaveContent is titled Generic RWAC Wave Content. If the format name is unknown, use a name most relevant to its purpose.
Structures
Structures in the Burnout games are fixed-length, with no exceptions. In cases where the position of data varies, pointers are invariably in use; members are accessed through them and the documentation should reflect this.
Structures should be displayed in the following format:
| Offset | Length | Type | Name | Description | Comments |
|---|---|---|---|---|---|
| 0x0 | 0x4 | int32_t | mExample | Example field for documentation guide | This is just an example |
Columns
Offset
The offset of the field within the structure. This should always be hexadecimal and prefixed with 0x.
Length
The length of the field. This should always be hexadecimal and prefixed with 0x, even if the length is less than decimal 10. This is for consistency between offsets and lengths—mixed base documentation has proven confusing in the past.
Though this column has been excluded in the past due to the presence of the type column, lengths are included for three primary reasons:
- In cases where a non-standard type is used, it may be useful to have immediate access to the length of said type.
- When a field has an unknown type, the size of the field is the only thing hinting at its potential types. In some cases, it may even be the only indicator the field exists.
- Areas that are entirely unknown may be given a row instead of being left undefined or having 1-byte rows for each unknown byte.
Type
The data type of the field. If the type is unknown, refer to choosing a data type.
If the type is known and is a structure, union, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type but it is still used as an enumerated value or similar, leave the link in the Comments column in the style "See [[link]]".
This column may be left blank if the area is known to be undefined (padding).
Name
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available, display a single question mark to mark it as unknown.
This column may be left blank if the area is known to be undefined (padding).
Description
A description of the field's meaning and/or purpose as defined by either official documentation, the user, or some combination of both.
User-defined types should not be described here; instead, they should be linked to from the Type column and described there. This column is solely for describing the field's use(s).
If nothing is known about the field, this column may be left blank.
Comments
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column. This is also where certain types, such as untyped enumerations, may be linked to in the style "See [[link]]".
If there are no additional comments, this column may be left blank.
Unions
Unions are types which use only one member at a time. They can be displayed similarly to structures but without the offset field.
| Length | Type | Name | Description | Comments |
|---|---|---|---|---|
| 0x4 | uint32_t | mExampleInt | An integer member. | This is an example |
| 0x4 | float | mExampleFloat | A floating point member. | This is an example |
Columns
Length
The length of the field. This should always be hexadecimal and prefixed with 0x, even if the length is less than decimal 10. See Structures for more details.
The length should be defined per member just as it is with structures. The overall length of the type will be determined by its largest member and should not be listed separately.
Type
The data type of the field. If the type is unknown, refer to choosing a data type.
If the type is known and is a structure, union, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type but it is still used as an enumerated value or similar, leave the link in the Comments column in the style "See [[link]]".
This column may be left blank if the area is known to be undefined (padding).
Name
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available, display a single question mark to mark it as unknown.
This column may be left blank if the area is known to be undefined (padding).
Description
A description of the field's meaning and/or purpose as defined by either official documentation, the user, or some combination of both.
User-defined types should not be described here; instead, they should be linked to from the Type column and described there. This column is solely for describing the field's use(s).
If nothing is known about the field, this column may be left blank.
Comments
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column. This is also where certain types, such as untyped enumerations, may be linked to in the style "See [[link]]".
If there are no additional comments, this column may be left blank.
Typedefs
Typedefs are unique in that they can only be detected when some form of official documentation is available. This means there are no unknowns associated with them. A Length column is provided regardless as it may be useful to have easy access to that information. There is typically little to say about typedefs, so the Description column is also discarded and any relevant information is provided in the Comments column.
Type definitions should be displayed in the following format:
| Name | Type | Length | Comments |
|---|---|---|---|
| ExampleType | int32_t | 0x4 | This is just an example |
Columns
Name
The name of the typedef.
Type
The type specifier used with the typedef.
Length
The length of the type in bytes. This should be a hexadecimal value prefixed with 0x.
Comments
A description of the typedef may be provided here, as well as any additional comments.
If there are no additional comments, this column may be left blank.
Enumerations
While best suited to fields explicitly typed as enum, this may be used when it is not known whether a field is an enumerated type or not but clearly has a constant set of values. Similarly, it may be used when a field clearly uses a constant set of values despite being typed as an integer in official documentation.
Enumerations should only be linked to from a structure's Type column if it is explicitly typed as an enum. Otherwise, it should be linked to from the Comments column in the style "See [[link]]".
Traditional enumerations
Most enumerations are sets of sequential values from which a single value may be used per variable. It follows that such enumerations are typically in decimal format, and wiki content should reflect this. Sometimes, however, it is appropriate to use hexadecimal, such as with how resource type IDs are split up along hexadecimal boundaries. These are the only situations in which mixed base formatting should be used.
Enumerations should be displayed in the following format:
| Name | Value | Comments |
|---|---|---|
| EXAMPLE_ENUM_ZERO | 0 | An example with the value 0. |
| EXAMPLE_ENUM_ONE | 1 | An example with the value 1. |
| EXAMPLE_ENUM_FORCE_INT | 0x7FFFFFFF | Forces the enum to compile to a 32-bit int. |
Binary flags
Flags allow multiple options to be selected in a single enumeration by way of making each bit a flag. Because of this, there are multiple ways to specify their values. The 3rd least significant bit could be written as bit 2, 1 << 2, 0b00000100, and 0x4. All of these are valid (though the first option is ambiguous), but to maintain consistency and readability across the wiki, only hexadecimal should be used.
Binary flags should be displayed in the following format:
| Name | Value | Comments |
|---|---|---|
| EXAMPLE_FLAG_IS_DAMAGEABLE | 0x1 | The vehicle can be damaged. |
| EXAMPLE_FLAG_CAN_BOOST | 0x2 | The vehicle can boost. |
| EXAMPLE_FLAG_HAS_REAR_LIGHTS | 0x4 | Taillights are attached to the vehicle. |
| EXAMPLE_FLAG_HAS_FRONT_LIGHTS | 0x8 | Headlights are attached to the vehicle. |
Columns
Name
The name of the enumerated value. This must be from official documentation. If no official documentation is available, display a single question mark to mark it as unknown.
Value
The value referenced by the name given in the enumeration. This must be a valid value and can never be unknown or blank.
Comments
Any description or additional comments related to the enumerated values may be provided here.
If there are no additional comments, this column may be left blank.
Bit fields
Bit fields should be denoted in a similar manner to structures and should be listed under the same top-level section. There are, however, some important differences to note.
| Offset (bits) | Length (bits) | Name | Description | Comments |
|---|---|---|---|---|
| 0 | 4 | exampleFourBitField | An example field starting at bit 0 extending for 4 bits. | This is just an example |
LSB 0 vs MSB 0
As with flags, the generally accepted standard is to document binary structures in LSB 0 notation; that is, the least significant bit is listed first. However, this only readable when said structure is split evenly along byte boundaries such as in Xbox 360 textures. In structures such as SndPlayer assets, the structure can be difficult to read when reversed and is actually defined in MSB 0 in the source code.
This solution used by the wiki is to display all binary structures in MSB 0 notation, even when official documentation has it in LSB 0. This improves consistency and readability.
Examples
Binary structures can be far more confusing than normal structures. Thus, though not required, an example is always helpful.
These are created by listing each bit as a column in the header row, the parsed value of the bits in the second row, and a brief description of the parsed data in the third row. The colspan tag can be used to merge columns. The caption, if present, should state the hexadecimal code for the bits.
The following is an example of a bit field header structure for a larger asset:
| Offset (bits) | Length (bits) | Name | Description | Comments |
|---|---|---|---|---|
| 0 | 4 | version | Example version | |
| 4 | 12 | size | Example size | |
| 16 | 4 | numElements | Example number of elements | |
| 20 | 4 | assetIndex | Example asset index | |
| 24 | 8 | elementSize | Example size of elements in the bit field |
And some example data:
| Bit value | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 0 | 0 |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Parsed value | 1 | 0x1FC | ||||||||||||||
| Description | Version 1 | Total asset size of 0x1FC | ||||||||||||||
Should a bit field's table extend past the default width of the default skin (960px), it should be split at the last field before that width and a new table should be started below the first with the first column being (cont.).
| (cont.) | 0 | 0 | 1 | 1 | 0 | 0 | 1 | 1 | 1 | 0 | 1 | 0 | 1 | 0 | 0 | 0 | |||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 3 | 3 | 0xA8 | |||||||||||||||||
| 3 total elements in this asset | Asset index 3 | Each element has a size of 0xA8 | |||||||||||||||||
Columns
Offset
The bit index of the field. This should always be in base 10.
Length
The number of bits the field uses. This should always be in base 10.
Name
The name of the field. This must be provided in some official capacity, such as source code, debugging symbols, or online documentation. If no official documentation is available, display a single question mark to mark it as unknown.
This column may be left blank if the area is known to be undefined (padding).
Description
A description of the field's meaning and/or purpose as defined by either official documentation, the user, or some combination of both.
If nothing is known about the field, this column may be left blank.
Comments
Any comments about the field may be left here. This includes example values, whether the field has a constant value in all samples (such as it being null), and other speculation on it that does not fit the Description column.
If there are no additional comments, this column may be left blank.