abcdefg30 edited this page Oct 24, 2016 · 144 revisions
Clone this wiki locally

OpenRA comes with a easy to understand ingame map editor. You can access it from the main menu: -> Extras -> Map Editor. With this tool you can create new or edit maps that already exist.


It has a drag and drop interface which should be intuitive. You can middle mouse drag to move and use the mouse wheel to zoom in and out.

Converting maps for the original games to the OpenRA map format

The OpenRA.Utility.exe command can be used to convert TD, RA and D2k maps to the OpenRA .oramap format. The syntax is as follows:

OpenRA.Utility.exe cnc --import-td-map filename.ini
OpenRA.Utility.exe ra --import-ra-map filename.ini
OpenRA.Utility.exe d2k --import-d2k-map TILESET

where TILESET is something like BLOXBASE.R8 (also see D2k Mission Map Tilesets).

The converted map will be saved in the current working directory as filename.oramap.

File Format

Maps are created with the .oramap extension by default. These files basically work as a ZIP archive with a custom file ending. You can open these files with an archive program. At minimum each map contains a map.bin containing the terrain and resource information in binary format as well as map.yaml which describes actor placement, weapon definitions, even override default game rules using all Traits. For missions you can use Map scripting powered by Lua.

As creating extremely customized maps is error prone there are some additional checks in place. You can use OpenRA.Utility.exe --check-yaml to run automated tests on it. If these fail, the game will not allow you to play the map to prevent crashes. While the engine progresses your map may become incompatible with the next release. Check the Map Upgrading Guide as OpenRA.Utility.exe provides a helper command to automate the porting as much as possible.

The map boundaries have to stay divisible by 8 and require an outer boundary that is inaccessible by the players (cordons). The size has no limits though extremely large maps degrade game performance and may make no sense gameplay wise.

Sharing is the central repository to upload and showcase custom maps. It is tied to the client and allows everyone who joins the game to download maps that have been shared there. Every time you make changes to a map, the numerical hash to uniquely identify it, will also be different to prevent desyncs.


Custom maps are stored in the user directories with sub-directories per mod. From playtest-20160403 onwards, another sub-directory per mod version is used to store the maps (e.g. My Documents\OpenRA\maps\ra\playtest-20160403).

  • Windows: My Documents\OpenRA\maps\
  • Mac OSX: ~/Library/Application Support/OpenRA/maps
  • Linux: ~/.openra/maps

An unzipped folder containing the necessary files will also work which is useful when the terrain editing is done and the text files are tweaked manually. When contributing maps to be distributed with the main game, only zip regular maps without custom rules. Otherwise the changes won't be visible in the revision control system. It is also suggested to avoid spaces in the map filename.

Singleplayer missions

Singleplayer missions will appear in the missions menu if they are specified in a mission group in one of the mission files referenced from mod.yaml and have the following set

Visibility: MissionSelector

Categories: Campaign

in their map.yaml.

Custom (third party) missions in standard mods are currently included in the unsorted catch-all "Missions" group. Support for custom campaigns will be added in a future release.

Singleplayer missions should include a custom map preview by including a 360 x 200px map.png file in the map package. Generic Allied and Soviet mission previews are included in the mods/ra/maps/allies-* and mods/ra/maps/soviet-* directories, respectively.

Creating previews from the TD campaign maps

  1. Use XCC Mixer to find and convert the wsa animation to a set of png files. They are located inside general.mix.
  2. Find the frames that correspond to the full map with and without the mission arrow, and open them in your image editor of choice.
  3. Select and erase black background from both images, and then copy the two layers into one image. Don't forget the two-px black region between Denmark and Germany!
  4. Correct the image's aspect ratio by rescale the image to 267 x 200px, and then increase the canvas width to 360px.
  • Extract the arrow images from the original (non-resized) imaged, copy to the resized image, and use the stretched-arrow layer as a guide to position the non-stretched arrows. Delete the stretched-arrow layer.
  • Export the preview to png, and save the source file (with layers for the background and arrows) in the artsrc directory.

See also