Skip to content

Getting Started

Jump to bottom Edit New page
Matthias Mailänder edited this page Nov 16, 2022 · 16 revisions

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 source code of 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.

The following steps outline how to create a mod based on Red Alert, with files for overriding the mod rules and weapons. This is illustrated with an example ratc mod that makes Tesla Coils fire lasers. Adapt as necessary for your own purposes.

  1. Download and extract a copy of the SDK template and follow the instructions above to build and test the example mod.
  2. Delete the mods/example and OpenRA.Mods.Example directories.
  3. Open ExampleMod.sln with a text editor and delete the Project() line referring to OpenRA.Mods.Example (line 4) and the EndProject line immediately after it (line 5).
  4. Create a new directory mods/ratc for your new mod files and copy mod.yaml and icon.png from engine/mods/ra to this new directory.
  5. Open mods/ratc/mod.yaml with a text editor and make the following changes:
    • In the Metadata section change Title to Red Alert (Tesla Coil Example) in the metadata section. Real mods should also change the Website and WebIcon32 definitions to your mod website and mod icon. icon.png in the mod directory should also be changed to match the file served by WebIcon32.
    • In the Packages section add a line $ratc: ratc. This tells the game that any file paths prefixed with ratc| refer to files in your mod directory. See the Mod Manifest wiki page for more details. Make sure your editor is configured to use tab indentation, which is the (non-standard for Yaml) default for OpenRA configuration files.
    • In the Rules section add a line ratc|rules.yaml at the bottom of the list. This tells the game what file to load your custom rule overrides from.
    • In the Weapons section add a line ratc|weapons.yaml at the bottom of the list. This tells the game what file to load your custom rule overrides from.
    • In the ModContent section update the mod title defined in InstallPromptMessage.
    • Define a new ModCredits section at the bottom of the file:
    ModCredits:
	ModCreditsFile: ratc|credits.txt
	ModTabTitle: Tesla Coil Example
    This enables a special tab in the OpenRA credits menu for your mod acknowledgements.
  6. Open mod.config with a text editor and make the following changes:
    • In the Core Configuration section:
      • Change the MOD_ID value to "ratc"
    • In the Packaging section:
      • Change the PACKAGING_COPY_ENGINE_FILES value to "./mods/modcontent ./mods/ra". This tells the SDK packaging script to copy the Content Installer and Red Alert mod files when packaging your mod for release.
      • Set PACKAGING_COPY_CNC_DLL to "True".
      • Real mods should also change PACKAGING_INSTALLER_NAME, PACKAGING_WEBSITE_URL, PACKAGING_AUTHORS, PACKAGING_WINDOWS_LAUNCHER_NAME, PACKAGING_WINDOWS_INSTALL_DIR_NAME, PACKAGING_WINDOWS_REGISTRY_KEY to appropriate values for your mod.
  7. Create a new text file mods/ratc/credits.txt and put your name or anything else you wish to show in the credits menu.
  8. Create a new text file mods/ratc/weapons.yaml and paste the following yaml definition: 
    TeslaLaser:
	ReloadDelay: 40
	Range: 7c512
	Report: tesla1.aud
	Projectile: LaserZap
   		Width: 85
   		HitAnim: burn-m
		ZOffset: 2047
	Warhead@1Dam: SpreadDamage
		Spread: 42
		Damage: 36000
		DamageTypes: Prone50Percent, TriggerProne, FireDeath
	Warhead@2Smu: LeaveSmudge
		SmudgeType: Scorch
		InvalidTargets: Vehicle, Structure, Wall, Trees, Husk
    to define the new laser weapon that the Tesla Coil will fire.
  9. Create a new text file mods/ratc/rules.yaml and paste the following yaml definition: 
    TSLA:
	Armament:
		Weapon: TeslaLaser
    to override the Tesla Coil weapon.
  10. Run the make script to rebuild the mod, and then run it again with the test argument to check for errors in your definitions.
  11. Try the changes in-game by running the launch-game script. The Telsa Coil should now fire lasers!

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 further changes that are explained in this video.

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.

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