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 question mark may be used instead.

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

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, enumeration, or custom typedef, this should be a link to the relevant section. If the official documentation states it is a standard type, 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, use a question mark.

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. A question mark should never be used.

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. A question mark should never be used.

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, making a Length column unnecessary. 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	Comments
ExampleType	int32_t	This is just an example

Columns

Name

The name of the typedef.

Type

The type specifier used with the typedef.

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. A question mark should never be used.

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, such 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, 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, use a question mark.

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. A question mark should never be used.

Bit fields

TODO