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).

Halo's tags are a binary format that must be edited with purpose-built tools like the H1A-EK, MEK, or Invader.

Differences between editions

Each edition of the game has a slightly different tag set in its maps. Be aware of this when extracting tags with Refinery or invader-extract or mixing tags.

Tags list

Tag name

Group ID

Parent

Purpose

actoractr

Defines core AI behaviours shared by actor variants.

actor_variantactv

Specializes an actor by defining their appearance, weapon use, grenades, health, and dropped equipment.

antennaant!

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.

bipedbipdunit

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

bitmapbitm

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

camera_tracktrak

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_tablecolo
continuous_damage_effectcdmg

Creates a continuous screen shake and controller vibration within a radius of a sound_looping source. This tag class is not used in any stock maps and the effect only applies while certain damage_effect are also applying to the player.

contrailcont

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_effectjpt!

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

decaldeca

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

detail_object_collectiondobc

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

devicedeviobject

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

device_controlctrldevice

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

device_light_fixturelifidevice

Used for dynamically toggled light sources or decorate lighting objects.

device_machinemachdevice

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

dialogueudlg

Gives units situational sounds, such as when taking damage or fleeing.

effecteffe

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

equipmenteqipitem

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

flagflag

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

fogfog

Describes the appearance of fog planes.

fontfont
garbagegarbitem
gbxmodelmod2

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

globalsmatg

Contains global configuration related to singleplayer, multiplayer, rasterizer data, the HUD, and more.

glowglw!

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

grenade_hud_interfacegrhi
hud_globalshudg
hud_message_texthmt

Contains the text for messages that appear on the HUD like objectives and interactions.

hud_numberhud#
input_device_defaultsdevc
itemitemobject

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

item_collectionitmc
lens_flarelens

A 2D sprite which can fade by distance and angle. Can be part of a light or attached to the BSP.

lightligh

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

lightningelec
light_volumemgs2

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

material_effectsfoot

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

metermetr

Used for the global health and shield HUD meters.

modelmode

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

model_animationsantr
model_collision_geometrycoll

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

multiplayer_scenario_descriptionmply
objectobje
particlepart
particle_systempctl
physicsphys

Models the dynamic physics and propulsion of vehicles.

placeholderplacobject

Used only by Sapien to represent interactive handles/markers.

point_physicspphy

Controls how simulated points points physically interact with the environment.

preferences_network_gamengpr
projectileprojobject

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

scenarioscnr

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

scenario_structure_bspsbsp

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

sceneryscenobject

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

shadershdr
shader_environmentsenvshader

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

shader_modelsososhader

General-purpose opaque shader used for object materials.

shader_transparent_chicagoschishader
shader_transparent_chicago_extendedscexshader

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

shader_transparent_genericsotrshader

A transparent shader type supported by H1X and H1A only.

shader_transparent_glasssglashader
shader_transparent_metersmetshader

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_plasmasplashader

Used for energy shields like those on bipeds.

shader_transparent_waterswatshader
skysky

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

soundsnd!

Contains sound data such as sound effects and music and parameters affecting how sounds are played by the sound system.

sound_environmentsnde
sound_loopinglsnd
sound_sceneryssceobject

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

string_liststr#
tag_collectiontagc
ui_widget_collectionSoul
ui_widget_definitionDeLa
unicode_string_listustr
unitunitobject

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

unit_hud_interfaceunhi
vehiclevehiunit

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

virtual_keyboardvcky
weaponweapitem

Used for both weildable weapons and those attached to vehicles.

weapon_hud_interfacewphi
weather_particle_systemrain

Defines the appearance and behaviour of weather particles like rain and snow.

windwind

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

Unused tags

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.

Tag name

Group ID

Parent

Purpose

spheroidboom

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.

weapon_collection?wpcl

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_collection. Scenarios which are exported to text format and re-imported using HEK Guerilla may cause HEK Sapien to crash due to this unrecognized tag class. H1A Guerilla is immune to this issue.

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 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.

Blocks

A tag block field 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.

Some older unofficial tools refer to blocks as reflexives, a term considered outdated and comes from early halo-map-tools modding.

Group 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, HEK 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

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.

All tag files ("loose tags") have a common header structure. This header makes up the first 64 bytes of data, and contains the following fields. All primitive fields are big-endian.

FieldOffset (relative)TypeComments
tag id0x0uint32
  • Unused

Some kind of tag ID, seen in some official tag files. This is no longer used.

tag name0x4TagString
  • Unused

A tag name, seen in some official tag files. This is no longer used.

tag group0x24TagEngineId: enum32

A 4-character tag group ID encoded as an int. For example, 0x61637472 for actor.

checksum0x28uint32

Possibly unused CRC32 checksum.

header size0x2Cuint32

Meant to be the size of this header, but always equals 64 in practice. Official tools assume this size too.

unofficial flags0x30MozzFlags: bitfield64
  • Non-standard

8 bytes of padding are found here -- though Mozzarilla uses this space as an unofficial bitfield.

FlagMaskComments
edited with mozz0x1

Indicates that this tag was edited with Mozzarilla.

version0x38uint16

Definition version, always equals 1.

integrity00x3Auint8
integrity10x3Buint8

Compliment of integrity0.

engine id0x3Cuint32

A 4-character engine ID encoded as an int. Must equal 0x626C616D ("blam") for Halo. Stubbs also uses "blam" and the Shadowrun prototype used "sr_x".

Acknowledgements

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

  • Kavawuvi (Information about invalid tags and tag headers)
  • Mimickal (Information about tag headers)
  • Vaporeon (Information about modified stun values in Custom Edition)