Getting Started

The OpenRA Mod SDK includes an example mod that demonstrates the environment. As a first step, you should try building and running this mod to make sure that everything is working before you change anything to suit your mod.

1. Download the latest version of the SDK from the Releases page or using your git client. We recommend that you always use the latest tagged release, as the master branch may have incomplete or insufficiently tested changes.
2. Compile the example mod. If you are on Windows then double click make.cmd and then type all when you are presented with the list of commands. If you are on macOS or Linux then open terminal in the root of the SDK directory and then run make.
3. Run the example mod. If you are on Windows then double click launch-game.cmd. If you are on macOS or Linux then open terminal in the root of the SDK directory and then run ./launch-game.sh. The example mod should show a grey "Quit" button on a black screen.

Unfortunately, the example mod is missing many of the core definitions that are required for a basic game. We hope to eventually change this, but for now the best approach to creating a new mod is to copy and then adapt/replace parts from one of the official OpenRA mods.

• Delete the mods/example directory.
• Choose one of the default OpenRA mods to use as a base for your mod. In this example we will assume you are copying cnc.
• Choose a new internal name / id for you mod. In this example we will assume you are using mynewmod.
• Copy engine/mods/cnc to mods/mynewmod.
• Open mods/mynewmod/mod.yaml and make the following changes:
  • In the Metadata section set your mod title and version.
  • In the Packaging section replace $cnc: cnc with $mynewmod: mynewmod. This tells OpenRA that the explicit mount mymod should refer to the root of your mod package (see Mod manifest).
  • Change all lines that start with cnc| to mynewmod|. This updates the explicit mount references to account for the change that you have just made above.
• Open mod.config and replace MOD_ID="example" near the top of the file with MOD_ID="mynewmod".

You should now have a functioning stand-alone clone of the cnc mod that you can adapt / replace piece by piece with your own project.

If you don't plan on including any custom C# logic in your mod then you should delete ExampleMod.sln and the OpenRA.Mods.Example directory. If you do plan on including custom logic, then you will need to make some futher changes:

• TODO: Explain updating the GUIDs, project name, and changing the build output to mods/mynewmod/
• TODO: Explain how to customize a new C# library to reference the engine and output files to the correct location.

If you would like to adapt an existing mod to the SDK, then the steps are largely the same as above. Copy your mod files to the SDK mod directory, and if you have custom code copy these files to the root of the repository. The main difference is that you may need to update your mod to be compatible with the latest engine release. If your mod already targets bleed then you probably already know how to do this; just update ENGINE_VERSION in mod.config to reference the upstream commit that you are targeting and you should be set. Otherwise, see Updating to a new SDK or Engine version for instructions on how to update your mod to to the latest engine.