diff --git a/OpenRA.Mods.Example.sln b/OpenRA.Mods.Example.sln new file mode 100644 index 0000000..22d1d11 --- /dev/null +++ b/OpenRA.Mods.Example.sln @@ -0,0 +1,17 @@ + +Microsoft Visual Studio Solution File, Format Version 12.00 +# Visual Studio 2012 +Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OpenRA.Mods.Example", "OpenRA.Mods.Example\OpenRA.Mods.Example.csproj", "{4E5B38F7-4E99-4C92-BB39-9100CC7F3829}" +EndProject +Global + GlobalSection(SolutionConfigurationPlatforms) = preSolution + Debug|x86 = Debug|x86 + Release|x86 = Release|x86 + EndGlobalSection + GlobalSection(ProjectConfigurationPlatforms) = postSolution + {4E5B38F7-4E99-4C92-BB39-9100CC7F3829}.Debug|x86.ActiveCfg = Debug|x86 + {4E5B38F7-4E99-4C92-BB39-9100CC7F3829}.Debug|x86.Build.0 = Debug|x86 + {4E5B38F7-4E99-4C92-BB39-9100CC7F3829}.Release|x86.ActiveCfg = Release|x86 + {4E5B38F7-4E99-4C92-BB39-9100CC7F3829}.Release|x86.Build.0 = Release|x86 + EndGlobalSection +EndGlobal diff --git a/OpenRA.Mods.Example/OpenRA.Mods.Example.csproj b/OpenRA.Mods.Example/OpenRA.Mods.Example.csproj new file mode 100644 index 0000000..14e9356 --- /dev/null +++ b/OpenRA.Mods.Example/OpenRA.Mods.Example.csproj @@ -0,0 +1,75 @@ + + + + Debug + x86 + {4E5B38F7-4E99-4C92-BB39-9100CC7F3829} + Library + OpenRA.Mods.Example + OpenRA.Mods.Example + v4.5 + + + true + full + DEBUG;TRACE + x86 + prompt + bin\Debug\ + AllRules.ruleset + true + + + true + bin\Release\ + TRACE + true + pdbonly + x86 + prompt + AllRules.ruleset + true + + + + + + + ..\engine\thirdparty\download\Eluant.dll + False + + + ..\engine\OpenRA.Game.exe + False + + + ..\engine\mods\common\OpenRA.Mods.Common.dll + False + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/OpenRA.Mods.Example/Widgets/Logic/TemplateMenuLogic.cs b/OpenRA.Mods.Example/Widgets/Logic/TemplateMenuLogic.cs new file mode 100644 index 0000000..9af34fe --- /dev/null +++ b/OpenRA.Mods.Example/Widgets/Logic/TemplateMenuLogic.cs @@ -0,0 +1,25 @@ +#region Copyright & License Information +/* + * Copyright 2007-2017 The OpenRA Developers (see AUTHORS) + * 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. + */ +#endregion + +using OpenRA.Widgets; +using OpenRA.Mods.Common.Widgets; + +namespace OpenRA.Mods.Example.Widgets.Logic +{ + public class TemplateMenuLogic : ChromeLogic + { + [ObjectCreator.UseCtor] + public TemplateMenuLogic(Widget widget, World world, ModData modData) + { + widget.Get("QUIT_BUTTON").OnClick = Game.Exit; + } + } +} diff --git a/README.md b/README.md index f24b8ca..f6a5c4b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,45 @@ # OpenRA Mod Template This repository contains a bare development environment for creating a new mod/game on the [OpenRA](https://github.com/OpenRA/OpenRA) engine. + +### Creating a new mod + +The `example` mod included in this repository provides the bare minimum structure to launch to the in-game main menu for the sole purpose of demonstrating the environment. +It is not recommended or supported to use this as the basis of a new OpenRA mod. + +Instead, you should copy one of the default OpenRA mods from `engine/mods/` to the `mods` subdirectory and make the following changes: +* Delete the `mods/example` directory. +* Choose one of the default OpenRA mods to use as a base for your mod. In this example we will assume you are copying `cnc`. +* Choose a new internal name / id for you mod. In this example we will assume you are using `mynewmod`. +* Copy `engine/mods/cnc` to `mods/mynewmod`. +* Open `mods/mynewmod/mod.yaml` and make the following changes: + * In the `Metadata` section set your mod title, version, and author. + * In the `Packaging` section replace `$cnc: cnc` with `$mynewmod: mynewmod`. This tells OpenRA that the explicit mount `mymod` should refer to the root of your mod package. + * Change all lines that start with `cnc|` to `mynewmod|`. This updates the explicit mount references to account for the change that you have just made above. +* Open `launch-mod.sh` and replace `MODID="template"` near the top of the file with `MODID="mynewmod"`. + +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 `OpenRA.Mods.Example.sln` and the `OpenRA.Mods.Example` directory. If you do plan on including custom logic, then you will need to make some futher changes: + * TODO: Explain updating the GUIDs, project name, and changing the build output to `mods/mynewmod/` + +### Developing / running your in-development mod + +Run the `launch-mod.sh` (Linux/macOS) or `TODO` (Windows) scripts to run your mod in development mode. +Before you run this for the first time you must fetch and compile the engine code by running the `TODO` (Linux/macOS) or `TODO` (Windows) script. + +### Packaging your mod for distribution + +When you are ready to share your mod with other players you have two options: +* Run the `TODO` (Linux/macOS) or `TODO` (Windows) scripts to generate a directory containing a self-contained version of your mod and the OpenRA engine that can be run by players on any operating system. +* Run the `TODO` script (Linux only) to generate OS-specific installers for players on Windows, macOS, and Debian-based Linux distributions. + +### Updating your mod for new OpenRA engine or mod template versions. + +It is no longer necessary to update your mod for every new OpenRA release, but if you want to take advantage of new engine features then the following outline explains how to update your mod: +* Make sure you have a backup of your mod directory. The upgrade probably won't work the first time. We *strongly* recommend that you use git to manage your mod development. +* Read the [changelog](https://github.com/OpenRA/OpenRA/wiki/Changelog) for the new release, paying close attention to any warnings or instructions in the "Engine / Modding" section. +* Check for new versions of this mod template, and copy any new or updated files into your mod. +* Update the `engine` submodule reference or directory to point at the new version of the OpenRA engine and run the `TODO` (Linux/macOS) or `TODO` (Windows) script to compile the new engine version. +* Use `OpenRA.Utility.exe`'s `--upgrade-mod` command to automatically update your mod rules for most of the changes in the new engine. Pay close attention to any error messages, you may need to manually change some of your rules before or after the utility successfully completes. +* `OpenRA.Utility.exe` may make unwanted changes (e.g. changing formatting or discarding comments), so we recommend using a git client to preview the automated changes, and discard or manually fix any unwanted changes. \ No newline at end of file diff --git a/launch-mod.sh b/launch-mod.sh new file mode 100755 index 0000000..d7cc01b --- /dev/null +++ b/launch-mod.sh @@ -0,0 +1,12 @@ +#!/bin/sh + +# Change this to match your mod +MODID="example" + +# Don't edit below this line +MODLAUNCHER=$(python -c "import os; print(os.path.realpath('$0'))") +MODROOT=$(dirname $MODLAUNCHER) + +cd engine +# TODO: Remove ./mods from the search path after we deprecate cross-mod references +mono OpenRA.Game.exe Engine.LaunchPath="$MODLAUNCHER" "Engine.ModSearchPaths=./mods,$MODROOT/mods" Engine.DefaultMod=$MODID Game.Mod=$MODID "$@" \ No newline at end of file diff --git a/mods/example/bits/blank.shp b/mods/example/bits/blank.shp new file mode 100644 index 0000000..2773f96 Binary files /dev/null and b/mods/example/bits/blank.shp differ diff --git a/mods/example/bits/dialog.png b/mods/example/bits/dialog.png new file mode 100644 index 0000000..7989c98 Binary files /dev/null and b/mods/example/bits/dialog.png differ diff --git a/mods/example/bits/mouse.shp b/mods/example/bits/mouse.shp new file mode 100644 index 0000000..8a52589 Binary files /dev/null and b/mods/example/bits/mouse.shp differ diff --git a/mods/example/bits/template.pal b/mods/example/bits/template.pal new file mode 100644 index 0000000..ccbf5ea Binary files /dev/null and b/mods/example/bits/template.pal differ diff --git a/mods/example/chrome.yaml b/mods/example/chrome.yaml new file mode 100644 index 0000000..18a0848 --- /dev/null +++ b/mods/example/chrome.yaml @@ -0,0 +1,32 @@ +button: dialog.png + background: 1,1,126,126 + border-r: 127,1,1,126 + border-l: 0,1,1,126 + border-b: 1,127,126,1 + border-t: 1,0,126,1 + corner-tl: 0,0,1,1 + corner-tr: 127,0,1,1 + corner-bl: 0,127,1,1 + corner-br: 127,127,1,1 + +button-hover: dialog.png + background: 1,129,126,126 + border-r: 127,129,1,126 + border-l: 0,129,1,126 + border-b: 1,255,126,1 + border-t: 1,128,126,1 + corner-tl: 0,128,1,1 + corner-tr: 126,128,1,1 + corner-bl: 1,255,1,1 + corner-br: 127,255,1,1 + +button-pressed: dialog.png + background: 129,1,126,126 + border-r: 255,1,1,126 + border-l: 128,1,1,126 + border-b: 129,127,126,1 + border-t: 129,0,126,1 + corner-tl: 128,0,1,1 + corner-tr: 255,0,1,1 + corner-bl: 128,127,1,1 + corner-br: 255,127,1,1 \ No newline at end of file diff --git a/mods/example/cursor.yaml b/mods/example/cursor.yaml new file mode 100644 index 0000000..3eb13fa --- /dev/null +++ b/mods/example/cursor.yaml @@ -0,0 +1,9 @@ +Palettes: + cursor: template.pal + +Cursors: + mouse.shp: cursor + default: + Start: 0 + X: -16 + Y: -12 \ No newline at end of file diff --git a/mods/example/english.yaml b/mods/example/english.yaml new file mode 100644 index 0000000..7dee16a --- /dev/null +++ b/mods/example/english.yaml @@ -0,0 +1,2 @@ +english: + english: English diff --git a/mods/example/mainmenu.yaml b/mods/example/mainmenu.yaml new file mode 100644 index 0000000..4a44196 --- /dev/null +++ b/mods/example/mainmenu.yaml @@ -0,0 +1,10 @@ +Container@MAINMENU: + Logic: TemplateMenuLogic + Children: + Button@QUIT_BUTTON: + X: (WINDOW_RIGHT - WIDTH) / 2 + Y: (WINDOW_BOTTOM - HEIGHT) / 2 + Width: 140 + Height: 30 + Text: Quit + Font: Bold diff --git a/mods/example/maps/blank-shellmap/map.bin b/mods/example/maps/blank-shellmap/map.bin new file mode 100644 index 0000000..8d718ac Binary files /dev/null and b/mods/example/maps/blank-shellmap/map.bin differ diff --git a/mods/example/maps/blank-shellmap/map.png b/mods/example/maps/blank-shellmap/map.png new file mode 100644 index 0000000..d866c8c Binary files /dev/null and b/mods/example/maps/blank-shellmap/map.png differ diff --git a/mods/example/maps/blank-shellmap/map.yaml b/mods/example/maps/blank-shellmap/map.yaml new file mode 100644 index 0000000..99ed01e --- /dev/null +++ b/mods/example/maps/blank-shellmap/map.yaml @@ -0,0 +1,26 @@ +MapFormat: 11 + +RequiresMod: example + +Title: Blank Shellmap + +Author: + +Tileset: TEMPLATE + +MapSize: 5,5 + +Bounds: 1,1,1,1 + +Visibility: Shellmap + +Categories: Shellmap + +Players: + PlayerReference@Neutral: + Name: Neutral + OwnsWorld: True + NonCombatant: True + Faction: Random + +Actors: diff --git a/mods/example/mod.yaml b/mods/example/mod.yaml new file mode 100644 index 0000000..70db24d --- /dev/null +++ b/mods/example/mod.yaml @@ -0,0 +1,71 @@ +Metadata: + Title: Example mod + Description: Illustrates the mod development scripts + Version: {DEV_VERSION} + Author: the OpenRA Developers + +RequiresMods: + +Packages: + . + $example: example + ./mods/common: common + example|bits + +MapFolders: + example|maps: System + +Rules: + example|rules.yaml + +TileSets: + example|tileset.yaml + +Cursors: + example|cursor.yaml + +Chrome: + example|chrome.yaml + +Assemblies: + common|OpenRA.Mods.Common.dll + example|OpenRA.Mods.Example.dll + +ChromeLayout: + example|mainmenu.yaml + +Notifications: + example|notifications.yaml + +Translations: + example|english.yaml + +LoadScreen: BlankLoadScreen + +ServerTraits: + LobbyCommands + PlayerPinger + MasterServerPinger + LobbySettingsNotification + +ChromeMetrics: + common|metrics.yaml + +Fonts: + Bold: + Font: common|FreeSansBold.ttf + Size:14 + +MapGrid: + TileSize: 32, 32 + Type: Rectangular + +SpriteFormats: ShpTS + +SpriteSequenceFormat: DefaultSpriteSequence + +GameSpeeds: + default: + Name: Normal + Timestep: 40 + OrderLatency: 3 \ No newline at end of file diff --git a/mods/example/notifications.yaml b/mods/example/notifications.yaml new file mode 100644 index 0000000..a45dff6 --- /dev/null +++ b/mods/example/notifications.yaml @@ -0,0 +1,4 @@ +Sounds: + Notifications: + ClickSound: + ClickDisabledSound: \ No newline at end of file diff --git a/mods/example/rules.yaml b/mods/example/rules.yaml new file mode 100644 index 0000000..2bdb574 --- /dev/null +++ b/mods/example/rules.yaml @@ -0,0 +1,19 @@ +World: + PaletteFromCurrentTileset: + Name: terrain + AlwaysVisible: + ActorMap: + ScreenMap: + LoadWidgetAtGameStart: + +Player: + AlwaysVisible: + TechTree: + PlaceBuilding: + SupportPowerManager: + PowerManager: + PlayerResources: + ActorGroupProxy: + DeveloperMode: + Shroud: + FrozenActorLayer: diff --git a/mods/example/tileset.yaml b/mods/example/tileset.yaml new file mode 100644 index 0000000..14d0f6b --- /dev/null +++ b/mods/example/tileset.yaml @@ -0,0 +1,18 @@ +General: + Name: Template + Id: TEMPLATE + Palette: template.pal + PlayerPalette: template.pal + +Terrain: + TerrainType@Clear: + Type: Clear + +Templates: + Template@255: + Id: 255 + Images: blank.shp + Size: 1,1 + Category: Terrain + Tiles: + 0: Clear \ No newline at end of file