Updating to a new SDK or Engine version
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:
- 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. - 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 mergeunless you are experienced with Git and resolving merge conflicts. - Take note of the current value of the
ENGINE_VERSIONsetting inmod.config(you will need it), then change it to the new engine version that you want to update to. - Run
make/make.cmdto fetch and compile the new engine version.
| 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. |
- 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.
| Also read the Changelog for the engine release, paying close attention to any warnings or instructions in the "Engine" and/or "Modding" sections |
- Run the
utilityscript (utility.cmdon Windows,utility.shon macOS/Linux) with the--update-modcommand. This will output a list of Update Paths, for example:
$ ./utility.sh --update-mod
--update-mod SOURCE [--detailed] [--apply] [--skip-maps]
Valid sources are:
Update Paths:
release-20171014
release-20180218
release-20180307
Individual Rules:
... (more lines omitted) ...
If this list does not include your previous ENGINE_VERSION then you may be trying to update over too many versions in one step. If this is the case, try updating to an older intermediate release first. If you are basing your mod on a custom engine version or OpenRA's bleed branch then you will need to apply the appropriate Individual Rules one by one (and we assume you already know how to do this).
Run the --upgrade-mod command again, now specifying your previous ENGINE_VERSION to see a list of the semi-automated update rules that will be applied. Include the --detailed flag if you want to see more information. For example:
$ ./utility.sh --update-mod release-20180307 --detailed
Found 16 API changes:
* RemoveTerrainTypeIsWaterFlag: Remove TerrainType IsWater flag
The IsWater flag on terrain type definitions has been unused for some time.
This flag has now been removed from the tileset yaml.
* DefineSquadExcludeHarvester: Add harvesters to ExcludeFromSquads
HackyAI no longer automatically excludes actors with Harvester trait from attack squads.
They need to be explicitly added to ExcludeFromSquads. HackyAI instances are listed for inspection.
... (more lines omitted) ...
Read through the details, and if you are happy with them you can apply them by running the command again with the --apply flag. When prompted, press y to confirm:
$ ./utility.sh --update-mod release-20180307 --apply
WARNING: This command will automatically rewrite your mod rules.
We strongly recommend that you have a backup of your mod rules, and
for best results, to use a Git client to review the line-by-line
changes and discard any unwanted side effects.
Press y to continue, or any other key to cancel: y
RemoveTerrainTypeIsWaterFlag: Remove TerrainType IsWater flag
Updating mod... COMPLETE
Updating system maps... COMPLETE
DefineSquadExcludeHarvester: Add harvesters to ExcludeFromSquads
Updating mod... COMPLETE
Updating system maps... COMPLETE
... (more lines omitted) ...
AddEditorPlayer: Add EditorPlayer
Updating mod... COMPLETE
Updating system maps... COMPLETE
Manual changes are required to complete this update:
* The map editor now requires an EditorPlayer actor.
Please add an EditorPlayer with the traits AlwaysVisible and Shroud to player.yaml
(or a different rules yaml file of your choice).
... (more lines omitted) ...
The utility will run through each rule in turn and update your mod yaml. Some of the rules require manual changes, which are described in the command output. For convenience, this output is also written to an update.log file in your mod directory. Follow these instructions to complete the update to the new engine version.
Please consult the following pages for instructions that must be manually followed before running the semi-automated yaml updater (step 6 above). The changes for individual playtests leading up to a release are typically included in that releases notes.