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 not manually created. Instead, tag definitions are created with the required information, and the game engine itself will generate these plugins 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">
The root node is named plugin, and contains several attributes.
| Attribute Name | Description | Expected Data |
|---|---|---|
| game | Legacy carry-over from Assembly's plugin format, not currently used. Will always be set to "blamite". | string |
| longName | The long name of the 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 |
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, but 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#
<custom id="custom_field_example"></custom>
| Attribute Name | Description | Expected Data |
|---|---|---|
TBA