Updating to a new SDK or Engine version

‼️ Attention ‼️
The instructions on this page refer to features that will not be available until the next official OpenRA playtest. We recommend that you wait for this to be publicly available before attempting to update your mod.

Building your mod against the Mod SDK ensures that new OpenRA releases will not break your mod – your project maintains its own version of the game engine, and you are free to update it (or not) on your own schedule.

The Mod SDK template will be updated periodically to target newer OpenRA engine versions or add new features. Follow the steps below if you want to update your mod to take advantage of the features and fixes available in newer OpenRA releases:

1. Make sure you have a backup of your project. If something goes wrong you may end up with a corrupted mod. We recommend that you use Git and GitHub to manage your mod development.
2. Check for new versions of the Mod SDK on the Releases page, and follow the instructions in the release notes to overwrite or edit any changed files. We recommend that you update the files directly, and do not use git merge unless you are experienced with Git and resolving merge conflicts.
3. Take note of the current value of the ENGINE_VERSION setting in mod.config (you will need it), then change it to the new engine version that you want to update to.
4. Run make / make.cmd to fetch and compile the new engine version.
   
   

⚠️ Warning ⚠️
If your mod contains custom C# code, API or trait changes may prevent your mod DLL from compiling. Consult the Changelog, Update Notes, and engine source code to identify what changed, then adapt your custom code to work with the new version.

5. Read the Update Notes below for the engine version that you are updating to (and any versions you may have skipped in between). These instructions will describe any manual changes that you must make to your mod files before running the semi-automated updater.

⚠️ Warning ⚠️
Also read the Changelog for the engine release, paying close attention to any warnings or instructions in the "Engine" and/or "Modding" sections

6. Run the utility script (utility.cmd on Windows, utility.sh on macOS/Linux) with the --update-mod command.

in your mod project, and then Use OpenRA.Utility.exe's --upgrade-mod command to automatically update your mod rules for most of the changes in the new engine. Pay close attention to any error messages, you may need to manually change some of your rules before or after the utility successfully completes.

Update Notes