Getting Started

‼️ Attention ‼️
The instructions on this page refer to features that will not be available until the next official OpenRA playtest. Refer to the original version of this page for instructions on the current release.

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.

Creating an "overlay" style mod

The simplest type of OpenRA mod inherits an already existing mod, and then changes it by overlaying custom rule (or weapon, ui, etc) overrides to change or add new units, weapons, or behaviour. This is very similar to custom map overrides, but applies automatically to all maps, and allows for more parts of the game to be changed.

We strongly recommend that all projects which want to customize the default Red Alert, Tiberian Dawn, Dune 2000, or Tiberian Sun mods follow this approach rather than creating a stand alone mod. This minimizes the amount of work that you will need to do when updating your mod to a new engine release, as you will only need to update your custom overrides.

• TODO: Explain all the steps.

Creating a stand-alone mod

More ambitious projects (e.g. porting a non-C&C game, or creating your own from scratch) are not recommended for new modders, and should only be attempted once you are familiar with how the OpenRA engine works and the process for updating to new engine releases.

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 one of the default mods and then replace piece-by-piece the default rules with your own content.

The following steps outline how to clone the cnc mod to create your own SDK-hosted cncex mod. This example assumes that your mod does not require any custom C# code. Adapt as necessary for your own purposes.

1. Delete the mods/example directory to remove the example mod.
2. Delete the OpenRA.Mods.Example directory and ExampleMod.sln file to remove the custom mod code.
3. Delete or adapt README.md, CONTRIBUTING.md, and CODE_OF_CONDUCT.md as appropriate for your own mod.
4. Make a copy of the base cnc mod from engine/mods/cnc to mods/cncex. This assumes that you ran the make command before you started!
5. Open mods/cncex/mod.yaml and make the following changes:
   • In the Metadata section set your mod title, version, website, and web icon.
   • In the Packaging section replace $cnc: cnc with $cncex: cncex. This tells OpenRA that the explicit mount cncex should refer to the root of your mod directory instead of the default cnc mod (see Mod manifest), which is not available by default from the SDK.
   • Change all lines that start with cnc| to cncex|. This updates the explicit mount references to account for the change that you have just made above.
6. Open mod.config and make the following change:
   • Replace MOD_ID="example" near the top of the file with MOD_ID="cncex". If you plan on creating proper installers for you mod then you should read through the "Packaging" section and make changes as appropriate.
7. Rebuild your mod by running the make command again, and then test your newly-cloned mod by running launch-game.

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.