Tags

The tags resource system is a central and distinguishing feature of Halo's engine, dating back even to Myth. They represent all assets and entities in the game world, such as textures, models, particle effects, AI behaviours, and weapons. The core systems of a sandbox FPS are implemented in the game's code (like physics, AI, and rendering) but tags are what allowed Bungie's artists (and now you) to create a huge variety of assets, objects, effects, and experiences without having to code (aside from scripts).

The creation and editing of tags are the core workflows of modding. Tags are packaged into distributable maps.

Creating and editing tags

Each games' mod tools come with a set of stock tags needed to build the game's original maps, plus tools used to create and edit tags. Here are some example workflows:

Tag groups

Tags come in many different types (called tag groups or classes), each with a predefined structure and data fields. Each game introduces or removes tag groups compared to its predecessor, but there is a lot of overlap in tag groups and they tend to work similarly in each generation. Tags are usually incompatible across games because their layout changes, unless the tag's layout hasn't changed (e.g. many H3 and ODST tags).

You can see a full list of tag groups for H1, H2, H3, and Reach. Some commonly used ones are:

  • scenario: A level's root tag, including all object placements, AI encounters, weather assignments, and more.
  • scenery: For basic non-moving objects like boulders.
  • scenario_structure_bsp: Contains level geometry and lighting information.
  • biped: Defines a playable or AI character, including its physics shape and movement.
  • weapon: Sets weapon characteristics like charging time, ammo account, what projectile it fires.
  • bitmap: Contains textures in a format ready to use by the engine and your GPU.
  • effect: Defines the particles, sounds, lights, and decals that can appear from effects like impacts or detonations.

An individual tag belonging to one of these tag groups, e.g. warthog.vehicle, is called a tag instance or definition since it defines one case of that tag class.

Tag paths and references

A tag path is like a URL for a tag; it corresponds to where you find a tag under the tags folder. For example, a scenario tag file at tags\levels\test\bloodgulch\bloodgulch.scenario would have the tag path levels\test\bloodgulch\bloodgulch (the file extension is not part of the tag path).

Many tag groups can reference other tags to take advantage of common assets, like different effects referencing the same particle. These references can be set when editing tags in Guerilla or Sapien and are stored using tag paths. Don't forget to update references to a tag if you need to move or rename it. Broken references will prevent your level from loading or building!

Tag loading

The tag files in your tags folder (also called loose tags) are not used by the game as-is. The game instead uses processed versions of these tags, e.g. by precalculating additional fields or replacing tag references with more efficient indices or pointers. The goal is to convert a tag intended for editing into a tag efficiently used by the engine.

This processing step will happen in one of two ways depending on the build type of the game or tool loading them:

  • Development tools which need to simulate the game world, like Standalone and Sapien, load the loose tags from your tags folder. All the tag files needed for a level are individually loaded from disk and processed. This process is slower but allows for quicker iteration during development of mods.
  • Release builds like MCC itself loads levels from map cache files in the maps folder. These .map files are created using Tool as the final step in map development and include almost all the tags needed for a level in an already-processed state. The engine can quickly load the single map file into memory and have all tags ready to use. Maps must be rebuilt with Tool if you want to make changes to the tags in them.