Tags

Tags are the fundamental unit of resources which comprise a map. They come in many different types (sometimes called tag classes or groups), each with a predefined structure and data fields. Tags can reference other tags, forming a tree-like structure of all resources necessary to compile a map.

The name "tag" was inspired by XML tags, which also have types and a structure with fields. However, unlike XML, Halo's tags are a binary format rather than plain text. To create and edit tags, you need to use purpose-built tools like the HEK, MEK, or Invader.

Tag structure #

Tag references and paths #

A tag path is like a URL for a tag. References from one tag file to another are stored as tag paths with an accompanying engine ID for the type. For example, the path levels\test\tutorial\tutorial and engine ID sbsp is how the tutorial scenario references its BSP. Tag paths are assumed relative to a tags directory, but are not literal filesystem paths since they don't contain an extension.

Be careful when moving or renaming tag files; you may create "dead links" in other tags that referenced them. Either correct the broken references after moving tags, or use invader-refactor to move tags safely.

When tags are compiled into a map, references are converted into pre-calculated pointers. An array of tag paths are still retained in the map but is not used by the game.

Tag paths also appear in arguments to Tool and scripting.

Blocks #

A tag block field, also known as a reflexive, is essentially a list of smaller data structures within a tag. An example is the scenario tag containing a block of vehicle spawns points. In visual tag editors, blocks appear as a list of elements which are often editable by adding or removing elements. A block field internally consists of an item count and a pointer to an array of structures of the expected type.

Engine IDs #

To identity tag types in-engine and within tag data, Halo uses compact fixed-size (4 character) identifiers rather than the longer tag names/extensions seen in the HEK. Some examples include bitm for bitmap, snd! for sound, and DeLa for ui_widget_definition. These identifiers are case-sensitive and may be padded with trailing spaces.

Unused tags and fields #

The types of tags and their structures changed during the game's development. Evidence of this can be seen in Halo's engine, the HEK's tools and tags, and official maps.

For example, Guerilla allows users to create new spheroid tags despite them containing no fields and being totally useless. The actor tag contains an unused weapon reference and probably predates the creation of actor_variant, which references both.

Invalid data #

Not only were fields added and removed during development, but some were repurposed to different types without correcting existing tag instances. This has resulted in tags which shipped with Halo's maps containing some technically invalid data. The tag warthog gunner.actor_variant still contains a projectile reference overlapping the space of 4 fields (starting with grenade type) in the final version of the tag structure.

Invalid data is common in extracted tags, either because they were already invalid or from using buggy tools like HEK+. Using invalid tags for new maps can produce undefined behaviour in-game and cause Sapien to crash. A tag which works in Custom Edition may cause crashes in MCC.

Invalid tags can often be corrected by resetting fields and re-saving the tag using visual tag editors (e.g. Mozarilla, Guerilla), or using invader-bludgeon.

Padding #

Fields are not always densely packed within a tag; sometimes there exists unused space between them without any known purpose. These spaces are often referred to as padding. Generally, any sort of data could be stored in these spaces without affecting the tags, and some community tools use this space to retain extra metadata.

Tags list #

Tag name Engine ID Parent Purpose
actor actr

Defines basic AI behaviour. Can be futher customized using the actor_variant tag.

actor_variant actv
antenna ant!

A springy antenna widget which can be attached to model markers, as seen on the Warthog and Scorpion. Widgets can be added to any object.

biped bipd unit

Represents the physical characteristics and appearance of characters like Elites, Marines, Cortana, and the player.

bitmap bitm

Stores texture data like sprite sheets, environment maps, normal maps, and more. Commonly (but not exclusively) referenced by shaders.

camera_track trak

Defines rotational constraints for the game's camera when controlling bipeds or occupying vehicles (e.g. prevents looking all the way up or down).

color_table colo
contrail cont

Contrails are trail-like repeating bitmap effects which can be attached to any object, optionally to one of their markers. Commonly used for projectiles, but also for the Banshee's wingtips.

damage_effect jpt!

Properties for the application of damage including material modifiers, screen effects, acceleration, and area of effect.

decal deca

Used for bullet holes, blood, burns, signs, and other 2D surface effects.

detail_object_collection dobc

Determines the mix and appearance of small 2D detail objects like grass, which are painted onto a BSP in Sapien.

device devi object

Parent tag for devices, controlled objects which have powered on/off states.

device_control ctrl device

Used for interactive switches and buttons to operate device_machines like doors and elevators.

device_light_fixture lifi device

Used for dynamically toggled light sources or decorate lighting objects.

device_machine mach device

An object which can animate between open and closed states, like doors and elevators.

dialogue udlg
effect effe

A multi-purpose tag used for responses to various events like material impacts, sound effects, and detonations.

equipment eqip item

Used for powerups, health packs, non-live grenades, and ammo pickups.

flag flag

Properties for a simulated cloth-like material which can be attached to objects.

fog fog

Describes the appearance of fog planes.

font font
garbage garb item
gbxmodel mod2

Stores the render model of objects in the Gearbox port of the game (and its derivatives).

globals matg
glow glw!

Used to create glowing effects like the Elite's energy sword.

grenade_hud_interface grhi
hud_globals hudg
hud_message_text hmt
hud_number hud#
input_device_defaults devc
item item object

Parent tag of weapon, garbage, and equipment. Represents a small moveable object with point-like physics.

item_collection itmc
lens_flare lens
light ligh

A dynamic light source which can be attached to objects and effects.

light_volume mgs2

Describes a dense line of glow particles, commonly used for projectile tails.

lightning elec
material_effects foot

Spawns effects when moving objects interact with surfaces, like tread marks, splashing footsteps, and scattering rocks.

meter metr
model mode

Stores the render model of objects in the original Xbox version of the game.

model_animations antr
model_collision_geometry coll

Contains the collision mesh (also referred to as hitbox) for objects as well as information about health and shields.

multiplayer_scenario_description mply
object obje

Base tag for everything that can be populated and spawned into a level, such as bipeds, scenery, and projectiles.

particle part
particle_system pctl
physics phys
placeholder plac object

Used only by Sapien to represent interactive handles/markers.

point_physics pphy
preferences_network_game ngpr
projectile proj object

Short-lived objects used for weapon projectiles and thrown grenades.

scenario scnr

The main "root" tag for a multiplayer, singeplayer, or UI map. Contains data about spawn locations, objects, BSPs, skies, scripts, and more.

scenario_structure_bsp sbsp

Contains geometric, lighting, weather, and other data for the playable spaces in which all objects are placed. Singleplayer maps often use multiple BSPs.

scenery scen object

Fixed decoration objects like boulders, plants, and crates. Placed in the level using Sapien.

shader shdr
shader_environment senv shader

General-purpose opaque and alpha-tested shader used for scenario_structure_bsp materials.

shader_model soso shader

General-purpose opaque shader used for object materials.

shader_transparent_chicago schi shader
shader_transparent_chicago_extended scex shader

A version of shader_transparent_chicago which contains an additional 2-stage block for supporting older graphics hardware.

shader_transparent_generic sotr shader

A transparent shader type supported on classic Xbox only.

shader_transparent_glass sgla shader
shader_transparent_meter smet shader

Used for transparent materials with an incrementally scaled area, such as first person (not HUD) heat meters for plasma weapons and the Warthog's speedometer.

shader_transparent_plasma spla shader
shader_transparent_water swat shader
sky sky

Defines a skybox with light sources for lightmaps and atmospheric fog.

sound snd!
sound_environment snde
sound_looping lsnd
sound_scenery ssce object

Identical to scenery but with collision rules like device_light_fixture. Used for invisible emitters of localized sound like rivers and waterfalls.

string_list str#
tag_collection tagc
ui_widget_collection Soul
ui_widget_definition DeLa
unicode_string_list ustr
unit unit object

Parent tag of bipeds and vehicles, containing fields common to these AI-driven or controllable objects.

unit_hud_interface unhi
vehicle vehi unit

Driveable or occupiable units with dynamic physics, such as the Warthog and cryo pod.

virtual_keyboard vcky
weapon weap item

Used for both weildable weapons and those attached to vehicles.

weapon_hud_interface wphi
weather_particle_system rain
wind wind

Describes the speed and variation of wind in a BSP cluster, affecting local point_physics like flags and weather.

Unused tags #

These vestigal tags were found within the game engine or tools, but are no longer used. They were used during Halo's development and then partially removed before release. The tags are listed here for informational purposes only, and you will not need to use them.

Tag name Engine ID Parent Purpose
continuous_damage_effect cdmg
spheroid boom

Acknowledgements

Thanks to the following individuals for their research or contributions to this topic:

  • Kavawuvi (Information about invalid tags)