Fieldset Versions#
Current fieldset version: 5
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 below.
Version 5#
| Name | Value |
|---|---|
| First Engine Version | TBA |
| Last Engine Version | N/A |
| Date Introduced | X |
| Commit Introduced | `` |
Fieldset version 5 only changes Data Reference fields. All Data References now use 0x20 (32) bytes instead of 0x18 (24) bytes. This introduces 8 additional bytes, used as empty padding for future format changes. The previous 4 bytes of padding are now utilized as a "value hint", which is used by the Editing Kit in some circumstances to detect what type of data is being stored, such as JSON, YAML, XML, or a number of other formats.
Data References#
Address range:
0x0 -> 0x1F(size 320x20)
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 -> 0x7 |
0x8 |
Dataref identifier, will always contain drfd (Data Reference ForwarD) followed by 4 null bytes. |
Light Blue |
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. | Salmon |
0x18 -> 0x1F |
0x8 |
Reserved/Empty padding. | Gray |
Version 4#
Note
In versions of Blamite prior to
00365.10.17.22.0315.blamite(before Oct 17, 2022), it was possible for some addresses to not line up correctly due to memory alignment. Starting from this version (commitd3a28c8d), all tag classes and field structures have memory packing enabled, ensuring that there is no unexpected padding between members.This change was made during the lifespan of Fieldset Version 4 and was not given a new fieldset version, as the previous behavior is considered a bug.
All Fieldset versions from 5 onward are not affected by this issue.
| Name | Value |
|---|---|
| First Engine Version | 00323.06.25.21.0123.blamite |
| Last Engine Version | 00388.06.24.23.2301.blamite |
| Date Introduced | 6/25/2021 |
| Commit Introduced | 2024b751 |
Bitfields are now stored in a slightly different format internally, with each being a data structure rather than a char array. This results in bitfields using significantly less memory and storage space.
You can view the complete documentation of the tag format at that time at this page.
Standard Fields#
| Field Name | Description/Purpose | Data Type | Size |
|---|---|---|---|
| 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 |
Version 3#
| Name | Value |
|---|---|
| First Engine Version | 00311.03.29.21.1456.blamite |
| Last Engine Version | 00322.06.23.21.0355.blamite |
| Date Introduced | ¾/2021 |
| Commit Introduced | 49b25ba5 |
Tag References and Data References have been reorganized to add additional reserved space, and to make better use of existing memory.
You can view the complete documentation of the tag format at that time at this page.
Tag References#
Address range:
0x0 -> 0x1F(size 320x20)
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 -> 0x7 |
0x8 |
Tagref identifier, will always contain trfd (T**ag **R**eference **F**orwar**D) followed by 4 null bytes. |
Light Blue |
0x8 -> 0xB |
0x4 |
Name of the tag's class. | Red |
0xC -> 0xF |
0x4 |
Reserved/Empty padding | Silver |
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 | Gray |
0x1C -> 0x1F |
0x4 |
The size of either the tag path, or the size of the referenced tag data. | Salmon |
Data References#
Address range:
0x0 -> 0x17(size 240x18)
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 ........
| Offset Range | Size | Description | Color |
|---|---|---|---|
0x0 -> 0x7 |
0x8 |
Dataref identifier, will always contain drfd (D**ata **R**eference **F**orwar**D) followed by 4 null bytes. |
Light Blue |
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 |
Reserved/Empty padding. | Gray |
Version 2#
| Name | Value |
|---|---|
| First Engine Version | 00310.02.05.21.0336.blamite |
| Last Engine Version | 00310.02.05.21.0336.blamite |
| Date Introduced | ⅖/2021 |
| Commit Introduced | 9f9429c9 |
Tag References have been made more memory efficient, and no longer use 256 bytes for the tag path. Instead, they store a variety of information about the referenced tag, and rather than directly storing the path inline, the memory address of the tag data and/or the offset of the tag path are merely referenced - ensuring that inline tagref data is as small as possible, and ensuring that there is minimal wasted space when storing tag references.
This version also introduces the Data Reference field type.
You can view the complete documentation of the tag format at that time at this page.
Tag References#
Address range:
0x0 -> 0x1B(size 280x1C)
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 FF FF trfd....bitm..ÿÿ
00000010 FF FF FF FF FF FF 00 00 00 02 00 00 ÿÿÿÿÿÿ......
| Offset Range | Size | Description | Color |
|---|---|---|---|
0x0 -> 0x7 |
0x8 |
Tagref identifier, will always contain trfd (T**ag **R**eference **F**orwar**D) followed by 4 null bytes. |
Light Blue |
0x8 -> 0xB |
0x4 |
Name of the tag's class. | Red |
0xC -> 0xD |
0x2 |
Reserved/Empty padding | Silver |
0xE -> 0x15 |
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 |
0x16 |
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 |
0x17 |
0x1 |
Reserved/Empty padding | Gray |
0x18 -> 0x1B |
0x4 |
The size of either the tag path, or the size of the referenced tag data. | Salmon |
Data References#
Address range:
0x0 -> 0x13(size 200x14)
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 ....
| Offset Range | Size | Description | Color |
|---|---|---|---|
0x0 -> 0x7 |
0x8 |
Dataref identifier, will always contain drfd (D**ata **R**eference **F**orwar**D) followed by 4 null bytes. |
Light Blue |
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 |
Version 1#
| Name | Value |
|---|---|
| First Engine Version | 00307.01.26.21.0804.blamite |
| Last Engine Version | 00309.02.03.21.0044.blamite |
| Date Introduced | 1/26/2021 |
| Commit Introduced | 0d063064 |
The very first tag fieldset version.
You can view the complete documentation of the tag format at that time at this page. Note that due to the early nature of this page, that some fields (such as tag references) are not documented yet.
Standard Fields#
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[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 |
8 Byte |
| Bitfield16 | A series of 16 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. | bitfield16 |
16 (0x10) Bytes |
| Bitfield32 | A series of 32 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. | bitfield32 |
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(size 320x20)
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 -> 0x7 |
0x8 |
Block identifier, will always contain tbfd (Tag Block ForwarD) followed by 4 null bytes. |
Light Blue |
0x8 -> 0xB |
0x4 |
Size of each entry | Red |
0xC -> 0xF |
0x4 |
Reserved/Empty padding | Silver |
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 | Gray |
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 -> 0x107(size 2640x108)
Offset (h) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F Decoded text
00000000 FF FF FF FF FF FF FF FF 2F 6C 65 76 65 6C 73 2F ÿÿÿÿÿÿÿÿ/levels/
00000010 73 6F 6C 6F 2F 74 65 73 74 2F 74 65 73 74 2E 73 solo/test/test.s
00000020 63 65 6E 61 72 69 6F 00 00 00 00 00 00 00 00 00 cenario.........
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
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 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000080 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000090 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000B0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000C0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000D0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000100 00 00 00 00 00 00 00 00 ........
| Offset Range | Size | Description | Color |
|---|---|---|---|
0x0 -> 0x7 |
0x8 |
The address of the referenced tag, in memory. Only used when a tag is loaded in memory. | Magenta |
0x8 -> 0x107 |
0x100 |
The referenced tag's path. Used in tag files on disk and when first resolving a tag reference. | Green |
Version 0#
| Name | Value |
|---|---|
| First Engine Version | 00173.03.24.20.0001.blamite |
| Last Engine Version | 00306.01.24.21.1348.blamite |
| Date Introduced | 3/24/2020 |
| Commit Introduced | d53d1d80 |
Version 0 is not an actual fieldset version like the others. Instead, it refers to the tag format as it existed during its initial implementation - before the concept of fieldset versioning was introduced. Several significant changes were made during this time. Listed below is the final field information before the introduction of fieldset versioning.
You can view each iteration of the tag file format specification up until Fieldset version 1 using the links below:
- Guides Build #32 - 5/11/2020 (Internal Docs)
- Guides Build #37 - 5/11/2020 (Internal Docs)
- Guides Build #52 - 7/27/2020
- Guides Build #61 - 1/13/2021
- Guides Build #64 - 1/22/2021
- Guides Build #67 - 1/23/2021
- Guides Build #68 - 1/24/2021
- Guides Build #69 - 1/24/2021
- Guides Build #70 - 1/24/2021
- Guides Build #71 - 1/25/2021
- Guides Build #72 - 1/25/2021
Standard Fields#
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. 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 |
8 Byte |
| Bitfield16 | A series of 16 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. | bitfield16 |
16 (0x10) Bytes |
| Bitfield32 | A series of 32 true or false flags grouped together. Should be used instead of Boolean fields wherever possible. | bitfield32 |
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(size 320x20)
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 -> 0x7 |
0x8 |
Block identifier, will always contain tbfd (Tag Block ForwarD) followed by 4 null bytes. |
Light Blue |
0x8 -> 0xB |
0x4 |
Size of each entry | Red |
0xC -> 0xF |
0x4 |
Reserved/Empty padding | Silver |
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 | Gray |
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 -> 0x107(size 2640x108)
Offset (h) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F Decoded text
00000000 2F 6C 65 76 65 6C 73 2F 73 6F 6C 6F 2F 74 65 73 /levels/solo/tes
00000010 74 2F 74 65 73 74 2E 73 63 65 6E 61 72 69 6F 00 t/test.scenario.
00000020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
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 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000070 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000080 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000090 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000A0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000B0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000C0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000D0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
000000F0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00000100 FF FF FF FF FF FF FF FF ÿÿÿÿÿÿÿÿ
| Offset Range | Size | Description | Color |
|---|---|---|---|
0x8 -> 0x9F |
0x100 |
The referenced tag's path. Used in tag files on disk and when first resolving a tag reference. | Green |
0x100 -> 0x107 |
0x8 |
The address of the referenced tag, in memory. Only used when a tag is loaded in memory. | Magenta |