Tags are the resources which represent all assets and entities in the game. While the core mechanics are implemented in game code, nearly everything else is customized using tags. They come in many different types (called tag classes or groups), each with a predefined structure and data fields. Tags can depend on other tags by reference, and are reusable between maps.
A playable level is represented by a scenario tag and all of its dependencies, which can include the vehicles which may spawn, any scenery placed, and any level textures. Bundles of tags required for a level are typically compiled into an optimized map cache file, though certain builds of the Halo engine are capable of loading tags on-demand directly from the
tags folder (e.g. Sapien or debug builds of Halo).
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.
- Some tag classes have fields which only apply in certain editions, for example H1A's actor metagame type.
- PC retail and Custom Edition are based on a slightly older version of Xbox tags, with the most famous difference being Keyes' uniform.
- Gearbox replaced model with gbxmodel and during the Xbox to PC port, and replaced instances of shader_
transparent_ generic with shader_ transparent_ chicago or other transparent shader classes.
- Gearbox made several changes to damage_
effect stuns in Custom Edition tags only.
- H1A in MCC restores shader_
transparent_ generic functionality and Keyes' uniform.
Each tag class is a binary (non-text) data structure with a fixed layout and size.
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 group ID for the type. For example, the path
levels\test\tutorial\tutorial and group 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.
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.
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_
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, H1CE 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_
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.
Some tags contain unused space between fields called 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.
Defines basic AI behaviour. Can be futher customized using the actor_
Specializes an actor by defining their use of weapons, grenades, their health, their color, and what equipment they drop.
Represents the physical characteristics and appearance of characters like Elites, Marines, Cortana, and the player.
Stores texture data like sprite sheets, environment maps, normal maps, and more. Commonly (but not exclusively) referenced by shaders.
Creates a continuous screen shake and controller vibration within a radius of a sound_
Properties for the application of damage including material modifiers, screen effects, acceleration, and area of effect.
Used for bullet holes, blood, burns, signs, and other 2D surface effects.
Parent tag for devices, controlled objects which have powered on/off states.
Used for interactive switches and buttons to operate device_
Used for dynamically toggled light sources or decorate lighting objects.
An object which can animate between open and closed states, like doors and elevators.
Gives units situational sounds, such as when taking damage or fleeing.
A multi-purpose tag used for responses to various events like material impacts, sound effects, and detonations.
Used for powerups, health packs, non-live grenades, and ammo pickups.
Properties for a simulated cloth-like material which can be attached to objects.
Describes the appearance of fog planes.
Stores the render model of objects in the Gearbox port of the game (and its derivatives).
Contains global configuration related to singleplayer, multiplayer, rasterizer data, the HUD, and more.
Used to create glowing effects like the Elite's energy sword.
Contains the text for messages that appear on the HUD like objectives and interactions.
A dynamic light source which can be attached to objects and effects.
Describes a dense line of glow particles, commonly used for projectile tails.
Spawns effects when moving objects interact with surfaces, like tread marks, splashing footsteps, and scattering rocks.
Used for the global health and shield HUD meters.
Stores the render model of objects in the original Xbox version of the game.
Contains the collision mesh (also referred to as hitbox) for objects as well as information about health and shields.
Models the dynamic physics and propulsion of vehicles.
Used only by Sapien to represent interactive handles/markers.
Controls how simulated points points physically interact with the environment.
Short-lived objects used for weapon projectiles and thrown grenades.
The main "root" tag for a multiplayer, singeplayer, or UI map. Contains data about spawn locations, objects, BSPs, skies, scripts, and more.
Contains geometric, lighting, weather, and other data for the playable spaces in which all objects are placed. Singleplayer maps often use multiple BSPs.
Fixed decoration objects like boulders, plants, and crates. Placed in the level using Sapien.
General-purpose opaque and alpha-tested shader used for scenario_
General-purpose opaque shader used for object materials.
A version of shader_
A transparent shader type supported by H1X and H1A only.
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.
Used for energy shields like those on bipeds.
Defines a skybox with light sources for lightmaps and atmospheric fog.
Contains sound data such as sound effects and music and parameters affecting how sounds are played by the sound system.
Driveable or occupiable units with dynamic physics, such as the Warthog and cryo pod.
Used for both weildable weapons and those attached to vehicles.
Defines the appearance and behaviour of weather particles like rain and snow.
The following tags are leftover from earlier in Halo's development and are unused or removed entirely from current versions. The tags are listed here for informational purposes only, and you will not need to use them.
Spheroid is an unused leftover tag class from earlier in Halo's development. Although references to it can be seen in the H1CE HEK, it no longer exists in the H1A-EK.
This group ID can still be found in leftover references in some stock scenario tags, but the tag itself no longer exists. It was probably replaced by item_
Thanks to the following individuals for their research or contributions to this topic:
- Kavawuvi (Information about invalid tags)
- Vaporeon (Information about modified stun values in Custom Edition)