Skip to content

Tag File Specification#

The format for tag files is still in its early stages. While we will try to avoid any breaking changes, don't be too surprised if any major format changes occur.

Tags are the primary way that any game content will be stored.

Tag data will vary wildly based on a class, but the following format details are consistent across all tags. The format is based loosely on the format used by Halo Custom Edition, while taking cues from future versions as well as injecting some of our own DNA to fit our needs better.

Remember: Any sizes that begin with 0x indicate a hexadecimal (base 16) length. Ex: 0x10 is equal to decimal 16.

File Header#

Address range: 0x0 -> 0x8F (size 144 0x90)

    
    Offset (h)   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    Decoded text
    00000000     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
    00000010     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
    00000020     00 00 00 00 62 69 74 6D 00 00 01 00 00 00 00 00    ....bitm........
    00000030     00 00 00 00 00 00 00 00 00 00 00 00 62 6C 61 6D    ............blam
    00000040     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
    00000050     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
    00000060     30 30 30 30 36 2E 30 39 2E 33 30 2E 31 39 2E 30    00006.09.30.19.0
    00000070     30 30 31 2E 62 6C 61 6D 69 74 65 00 00 00 00 00    001.blamite.....
    00000080     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ................
Offset Range Size Description Color
0x0 -> 0x23 0x24 Empty padding Silver/Gray
0x24 -> 0x27 0x4 Tag class (short name) Red
0x28 -> 0x29 0x2 Empty padding Gray
0x2A 0x1 Will be 01 in the case of a Blamite tag, legacy blam! tags will be something else (usually 00) Lime
0x2B -> 0x3B 0x11 Empty padding Gray
0x3C -> 0x3F 0x4 Will always contain blam Green
0x40 -> 0x43 0x4 An integer representing the plugin revision that was used to compile the tag. Will be used for backwards compatibility. Yellow
0x44 -> 0x47 0x4 An integer representing the tag fieldset version that was used to compile the tag. Used for backwards compatibility. Light Blue
0x48 -> 0x5F 0x18 Empty padding Silver
0x60 -> 0x7F 0x20 Engine version the tag was designed for, will be used in the future for backwards compatibility. Must end with 0x00 (null byte). Salmon
0x80 -> 0x8F 0x10 Empty padding Gray

Tag Data#

Address range: 0x90 -> End of File

Tag data will vary drastically for each tag class. Below, you can find information on how various tag fields are stored.

Tag Fields#

Below you can find details about all possible tag fields and how they are stored.

Field Name Description/Purpose Data Type Size
ASCII Plain text storage directly within tag data. char[128] 128 (0x80) Bytes
Int32 A 32-bit integer. int 4 Bytes
Int16 A 16-bit integer. short 2 Bytes
Int8 An 8-bit integer. byte (unsigned char) 1 Byte
Boolean A single true or false value, represented as 01 or 00. bool 1 Byte
Color Easy storage of color information. Color values are stored as 4 bytes in RGBA order. BlamColor 4 bytes
Enum A single selection of a series of potential options. enum 4 Bytes
Bitfield8 A series of 8 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. bitfield8 1 Byte
Bitfield16 A series of 16 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. bitfield16 2 Bytes
Bitfield32 A series of 32 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. bitfield32 4 Bytes

Tag Blocks#

Blocks are the most complex type of tag in the engine. They are used to group together many related fields, as well as provide support for "entries". A block's entries all share the same data structure, but can have unique values per-entry. These allow for more flexibility when defining new tags and see usage all over the place.

Memory Structure#

Below is the memory structure of tag blocks, as they are stored within normal field data. Entry data is stored in a separate location entirely - only the information about the tag block is stored within the normal field list. All offsets listed in the Offset Range column are relative to the start of the tag block data.

Address range: 0x0 -> 0x1F (size 32 0x20)

    
    Offset (h)   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    Decoded text
    00000000     74 62 66 64 00 00 00 00 14 00 00 00 00 00 00 00    tbfd............
    00000010     F8 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00    ø...............
Offset Range Size Description Color
0x0 -> 0x3 0x4 Block identifier, will always contain tbfd (Tag Block ForwarD). Light Blue
0x4 -> 0x7 0x4 Reserved/Empty padding Silver
0x8 -> 0xB 0x4 Size of each entry Red
0xC -> 0xF 0x4 Reserved/Empty padding Gray
0x10 -> 0x17 0x8 The 64-bit address in memory (when a tag is loaded in-engine), or the file offset to the block entry data Magenta
0x18 -> 0x1B 0x4 The number of entries in the block Green
0x1C -> 0x1F 0x4 Reserved/Empty padding Silver

Tag References (tagrefs)#

Tag References allow for tags to reference other tags within them. This can be used in cases where specific tags need to depend on another, such as a weapon referencing a model tag, or a shader referencing a bitmap.

Address range: 0x0 -> 0x1F (size 32 0x20)

    
    Offset (h)   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    Decoded text
    00000000     74 72 66 64 00 00 00 00 62 69 74 6D 00 00 00 00    trfd....bitm....
    00000010     FF FF FF FF FF FF FF FF 01 00 00 00 20 00 00 00    ÿÿÿÿÿÿÿÿ.... ...
Offset Range Size Description Color
0x0 -> 0x3 0x4 Tagref identifier, will always contain trfd (Tag Reference ForwarD) followed by 4 null bytes. Light Blue
0x4 -> 0x7 0x4 Reserved/Empty padding Silver
0x8 -> 0xB 0x4 Name of the tag's class. Red
0xC -> 0xF 0x4 Reserved/Empty padding Gray
0x10 -> 0x17 0x8 The 64-bit address pointing to either the referenced tag data, or pointing to a string containing the tag's path. When stored on disk, this will always be a file offset pointing to the tag's path. Magenta
0x18 0x1 The type of data that the address points to. When set to 00, it indicates that the address points to a tag path. When set to 01, it points to the referenced tag data. Green
0x19 -> 0x1B 0x3 Reserved/Empty padding Silver
0x1C -> 0x1F 0x4 The size of either the tag path, or the size of the referenced tag data. Salmon

Data References (datarefs)#

Data References allow for tags to store arbitrary, variable-sized data. This data can be used for virtually anything - as it simply stores an address and a size.

Address range: 0x0 -> 0x1F (size 32 0x20)

    
    Offset (h)   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    Decoded text
    00000000     64 72 66 64 00 00 00 00 FF FF FF FF FF FF FF FF    drfd....ÿÿÿÿÿÿÿÿ
    00000010     00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00    ....json........
Offset Range Size Description Color
0x0 -> 0x3 0x4 Dataref identifier, will always contain drfd (Data Reference ForwarD). Light Blue
0x4 -> 0x7 0x4 Reserved/Empty padding. Silver
0x8 -> 0xF 0x8 The 64-bit address pointing to the referenced data. When stored in a file on disk, this will be the file offset instead of a memory address. Magenta
0x10 -> 0x13 0x4 The size of the referenced data. Green
0x14 -> 0x17 0x4 Value hint, used by the Editing Kit to provide context for what type of content is being stored. For detailed information, see this page. Salmon
0x18 -> 0x1F 0x8 Reserved/Empty padding. Gray

Field References (fieldrefs)#

Field references allow for tags to reference the data of another field within the same tag. In certain cases, this can be used to help reduce data duplication.

It should be noted that, at this time, field references do not reference the data directly once loaded in-engine. When fieldrefs are loaded inside the game engine, they store a copy of the field data. This is something that will likely be resolved in the future in order to make more efficient usage of memory. When written to disk, however, these field references do in fact directly reference existing data - meaning that storage space on disk is not wasted.

It is also important to note that not all field types are supported by field references. Data References, Tag References, Tag Blocks, and other Field Reference fields currently cannot be referenced by Field References.

Address range: 0x0 -> 0x13 (size 20 0x14)

    
    Offset (h)   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    Decoded text
    00000000     66 72 66 64 03 00 00 00 FF FF FF FF FF FF FF FF    frfd....ÿÿÿÿÿÿÿÿ
    00000010     FC 01 00 00                                        ü...
Offset Range Size Description Color
0x0 -> 0x3 0x4 Fieldref identifier, will always contain frfd (Field Reference ForwarD). Light Blue
0x4 -> 0x7 0x4 The type of data that is being referenced. See table below for details. Lime
0x8 -> 0xF 0x8 The 64-bit address pointing to the referenced data. When written to disk, this data is ignored entirely. Magenta
0x10 -> 0x13 0x4 The offset of the referenced data within the file. Orange
Field Types#

Below are the list of field types that are supported by field references. These values directly correlate to the BlamTagFieldType enumerator within the engine.

Type Value
Unspecified/Unknown 0
Ascii 1
Int8 2
Int16 3
Int32 4
Int64 5
Real 6
Bitfield8 7
Bitfield16 8
Bitfield32 9
Enum8 10
Enum16 11
Enum32 12
Block (Unsupported) 13
Color 14
Boolean 15
StringID (Unimplemented) 16
Dataref (Unsupported) 17
Tagref (Unsupported) 18
Fieldref (Unsupported) 19
Vector2 20
Vector3 21
Vector4 22
Comment (Unsupported) 23

Fieldset Versions#

Each build of the game engine utilizes a "Fieldset" version to indicate breaking changes to the binary/compiled tag format. When these changes are made, all tags MUST be recompiled before use. The game engine will refuse to load tags with an incorrect fieldset version - as doing so would almost certainly lead to memory corruption and crashing.

Information about each fieldset version change can be found on this page.