Utility

How to use OpenRA Utility

The utility contains a set of console-run tools and is included inside every release.

Windows

Navigate to your OpenRA directory, press ⇧ and right-click: choose Open PowerShell window here. Type in .\OpenRA.Utility.exe to see a help screen.

MacOS

The Utility launcher is located in /Applications/[MOD].app/Contents/MacOS/Utility. To launch it you will need to use the Terminal command line application. Once open, you will need to set the working directory to the Utility's location. It is achieved via the cd [FOLDER] command. To avoid manually writing the folder path, in Terminal type cd , in Finder navigate to in-game files and drag and drop the folder named MacOS onto the Terminal window. Then to launch the Utility just type ./Utility, you'll see the help output showing all available arguments.

Linux

On a distribution installation, navigate to /usr/lib/openra and run ./OpenRA.Utility in a terminal window to see a set of instructions.

When downloading an AppImage run ./OpenRA-Red-Alert-x86_64.AppImage --utility in a terminal, but note that you don't have to specify the mod as a first parameter then.

List of commands

Run `OpenRA.Utility.exe [MOD]` to see a list of available commands.
The available mods are: all, cnc, d2k, modcontent, ra, ts

  --argb2hex 
  Convert a,r,g,b legacy colors into hex colors

  --check-conditional-trait-interface-overrides 
  Check for incorrect interface overrides in conditional traits defined in all assemblies referenced by the specified mod.

  --check-explicit-interfaces 
  Check for explicit interface implementation violations in all assemblies referenced by the specified mod.

  --check-missing-sprites 
  Check tileset and sequence definitions for missing sprite files.

  --check-yaml [MAPFILE]
  Check a mod or map for certain yaml errors.

  --clear-invalid-mod-registrations (system|user|both)
  Removes invalid metadata entries for the in-game mod switcher.

  --debug-chrome-regions IMAGE ZOOM
  Write a html page showing mapped chrome images.

  --docs [VERSION]
  Generate trait documentation in JSON format.

  --dump-sequence-sheets PALETTE TILESET-OR-MAP
  Exports sequence texture atlas as a set of png images.

  --emmy-lua-api 
  Generate EmmyLua API annotations for use in IDEs.

  --extract 
  Extract files from mod packages to the current directory

  --import-ra-map FILENAME
  Convert a legacy Red Alert INI/MPR map to the OpenRA format.

  --import-td-map FILENAME
  Convert a legacy Tiberian Dawn INI/MPR map to the OpenRA format.

  --import-ts-map FILENAME
  Convert a Tiberian Sun map to the OpenRA format.

  --list-installshield ARCHIVE.Z
  Lists the content ranges for a InstallShield V3 file

  --list-installshield-cab DATA.HDR
  Lists the filenames contained within an Installshield CAB volume set

  --list-mix ARCHIVE.MIX MIXDATABASE.DAT
  Lists the content ranges for a mix file

  --list-mscab ARCHIVE.CAB
  Lists the filenames contained within a MSCAB file

  --lua-docs 
  Generate Lua API documentation in MarkDown format.

  --man-page 
  Create a man page in troff format.

  --map-hash MAPFILE
  Generate hash of specified oramap file.

  --map-rules MAPFILE
  Merge custom map rules into a form suitable for including in map.yaml.

  --png SPRITEFILE PALETTE [--noshadow] [--nopadding]
  Convert a shp/tmp/R8 to a series of PNGs, optionally removing shadow

  --png-sheet-export PNGFILE
  Export png metadata to yaml

  --png-sheet-import PNGFILE
  Import yaml metadata to png

  --refresh-map MAP
  Opens and resaves a map to reformat map.yaml and regenerate the preview.

  --register-mod LAUNCHPATH (system|user|both)
  Generates a mod metadata entry for the in-game mod switcher.

  --remap SRCMOD:PAL DESTMOD:PAL SRCSHP DESTSHP
  Remap SHPs to another palette

  --replay-metadata REPLAYFILE
  Print the game metadata from a replay file.

  --resize-map MAPFILE WIDTH HEIGHT
  Resize the map at the bottom corners.

  --resolved-rules ACTOR [PATH/TO/MAP]
  Display the finalized, merged MiniYaml rules for the given actor. Input values are case-sensitive.

  --resolved-sequences IMAGE-NAME [PATH/TO/MAP]
  Display the finalized, merged MiniYaml sequence tree for the given image. Input values are case-sensitive.

  --resolved-weapons WEAPON [PATH/TO/MAP]
  Display the finalized, merged MiniYaml tree for the given weapon. Input values are case-sensitive.

  --rgba2hex 
  Convert r,g,b[,a] triples/quads into hex colors

  --rules-import RULES.INI ART.INI
  Convert ART.INI and RULES.INI to the OpenRA rules definition format.

  --sequence-import FILENAME
  Convert ART.INI to the OpenRA sequence definition format.

  --settings-docs [VERSION]
  Generate settings documentation in markdown format.

  --shp PNGFILE [PNGFILE ...]
  Combine a list of PNG images into a SHP

  --sprite-sequence-docs [VERSION]
  Generate sprite sequence documentation in JSON format.

  --tileset-import FILENAME TEMPLATEEXTENSION [TILESETNAME]
  Convert a legacy tileset to the OpenRA format.

  --unregister-mod (system|user|both)
  Removes the mod metadata entry for the in-game mod switcher.

  --update-map MAP SOURCE [--detailed] [--apply]
  Updates a map to the latest engine version. SOURCE is either a known tag or the name of an update rule.

  --update-mod SOURCE [--detailed] [--apply] [--skip-maps]
  Updates a mod to the latest version. SOURCE is either a known tag or the name of an update rule.

  --weapon-docs [VERSION]
  Generate weaponry documentation in JSON format.

  --zbstudio-lua-api 
  Generate ZeroBrane Studio Lua API and auto-complete descriptions.

How to convert an icon with OpenRA Utility

The procedure is not very complicated, though there are quirks due to the nature of the SHP format.

Get the palette of the game, e.g. Red Alert: OpenRA.Utility ra --extract temperat.pal
Extract the SHP file you want to edit or use as a template from the .MIX archives: OpenRA.Utility ra --extract ttnkicon.shp with ttnkicon.shp beeing the cameo for the tesla tank.
Get a PNG file with the right palette settings by extracting it using the right palette setting: OpenRA.Utility ra --png ttnkicon.shp temperat.pal
Use Photoshop, Paint.NET, GIMP (or any other program that uses the palette formats) to open the newly created ttnkicon.png and save the color table of the picture or edit the PNG file right here. If you want to start from scratch be sure convert your PNG format to 8bit/channel, using the custom palette saved before otherwise the in-game result will be pixel garbage.
OpenRA.Utility ra --shp YourImage0000.png