Basic command-line skills are helpful in Halo modding. Tool and some community tools like Invader are used via a command-line interface. In a CLI, you type commands into a shell window which runs programs and displays their output. CLIs may seem a bit intimidating compared to GUIs, but they allow you to easily share commands and output as text and run them in scripts for repetitive tasks.
Much like an Explorer window, Command Prompt always has a current directory. For most purposes you'll want the current directory to be one of your mod tools installations, where
tool.exe is found. The easiest way to open Command Prompt this way is to navigate to your mod tools installation in Explorer (Steam can do it) and type
cmd into the navigation bar. Alternatively, some modders copy
C:\Windows\System32\cmd.exe into their mod tools directory and launch it from there. You can confirm that the correct current directory is shown at the start of the prompt line.
Commands are entered in the form
<program> <arguments>. Command Prompt will first look in the current directory for the program you want to run, and the
.exe extension is optional. To run Tool commands, type them into the prompt and hit Enter. For example, to build the tutorial map for H1:
tool build-cache-file levels\test\tutorial\tutorial
The arguments then tell Tool what to do, and are documented per-game (e.g. H1 Tool). Programs and each argument are always separated by spaces. If a single argument contains spaces you need to wrap it with quotes:
dir command to list files in the current directory, and
cd <path> to navigate to a different one. The parent directory can be referred to using
... Sub-directories are always separated with backslashes.
dir cd "C:\Program Files (x86)\Microsoft Games\Halo Custom Edition" cd tags cd ..\data
If you need to switch to a different physical drive, enter the drive letter followed by a colon like:
D:. You can always open an Explorer window at the working directory by entering
You can automate a series of frequently run commands by putting them as multiple lines in a
.bat file, which you can create with notepad. Suppose you were quickly iterating on your level's BSP and created a file
REM Comment lines begin with "REM ". REM Import and light the level: tool structure levels\test\tutorial tutorial tool lightmaps levels\test\tutorial\tutorial tutorial 0 0.6 REM Launch Standalone: halo_tag_test.exe
Then you just need to double-click the file in Explorer, or enter
import_level.bat in Command Prompt and it will perform these steps for you. Don't forget that you can also have Standalone automatically run console commands on startup by creating an
init.txt file with one command per line.
It was mentioned earlier that Command Prompt first looks in the current directory for the program you want to run, and this isn't the only place it looks. If you wish to keep tools like Invader in a separate location from the mod tools, but still want to be able to run its executables like
invader-extract from any current directory, you can include the location of its executables in the system PATH environment variable, for which there are plenty of online guides. This is a list of directories where Windows will search for executables you want to run.
PowerShell is a newer Windows shell which was intended to improve upon Command Prompt. For the purposes of Halo modding, you would use it very similarly to Command Prompt, though it has a few small differences:
- When running a program in the current directory, prefix it with
.\and include the extension like
- You can switch drives using
In the rare case you're using the HEK on Linux, you probably already know what you're doing, but here are some tips for working under this setup specifically.
Since we are mainly interested in running Halo and HEK programs like Tool, which are Windows programs, you will need to set up Wine to run them on Linux. This page will not cover how to install and use Wine, but to run an EXE program you will need to invoke it like so:
# Assuming tool.exe is in the CWD: wine tool.exe build-cache-file levels\\test\\tutorial\\tutorial
Because tool.exe is a Windows program, it expects paths with Windows directory separators (backslashes). However, in Bash the backslash has special meaning and must be escaped. In other words, use double backslashes where you would normally use a single one.
Scripting is also possible. Here's an example,
set -e wine tool.exe structure levels\\test\\tutorial tutorial wine tool.exe lightmaps levels\\test\\tutorial\\tutorial tutorial 0.8 0.6 wine tool.exe build-cache-file levels\\test\\tutorial\\tutorial wine haloce.exe
Run this script with the command
sh compile-map.sh and it will compile, light, and build the map for you, then launch the game.