From 782b5133ef58b228664a53b2dadcb93982012112 Mon Sep 17 00:00:00 2001 From: Paul Chote Date: Sat, 28 Jan 2017 16:48:56 +0000 Subject: [PATCH] Add basic mod template. --- OpenRA.Mods.Example.sln | 17 ++++ .../OpenRA.Mods.Example.csproj | 75 ++++++++++++++++++ .../Widgets/Logic/TemplateMenuLogic.cs | 25 ++++++ README.md | 42 ++++++++++ launch-mod.sh | 12 +++ mods/example/bits/blank.shp | Bin 0 -> 32 bytes mods/example/bits/dialog.png | Bin 0 -> 2756 bytes mods/example/bits/mouse.shp | Bin 0 -> 161 bytes mods/example/bits/template.pal | Bin 0 -> 768 bytes mods/example/chrome.yaml | 32 ++++++++ mods/example/cursor.yaml | 9 +++ mods/example/english.yaml | 2 + mods/example/mainmenu.yaml | 10 +++ mods/example/maps/blank-shellmap/map.bin | Bin 0 -> 142 bytes mods/example/maps/blank-shellmap/map.png | Bin 0 -> 147 bytes mods/example/maps/blank-shellmap/map.yaml | 26 ++++++ mods/example/mod.yaml | 71 +++++++++++++++++ mods/example/notifications.yaml | 4 + mods/example/rules.yaml | 19 +++++ mods/example/tileset.yaml | 18 +++++ 20 files changed, 362 insertions(+) create mode 100644 OpenRA.Mods.Example.sln create mode 100644 OpenRA.Mods.Example/OpenRA.Mods.Example.csproj create mode 100644 OpenRA.Mods.Example/Widgets/Logic/TemplateMenuLogic.cs create mode 100755 launch-mod.sh create mode 100644 mods/example/bits/blank.shp create mode 100644 mods/example/bits/dialog.png create mode 100644 mods/example/bits/mouse.shp create mode 100644 mods/example/bits/template.pal create mode 100644 mods/example/chrome.yaml create mode 100644 mods/example/cursor.yaml create mode 100644 mods/example/english.yaml create mode 100644 mods/example/mainmenu.yaml create mode 100644 mods/example/maps/blank-shellmap/map.bin create mode 100644 mods/example/maps/blank-shellmap/map.png create mode 100644 mods/example/maps/blank-shellmap/map.yaml create mode 100644 mods/example/mod.yaml create mode 100644 mods/example/notifications.yaml create mode 100644 mods/example/rules.yaml create mode 100644 mods/example/tileset.yaml 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 0000000000000000000000000000000000000000..2773f966675bed1e4ade0319c3d562d35cec0388 GIT binary patch literal 32 RcmZQzU<5-36u=JW0RRBH01E&B literal 0 HcmV?d00001 diff --git a/mods/example/bits/dialog.png b/mods/example/bits/dialog.png new file mode 100644 index 0000000000000000000000000000000000000000..7989c982489be427f8da43c2d09f1a028ff777ee GIT binary patch literal 2756 zcmeAS@N?(olHy`uVBq!ia0y~yU<5K58911L)MWvCLmzCHb_`sNdc^+B->Ug!Z$#{Ilm}X!Bo#g&p^qJOF==wrYI%ND#*nR zsvXF)RmvzSDX`MlFE20GD>v55FG|-pw6wI;H!#vSGSUUA&@HaaD@m--%_~-h7y>iL zCAB!YD6^m>Ge1uOWNuvYb~$u9~nNK8%zxeTlYNeEpv*q%t7_8`e1=}bwsDlSdRN=+_7iZ5WSfm6RzV!A$( zu#G-e)i%JiVC9>il9^WNl30>zXJlY#Ze?I-Wn`gXXaZr_=%cAYasf!jxhOTUB)=#m zKR?F~?2TLySHV~h7*go+P^~ulpnQasuOOKgEDFrEc3eQ6uoA$Ii%CCRnSp`L%+tj& zq=ND7^^Lh%i6ShCzfbZCSgLGtVVb*x;m_N6dX>+ zSNSwBd}MeO&BT)N)4QKjKtax-#=C(*xBjIeBhwM)j(kpm1yA)yEg222p_01x%s>D9 rvBjfsp5yy}+|S#d$dLN=`RAYVnVwqwRvXKiLG4OUS3j3^P6}AJp>3izlPtJy jfYDSEetaS&<#~Ex@4q0Zi1M7l#>)!mdZ`~MOMv2UiP8a> literal 0 HcmV?d00001 diff --git a/mods/example/bits/template.pal b/mods/example/bits/template.pal new file mode 100644 index 0000000000000000000000000000000000000000..ccbf5eab6f9267ed77b2f6d2443cdbf8a5af4134 GIT binary patch literal 768 VcmZQzVEF(4Kf@>(4S^9E0s!uW0{#F1 literal 0 HcmV?d00001 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 0000000000000000000000000000000000000000..8d718ac90aaaf2b79880b9295a75ca64ffbaa129 GIT binary patch literal 142 vcmZQ#Wng6xWPpGeAoU*$;`-0PgCx%SpMeF8Ad30HQk+N%poTzAC4m9}`+ymo literal 0 HcmV?d00001 diff --git a/mods/example/maps/blank-shellmap/map.png b/mods/example/maps/blank-shellmap/map.png new file mode 100644 index 0000000000000000000000000000000000000000..d866c8c7b8d9eb90087fb377226b737eaa5473b9 GIT binary patch literal 147 zcmeAS@N?(olHy`uVBq!ia0vp^%plCc1|-8Yw(bW~Ea{HEjtmSN`?>!lvI6;x#X;^) z4C~IxyaaL-l0AZa85pY67#JE_7#My5g&JNkFq9fFFuY1&V6d9Oz#v{QXIG#NP(skt o#W93qW^zV%`CtCSJQkJ=rK!S2(y!hr03{hbUHx3vIVCg!0NczXhX4Qo literal 0 HcmV?d00001 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