Utility

How to use OpenRA Utility

Linux users are normally familiar with the command line ("terminal" application). When OpenRA is installed in the classic way (in contrast to AppImage), simply add mono or mono --debug (additional information if something goes wrong) in front of all the following commands. The files are normally found in /usr/share/openra. cd to there instead. However, if the AppImage build is used, use the --utility argument to call the utility instead of the game. The [MOD] specifier mentioned below is not required for AppImage builds. Example:

./OpenRA-Red-Alert-x86_64.AppImage --utility --check-yaml /path/to/map-dir-or-file

Windows users should run cmd.exe. Simply double-clicking OpenRA.Utility.exe will not work as it is not a GUI-capable application. Navigate to your OpenRA directory with e. g. cd "Program Files" and cd OpenRA and then execute OpenRA.Utility.exe ra to see the help output showing all available arguments:

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-runtime-assemblies ASSEMBLY [ASSEMBLY ...]
  Check the runtime dependencies of the mod against a given whitelist of assembly (dll and exe) names and generate an error if any unlisted files are required.

  --check-sequence-sprites
  Check the 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 MarkDown format.

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

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

  --extract-language-strings
  Extract translatable strings that are not yet localized and update chrome layout.

  --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

  --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 MarkDown 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.

1. Get the palette of the game, e.g. Red Alert: OpenRA.Utility ra --extract temperat.pal
2. 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.
3. 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
4. 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.
5. OpenRA.Utility ra --shp YourImage0000.png