Tool (tool.exe), is a command-line utility used to compile data into tags, and tags into maps. It is part of the HEK.

Model compilation

A JMS file containing model geometry can be compiled into a gbxmodel using the model verb:

# model <source-directory>
tool.exe model "scenery\rock"

For the example above, Tool would expect to find a corresponding JMS file at data\scenery\rock\models\rock.JMS. Assuming no errors, it would be compiled into tags\scenery\rock\rock.gbxmodel. Geometry errors will cause Tool to create WRL files for troubleshooting.

Something to note is that Tool reads the filename of the JMS to decide how to generate specific tag data for the model. The format for this is as follows:

# <permutation_string> <lod_level>.JMS
base superhigh.JMS

Permutations are variants for model's regions. LODs (level of detail) are different quality models rendered depending on the object's size on screen. Permutations can be named arbitrarily, though they should match a model's existing permutation names if modifying an existing asset. LOD needs to use a specific string from the list below:

• superhigh
• high
• medium
• low
• superlow

Use multiple JMS files to generate multiple permutations in a model.

Animation compilation

Animation data files containing transforms for a skeleton can be compiled into a model_animations tag using the animations verb:

# animations <source-directory>
tool.exe animations "characters\cyborg"

For the example above, Tool would expect to find corresponding animation data files at data\characters\cyborg\animations\. Assuming no errors, it would be compiled into tags\characters\cyborg\cyborg.model_animations.

See the animation data page for more info on the various extensions used during animation importing and their purpose.

String compilation

UTF-8 text files containing strings can be compiled into a string_list using the strings verb:

# strings <source-directory>
tool.exe strings "weapons\assault rifle"

For the example above, Tool would expect to find text files at data\weapons\assault rifle\. Assuming no errors, a file named "assault rifle.txt" would be compiled into tags\weapons\assault rifle.string_list. Each text file that exists in the source directory will be compiled into its own individual tag with the name of the tag coming from the text filename.

Unicode String compilation

UTF-16 text files containing strings can be compiled into a unicode_string_list using the unicode-strings verb:

# unicode-strings <source-directory>
tool.exe unicode-strings "ui\mp_map_ui"

For the example above, Tool would expect to find text files at data\ui\mp_map_ui\. Assuming no errors, a file named "prisoner.txt" would be compiled into tags\ui\mp_map_ui\prisoner.unicode_string_list. Each text file that exists in the source directory will be compiled into its own individual tag with the name of the tag coming from the text filename.

For more in depth instructions see the string list format reference.

Batch bitmap compilation

TIFF (.tif) images can be compiled into a bitmap using the bitmaps verb:

# bitmaps <source-directory>
tool.exe bitmaps "characters\cyborg\bitmaps"

For the example above, Tool would expect to find .tif files at data\characters\cyborg\bitmaps\. Assuming no errors, each image file will be compiled into a bitmap tag at tags\characters\cyborg\bitmaps\. Each image file that exists in the source directory will be compiled into its own individual tag with the name of the tag coming from the image filename.

Be aware that all images must use the .tif extension for this command to work. If you have .tiff files in the source directory, then rename their extensions to .tif.

Tool supports TIFF files with a colour depth of at least 8 bits per pixel, 32-bit color (8 bits per channel) being typical.

Bitmap compilation

Compile a single TIFF image into a bitmap using the bitmap verb:

# bitmap <source-file>
tool.exe bitmap "characters\cyborg\bitmaps\cyborg"

For the example above, Tool would expect to find a .tif or .tiff file at data\characters\cyborg\bitmaps\cyborg.tif. Assuming no errors, the image file will be compiled into a bitmap tag at tags\characters\cyborg\bitmaps\cyborg.bitmap. The bitmap filename will come from the image filename.

As with the bitmaps verb, TIFF files must have at least 8-bit colour depth and are typically 32-bit.

Structure compilation

A JMS file containing level geometry can be compiled into a scenario_structure_bsp using the structure verb:

# structure <scenario-directory> <bsp-name>
tool.exe structure levels\a30 a30_a

For the example above, Tool would expect to find a corresponding JMS file at data\levels\a30\models\a30_a.JMS. Assuming no errors, it would be compiled into tags\levels\a30\a30_a.scenario_structure_bsp. Geometry errors will cause Tool to create WRL files for troubleshooting.

Structure compilation converts the raw polygon and materials data from the JMS into data structures which are more efficient for Halo to use during rendering, collision tests, and AI pathfinding among other tasks. Note that lightmaps are not produced during this step, but rather with the lightmaps verb. Structure compilation will create a scenario tag if one does not exist already.

Multiple JMS files can be placed in a level's models directory for multiple BSPs (used for large singleplayer levels). Each JMS will be compiled into a separate structure BSP and added to the scenario. Scripts and trigger volumes can then be used to switch between the BSPs.

Structure lens flares

This command updates a BSP's lens flare markers using the current lens flare fields in the BSP's referenced shader_environment tags. This can be used to update the markers after changes to the shader fields without having to recompile the BSP entirely with the structure verb.

# structure-lens-flares <bsp-path>
tool.exe structure-lens-flares "levels\a10\a10a"

Structure breakable surfaces

Updates breakable surface data for an existing BSP tag. Saves the tag if only if there was no error.

# structure-breakable-surfaces <bsp-path>
tool.exe structure-breakable-surfaces "levels\a10\a10a"

Collision geometry compilation

A JMS file containing a collision model can be compiled into a model_collision_geometry using the collision-geometry verb:

# collision-geometry <source-directory>
tool.exe collision-geometry "scenery\rock"

For the example above, Tool would expect to find a corresponding JMS file at data\scenery\rock\physics\rock.JMS. Assuming no errors, it would be compiled into tags\scenery\rock\rock.model_collision_geometry. Geometry errors will cause Tool to create WRL files for troubleshooting.

Permutations and LODs are also supported using the same file name conventions as render model compilation:

# <permutation_string> <lod_level>.JMS
base superhigh.JMS

Physics compilation

A JMS file containing collision spheres can be compiled into a physics using the physics verb:

# physics <source-directory>
tool.exe physics "vehicles\wraith"

For the example above, Tool would expect to find a corresponding JMS file at data\vehicles\wraith\physics\wraith.JMS. Assuming no errors, it would be compiled into tags\wraith\wraith.physics.

Sounds compilation

A 16-bit WAV file can be compiled into a sound tag using the sounds verb:

# sounds <source-directory> platform<xbox,wav,ogg> ogg_only_value_flag<quality or bitrate>
tool.exe sounds "vehicles\ghost" ogg 1

The "ogg_only_value_flag" argument is only required if "platform" is OGG, and must be a real number in the range 0.0 - 1.0. The value 0 is the lowest quality and 1 is the highest.

In order to import Xbox sounds you will need the XBADPCM codec installed on your PC. You will get tool errors when trying to convert the sound file otherwise.

Regardless of the platform you choose, the sound file you import should still be saved as a 16 bit WAV file.

Sounds by type

A 16-bit WAV file can be compiled into a sound tag using the sounds_by_type verb:

# sounds_by_type <source-directory> type<sound_class> <round to 64 samples:yes/no>
tool.exe sounds_by_type "vehicles\ghost" projectile_impact yes

Sounds imported with this command will default to Xbox platform so make sure you have the codec installed.

Replace type with a string of your choosing from the following list.

The sound class will influence the capabilities of the sound tag, and may be used when the map is compiled or at runtime. See the sound class field for more info.

Build cache file

A scenario can be compiled into a map using the build-cache-file verb. Simply provide your scenario's tag path:

# build-cache-file <scenario-name>
tool.exe build-cache-file "levels\test\tutorial\tutorial"

The resulting map file can be found in Halo's maps directory.

Hardcoded tag patches

There are a number of gameplay-balancing tag patches ("Jason Jones edits") made at runtime on Xbox, but also at map compilation time by Tool. On both platforms, these patches are only made to singleplayer scenarios.

These changes are made only to the resulting tag data in the map file, but be careful when extracting tags from singleplayer maps (both PC and Xbox)! You will actually overwrite the original weapon tags and cause your custom multiplayer maps to also use these values.

Windows font

This will open a window to preview font packaged installed on your machine. From there you can select a font to package into a valid tag for Halo to make use of.

HUD messages compilation

UTF-16 text files with an .HMT extension can be compiled into a hud_message_text using the hud-messages verb:

# hud-messages <path> <scenario-name>
tool.exe hud-messages "levels\a10" "a10"

For the example above, Tool would expect to find a text file at data\levels\a10\hud messages.hmt. Assuming no errors, a file named "hud messages.hmt" would be compiled into tags\levels\a10\hud messages.hud_message_text.

It's important that the file's name be "hud messages.hmt". Tool specifically looks for a file with this name when compiling HUD messages. You can simply edit the ".hmt" file with notepad. Simply renaming it from .TXT to .HMT will take care of that. The text file must also exist in the root of the scenario folder in data.

See more in-depth instructions.

Lightmaps

Both Tool and Sapien can be used to generate lightmaps (radiosity). Using Tool, you will need the following arguments:

1. Scenario tag path: This is not a file path! Leave off the ".scenario" extension and start the path from within the tags directory.
2. BSP name: The name of the BSP tag without the file extension. Although this is labeled as "bsp index" in Tool's usage, it is not intended to be a numeric value.
3. Radiosity quality: A value of 0 runs an inaccurate "fast radiosity", with fewer light bounces, a lower resolution lightmap, and ignoring light occlusion or blocking caused by models. A value of 1 runs a "full radiosity", which is much slower but is used for the release version of maps. For further details, see the radiosity quality settings below.
4. Stop threshold: Light is cast in multiple passes from each surface, getting progressively finer with each pass. Each pass also reduces the total amount of light to be cast from each surface. When the average radiosity of the scene reaches this value, the process will stop and results saved. This is the equivalent of choosing when to run radiosity_save in Sapien.

For example:

# lightmaps <scenario> <bsp index> <quality> <stop threshhold>
tool.exe lightmaps "levels\test\tutorial\tutorial" tutorial 1 0.01

After a short time, you should observe a number counting down towards 0. The radiosity process will stop once this number reaches your "stop" argument. If the number counts up instead, it indicates an issue with your level geometry and you should cancel radiosity to address it (check for WRL warnings).

Consider using the faster LM_Tool instead for rendering final lightmaps.

Radiosity quality technical details

The radiosity process internally subdivides/tessellates the mesh into an intermediate lightmap structure which is much denser in some places. Depending on the radiosity quality chosen and shader detail level, different constraints will be placed on this process:

Process sounds

This command searches for sounds in a tag directory and sets the values in the sound tag.

# process-sounds <root path> <substring> <gain+|gain-|gain=|maximum-distance|minimum-distance> <value>
tool.exe process-sounds "sound\sfx\ambience\a10" "klax" gain+ 1

For the example above, Tool would expect to find a set of sound tags at tags\sound\sfx\ambience\a10\. Any sound tags that contain the substring "klax" in the filename will have a value of 1 added to gain.

Merge scenery

This command can merge the scenery tag blocks of the source scenario to the destination scenario. This was probably used to automate work on child scenarios in Halo's development.

# merge-scenery <source scenario> <destination scenario>
tool.exe merge-scenery "levels\a10\a10" "levels\a30\a30"

For the example above, Tool would expect to find a source scenario tag file at tags\levels\a10\a10. The tag blocks in the scenery tag block will be copied over to the destination scenario tag file at tags\levels\a30\a30. This will not include scenery palette tag block or object names tag block so watch out for bad indices.

Zoners model upgrade

Upgrades models to gbxmodel, likely used to port models from the Xbox edition of the game to PC by Gearbox.

tool.exe zoners_model_upgrade

Import device defaults

Unknown purpose.

# import-device-defaults <defaults|profiles> <savegame path>
tool.exe import-device-defaults <defaults|profiles> <savegame path>

Acknowledgements

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

• gbMichelle (Hardcoded tag patch reversing)
• General_101 (Documenting tool commands)
• Kavawuvi (Warning about Tool only using marker from superhigh LOD)
• MosesOfEgypt (Explanation of radiosity passes)