openra / openramodsdk

Software Development Kit for building your own games using the OpenRA engine.

OpenRA

A Libre/Free Real Time Strategy game engine supporting early Westwood classics.

• Website: https://www.openra.net
• Chat: #openra on Libera (web) or Discord
• Repository: https://github.com/OpenRA/OpenRA

Please read the FAQ in our Wiki and report problems at https://github.com/OpenRA/OpenRA/issues.

Join the Forum for discussion.

Play

Distributed mods include a reimagining of

• Command & Conquer: Red Alert
• Command & Conquer: Tiberian Dawn
• Dune 2000

EA has not endorsed and does not support this product.

Check our Playing the Game Guide to win multiplayer matches.

Contribute

• Please read INSTALL.md and Compiling on how to set up an OpenRA development environment.
• See Hacking for a (now very outdated) overview of the engine.
• Read and follow our Code of Conduct.
• To get your patches merged, please adhere to the Contributing guidelines.

Mapping

• We offer a Mapping Tutorial as you can change gameplay drastically with custom rules.
• For scripted mission have a look at the Lua API.
• If you want to share your maps with the community, upload them at the OpenRA Resource Center.

Modding

• Download a copy of the OpenRA Mod SDK to start your own mod.
• Check the Modding Guide to create your own classic RTS.
• There exists an auto-generated Trait documentation to get started with yaml files.
• Some hints on how to create new OpenRA compatible Pixelart.
• Upload total conversions at our Mod DB profile.

Support

• Sponsor a mirror server if you have some bandwidth to spare.
• You can immediately set up a Dedicated Game Server.

License

Copyright (c) OpenRA Developers and Contributors This file is part of OpenRA, which is free software. It is made available to you under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. For more information, see COPYING.

openramodsdk's Issues

Build of mod fails on Windows

Enter command: all
OpenRA engine version c9483448557d043e3d9b11e51274711910e11718 is required.
Downloading engine...
Move-Item : Das Argument kann nicht an den Parameter "Path" gebunden werden, da es NULL ist.
In D:\IronDominion\make.ps1:332 Zeichen:13
+         Move-Item $extractedDir.FullName -Destination $templateDir
+                   ~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Move-Item], ParameterBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.MoveItemCom
   mand

Rename-Item : Das Argument kann nicht an den Parameter "Path" gebunden werden, da es NULL ist.
In D:\IronDominion\make.ps1:333 Zeichen:15
+         Rename-Item $extractedDir.Name (Split-Path -leaf $env:ENGINE_ ...
+                     ~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidData: (:) [Rename-Item], ParameterBindingValidationException
    + FullyQualifiedErrorId : ParameterArgumentValidationErrorNullNotAllowed,Microsoft.PowerShell.Commands.RenameItemC
   ommand

cd : Der Pfad "D:\IronDominion\engine" kann nicht gefunden werden, da er nicht vorhanden ist.
In D:\IronDominion\make.ps1:337 Zeichen:3
+         cd $env:ENGINE_DIRECTORY
+         ~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : ObjectNotFound: (D:\IronDominion\engine:String) [Set-Location], ItemNotFoundException
    + FullyQualifiedErrorId : PathNotFound,Microsoft.PowerShell.Commands.SetLocationCommand

Version strings set to 'c9483448557d043e3d9b11e51274711910e11718'.
OpenRA engine version c9483448557d043e3d9b11e51274711910e11718 is required.
Downloading engine...

Scripts should die with a sensible error when required variables are missing

e.g. when the linux packaging scripts run with missing PACKAGING_APPIMAGE_* values.

SDK is targeting an older bleed commit

It is missing the CommandBarBlacklist and other commits that are in the playtest.

Add explicit GPLv3+ licence to project.

The project is implicitly GPL3 to match the rest of OpenRA, but we don't actually state this anywhere. This was a fairly major oversight.

Add a mod.config field defining files/dirs to copy when packaging.

This can default to the mods/common dir. This will provide a simple way to copy e.g. the d2k dll, modcontent files, or base ra/td/d2k mods for addon-style mods.

Remove surrounding quotes from MOD_ID via `tr`

MOD_ID = $(shell cat user.config mod.config 2> /dev/null | awk -F= '/MOD_ID/ { print $$2; exit }' | tr -d \")

Maybe use WAF build system?

• https://pypi.python.org/pypi/waftools
  Windows support would be hard implement using current Makefile and script system. I tried Babun to run them but it wasn't that simple. Since the SDK is meant to "build" things in order, I think we need a customizable build system that runs on both Windows and Linux to reduce the effort to keeping two build systems. I think WAF might be one candidate.

• It lets you use all the Python stuff, including os.path.exists(), ZIP archiving, os.system()

• It is a build framework that knows how to build things in dependency order.

• Installable on Windows (they say, haven't tried it yet)

• Supports invocation of another WAF build script, unifying packaging/package-all.sh, make.cmd, Makefile.

The down side is that WAF isn't popular on Linux and doesn't come by default. But mod Devs should be able to go through the installation!

fetch-engine ignores user.config

I deleted the engine folder.

Added a user.config with

AUTOMATIC_ENGINE_MANAGEMENT="False"

Linked my developed repository into the location:

ln -sf /home/matthias/Entwicklung/OpenRA /home/matthias/Entwicklung/ra2/engine

which was undone upon make:

OpenRA engine version e92e48e94c3f82e31ca9f835d10dd037337be53d is required.
Deleting engine version {DEV_VERSION}.

Port Contributing and Code of conduct guidelines from OpenRA/OpenRA

Add packaging scripts

Adapt https://github.com/pchote/OpenRA/tree/master/packaging, adapting the local make install logic to remove the default mods, and replacing the hardcoded OpenRA-esque values with variables in mod.config.

Windows packaging fails with mono 4.6.2.7+dfsg-1ubuntu1

error CS8001: Warning as Error: SDK path could not be resolved

This can be fixed by removing the -sdk:4.5 in https://github.com/OpenRA/OpenRAModSDK/blob/master/packaging/windows/buildpackage.sh#L65.

Update documentation

Having everything in README.md isn't good. The default readme should have just the basics for how to compile and run a template based mod. The documentation for creating and developing mods should be split off to either multiple md files in a docs directory, or to the wiki here.

We could also think about renaming "Mod Template" to "Mod SDK" as part of this, which sounds a bit more professional.

Using a non-standard engine path is tedious with csproj references

This also does not scale easily to multiple developers (unless we are going to tell them all to use the exact same file structure [without providing a tool that does this for them!] which is not good for UX).

INCLUDE_DEFAULT_MODS doesn't work reliably

See OpenRA/ra2#386 (comment). It might be that it only fails on Travis though, as it worked locally for me.

Package a "portable" windows distribution

Zip the build directory immediately before / after running makensis.

launch-game script fails on macOS with mono 5.2

Mono 5.2 changed the default mono command to default to 64 bit. We should run mono32 instead on macOS if it exists.

Package macOS releases as dmg

This is the expected convention and is much more polished than a zip file.

The issue is that mods will need to modify the .DS_Store to account for PACKAGING_DISPLAY_NAME, and we don't have a simple cross-platform way to do this.

ModSDK uses wget while engine's Makefile uses curl

I think ModSDK should use curl as well.

Make overwriting of mod.yaml version value by release tag optional.

It should be an optional setting if the SDK release tag should overwrite the mod.yaml version value. There are situations where you want to update your installers (and use a new sdk release version tag) but not update the mod version, for example if you change SDK code or add new icons you want a new SDK release tag but not update the mod servers to the new version.

MOD_ID should not be read from user.config as it is not a user-specific setting

ModSDK doesn't offer a practical solution towards mods with huge amount of noncopyleft assets.

As it stands, if a project decides to use the ModSDK to compile it's own releases, the modder have two choices.

1. Upload all of the assets as part of the mod to the ModSDK repository which will allow a script/CI (Travis assumed) to compile a standalone release.
2. Upload a skeleton mod which will be expanded with the content installer on the fly.

Do note that GitHub's EULA explicitly requires a project to apply an OS license to every file in a repository, which prevents solution 1 being applied to mods intending to go with nonfree assets + GPL codebase. Solution 2 is technically good for these projects, but that means that the project needs to provide a static direct link to the assets (something even ModDB doesn't provide) AND there is also the backside that the content installer places assets to very questionable places in the ecosystem.

package-all.sh output directory parameter is confusing

$ ./package-all.sh
Usage: package-all.sh version outputdir

outputdir is not created automatically and gives

mv: cannot move 'OpenRA.Setup.exe' to 'tmp/OverPoweredMod-r015.exe': No such file or directory

error instead.

Also, it seems that output dir needs to be absolute? Unless it is best to leave it as ./ so that the output is created as packaging/windows/OverPoweredMod-r015.exe. I find this one surprising as it is more common to have outputdir relative to where the script is invoked.

P.S, While I find the SDK has some rough the edges I think I like it. My mod was getting more and more difficult to distribute and install for the users. Great work!

Makefiles should gracefully ignore missing *.sln files

As part of the mod setup documentation we tell modders to delete ExampleMod.sln and related files if they do not plan on including any custom code. The makefiles unconditionally call msbuild/xbuild which then error out if there are no slns in the root directory. We should instead be checking that there is something to compile first.

Check if the engine version matches the one in mod.config before mod launch

The launch-game scripts have no version checks and might want to indicate a version mismatch (asking for a rebuild using make).

Next release notes

Saving some time for later. We also shouldn't forget to update mod.config to point at the new playtest tag.

The notes at the top of these pages should be removed:

• https://github.com/OpenRA/OpenRAModSDK/wiki/Updating-to-a-new-SDK-or-Engine-version
• https://github.com/OpenRA/OpenRAModSDK/wiki/Getting-Started

---

• Added Linux AppImage packaging
• Added checks for missing mod.yaml definitions and outdated engine files
• Added ability to customize the license text shown in the Windows installer
• Added ability to decouple the mod.yaml (in-game) version and packaging version
• Fixed an issue when mods contain symbolic links (note: this is not recommended)
• Improved support for shipping default-mod files in mod packages
• Added support for macOS 10.14 dark titlebars
• Updated default engine version to (TODO:)playtest-201807XX

This is a major update to the mod SDK. We recommend updating by making a backup of your mod.config and any custom icons you have set in the platform-specific packaging directories, and then overwriting all the SDK files in your project with the updated versions in this release. Replace the icons (and don't forget to add new icons for your Linux releases!) and mod.config file, and then make the following changes to your mod.config:

• In the Core Configuration section remove the INCLUDE_DEFAULT_MODS definition.
• In the Packaging section add the following definitions

  # Path to the file containing the text to show in the Windows installer license dialog
  PACKAGING_WINDOWS_LICENSE_FILE="./COPYING"
  
  # The git tag to use for the AppImage dependencies.
  PACKAGING_APPIMAGE_DEPENDENCIES_TAG="20180723"
  
  # Space delimited list of additional files/directories to copy from the engine directory
  # when packaging your mod. e.g. "./mods/modcontent" or "./mods/d2k/OpenRA.Mods.D2k.dll"
  PACKAGING_COPY_ENGINE_FILES=""
  
  # Overwrite the version in mod.yaml with the tag used for the SDK release
  # Accepts values "True" or "False".
  PACKAGING_OVERWRITE_MOD_VERSION="True"
  

  and change PACKAGING_OSX_LAUNCHER_TAG to osx-launcher-20180723.
• In the Advanced Configuration section add the following definitions

  # The url to download the OpenRA AppImage dependencies.
  PACKAGING_APPIMAGE_DEPENDENCIES_SOURCE="https://github.com/OpenRA/AppImageSupport/releases/download/${PACKAGING_APPIMAGE_DEPENDENCIES_TAG}/libs.tar.bz2"
  
  # Temporary file name used when downloading the OpenRA AppImage dependencies.
  PACKAGING_APPIMAGE_DEPENDENCIES_TEMP_ARCHIVE_NAME="libs.tar.bz2"
  

This SDK version remains compatible with OpenRA's engine version release-20180307. If you wish to update to take advantage of the improvements added in (TODO:)playtest-201807XX then you may now proceed to the Engine update guide.

"make check" fails on case sensitive file systems

"OpenRA.Mods.example" is not a valid directory.

The simplest solution would be to add a space delimited list of directories/project names to mod.config and then enumerate them from the Makefile / make.ps1.

Update macOS launcher package to the new tag.

Investigate whether the packaging scripts can run under cygwin

...without too much work or nastyness.

This might serve a useful stop-gap for windows-based people who don't want to / don't know how to work with Linux or github/travis auto-building.

Build system: Don't print success in the event of failure

The build target of the Makefile currently prints success regardless of {ms,x}build outcome:

OpenRAModSDK/Makefile

Line 58 in 4afe9d1

@find . -maxdepth 1 -name '*.sln' -exec printf "The mod logic has been built.\n" \;

Packing doesn't stop on error

The packaging encounters error but doesn't stop and continues to build as follows:

Building Windows package
Building core files
/bin/sh: mods/yupgi_alert/mod.yaml.tmp: No such file or directory
make: *** [Makefile:72: version] Error 1
Installing OpenRA engine to /home/ubuntu/mod/OpenRAModSDK/packaging/windows/build
Installing OpenRA common mod files to /home/ubuntu/mod/OpenRAModSDK/packaging/windows/build
cp: cannot stat 'yupgi_alert.ico': No such file or directory
Compiling Windows launcher
error CS7064: Error opening icon file `yupgi_alert.ico'. Could not find file "/home/ubuntu/mod/O
penRAModSDK/packaging/windows/yupgi_alert.ico".
Compilation failed: 1 error(s), 0 warnings                                                   
Unhandled Exception:                                                                         System.IO.FileNotFoundException: Could not find file "/home/ubuntu/mod/OpenRAModSDK/packaging/w$
ndows/build/Over Powered Mod.exe".
File name: '/home/ubuntu/mod/OpenRAModSDK/packaging/windows/build/Over Powered Mod.exe'
  at System.IO.FileStream..ctor (System.String path, System.IO.FileMode mode, System.IO.File$
ccess access, System.IO.FileShare share, System.Int32 bufferSize, System.Boolean anonymous, $
ystem.IO.FileOptions options) [0x0019c] in <73ee1b14c2fa4d61b481096ff3d8d6d7>:0
  at System.IO.FileStream..ctor (System.String path, System.IO.FileMode mode, System.IO.File$
ccess access, System.IO.FileShare share) [0x00000] in <73ee1b14c2fa4d61b481096ff3d8d6d7>:0
  at (wrapper remoting-invoke-with-check) System.IO.FileStream:.ctor (string,System.IO.FileM$
de,System.IO.FileAccess,System.IO.FileShare)
  at System.IO.File.OpenRead (System.String path) [0x00000] in <73ee1b14c2fa4d61b481096ff3d8$
6d7>:0
  at System.IO.File.ReadAllBytes (System.String path) [0x00000] in <73ee1b14c2fa4d61b481096ff
3d8d6d7>:0
  at fixheader.fixheader.Main (System.String[] args) [0x0000e] in <a45ea5af25b24d438b3ef44956
4ce093>:0

Ctrl+C is the only way to stop.

Automatically manage engine versions

Submodules are horrible to deal with even for experienced git users. We can and should do better:

Introduce new mod.config options:

• ENGINE_VERSION="<version string>"
• ENGINE_DIRECTORY="./engine"
• AUTOMATIC_ENGINE_MANAGEMENT="True"/"False"
• AUTOMATIC_ENGINE_SOURCE="https://github.com/OpenRA/OpenRA/archive/${ENGINE_VERSION}.zip"

Before compiling or running any of the launchers compare ENGINE_VERSION against ${ENGINE_DIRECTORY}/VERSION. If the version doesn't match:

If AUTOMATIC_ENGINE_MANAGEMENT="True":

• Delete current ${ENGINE_DIRECTORY}
• Download ${AUTOMATIC_ENGINE_SOURCE} and extract to ${ENGINE_DIRECTORY}
• Compile and make version the engine.
• Check ${ENGINE_VERSION} again, and fail with an error if it still doesn't match.

If AUTOMATIC_ENGINE_MANAGEMENT="False":

• Fail with an error telling the user to update the engine to ${ENGINE_VERSION}.

Depends on OpenRA/OpenRA#13443

NSIS packaging error

I'm using NSIS2 package from AUR, on Arch Linux:

$ bash packaging/package-all.sh r015 tmp
Building Windows package
Building core files
/bin/sh: mods/yupgi_alert/mod.yaml.tmp: No such file or directory
make: *** [Makefile:72: version] Error 1
Installing OpenRA engine to /home/arch/mod/SDK/packaging/windows/build
Installing OpenRA common mod files to /home/arch/mod/SDK/packaging/windows/build
Compiling Windows launcher
Building Windows setup.exe
CreateShortCut expects 2-8 parameters, got 10.
Usage: CreateShortCut shortcut_name.lnk shortcut_target [parameters [icon_file [icon index [showmode [hotkey [comment]]]]]]
showmode=(SW_SHOWNORMAL|SW_SHOWMAXIMIZED|SW_SHOWMINIMIZED)
hotkey=(ALT|CONTROL|EXT|SHIFT)|(F1-F24|A-Z)
Error in script "buildpackage.nsi" on line 103 -- aborting creation process
Windows package build failed.
Package build done.

• I have no idea where /bin/sh: mods/yupgi_alert/mod.yaml.tmp: No such file or directory is coming from. Is it safe to ignore?

--symlinks in Windows buildpackage.sh is a bug

In zip command to compress standalone zip file for windows, --symlinks is a bug.

I think it is there to make zip follow symlinks but it works the opposite:

   --symlinks
          For UNIX and VMS (V8.3 and later), store symbolic links as such in the zip archive, instead of compressing and storing the file referred to by the link.  This can avoid multiple copies of files being included in  the
          archive as zip recurses the directory trees and accesses files directly and by links.

make.ps1 is not compatible with powershell 2.0 on Windows 7

It appears that Add-Type is a PS >=3 feature, so the engine fetching fails when trying to import the compression method.

Some googling suggests the following as a compatible replacement:

[Reflection.Assembly]::LoadWithPartialName("System.IO.Compression.Filesystem")

Reported by @MustaphaTR on IRC, but unfortunately he "fixed" the issue by upgrading PS. We'll need to find someone else with an old system or set up a VM to test the fix.

Add support for user.config

People actively developing a mod may wish to customize their mod config without pushing those to the repository. The main example for this is having an external manually managed engine repository that is used to submit PRs upstream, while letting normal mod testers still use the automatic engine management.

This should be pretty easy: add user.config to .gitignore, and then source/parse it if it exists immediately after mod.config. Anything defined in user.config will override the same keys in mod.config.

Make.cmd error downloading engine.

Using the 20180307 SDK I get this error with make.cmd (downloading engine) following the guide compiling the example mod.

I encounter this error with any repository make.cmd attempting to download the engine. My OS is Win7 64-bit and I'm currently experiencing issues with folder renaming and moving which seem likely related and cause for the issue.

• added mod.config.zip

Add a packaging script for creating a portable package

Not everybody has the permissions to install new applications on his system or wants to install an application just for testing it. This could be a simple .zip of the windows version but it has to include all .dll.config and .exe.config files to run on linux.

user.config is ignored by the Makefile

SDK win-portable version crash

I get this crash by using the winportable version of my sdk mod on Windows 7, the fix was presented by @pchote and consisted on copying a file called OpenRA.Mod.exe.config into ShatteredParadise.exe.config

Target SDK release https://github.com/ABrandau/OpenRAModSDK/releases/tag/SP-Build-20180722

Date: 2018-07-22 20:34:12Z
Operating System: Windows (Microsoft Windows NT 6.1.7601 Service Pack 1)
Runtime Version: .NET CLR 4.0.30319.42000
Exception of type System.InvalidOperationException: Failed to initialize platform-integration library. Check graphics.log for details.
   en OpenRA.Game.Initialize(Arguments args)
   en OpenRA.Game.InitializeAndRun(String[] args)
   en OpenRA.WindowsLauncher.RunGame(String[] args)```

System.NotSupportedException: Se intentó cargar un ensamblado desde una ubicación de red, por lo que el ensamblado habría sido incluido en un espacio aislado de versiones anteriores de .NET Framework. Esta versión de .NET Framework no habilita la directiva CAS de forma predeterminada, por lo que esta carga puede ser peligrosa. Si esta carga no va a incluir el ensamblado en un espacio aislado, habilite el modificador loadFromRemoteSources. Vea http://go.microsoft.com/fwlink/?LinkId=155569 para obtener más información.
   en System.Reflection.RuntimeAssembly.nLoadFile(String path, Evidence evidence)
   en System.Reflection.Assembly.LoadFile(String path)
   en OpenRA.Game.Initialize(Arguments args)
System.NotSupportedException: Se intentó cargar un ensamblado desde una ubicación de red, por lo que el ensamblado habría sido incluido en un espacio aislado de versiones anteriores de .NET Framework. Esta versión de .NET Framework no habilita la directiva CAS de forma predeterminada, por lo que esta carga puede ser peligrosa. Si esta carga no va a incluir el ensamblado en un espacio aislado, habilite el modificador loadFromRemoteSources. Vea http://go.microsoft.com/fwlink/?LinkId=155569 para obtener más información.
   en System.Reflection.RuntimeAssembly.nLoadFile(String path, Evidence evidence)
   en System.Reflection.Assembly.LoadFile(String path)
   en OpenRA.Game.Initialize(Arguments args)

Icon specification for windows mod.ico is "hard coded"

It seems the mod icon, mod.ico is specified in packaging/windows/buildpackage.sh.
The problem is

• mod.ico is tracked by git, upstream.
• buildpackage.sh is tracked upstream too.

This could get troublesome if OpenRAModSDK gets updated and file merges should be kept minimal, preferably only in mod.config.

Enable Travis CI on the template

That could help with #11.

Make fails to remove VERSION file while deleting old engine

I can remove the file manually.

Add an install target to the Makefile

This will greatly simplify packaging for non-debian linux distros.

Explicitly require Python 3 in package-all.sh

The whole packaging process fails if one tool for one packaging method is missing

This is caused by commit 3b57ec1702e592a5e9ef34475fe1d067abcca227. Either skip the packaging method if a tool is missing and continue with everything else or provide a configuration option to disable packaging methods individually!

Dockerfile for windows compilation

This is the minimal build system for OpenRA engine and SDK.

python and python3 can be removed. libtolua-dev can be removed too I think. I haven't without it yet.

https://github.com/forcecore/OpenRAModSDK/blob/master/Dockerfile

Add a .deb packaging script.

For consistency with upstream releases.

Add a setting for windows installers to define a default start menu directory

The windows installer currently uses "OpenRA" as a default value for the start menu entry.

Unless this is intended, I would suggest to add a setting to define the default entry to mod.config.

Add an appimage packaging script

Appimages advertise cross-distro compatibility, so would bring a lot more value than individual distro packages like #19. I expect it will be easier to implement these first on the Mod SDK than for the main OpenRA project (which needs to worry about multiple mod launchers).

References:

• OpenRA/OpenRA#12257
• https://github.com/AppImage/AppImages/blob/master/recipes/meta/OpenRA.yml

Update documentation with examples of overlay mods and rule updates.