Plugin Files#
Plugin files are files used by the Editing Kit to know how to properly prepare a tag editor. Plugin files are simply XML documents which contain all information required for tag editing, viewing, compilation, and decompilation.
In addition to storing the layout of a tag, plugin fields can also contain a number of additional attributes that aid in creating a more intuitive user interface.
The plugin format used by Blamite's Editing Kit is nearly identical to the plugin format used by XboxChaos' Assembly, a community-made tool created for editing Halo's cache files directly. The details of Blamite's implementation is detailed within this file.
Unlike Assembly's plugins, the plugin files used by Blamite's Editing Kit are typically not handwritten. Instead, they are created using the Tag Designer within Guerilla or Foundry. The Tag Designer allows for tag classes to be more easily authored, and it has the ability to automatically create C++ source code from these plugin files - making it super simple to add or alter tag classes within the game engine itself. These can also be created on a per project basis. For more information on the Tag Designer, see this page.
Additionally, the game engine itself is capable of generating default plugin files automatically. The generate_plugins script command can be used in init.txt and the console to generate plugin files that are ready for use within the editing tools.
Plugin File Specification#
Root Node#
<plugin game="blamite" longName="bitmap" engineVersion="00006.09.30.19.0001.blamite" baseSize="128" fieldSet="4">
<plugin project="blamite" longName="bitmap" shortName="bitm" engineVersion="00006.09.30.19.0001.blamite" baseSize="128" fieldSet="4" shortDescription="An example short description">
The root node is named plugin, and contains several attributes.
| Attribute Name | Description | Expected Data |
|---|---|---|
| project | The name of the project or game that this tag class belongs to. In older plugins, the attribute name was called game, which is also accepted in order to maintain parity with the Assembly plugin format. |
string |
| longName | The long name of the tag class. | string |
| engineVersion | The engine version which generated this plugin file. Was originally planned to be used for compatibility purposes but is unused in favor of fieldSet version and revisions. | string |
| baseSize | The base size of the tag fields. Does not include the sizes of any referenced data. | int |
| fieldSet | The fieldset version used to generate this plugin. This is used to determine what sizes to expect each tag field to be. | int |
| shortName | The short tag class name, consisting of up to 4 characters. This should generally be considered a required attribute, however if it is absent, then the short name is inferred from the file name. | string |
| shortDescription | An optional short description of the tag class. | string |
Description#
<description>
A cool description for a tag class.
\n\n
You can even have multiple lines!
</description>
Plugin files can also include a description. These are used in both exported C++ code, as well as in certain areas within the Editing Kit's user interface. These can have any length desired, and can contain multiple paragraphs and lines. Descriptions are not required, and if a description node is not present within the file, it is simply excluded.
Revisions#
<revisions>
<revision author="haloman30" version="1">Initial implementation.</revision>
<revision author="haloman30" version="2">Add test datarefs and tagrefs</revision>
</revisions>
The revisions node is the first node within the root node. This node is a special node which contains a list of individual revisions. These revisions describe changes made to plugins over time and are used to identify the plugin version. The revision of a plugin is written to any tag that is compiled using it to allow for tag/plugin matching.
Each revision contains two attributes and a description.
<revision author="haloman30" version="2">Add test datarefs and tagrefs</revision>
| Attribute Name | Description | Expected Data |
|---|---|---|
| author | The author of this plugin revision. | string |
| version | The revision number. | int |
Field Types#
All nodes after the revisions node are treated as fields. For details on the purpose of each tag field, see (tags.md)[tags.md].
All fields (excluding comments) are REQUIRED to contain the following attributes in order for the plugin to load correctly:
| Attribute Name | Description | Expected Data |
|---|---|---|
| id | The unique identifier of a given field. Used to avoid duplicate fields. | string |
| offset | The offset of the field, relative to its container. The container can be either the root node of the plugin or a tag block. | int |
Additionally, the following optional attributes can be present in any field (but are not required for the plugin to load properly):
| Attribute Name | Description | Expected Data |
|---|---|---|
| visible | Used to control whether or not the field is visible within the editor by default. Generally should not be used, but has it's functionality carried over from Assembly. When not provided, the field is visible. | bool |
| name (title) | Used to show a more user-friendly display name with a field. When not provided, the field ID is used as a fallback. | string |
Some fields have additional required attributes or child nodes. These additional requirements are detailed below.
Bitfield (bitfield8, bitfield16, bitfield32)#
<bitfield8 id="format_flags" name="format flags" offset="5" visible="true">
<bit id="bit_0" name="bit 0" index="0" visible="true"></bit>
<bit id="bit_1" name="bit 1" index="1" visible="true"></bit>
<bit id="bit_2" name="bit 2" index="2" visible="true"></bit>
<bit id="is_tiled" name="is tiled" index="3" visible="true"></bit>
</bitfield8>
<bitfield16 id="extra_flags" name="extra flags" offset="0" visible="true">
<bit id="can_you_imagine_needing_this_many_flags" name="can you imagine needing this many flags" index="0" visible="true"></bit>
<bit id="yea_me_neither" name="yea me neither" index="1" visible="true"></bit>
</bitfield16>
<bitfield32 id="who_needs_this_many_fucking_flags" name="who needs this many fucking flags" offset="2" visible="true">
<bit id="enable_diffusion_dithering" name="enable diffusion dithering" index="0" visible="true"></bit>
<bit id="disable_height_map_compression" name="disable height map compression" index="1" visible="true"></bit>
<bit id="uniform_sprite_sequences" name="uniform sprite sequences" index="2" visible="true"></bit>
<bit id="filthy_sprite_bug_fix" name="filthy sprite bug fix" index="3" visible="true"></bit>
<bit id="use_sharp_bump_filter" name="use sharp bump filter" index="4" visible="true"></bit>
<bit id="unused" name="UNUSED" index="5" visible="true"></bit>
<bit id="use_clamped/mirrored_bump" name="use clamped/mirrored bump" index="6" visible="true"></bit>
<bit id="invert_detail_fade" name="invert detail fade" index="7" visible="true"></bit>
<bit id="swap_x-y_vector_components" name="swap x-y vector components" index="8" visible="true"></bit>
<bit id="convert_from_signed" name="convert from signed" index="9" visible="true"></bit>
<bit id="convert_to_signed" name="convert to signed" index="10" visible="true"></bit>
<bit id="import_mipmap_chains" name="import mipmap chains" index="11" visible="true"></bit>
<bit id="intentionally_true_color" name="intentionally true color" index="12" visible="true"></bit>
</bitfield32>
Bitfields do not contain any additional required attributes, but do expect to contain multiple child nodes. Each child node represents a flag within the bitfield.
<bit id="intentionally_true_color" name="intentionally true color" index="12" visible="true"></bit>
Each bit must contain the following attributes:
| Attribute Name | Description | Expected Data |
|---|---|---|
| id | The ID of the bit. | string |
| index | The index of the bit within the bitfield. | int |
Additionally, each bit may also contain the following attributes, though these are not required:
| Attribute Name | Description | Expected Data |
|---|---|---|
| name | The display name of the option. | string |
| visible | Used to control whether or not the option is visible within the editor by default. Generally should not be used. When not provided, the option is visible. | bool |
Block#
<tagblock id="test_block" title="Test Block" offset="39" entrySize="6" visible="true">
...
</tagblock>
<reflexive id="test_block" title="Test Block" offset="39" entrySize="6" visible="true">
...
</reflexive>
Tag blocks require additional attributes to load properly.
| Attribute Name | Description | Expected Data |
|---|---|---|
| entrySize | The size of each block entry. Required for compilation/decompilation. | int |
Comment#
<comment title="Bitmap" visible="true" type="warning">im gonna shove a bitmap up your ass</comment>
Comment fields have additional optional attributes.
| Attribute Name | Description | Expected Data |
|---|---|---|
| type | The style to use for the comment. Specific appearance will vary by theme. When not provided, the comment is treated as though this setting was set to none. |
string, valid options are: none, info, warning, error |
Comments may also contain descriptions. These descriptions are not stored in an attribute, but are rather stored as the text value of the node itself.
Enum (enum8, enum16, enum32)#
<enum32 id="argh" name="argh" offset="130" visible="true">
<option id="on_e" name="ON E" value="0" visible="true"></option>
<option id="two" name="tWo" value="1" visible="true"></option>
<option id="thr__e__e" name="thR e E" value="2" visible="true"></option>
<option id="4" name="4" value="3" visible="true"></option>
</enum32>
Enum fields do not require additional attributes, however they can support several additional attributes for global scope and binding, though these are not required:
| Attribute Name | Description | Expected Data |
|---|---|---|
| globalCppScope | Whether this enum field should be defined in the global C++ scope upon export. This also allows other enums to be bound to it. | bool |
| globalCppName | An optional name for the global C++ enum upon export. If not present, then the field ID is used instead. Is only used if globalCppScope is true. |
string |
| bindToGlobal | The ID of the other enum that this enum is bound to. Not used if globalCppScope is true. |
string |
Additionally, enums do expect child nodes to be present. Each child node represents an enumerator option.
<option id="on_e" name="ON E" value="0" visible="true"></option>
Each option must have the following attributes:
| Attribute Name | Description | Expected Data |
|---|---|---|
| id | The ID of the option. This value gets written to XML tag files. | string |
| value | The value of the option. This value gets written to compiled tag files. | int |
Each option may also include the following attributes, though these are not required:
| Attribute Name | Description | Expected Data |
|---|---|---|
| name | The display name of the option. | string |
| visible | Used to control whether or not the option is visible within the editor by default. Generally should not be used. When not provided, the option is visible. | bool |
Tagref#
<tagRef id="string_reference" name="String reference" offset="0" visible="true" validClasses="unic"></tagRef>
<tagref id="example_tagref" name="Example Tag Reference" offset="8" visible="true" validClasses="plt3,ttag"></tagref>
Tag reference fields have additional optional attributes.
| Attribute Name | Description | Expected Data |
|---|---|---|
| validClasses | A list of valid tag classes that this tagref can accept, used to ensure that an unexpected tag is not provided. | string |
Custom Fields (Not yet Implemented)#
<custom id="custom_field_example"></custom>
| Attribute Name | Description | Expected Data |
|---|---|---|
TBA