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 decimal16
.
File Header#
Address range:
0x0 -> 0x8F
(size0x90
)
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00 00 00 00 62 69 74 6D 00 00 01 00 00 00 00 00 ....bitm........
00 00 00 00 00 00 00 00 00 00 00 00 62 6C 61 6D ............blam
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
30 30 30 30 36 2E 30 39 2E 33 30 2E 31 39 2E 30 00006.09.30.19.0
30 30 31 2E 62 6C 61 6D 69 74 65 00 00 00 00 00 001.blamite.....
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 | Light Blue |
0x24 -> 0x27 |
0x4 |
Tag class (short name) | Red |
0x28 -> 0x29 |
0x2 |
Empty padding | Orange |
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 | Magenta |
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 -> 0x5F |
0x1C |
Empty padding | Cyan |
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). |
Light Red |
0x80 -> 0x8F |
0x10 |
Empty padding | White |
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.
Be aware: Modern systems perform something known as "clamping" to ensure that variables are located at even addresses. If you encounter an exception relating to a tag using Int8 or Boolean fields, keep this in mind if addresses are seemingly "offset" by 1.
Field Name | Description/Purpose | Data Type | Size |
---|---|---|---|
ASCII | Plain text storage directly within tag data. | char[32] |
32 (0x20 ) 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. | BlamColor |
|
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. | bool[8] |
8 Bytes |
Bitfield16 | A series of 16 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. | bool[16] |
16 (0x10 ) Bytes |
Bitfield32 | A series of 32 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. | bool[32] |
32 (0x20 ) 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
(size0x20
)
74 62 66 64 00 00 00 00 14 00 00 00 00 00 00 00 tbfd............
F8 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 ΓΈ...............
Offset Range | Size | Description | Color |
---|---|---|---|
0x0 -> 0x7 |
0x8 |
Block identifier, will always contain tbfd followed by 4 null bytes. |
Light Blue |
0x8 -> 0xB |
0x4 |
Size of each entry | Red |
0xC -> 0xF |
0x4 |
Reserved/Empty padding | Orange |
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 | Yellow |