Tags are structured data files used to define instances of the game's resources, like vehicles, weapons, bitmaps and more. When working with tags you should understand the basics like tag groups, references, paths, and blocks.
Playable maps are built from scenario tags and all of their direct and indirect dependencies, plus globals and its dependencies. Certain builds of the Halo engine are capable of loading tags directly from the tags folder (e.g. Sapien or Standalone).
For H1, you can edit tags with purpose-built tools like the H1A-EK, MEK, or Invader. Use invader-refactor if you need to move tags and want to avoid tedious reference updates.
Differences between editions
Each edition of H1 has slight differences to the tag set in its maps. Be aware of this when extracting tags with Refinery or invader-extract or mixing tags:
- Some tag classes have fields which only apply in certain editions, for example H1A's actor metagame type.
- PC retail and Custom Edition include some older versions of assets compared to Xbox, with the most famous difference being Keyes' uniform. This is restored in MCC.
- Gearbox replaced model with gbxmodel during the Xbox to PC port, and replaced instances of shader_
transparent_ generic with shader_ transparent_ chicago or other transparent shader classes. MCC restores shader_ transparent_ generic use. - Gearbox made several changes to damage_
effect stuns in Custom Edition tags only.
List of tag groups
Tag name | Group ID | Parent | Purpose |
|---|---|---|---|
| actor | actr | Defines core AI behaviours shared by actor variants. | |
| actor_variant | actv | Specializes an actor by defining their appearance, weapon use, grenades, health, and dropped equipment. | |
| 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 | ||
| continuous_damage_effect | cdmg | Creates a continuous screen shake and controller vibration within a radius of a sound_ | |
| 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_ |
| 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 | Gives units situational sounds, such as when taking damage or fleeing. | |
| 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 | Contains global configuration related to singleplayer, multiplayer, rasterizer data, the HUD, and more. | |
| glow | glw! | Used to create glowing effects like the Elite's energy sword. | |
| grenade_hud_interface | grhi | ||
| hud_globals | hudg | ||
| hud_message_text | hmt | Contains the text for messages that appear on the HUD like objectives and interactions. | |
| 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 | A 2D sprite which can fade by distance and angle. Can be part of a light or attached to the BSP. | |
| light | ligh | A dynamic light source which can be attached to objects and effects. | |
| lightning | elec | ||
| light_volume | mgs2 | Describes a dense line of glow particles, commonly used for projectile tails. | |
| material_effects | foot | Spawns effects when moving objects interact with surfaces, like tread marks, splashing footsteps, and scattering rocks. | |
| meter | metr | Used for the global health and shield HUD meters. | |
| 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 | ||
| particle | part | ||
| particle_system | pctl | ||
| physics | phys | Models the dynamic physics and propulsion of vehicles. | |
| placeholder | plac | object | Used only by Sapien to represent interactive handles/markers. |
| point_physics | pphy | Controls how simulated points physically interact with the environment. | |
| 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_ |
| 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_ |
| shader_transparent_generic | sotr | shader | A transparent shader type supported by H1X and H1A 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 | Used for energy shields like those on bipeds. |
| shader_transparent_water | swat | shader | |
| sky | sky | Defines a skybox with light sources for lightmaps and atmospheric fog. | |
| sound | snd! | Contains sound data such as sound effects and music and parameters affecting how sounds are played by the sound system. | |
| sound_environment | snde | ||
| sound_looping | lsnd | ||
| sound_scenery | ssce | object | Identical to scenery but with collision rules like device_ |
| 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 | Defines the appearance and behaviour of weather particles like rain and snow. | |
| wind | wind | Describes the speed and variation of wind in a BSP cluster, affecting local point_ |
Unused groups
The following tag groups are leftover from earlier in Halo's development and are unused or removed entirely from current versions. The tags are listed here in case you see references to them, but they can otherwise be ignored.
Tag name | Group ID | Parent | Purpose |
|---|---|---|---|
| spheroid | boom | 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 group itself no longer exists. It was probably replaced by item_ |
Tag structure
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_
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.
Header
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.
| Field | Offset (relative) | Type | Comments | ||||||
|---|---|---|---|---|---|---|---|---|---|
| tag id | 0x0 | uint32 | Some kind of tag ID, seen in some official tag files. This is no longer used. | ||||||
| tag name | 0x4 | TagString | A tag name, seen in some official tag files. This is no longer used. | ||||||
| tag group | 0x24 | TagEngineId: enum32 | A 4-character tag group ID encoded as an int. For example, | ||||||
| checksum | 0x28 | uint32 | Possibly unused CRC32 checksum. | ||||||
| header size | 0x2C | uint32 | Meant to be the size of this header, but always equals | ||||||
| unofficial flags | 0x30 | MozzFlags: bitfield64 | 8 bytes of padding are found here -- though Mozzarilla uses this space as an unofficial bitfield. | ||||||
| |||||||||
| version | 0x38 | uint16 | Definition version, always equals | ||||||
| integrity0 | 0x3A | uint8 | |||||||
| integrity1 | 0x3B | uint8 | Compliment of integrity0. | ||||||
| engine id | 0x3C | uint32 | A 4-character engine ID encoded as an int. Must equal | ||||||
Acknowledgements
Thanks to the following individuals for their research or contributions to this topic:
- Mimickal (Information about tag headers)
- SnowyMouse (Information about invalid tags and tag headers)
- Vaporeon (Information about modified stun values in Custom Edition)