Add basic mod template.

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

OpenRA.Mods.Example/OpenRA.Mods.Example.csproj

@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <PropertyGroup>
+    <Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
+    <Platform Condition=" '$(Platform)' == '' ">x86</Platform>
+    <ProjectGuid>{4E5B38F7-4E99-4C92-BB39-9100CC7F3829}</ProjectGuid>
+    <OutputType>Library</OutputType>
+    <RootNamespace>OpenRA.Mods.Example</RootNamespace>
+    <AssemblyName>OpenRA.Mods.Example</AssemblyName>
+    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Debug|x86'">
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+    <DefineConstants>DEBUG;TRACE</DefineConstants>
+    <PlatformTarget>x86</PlatformTarget>
+    <ErrorReport>prompt</ErrorReport>
+    <OutputPath>bin\Debug\</OutputPath>
+    <CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
+    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'Release|x86'">
+    <DebugSymbols>true</DebugSymbols>
+    <OutputPath>bin\Release\</OutputPath>
+    <DefineConstants>TRACE</DefineConstants>
+    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
+    <DebugType>pdbonly</DebugType>
+    <PlatformTarget>x86</PlatformTarget>
+    <ErrorReport>prompt</ErrorReport>
+    <CodeAnalysisRuleSet>AllRules.ruleset</CodeAnalysisRuleSet>
+    <Optimize>true</Optimize>
+  </PropertyGroup>
+  <ItemGroup>
+      <Reference Include="System" />
+      <Reference Include="System.Core" />
+      <Reference Include="System.Drawing" />
+      <Reference Include="Eluant">
+        <HintPath>..\engine\thirdparty\download\Eluant.dll</HintPath>
+        <Private>False</Private>
+      </Reference>
+      <Reference Include="OpenRA.Game">
+		<HintPath>..\engine\OpenRA.Game.exe</HintPath>
+        <Private>False</Private>
+      </Reference>
+      <Reference Include="OpenRA.Mods.Common">
+		<HintPath>..\engine\mods\common\OpenRA.Mods.Common.dll</HintPath>
+        <Private>False</Private>
+      </Reference>
+  </ItemGroup>
+  <ItemGroup>
+    <Compile Include="Widgets\Logic\TemplateMenuLogic.cs" />
+  </ItemGroup>
+  <ItemGroup>
+    <Folder Include="Widgets\" />
+    <Folder Include="Widgets\Logic\" />
+  </ItemGroup>
+  <Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
+  <Target Name="AfterBuild">
+    <MakeDir Directories="$(SolutionDir)mods/example/" />
+    <Copy SourceFiles="$(TargetPath)" DestinationFolder="$(SolutionDir)mods/example/" />
+    <!--
+        We need to copy OpenRA.Mods.Cnc.pdb (not `.dll.pdb`). This is only necessary on Windows.
+        Mono outputs a `.dll.mdb` so we can just append `.mdb` directly.
+    -->
+    <Copy SourceFiles="$(TargetDir)$(TargetName).pdb" DestinationFolder="$(SolutionDir)mods/example/" Condition="'$(OS)' == 'Windows_NT'" />
+    <Copy SourceFiles="$(TargetPath).mdb" DestinationFolder="$(SolutionDir)mods/example/" Condition="'$(OS)' == 'Unix'" />
+    <!-- Uncomment these lines when debugging or adding to this target
+    <Message Text="DEBUG OS:                     $(OS)"/>
+    <Message Text="DEBUG SolutionDir:            $(SolutionDir)"/>
+    <Message Text="DEBUG TargetPath:             $(TargetPath)"/>
+    <Message Text="DEBUG TargetDir:              $(TargetDir)"/>
+    <Message Text="DEBUG TargetName:             $(TargetName)"/>
+	-->
+  </Target>
+</Project>

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<ButtonWidget>("QUIT_BUTTON").OnClick = Game.Exit;
+		}
+	}
+}

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.

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 "$@"

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

mods/example/cursor.yaml

@@ -0,0 +1,9 @@
+Palettes:
+	cursor: template.pal
+
+Cursors:
+	mouse.shp: cursor
+		default:
+			Start: 0
+			X: -16
+			Y: -12

mods/example/english.yaml

@@ -0,0 +1,2 @@
+english:
+	english: English

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

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:

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

mods/example/notifications.yaml

@@ -0,0 +1,4 @@
+Sounds:
+	Notifications:
+		ClickSound:
+		ClickDisabledSound:

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:

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