XML 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. XML tags, or "decompiled" tags, are used by the Editing Kit and, as the name implies, are stored as an XML document. Tags stored in this format will take up more disk space, but are able to be significantly more resilient to format changes. When creating or working with any project in Blamite, all tags should be stored in this format.
Note that the game engine itself cannot interact with these tags in any way. As a result, the Editing Kit will compile the tag as part of the save process, ensuring the engine is able to read the updated tag.
Root Node#
The name of the root node will always be the long class name. In the example below, a scenario
tag is used - whose short name is scnr
, and whose long name is scenario
.
<scenario pluginVersion="2">
...
</scenario>
Attribute Name | Type | Description |
---|---|---|
pluginVersion |
Integer | The version of the plugin that this tag was created from. |
Tag Fields#
Standard Fields#
Most tag fields share a common, standard format.
<type id="field_id">value</type>
Attribute Name | Type | Description |
---|---|---|
id |
String | The unique identifier of the field. |
valueHint |
String | An optional attribute for dataref fields. Provides context for the Editing Kit as to what data is being stored. |
Below is a list of all possible common field types, and the data type that corresponds to the field in-engine.
Name | Data Type | Description |
---|---|---|
int8 |
int8_t |
An 8-bit signed integer. |
int16 |
int16_t |
A 16-bit signed integer. |
int32 |
int (int32_t) |
A 32-bit signed integer. |
real , float32 |
float |
A 32-bit floating-point number. |
enum32 |
int (int32_t) |
A 32-bit enumerator value. |
bitfield8 |
bitfield8 (int8_t ) |
A collection of up to 8 boolean flags. |
bitfield16 |
bitfield16 (int16_t ) |
A collection of up to 16 boolean flags. |
bitfield32 |
bitfield32 (int (int32_t) ) |
A collection of up to 32 boolean flags. |
dataref |
data_reference |
A general-purpose data reference. Can store any arbitrary data. |
tagref |
tag_reference |
A reference to another tag. Will contain a string with the path of the referenced tag. |
fieldref |
field_reference |
A field which stores a reference to another field's data within a tag. Will contain a string with the address of the referenced field. |
unknown |
N/A | An unknown field type. Will only ever be used in the case of an error as a fallback, though data will likely not be saved. |
Deprecated Field Types#
The below common field types are deprecated and will be removed in the future.
Name | Data Type | Description |
---|---|---|
enum8 |
int8_t |
An 8-bit enumerator value. Deprecated due to buggy behavior within the engine - all enums are treated as 32-bit enums in C++, and there is little reason to support these as such. |
enum16 |
int16_t |
A 16-bit enumerator value. Deprecated due to buggy behavior within the engine - all enums are treated as 32-bit enums in C++, and there is little reason to support these as such. |
ascii |
ascii (char[128]) |
A string, up to 128 characters in length. Deprecated as datarefs and/or a future string field should be used instead. |
Specific Fields#
Some fields are stored in a different, specific format or have additional attributes. Those fields are listed below.
Tag Blocks#
Tag blocks store their entries as separate child nodes.
<tagblock id="field_id">
<entry name="entry 1">
...
</entry>
<entry name="entry 2">
...
</entry>
</tagblock>
Each <entry>
node will contain a list of all fields within it. Each entry will also have the following attributes:
Name | Type | Description |
---|---|---|
name |
String | The display name of the entry. |
Data References#
<dataref id="example" length="65" valueHint="json">7B0D0A0922796F755F6469645F6974223A2022636F6E67726174756C6174696F6E7320796F752068617665207265616420746865206279746573203A29220D0A7D</dataref>
Data References are largely identical to most other fields. However, they do include additional attributes, which are detailed below:
Attribute Name | Type | Description |
---|---|---|
length |
Integer | The size, in bytes, of the stored data. |
valueHint |
String | An optional attribute. Provides context for the Editing Kit as to what data is being stored. Must not be longer than 4 characters. |
Value Hints#
Data References can optionally include a 4-character string of text that can be used by the Editing Kit to help identify the data being stored. While this data is available to the game engine as well, the engine itself will often not utilize it. This extra data is referred to as a "value hint".
In most cases, the value hint will instruct the Editing Kit what type of data is stored - such as a markup or programming language. This can be used to provide features such as syntax highlighting when editing the data, for instance.
The current list of available value hints, along with their 4-character identifier, are outlined below. Note that not all of these formats are utilized directly by the game engine.
Name | Identifier | Description |
---|---|---|
Assembly | asm |
Assembly Code |
Bash | bash |
Bash Script |
C | c |
C Code |
C++ | cpp |
C++ Code |
CMake | cmk |
CMake Script |
C# | cs |
C# Code |
CSS | css |
CSS Stylesheet |
Go | go |
Go (GoLang) Code |
BlamScript | hsc |
BlamScript Code |
HTML | html |
HTML Markup |
INI | ini |
INI Configuration |
JavaScript | js |
JavaScript Code |
Java | java |
Java Code |
JSON | json |
JSON Data |
Lua | lua |
Lua Script |
Make | make |
Make Script |
PHP | php |
PHP Code |
Python | py |
Python Code |
QML | qml |
QML Markup |
Rust | rust |
Rust Code |
SQL | sql |
SQL Statements |
Text | text |
Plain Text |
TypeScript | ts |
TypeScript Code |
V | v |
V Code |
Vex | vex |
Vex Code |
XML | xml |
XML Markup |
YAML | yaml |
YAML (YML) Configuration |