Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
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
mod.config(you will need it), then change it to the new engine version that you want to update to.
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
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).
--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.