HR Tool

This page is incomplete! You can contribute information using GitHub issues or pull requests.

HR-Tool (tool.exe), is a command-line utility used to compile data into tags, and tags into maps. It was released as a part of the Halo Reach Editing Kit by 343 Industries in 2021. Users can also run Tool commands in Foundation where commands can be filtered and favorited.

Users should note that whilst HR Tool includes several legacy commands for creating render, collision and physics models, the expected workflow is to use the Import command which uses the granny format.

Tips

  • If an invalid command is typed into tool then tool will print a list of commands that have the same starting character as what was typed in. This means that if we type tool s into command prompt then tool will only output commands that start with the letter s.

Conventions used in this article

  • <argument> - refers to an argument.
  • <option1|option2> - Either option1 or option2 can be passed as argument.
  • Tool or tool.exe - refers to the subject of this article, the HR Tool, if the legacy Tool is being referred to that will be made explicit.

FBX to GR2

This command takes an FBX and converts it to a GR2 file for Halo Reach importing. It is a required step in the process of creating a file that can be used by the import command.

# fbx-to-gr2 <fbx> <json> <gr2>
tool fbx-to-gr2 "F:\dreamer.fbx" "F:\dreamer.json" "F:\dreamer.gr2"
  • fbx - An absolute filepath to a valid FBX file.
  • json - An absolute filepath to a JSON file. Will be generated if one does not already exist.
  • gr2 - An absolute filepath that includes name and extension to write the output to.

Bitmap single

Imports a single image file and converts it to a bitmap.

#  bitmap_single <image-file>
tool bitmap_single
  • image-file - A local data path to a tif/tiff file with extension.

Bitmaps

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

# bitmaps <source-directory>
tool bitmaps "levels\multi\chill\bitmaps"
  • source-directory - A local data path to a folder containing a set of images for processing.

For the example above, Tool would expect to find .tif/.tiff files at data\levels\multi\chill\bitmaps\. Assuming no errors, each image file will be compiled into a bitmap tag at tags\levels\multi\chill\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.

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

Any bitmaps that end in _bump will automatically be converted to a bitmap set as a bump map.

Bitmaps with type

This command compiles images like the bitmaps command but allows the user to set the type of bitmap to generate.

# bitmaps-with-type <source-directory> <type>
tool bitmaps-with-type "levels\multi\30_settlement\bitmaps" 2d
  • source-directory - A local data path to a folder containing a set of images for processing.
  • type - sets the type of bitmap the image will be converted to. This will change how the source image is expected to be setup. The list of valid options is as follows:
    • 2d
    • 3d
    • cubemaps
    • sprites
    • interface

Building cache files

Cache files can be built using multiple tool verbs, but you will likely only use build-cache-file

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> <platform> <target-language> <dedicated-server-(optional)> <compress_more|compress_most-(optional)> <use-fmod-data-(optional)> <audio-configuration>
tool build-cache-file "levels\multi\30_settlement\30_settlement" pc
  • scenario - A local tag path to your scenario without the file extension
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • target-language - ??? This is an optional argument
  • dedicated-server - ??? This is an optional argument
  • compress_more|compress_most - ??? This is an optional argument
  • use-fmod-data - ??? This is an optional argument
  • audio-configuration - ??? This is an optional argument

The resulting map file can be found in the editing kit's maps directory. This verb also generates reports under reports\<mapname> including a compilation-specific debug.txt.

Build cache file cache

Builds the resource maps and associated cache files needed for tag sharing.

# build-cache-file-cache <platform>
tool build-cache-file-cache pc
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file cache campaign second

Builds resources files and cache files for campaign maps. Requires build-cache-file-cache-shared-first to be done first.

# build-cache-file-cache-campaign-second <platform> <target-language> <minor-version-number> <optimizable> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-cache-campaign-second pc
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • target-language - ??? This is an optional argument
  • minor-version-number - ??? This is an optional argument
  • optimizable - ??? This is an optional argument
  • dedicated-server - ??? This is an optional argument
  • use-fmod-data - ??? This is an optional argument

Build cache file cache custom

Builds cache files needed for tag sharing.

# build-cache-file-cache-custom <shared-manifest-list> <campaign-manifest-list> <platform>
tool build-cache-file-cache-custom
  • shared-manifest-list - ???
  • campaign-manifest-list - ???
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file cache language version

Builds the resource maps and associated cache files needed for tag sharing.

# build-cache-file-cache-language-version <target-language> <minor-version-number> <platform>
tool build-cache-file-cache-language-version english "" pc
  • target-language - self explanatory
  • minor-version-number - ???
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file cache shared first

Builds the resource maps and associated cache files needed for tag sharing.

# build-cache-file-cache-shared-first <platform> <target-language> <minor-version-number> <sound-config> <optimizable> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-cache-shared-first pc
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • target-language - ??? This is an optional argument
  • minor-version-number - ??? This is an optional argument
  • sound-config - ??? This is an optional argument
  • optimizable - ??? This is an optional argument
  • dedicated-server - ??? This is an optional argument
  • use-fmod-data - ??? This is an optional argument

Build cache file cache sounds

Builds the resource maps and associated cache files needed for tag sharing. Requires build-cache-file-cache-sounds-index to be done first.

# build-cache-file-cache-sounds <platform> <target-language> <minor-version-number> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-cache-sounds pc
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • target-language - ??? This is an optional argument
  • minor-version-number - ??? This is an optional argument
  • dedicated-server - ??? This is an optional argument
  • use-fmod-data - ??? This is an optional argument

Build cache file for cubemaps

Builds the provided scenario along with the associated cache files needed for tag sharing cubemap data.

# build-cache-file-for-cubemaps <scenario> <platform>
tool build-cache-file-for-cubemaps "levels\multi\30_settlement\30_settlement" pc
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file language

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

# build-cache-file-language <target-language> <scenario> <platform>
tool build-cache-file-language english "levels\multi\30_settlement\30_settlement" pc
  • target-language - ???
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file language version

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

# build-cache-file-language-version <target-language> <minor-version-number> <scenario> <platform>
tool build-cache-file-language-version english "" "levels\multi\30_settlement\30_settlement" pc
  • target-language - ???
  • minor-version-number - ???
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Bulk imports

Bulk import commands allow you to import many files at once using a JMI file. Other than that they work similarly to individual imports.

Bulk collision

Multiple directories can have their collision files compiled in a single run using this command.

#  bulk-collision <jmi-file>
tool bulk-collision "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import crates

Compile multiple source directories in a single run to generate a crate tag and all the relevant tags involved. Render tags will use PRT

#  bulk-import-crates <jmi-file>
tool bulk-import-crates "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import crates draft

Compile multiple source directories in a single run to generate a crate tag and all the relevant tags involved. Render tags will not use PRT

#  bulk-import-crates-draft <jmi-file>
tool bulk-import-crates-draft "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import crates folder

Generates a crate tag and compiles the render, collision, and physics directory of a model in a single run. Just point it at the root of your model folder and go! Render tags will use PRT

#  bulk-import-crates-folder <source-directory>
tool bulk-import-crates-folder "objects\multi\world_node_a"
  • source-directory - A local data path to the root of a model source directory.

Bulk import crates folder draft

Generates a crate tag and compiles the render, collision, and physics directory of a model in a single run. Just point it at the root of your model folder and go! Render tags will not use PRT

#  bulk-import-crates-folder-draft <source-directory>
tool bulk-import-crates-folder-draft "objects\multi\world_node_a"
  • source-directory - A local data path to the root of a model source directory.

Bulk import model folder

Generates a model tag and compiles the render, collision, and physics directory of a model in a single run. Just point it at the root of your model folder and go! Render tags will use PRT

#  bulk-import-model-folder <source-directory> <skip-coarse-optimization|-s(optional)>
tool bulk-import-model-folder "objects\multi\world_node_a"
  • source-directory - A local data path to the root of a model source directory.
  • skip-coarse-optimization - ???

Bulk import model folder draft

Generates a model tag and compiles the render, collision, and physics directory of a model in a single run. Just point it at the root of your model folder and go! Render tags will not use PRT

#  bulk-import-model-folder-draft <source-directory>
tool bulk-import-model-folder-draft "objects\multi\world_node_a"
  • source-directory - A local data path to the root of a model source directory.

Bulk import models

Compile multiple source directories in a single run to generate a model tag and all the relevant tags involved. Render tags will use PRT

#  bulk-import-models <jmi-file>
tool bulk-import-models "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import models draft

Compile multiple source directories in a single run to generate a model tag and all the relevant tags involved. Render tags will not use PRT

#  bulk-import-models-draft <jmi-file>
tool bulk-import-models-draft "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import scenery

Compile multiple source directories in a single run to generate a scenery tag and all the relevant tags involved. Render tags will use PRT

#  bulk-import-scenery <jmi-file>
tool bulk-import-scenery "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import scenery draft

Compile multiple source directories in a single run to generate a scenery tag and all the relevant tags involved. Render tags will not use PRT

#  bulk-import-scenery-draft <jmi-file>
tool bulk-import-scenery-draft "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk import scenery folder

Generates a scenery tag and compiles the render, collision, and physics directory of a model in a single run. Just point it at the root of your model folder and go! Render tags will use PRT

#  bulk-import-scenery-folder <source-directory>
tool bulk-import-scenery-folder "objects\multi\world_node_a"
  • source-directory - A local data path to the root of a model source directory.

Bulk import scenery folder draft

Generates a scenery tag and compiles the render, collision, and physics directory of a model in a single run. Just point it at the root of your model folder and go! Render tags will not use PRT

#  bulk-import-scenery-folder-draft <source-directory>
tool bulk-import-scenery-folder-draft "objects\multi\world_node_a"
  • source-directory - A local data path to the root of a model source directory.

Bulk physics

Multiple directories can have their physics files compiled in a single run using this command.

#  bulk-physics <jmi-file>
tool bulk-physics "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk render

Multiple directories can have their render files compiled in a single run using this command. Render tags will not use PRT

#  bulk-render <jmi-file>
tool bulk-render "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Bulk render final

Multiple directories can have their render files compiled in a single run using this command. Render tags will use PRT

#  bulk-render-final <jmi-file>
tool bulk-render-final "objects\multi\jmi_Test.JMI"
  • jmi-file - A local data path to where the JMI file is located.

Camera track

This commands takes a JMA file directly and converts it to a camera_track for the game. The length of the animation should be at most 16 as that is the max number of control points a camera track tag can contain. The JMA should contain a skeleton made up of a single bone that will change its position each frame. The orientation of the bone will determine the position and rotation of the control point for that index. The name of the JMA file will be the name of the tag. Keep in mind that the extension check for this command is case sensitive. Keep the JMA portion lower case.

# camera-track <source-file>
tool camera-track camera\vehicle_longsword.jma
  • source-file - A local data path to where the JMA file is located.

Check all tags

Checks if your tags are valid.

# check-all-tags
tool check-all-tags

Collision

A JMS file containing a collision model can be compiled into a collision model tag

# collision <source-directory>
tool collision "objects\characters\masterchief"
  • source-directory - A local data path to the root of a model source directory.

For the example above, Tool would expect to find a corresponding JMS file at data\objects\characters\masterchief\collision\mc_collision.JMS. Assuming no errors, it would be compiled into tags\objects\characters\masterchief\masterchief.collision_model. Geometry errors will cause Tool to create WRL files for troubleshooting.

Compile shader

Compile the template needed for a specific shader.

# compile-shader <render-method>
tool compile-shader "objects\block\shaders\discard" "win"
  • render-method - Shader to compile
  • platform - set this to win

Shaders

Compiles non-template shaders, only useful if you are writing custom shaders.

# shaders <-debug-(optional)> <-pdb-path-(optional)> <platform>
tool shaders win

Count all class sounds

Goes through all of the sound tags in a directory and prints how many sounds belong to a specific class

# count-all-class-sounds <root-path>
tool count-all-class-sounds "sound\ambience"
  • root-path - A local tag path to the root of a directory containing sound tags or child folders with sound tags.

Count class sounds

Goes through all of the sound tags in the tags directory and prints the paths for sounds that use a specific sound class

# count-class-sounds <sound-class>
tool count-class-sounds projectile_impact
  • sound-class - The sound class you want to specify. The list is as follows.
    • Placeholder

Count class sounds

Prints all existing sound tags in a directory.

# count-sound-tags <root-path>
tool count-sound-tags "sound\ambience"
  • root-path - A local tag path to the root of a directory containing sound tags or child folders with sound tags.

Cubemaps

Generates cubemaps to be used by dynamic cubemap enabled shaders. There are two things you will need to do first before running this command. Open the level you want to generate cubemaps for in Sapien and place down some cubemap points. You can find cubemap points in the hierarchy view under the folder path Structure Data > Cubemaps.These points will be used by the command cubemap_dynamic_generate to generate the cubemaps we will need. Once that's done open up your level in Standalone and run the command cubemap_dynamic_generate. The results of this command will be written to a folder in the root of your HREK named cubemaps. Once you've done that you can run the cubemaps command from tool.

# cubemaps <scenario> <input-folder>
tool cubemaps "levels\multi\70_boneyard\70_boneyard" "F:\HREK\cubemaps"
  • scenario - A local tag path to a scenario file without extension.
  • input-folder - An absolute path to a folder containing cubemap DDS files generated by standalone

Decorator set link render model

Sets the render_model tag reference in a decorator-set tag.

# decorator-set-link-render-model <decorator-set> <render-model>
tool decorator-set-link-render-model "levels\shared\decorators\barnacles\barnacles" "levels\shared\decorators\barnacles\barnacles"
  • decorator-set - A local tag path to a decorator_set tag file without extension.
  • render-model - A local tag path to a render_model tag file without extension.

Dialogue globals import

Compiles a CSV file to generate a new ai_dialogue_globals tag. The file path for the CSV file is data\ai\ai_dialogue_globals.csv and tags\ai\ai_dialogue_globals.ai_dialogue_globals is generated.

# dialogue-globals-import
tool dialogue-globals-import

Dialogue import

Collects all sound tag paths and adds them to a generated dialogue tag.

# dialogue-import <root-directory>
tool dialogue-import "sound\dialog\combat\brute_bloodthirsty"
  • root-directory - A local tag path to a root directory containing sound tags. A dialogue tag is generated adjacent to this root directory with the same name, e.g. sound\dialog\combat\brute_bloodthirsty.dialogue.

Dump render method options

Dumps an index of all shader templates used by shaders, once it's done it prints out some statistics and saves information to the shaders folder in binary or text form. Required for building templates.

# dump-render-method-options
tool dump-render-method-options

Exporting bitmaps

Tool has serval commands for exporting bitmap data into various formats.

Export bitmap DDS

Takes the processed pixel data from a bitmap tag and dumps it to a DDS image.

# export-bitmap-dds <bitmap-tag> <output-path-prefix>
tool export-bitmap-dds "objects\characters\brute\bitmaps\brute_base_diffuse" "C:\pixel_data_"
  • bitmap-tag - A local tag path to a bitmap tag without extension.
  • output-path-prefix - An absolute file path to a directory to output the DDS file to along with a prefix to append to the start of the DDS filename. If only a prefix is given then the file will be dumped at the root of your HREK directory.

Export bitmap PFM

Takes the processed pixel data from a bitmap tag and dumps it to a PFM image.

# export-bitmap-pfm <bitmap-tag> <output-path-prefix>
tool export-bitmap-pfm "objects\characters\brute\bitmaps\brute_base_diffuse" "F:\pixel_data_"
  • bitmap-tag - A local tag path to a bitmap tag without extension.
  • output-path-prefix - An absolute file path to a directory to output the PFM file to along with a prefix to append to the start of the PFM filename. If only a prefix is given then the file will be dumped at the root of your HREK directory.

Export bitmap TGA

Takes the processed pixel data from a bitmap tag and dumps it to a TGA image.

# export-bitmap-tga <bitmap-tag> <output-path-prefix>
tool export-bitmap-tga "objects\characters\brute\bitmaps\brute" "F:\pixel_data_"
  • bitmap-tag - A local tag path to a bitmap tag without extension.
  • output-path-prefix - An absolute file path to a directory to output the TGA file to along with a prefix to append to the start of the TGA filename. If only a prefix is given then the file will be dumped at the root of your HREK directory.

Export DXT5 array from bitmap array

Takes the processed pixel data from a bitmap tag and dumps it to PFM images.

# export-dxt5-array-from-bitmap-array <bitmap-tag> <output-path-prefix>
tool export-dxt5-array-from-bitmap-array "levels\multi\cyberdyne\cyberdyne_lightmap_cyberdyne_16f_lp_array_dxt5" "F:\pixel_data_"
  • bitmap-tag - A local tag path to a lightmap bitmap tag without extension.
  • output-path-prefix - An absolute file path to a directory to output the file to along with a prefix to append to the start of the filename. If only a prefix is given then the file will be dumped at the root of your HREK directory.

Export structure mesh OBJ

Takes a scenario tag and finds the structure_bsp referenced. The mesh is then outputted in an OBJ file format in tool output.

# export-structure-mesh-obj <scenario>
tool export-structure-mesh-obj "levels\multi\snowbound\snowbound"
  • scenario - A local tag path to a scenario tag without extension.

Export tag to XML

Takes a tag and dumps the contents to an XML format. Use this for easy comparisons.

# export-tag-to-xml <tag-file> <output-file>
tool export-tag-to-xml "F:\HREK\tags\objects\characters\spartans\spartans.render_model" "F:\spartans.xml"
  • tag-file - An absolute tag path to a tag with extension.
  • output-file - An absolute file path to an output directory with file name and extension.

Extract import info

Dumps the stored import-info data used to originally import the tag file. Only tags that contain valid import-info can use this. This means only render_model, collision_model, physics_model, and scenario_structure_bsp.

The stock tags that come with the HREK do not contain any import info, so this command will not work on them.

# extract-import-info <tag-file>
tool extract-import-info "F:\HREK\tags\objects\characters\spartans\spartans.render_model"
tool extract-import-info "F:\HREK\tags\objects\characters\spartans\spartans.collision_model"
tool extract-import-info "F:\HREK\tags\objects\characters\spartans\spartans.physics_model"
tool extract-import-info "F:\HREK\tags\levels\multi\30_settlement\30_settlement.scenario_structure_bsp"
  • tag-file - An absolute file path to a tag containing valid import info.

Extract LPC data

Dumps a file called test.aif in the root of HREK. This is likely to be linear predictive coding data for the sound file but this hasn't be verified.

# extract-lpc-data <sound-file>
tool extract-lpc-data "sound_test\aiff\soundtest.aiff"
  • sound-file - A local data path to an AIF/AIFF file.

Extract render data

Dumps the stored import-info data used to originally import the render_model file. Only render_model tags that contain valid import-info can use this.

# extract-render-data <render-model>
tool extract-render-data "objects\characters\spartans\spartans"
  • render-model - A local tag path to a render_model tag without extension.

Baking lightmaps (Faux)

Halo Reach uses a fairly sophisticated lightmapping pipeline compared to the earlier games, for more information see the Lighting and material of Halo 3 GDC talk or the research paper of the same name. The end result of this is a system that produces much nicer looking lightmaps if used correctly (you are still responsible for setting up the lights correctly). Lightmapping is also faster than stock H1 and H2 as multi-process/core support is included out of the box - in fact currently single process lightmapping is broken and multi process lightmapping has to be used.

Data sync

Before you can start the lightmapping process you need to ensure certain data is synced. If the data is synced already this process is nearly instantaneous otherwise it can take a while depending on the BSP.

#tool faux_data_sync <scenario> <bsp-name>
tool faux_data_sync "levels\multi\20_sword_slayer\20_sword_slayer" "20_sword_slayer"
  • scenario - A local tag path to a scenario without extension
  • bsp-name - The name of a BSP tag referenced by the scenario tag

If you use the Osoyoos launcher or the Python script supplied this step will be done automatically.

Lightmapping using the Python script

You need to install Python if you haven't already see the official documentation on how to do that for your platform, if at some point you are asked if you wish to add python to PATH it is suggested you do that as it will make your life easier. Once Python is installed and working run the calc_lm_farm_local.py script in the toolkit root directory.

#python calc_lm_farm_local.py <scenario> <bsp name> <quality(high, medium, low, direct_only)> <light group>
python calc_lm_farm_local.py "levels\multi\30_settlement\30_settlement" 30_settlement medium all

If you aren't sure what to use for light group/region just use the catch all value of all, this will ensure all regions are lit correctly. As for quality keep in mind that it will have an impact on how long lightmapping takes but should have only a minor impact on CPU utilisation percentage during that time - the script will use 100% of your CPU as it's hardcoded to use all the logical processors accessible to it.

Lightmapping using the Osoyoos launcher

Lightmapping using the launcher should be more or less the same as lightmapping Halo 2 using it, just keep in mind the fact that super quality is somewhat unstable and high might be good enough. You don't need to set a lightmap region if you don't know what it does.

Manually lightmapping using the command line

The faux_lightmap and faux_checkerboard commands are meant to handle local single instance lightmaps but they are sadly currently broken. In principle you can invoke the same commands the launcher and the script invoke manually but this isn't recommended. In the interest of brevity it will not be discussed here - read the Python script if you are interested in how it works, it should be easy to understand as it's quite short.

Disk usage

The multi-instance faux process dumps a fair bit of intermediate data to disk which might not be desirable on a slow medium (e.g. external HDD or network drive) or an SSD if you are running a lot of lightmaps and don't want to needlessly wear it out. This data will be saved to the faux folder in the toolkit root directory. You can create a link (junction point or symbolic) from this folder to somewhere that is more convenient for you. If you have enough free main memory a RAM Disk might be a good solution - 30 gigabytes of dynamically allocated space should be enough (empirical result for a 16 logical processor system lighting Halo 3's Edge map at the highest quality - results may differ in Reach).

Import

The import command is a multi-purpose command used for importing animations, collision, physics and render geometry. It is also the only command that can be used to import structures, superceding the structure command used in prior editing kits.

# import <sidecar-file> <check|force|verbose|repro|draft|seam_debug|skip_instances|local|farm_seams|farm_bsp|decompose_instances|suppress_errors_to_vrml <string-array>
tool import "objects\weapons\rifle\dmr\dmr.sidecar.xml" force local
  • sidecar-file - A file containing a list of objects and properties within a directory for importing.
  • force - Forces all files to import even if they haven't changed
  • draft - Skip generating PRT data, allowing for faster speed at a lower quality (models only).
  • seam_debug - Provides extra seam debugging information (structures only).
  • local - Build is orphaned from the depot (structures only).
  • decompose_instances - Run convex decomposition for poop physics, very slow (structures only).
  • suppress_errors_to_vrml - Do not write errors to vrml files.

Megalo convert variant files

Converts mglo files built with MegaloEdit and converts them to bin files that can be used in MCC.

# megalo-convert-variant-files <source-directory> <destination-directory>
tool megalo-convert-variant-files "maps\megalo" "maps\game_variants"
  • source-directory - A directory containing mglo files.
  • destination-directory - The output directory to store the converted bin files.

Sounds

Reimport sounds

Goes through all sound tags in a directory or child directories. Any sound tags that are found will have their sound files from data reimported.

# reimport-sounds <source-directory> <compressor> <downmix> <-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)>
tool reimport-sounds "sound\dialog\combat" default downmix unit_dialog english
  • source-directory - A local tag path to a directory or child directory containing sound tags.
  • compressor - Specify the compressor (default, pcm, xma, xma2)
  • downmix - Down mix the adpcm sample (downmix). This is an optional argument
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Reimport sounds for senario

Reimports the sounds for a scenario if the sound data is found in the data folder.

# reimport-sounds-for-senario <scenario> <compressor> <downmix> <type> <-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)>
tool reimport-sounds-for-senario "levels\multi\riverworld\riverworld" default downmix music sfx
  • scenario - A local tag path to a scenario without extension.
  • compressor - Specify the compressor (default, pcm, xma, xma2)
  • downmix - Down mix the adpcm sample (downmix). This is an optional argument
  • type - Only reimport the sample if it matches the specified type criteria.
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Reimport sounds single

Reimports the specified sound if sound data was found in the data folder.

# reimport-sounds-single <source-file> <compressor> <downmix> <-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)>
tool reimport-sounds "sound\dialog\combat" default downmix unit_dialog english
  • source-file - A local tag path to a sound tag without extension.
  • compressor - Specify the compressor (default, pcm, xma, xma2)
  • downmix - Down mix the adpcm sample (downmix). This is an optional argument
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Set sound class

Grabs all the sound tags in a directory and changes the class to whatever was specified by the user.

#  set-sound-class <source-directory> <path-spec> <new-sound-class>
tool set-sound-class sound_test ??? projectile_impact
  • source-directory - A local tag path to the root of a directory containing sound tags or child folders with sound tags.
  • path-spec - ???
  • new-sound-class - A sound class string.

Sound multi layer

Imports sound files in a directory with the import type set to multi-layer. All sound files the source directory and child directories will be combined into one sound file.

#  sound-multi-layer <source-directory> <type> [-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)]
tool sound-multi-layer "sound_test" projectile_impact sfx
  • source-directory - A local data path to a directory or child directories containing sound files. Supported extensions are WAV saved as 16 bit PCM and AIFF.
  • type - Set the sound class
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Sound single

Imports a single sound file

#  sound-single <source-file> <type> [-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)]
tool sound-multi-layer "sound_test\aiff" projectile_impact sfx
  • source-file - A local data path to the root of a directory containing sound files. Supported extensions are WAV saved as 16 bit PCM and AIFF.
  • type - Set the sound class
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Sounds one shot

Imports sound files in a directory with the import type set to single-shot. Each sound file will get its own sound tag.

#  sounds-one-shot <source-directory> <type> [-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)]
tool sounds-one-shot "sound_test" projectile_impact sfx
  • source-file - A local data path to the root of a directory or child directories containing sound files. Supported extensions are WAV saved as 16 bit PCM and AIFF.
  • type - Set the sound class
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Sounds single layer

Imports sound files in a directory with the import type set to single-layer. Each directory will get its own sound tag.

#  sounds-single-layer <source-directory> <type> [-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)]
tool sounds-single-layer "sound_test" projectile_impact sfx
  • source-file - A local data path to the root of a directory or child directories containing sound files. Supported extensions are WAV saved as 16 bit PCM and AIFF.
  • type - Set the sound class
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Sounds single mixed

Imports sound files in a directory with the import type set to single-layer. Each directory will get its own sound tag.

#  sounds-single-mixed <source-directory> <type> [-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)]
tool sounds-single-mixed "sound_test" projectile_impact sfx
  • source-file - A local data path to the root of a directory or child directories containing sound files. Supported extensions are WAV saved as 16 bit PCM and AIFF.
  • type - Set the sound class
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Sounds music

Generates an empty sound looping tag from the folders in data. Probably an error?

#  sounds-music <source-directory> <type> [-bank:suffix-where-suffix-is-a-fmod-bank-suffix-(optional)]
tool sounds-music "sound_test" projectile_impact sfx
  • source-file - A local data path to the root of a directory or child directories containing sound files. Supported extensions are WAV saved as 16 bit PCM and AIFF.
  • type - Set the sound class
  • bank - Specify the fmod soundbank that should contain this sound. This is an optional argument

Broken and development commands

Not all commands work or are of any use to anyone anymore. They are listed here for completeness but shouldn't be used.

  • faux-unit-tests - Unit tests for the lightmapping process. Currently these fail for an unknown reason but even if they succeeded they wouldn't be useful for end users.
  • dump-tag-table - Broken/doesn't do anything. Intended use is unknown.
  • cubemap-farm-new - This command does not work. Was intended to run a farm setup for generating cubemaps to be used by dynamic cubemap enabled shaders.
  • crash - Intentionally induces a crash to test the crash reporting subsystem. Crash types: test_fatal_error, assert, now and halt
  • progress-quest - Doesn't do anything other than display a progress bar.
  • old-physics - Doesn't do anything at all.
  • convert-tag-files-pilot - Doesn't work anymore as it tries to use a removed backend.
  • analyze-dvd-cache-files - HR no longer runs of a DVD.
  • build-cache-file-verify-dvd-layouts - ...
  • analyze-shader - Is meant to analyse shader performance but it doesn't work since it was designed for Xenon.
  • analyze-shaders - Runs out of 32-bit addressable memory and crashes.
  • faux_checkerboard- is meant to compile checkboard quality lightmaps but it crashes for unknown reasons.
  • export-structure-mesh - This command has not been updated for DX11. Avoid this command.
  • export-render-model-mesh - This command has not been updated for DX11. Avoid this command.
  • export-fmod-banks - FMOD banks are automatically updated so you shouldn't need to rebuild them.
  • dump-tag-file-index - creates a copy of the tag_database_index.dat, seems like a dev command but maybe could be used to index tags without using Guerilla?
  • convert-pc-bitmaps - Likely used when porting.

Convert tag files explicit pilot

Converts tags from one backend to another. E.g. loose tag files to the monolithic backend. Seems to crash, maybe will be fixed in the future. Likely not useful for non-devs.

# convert-tag-files-explicit-pilot <source-backend> <dest-backend> <optional:-tag-list>
tool convert-tag-files-explicit-pilot default monolithic_new ""

Dump binary

Dumps binary files to a C style array. Meant for developers.

# dump-binary <binary-file> <output-file>
tool dump-binary "C:\processed_pixel_data.bin" "C:\processed_pixel_data_output.txt"
  • binary-file - An absolute file path to a binary file with extension.
  • output-file - An absolute file path to an output location with filename and extension

Estimate overdraw threshold

Requires the shader compiler fix, but it's very useful seems to be designed for Xenon.

# estimate-overdraw-threshold <effect>
tool estimate-overdraw-threshold "objects\weapons\turret\flamethrower\fx\projectile"
  • effect - A local tag path to an effect tag without extension.

Export game variant settings

Takes a multiplayer_variant_settings_interface_definition tag and outputs some debug info in command prompt.

# export-game-variant-settings <tag-file>
tool export-game-variant-settings "multiplayer\game_variant_settings\slayer\slayer.multiplayer_variant_settings_interface_definition"
  • tag-file - A local tag path to a `multiplayer_variant_settings_interface_definition tag with extension.

Commands with unknown usage

Not much is know about these commands, if you know something let us know!

Analysis commands

Tool includes a few commands to analyze (memory usage, read time, GPU usage, etc) files and caches but these aren't very useful for modders.

Analyze cache file sharing

???

#  analyze-cache-file-sharing <starting-cache-file> <ending-cache-file>
tool analyze-cache-file-sharing
  • starting-cache-file - ???
  • ending-cache-file - ???

Analyze font

???

#  analyze-font <font-file>
tool analyze-font
  • font-file - ???

Analyze font table

???

#  analyze-font-table <font-table-to-analyze>
tool analyze-font-table
  • font-table-to-analyze - ???

Analyze fonts

Crashes

#  analyze-fonts
tool analyze-fonts

Analyze implicit sharing

???

#  analyze-implicit-sharing <tag-list>
tool analyze-implicit-sharing
  • tag-list - ???

Build animation database

???

# build-animation-database
tool build-animation-database

Build cache file generate DLC layout

Crashes

# build-cache-file-generate-dlc-layout <map-name> <platform> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-generate-dlc-layout "" pc
  • map-name - ???
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • dedicated-server - ??? This is an optional argument.
  • use-fmod-data - ??? This is an optional argument.

Build cache file generate main menu layout

Crashes

# build-cache-file-generate-main-menu-layout <map-name> <platform> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-generate-main-menu-layout "" pc
  • map-name - ???
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • dedicated-server - ??? This is an optional argument.
  • use-fmod-data - ??? This is an optional argument.

Build cache file generate new layout

Crashes

# build-cache-file-generate-new-layout <map-name> <platform> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-generate-new-layout "" pc
  • map-name - ???
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • dedicated-server - ??? This is an optional argument.
  • use-fmod-data - ??? This is an optional argument.

Build cache file language version optimizable use sharing

Crashes

# build-cache-file-language-version-optimizable-use-sharing <target-language> <minor-version-number> <scenario> <platform> <sound-config> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-language-version-optimizable-use-sharing english "" "levels\multi\chill\chill" pc
  • target-language - ???
  • minor-version-number - ???
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • sound-config - ???
  • dedicated-server - ???
  • use-fmod-data - ???

Build cache file language version sharing main menu

Crashes

# build-cache-file-language-version-sharing-main-menu <target-language> <minor-version-number> <scenario> <platform>
tool build-cache-file-language-version-sharing-main-menu english "" "levels\multi\chill\chill" pc
  • target-language - ???
  • minor-version-number - ???
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

???

# build-cache-file-link <scenario> <platform> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-link "levels\multi\chill\chill" pc
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • dedicated-server - ??? This is an optional argument
  • use-fmod-data - ??? This is an optional argument

Build cache file optimize

???

# build-cache-file-optimize <map-name> <platform>
tool build-cache-file-optimize "chill" pc
  • map-name - The filename of a map file located in your maps folder without extension
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file optimize post link

Crashes

# build-cache-file-optimize-post-link <map-name> <platform>
tool build-cache-file-optimize-post-link "chill" pc
  • map-name - The filename of a map file located in your maps folder without extension
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file pilot

Crashes

# build-cache-file-pilot <scenario> <platform>
tool build-cache-file-pilot "levels\multi\chill\chill" pc
  • scenario - A local tag path to a scenario tag without extension.
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file profile

???

# build-cache-file-profile <scenario>
tool build-cache-file-profile "levels\multi\chill\chill"
  • scenario - A local tag path to a scenario tag without extension.

Build cache file use sharing

crashes

# build-cache-file-use-sharing <scenario> <platform> <target-language> <minor-version-number> <sound-config> <dedicated-server-(optional)> <use-fmod-data-(optional)>
tool build-cache-file-use-sharing "levels\multi\chill\chill" pc
  • scenario - A local tag path to your scenario without the file extension
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument
  • target-language - ??? This is an optional argument
  • minor-version-number - ??? This is an optional argument
  • sound-config - ??? This is an optional argument
  • dedicated-server - ??? This is an optional argument
  • use-fmod-data - ??? This is an optional argument

Build cache file cache sounds index

???

# build-cache-file-cache-sounds-index <scenario> <append> <sound-configuration> <platform>
tool build-cache-file-cache-sounds-index
  • scenario - ??? This is an optional argument
  • append - ??? This is an optional argument
  • sound-configuration - ??? This is an optional argument
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Build cache file cache version

Build a cache files with a specific version

# build-cache-file-cache-version <minor-version-number> <platform>
tool build-cache-file-cache-version "" pc
  • minor-version-number - ??? This is an optional argument
  • platform - The platform this cache file is being built for. If nothing is set then it will default to pc. This is an optional argument

Cache asset depot thumbnails

???

#  cache-asset-depot-thumbnails <tag-file>
tool cache-asset-depot-thumbnails
  • tag-file - ???

Cache asset depot thumbnails from directory

???

#  cache-asset-depot-thumbnails-from-directory <tag-directory>
tool cache-asset-depot-thumbnails-from-directory
  • tag-directory - ???

Cache asset depot thumbnails list

???

#  cache-asset-depot-thumbnails-list <tag-list>
tool cache-asset-depot-thumbnails-list
  • tag-list - ???

Convert tiled tiff

???

# convert-tiled-tiff <input-tiff-file> <output-tiff-file>
tool convert-tiled-tiff "F:\masterchief.tiff" "F:\masterchief_output.tiff"
  • input-tiff-file - An absolute path to a tiff file.
  • output-tiff-file - An absolute path to a path with filename and extension to generate the output file in.

Create custom network hopper and variant files

???

# create-custom-network-hopper-and-variant-files <hopper-file>
tool create-custom-network-hopper-and-variant-files
  • hopper-file - ???

Create custom network hopper file

???

# create-custom-network-hopper-file <hopper-file>
tool create-custom-network-hopper-file
  • hopper-file - ???

Create custom network variant file

???

# create-custom-network-variant-file <variant-file> <output-directory>
tool create-custom-network-variant-file
  • variant-file - ???
  • output-directory - ???

Create network hopper file

???

# create-network-hopper-file
tool create-network-hopper-file

Dump cache resource gestalt

???

# dump-cache-resource-gestalt <cache-resource-gestalt>
tool dump-cache-resource-gestalt
  • cache-resource-gestalt - ???

Dump cache resource gestalt file locations

???

# dump-cache-resource-gestalt-file-locations <cache-resource-gestalt>
tool dump-cache-resource-gestalt-file-locations
  • cache-resource-gestalt - ???

???

# dump-gestalt-links <cache-resource-gestalt> <tag/resource-substring> <tag-type>
tool dump-gestalt-links
  • cache-resource-gestalt - ???
  • tag/resource-substring - ???
  • tag-type - ???

???

# dump-gestalt-links-from-file <cache-resource-gestalt> <file-of-tag/resource-substrings-(one-per-line)> <tag-type>
tool dump-gestalt-links
  • cache-resource-gestalt - ???
  • file-of-tag/resource-substrings - ???
  • tag-type - ???

Dump tiff to header

???

# dump-tiff-to-header <quantization-factor> <tiff-file> <constant-prefix-string> <output-file>
tool dump-tiff-to-header
  • quantization-factor - ???
  • tiff-file - ???
  • constant-prefix-string - ???
  • output-file - ???

Export windows font

???

# export-windows-font <output-directory> <font-file-(optional)> <typeface-name> <point-size>
tool export-windows-font
  • output-directory - ???
  • font-file - ???
  • typeface-name - ???
  • point-size - ???

Export xenon bitmap PFM

???

# export-xenon-bitmap-pfm <bitmap-tag> <output-path-prefix>
tool export-xenon-bitmap-pfm
  • bitmap-tag - ???
  • output-path-prefix - ???

Faux build linear textures-with intensity from quadratic

???

# faux-build-linear-textures-with-intensity-from-quadratic <scenario> <bsp-name>
tool faux-build-linear-textures-with-intensity-from-quadratic "levels\multi\example\example" "example"
  • scenario - A local tag path to a scenario without extension
  • bsp-name - The name of a BSP tag referenced by the scenario tag

Faux compress scenario bitmaps DXT5

???

# faux-compress-scenario-bitmaps-dxt5 <scenario> <bsp-name>
tool faux-compress-scenario-bitmaps-dxt5 "levels\multi\example\example" "example"
  • scenario - A local tag path to a scenario without extension
  • bsp-name - The name of a BSP tag referenced by the scenario tag

Faux farm compression merge

???

# faux-farm-compression-merge <scenario> <bsp-name>
tool faux-farm-compression-merge "levels\multi\example\example" "example"
  • scenario - A local tag path to a scenario without extension
  • bsp-name - The name of a BSP tag referenced by the scenario tag

Faux farm begin

???

# faux_farm_begin <scenario> <bsp-name> <light-group-name> <quality-setting> <job-id>
tool faux_farm_begin "levels\multi\example\example" "example" all direct_only 123
  • scenario - A local tag path to a scenario without extension.
  • bsp-name - The name of a BSP tag referenced by the scenario tag.
  • light-group-name - Only light a certain region of the level.
  • quality-setting - The quality used for lightmapping. The following are valid options:
    • direct_only
    • draft
    • debug
    • low
    • medium
    • high
    • super
  • job-id - A random value to use for the faux data.

Faux farm dillum

???

# faux_farm_dillum <blob-path> <client-index> <client-count>
tool faux_farm_dillum
  • blob-path - ???
  • client-index - ???
  • client-count - ???

Faux farm dillum merge

???

# faux_farm_dillum_merge <blob-path> <client-count>
tool faux_farm_dillum
  • blob-path - ???
  • client-count - ???