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