Ringtool¶

ringtool.exe is Ringworld's command line tool. It builds maps like the stock tool.exe, and also extracts maps, compiles scripts and adds Ringworld's shaders to the game's shader files.

Warning

Ringtool is experimental and may have problems. Keep backups of your tags and maps, and check the maps it builds before sharing them.

ringtool <command> [parameters...]

Running it without a command prints the list of commands.

Several commands take a <tags-directories> parameter. It is a list of tags folders separated by ;, highest precedence first: a tag is taken from the first folder that has it, so a folder with a few modified tags can be placed in front of a full tags folder:

ringtool build-cache "my_mod_tags;tags" levels\test\bloodgulch\bloodgulch bloodgulch.map

Maps¶

build-cache¶

ringtool build-cache <tags-directories> <scenario-path> <output-map> [--tag-order <map-file or tag-order.json>] [--allow-missing] [--checksum <map-file or hex value>]

Builds a map from a scenario. Tags are processed the same way tool.exe processes them, and the map is marked as a Ringworld map. Problems that make tool.exe refuse a tag are reported as warnings instead of stopping the build.

--tag-order puts the tags in the same order as another map, given as a map file or a file written by export-tag-order. A modded map built this way stays compatible over the network with players and servers that have the original.
--allow-missing lets the build continue when a tag of the reference order is missing. It needs --tag-order.
--checksum makes the built map have the checksum of another map, or the given hexadecimal value.

extract-map¶

ringtool extract-map <map-file> <output-tags-dir>

Extracts every tag of a Custom Edition or Ringworld map into a tags folder. The extracted tags can be built into a map again with build-cache.

export-tag-order¶

ringtool export-tag-order <map-file> <output.json>

Writes the tag order of a map to a JSON file for build-cache --tag-order.

load-scenario¶

ringtool load-scenario <tags-directories> <scenario-path>

Loads a scenario the way the game does with -tags, and lists the tags that loaded and the ones that failed. Useful to check a scenario before building it.

load-tag¶

ringtool load-tag <tags-directories> <group-fourcc> <tag-path>

Loads a single tag and its references.

Scripts¶

compile-scripts¶

ringtool compile-scripts <tags-directories> <scenario-path> [--data <data-directory>]

Compiles the scripts of a scenario and saves them in the scenario tag, in the first tags folder. With --data, the script sources are read from <data-directory>\global_scripts.hsc and from the scripts folder of the scenario inside the data folder.

verify-scripts¶

ringtool verify-scripts <tags-directories> <scenario-path> <map-file>

Compiles the scripts of a scenario and compares the result with the scripts of a built map. Exits with 0 when they are identical.

Shaders¶

The game reads its pixel shaders from shaders\EffectCollection_ps_*.enc and its vertex shaders from shaders\vsh.enc. These commands add Ringworld's shaders to those files.

update-effect-collection¶

ringtool update-effect-collection <effect-collection-file> <output-file>

Adds Ringworld's pixel shaders to an effect collection: HUD meters, transparent generic shaders, the model shader extension and the fog screen.

Warning

Do not run it under Wine. The shader compiler there produces broken HUD meter shaders.

update-vertex-shaders¶

ringtool update-vertex-shaders <vsh-file> <output-file>

Adds the vertex shaders of the model shader extension.

Installation¶

install-loader¶

ringtool install-loader <exe-file>

Patches haloce.exe or haloceded.exe so that it loads ringloader.dll at startup. The original is saved as <exe-file>.bak the first time. Signed executables are refused, and an executable that is already patched is left alone.