Burnout Wiki:Format documentation guide

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
The offset of the field within the structure. This should always be hexadecimal and prefixed with.

Length
The length of the field. This should always be hexadecimal and prefixed with, 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
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 =

Traditional enumerations
TODO

Binary flags
TODO

= Bit fields = TODO