Skip to content

Updating to a new SDK or Engine version

Jump to bottom Edit New page
Paul Chote edited this page Sep 23, 2018 · 37 revisions

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 :octocat: 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.
  1. 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
  1. Run the utility script (utility.cmd on Windows, utility.sh on macOS/Linux) with the --update-mod command. 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.

Update Notes

Please consult the following pages for instructions that must be manually followed before running the semi-automated yaml updater (step 6 above):

Add a custom footer
Add a custom sidebar
Clone this wiki locally