Scenario Modding

Modders can add custom **scenarios** to Hegemony III. These custom scenarios can take place on a custom map, or may re-use the vanilla map of Italy. They can use modded factions (which in turn may use custom brigades, tech trees etc), or simply re-use those of vanilla. Custom scenarios can range in complexity from simple sandboxes to fully scripted campaigns with narrative events.

# Scenario Basics

## Folder

Custom scenarios will be located in a folder called 'Scenarios' within the 'Resources' folder of your mod. Each custom scenario that your mod adds will then require its own subfolder inside your mod's 'Resources/Scenarios' folder. The name of the specific scenario's subfolder will serve as the internal name for this scenario and is up to the modder, but shouldn't include spaces or special characters.

## Scenario Set-Up Through Map Editor

The **Map Editor** has functions to help setting up the basics of a scenario on a custom map a lot easier, this tutorial on steam explains how to make use of them.

This is not an option for scenarios that take place on the vanilla map of Italy, as the source file of the Italy map isn't available in the game's installation and thus cannot be opened in the map editor. In that case, the scenario will need to be set-up by hand instead. It is possible to copy the scenario configuration of one of vanilla's scenarios (located in the Resources/Scenarios folder of your game's main installation directory) and make edits from there, to make things easier.

# Minimum Requirements

The scenario subfolder will at a minimum need 2 files: a config.xnt file and a start.lua file. (Though you will nearly always also want to include a .xml file with custom start settings data).

You will also need to create some text strings.

## Scenario Name and Description Strings

You will need to create 2 text strings for the scenario's name and description, which will be displayed for your scenario in the scenario selection menu. Refer to the String Modding page for basic information on how to add these strings to your mod's file system.

The strings should be named as follows:

* Scenario::YOURSCENARIO::NAME
* Scenario::YOURSCENARIO::DESC

Where YOURSCENARIO must be replaced with the internal name for your scenario, which is also the name of your scenario's sub-folder.

## config.xnt

The config.xnt looks somewhat like this:

```
 <scenario>
        <sortorder>50</sortorder>
 </scenario>

```

When displaying the scenario selection menu after choosing to start a new game, the game takes the 'sortorder' numbers of all active scenarios, and sorts those with lower sortorder numbers further to the front and those with higher ones further to the back. Changing the sortorder number therefore allows you to control where your scenario will appear in the scenario selection menu, relative to other scenarios.
Otherwise, this is a simple file that's only necessary for the scenario to register in the scenario selection menu, and will not require further changes.

## start.lua

The start.lua file contains a very small script with a loadgame function that is executed when selecting the scenario in the scenario selection menu. It will load the basic scenario set-up (detailing starting factions, city ownerships etc) from a given filepath, and then tells the game where to go from there (this can mean showing a sandbox 'faction selection' type screen for a sandbox, or going further to another script file for scripted campaigns)

### Examples for Scripted Campaigns

Examples of start.lua files of scripted campaigns:

The Pyrrhus campaign in the Eagle King DLC of vanilla:

* `loadgame("Resources/Scenarios/Pyrrhus/pyrrhus.fi", false, "dofile([[`Resources/Scenarios/Pyrrhus/intro.lua`]])", true);`

A modded campaign:

* `loadgame("Resources/Scenarios/Scipio/Scipio.xml", false, "dofile([[`Resources/Scenarios/Scipio/intro.lua`]])", true);`

### Examples for Sandbox Scenarios

Examples of start.lua files of sandbox scenarios:

The main vanilla sandbox:

* `local sCampaignName = getstring("PH", "Scenario::Unification::NAME");`
* `local sStartScript = [[`configscenario("`]] .. sCampaignName .. [[`", {"senones"}, "FactionScreen" );`]];`
* `loadgame("Resources/Scenarios/Unification/unification.fi", false, sStartScript, true);`

A modded sandbox (where the script is a bit condensed to a single line):

* `loadgame([[`Resources/Scenarios/Iberia300BC/Iberia300BC.xml`]], false, [[`configscenario("", {"iberia300bc"}, "FactionScreen" );/`]], true);`

Another, more advanced modded sandbox (using a custom faction selection screen):

* `loadgame([[`Resources/Scenarios/LatVet700BC/LatVet700BC.xml`]], false, [[`configscenario("", {"latvet700bc", "fristireligion"}, "LatVet700BCFactionScreen");`]], true);`

### Parameter Explanation

The first and third parameters of the loadgame function should likely be changed when making a new scenario.

The **first parameter** in any type of scenario points to a .xml or .fi file (either enclosed in `" "` or `[[ ]]` ) that defines the basic set-up for the game, including information on which map the scenario uses as well as its starting factions and starting city ownerships at a minimum.
.fi files are harder to use, so for modding purposes it is generally recommended to use a .xml file which can be opened easily with a plain text editor.
(Both .fi files and .xml files are available in the vanilla scenarios in your main game installation folder. As you can see in the vanilla start.lua examples the .fi file is the one actually used, the .xml file is there in the vanilla installation as well for modders to read and/or copy)
Often, scenarios will each have their own such file included in the scenario's sub-folder, but it is also possible to simply point this parameter to an existing file of another scenario if you want to use exactly the same starting positions.

The **third parameter** defines what the game should do AFTER loading the initial scenario set-up and is different for sandboxes and scripted campaigns.

* In the case of scripted campaigns, this will be a dofile function which simply point to another .lua script file which will handle additional scenario configurations and may also initialize a scripted starting cutscene. This will require more advanced scripting which is beyond the scope of this article. To see an example of what this script may look like, you can check out the intro.lua file in the 'DLC/TheEagleKing/Resources/Scenarios/Pyrrhus' folder of your game's main installation directory if you have the Eagle King DLC installed.

* For sandboxes, this will instead be a configscenario function which automatically handles additional scenario configuration. The configscenario function in turn takes three parameters.
	+ The **first parameter** isn't very important. It takes a string (enclosed in `" "`) which will be set as the internal "campaign name" in the scenario's save state. This is only important if you have a script that at some point uses the getcampaignname() function, but it is generally better to use event tags (in the second parameter) for such purposes instead. You can usually just leave this as an empty string ( `""` )
	+ The **second parameter** takes an array of event tags which will be active in this scenario. The array is enclosed in `{ }` and can contain any amount of event tags, which are strings enclosed in `" "` and separated by commas. Scripted events can be configured to only trigger if a certain event tag is active in the scenario, so this array lets you control which scripted events will fire in your scenario. If you do not plan to make use of events, you can just leave it as an empty array ( `{}` ) For example, vanilla's event where the Senones appear as a new faction in northern Italy requires the "senones" tag to be active. We can see that `"senones"` appears in the event tags array in the example of the main vanilla sanbox scenario, but not in the modded sandboxes. This ensures that the Senones invasion event will be called in the vanilla sandbox, but not in the modded sandboxes. Note that not all events use event tags (meaning they will fire in every scenario), and some event tags may be set by default through the FactionScreen in the third parameter rather than being listed explicitly in this array.
	+ The **third parameter** is the internal name of the type of Faction Selection Screen that will be shown at the beginning of the scenario (as a string enclosed in `" "`). In vanilla, without DLC, the only available option for this parameter is the `"FactionScreen"` screen which is the default faction selection screen for normal sandboxes. The Eagle King DLC adds an `"InvadersScreen"` option for special sandboxes that start the player with a migrating army but no cities (this is slightly more complex and will require an additional invaders.lua to be present in the scenario sub-folder with all the necessary information. It is possible to create and use custom Faction Screen types (e.g. the LatVet700BCFactionScreen in the final modding example), requiring the creation of a new gui element and script by that name, but this is more advanced and beyond the scope of this tutorial. For most purposes, the vanilla FactionScreen should do fine.

### Simple start.lua Set-Up

If all of the above is too involved for you, and you just want to try your hand at creating a simple sandbox scenario without dealing with complicated scripting, just have your start.lua consist of only the below code:

`loadgame("Resources/Scenarios/Unification/Unification.xml", false, [[`configscenario("", {}, "FactionScreen");`]], true);`

and change the `"Resources/Scenarios/Unification/Unification.xml"` filepath in the first parameter to that of a custom .xml file for your scenario if desired.

# Optional requirements

## Scenario configuration .xml file

Most custom scenarios will want to include a .xml file with essential details regarding the scenario and its starting state. This file's name and location can theoretically be anything you want as long as it is somewhere within your mod's Resources folder and your start.lua correctly points to its location. Usually though, it will be located within the scenario's sub-folder alongside the start.lua file, and given the same name as that of the sub-folder it is in (see the start.lua examples for reference).

For scenarios on custom maps, it is easiest to generate the basics of this .xml file through the map editor, following this tutorial on steam. For scenarios that take place on the vanilla map of Italy, it is easiest to copy the Resources/Scenarios/Unification/Unification.xml file from your main game installation directory to your mod, rename the copy, and then make changes to the copy from there.

At a minimum, this file configures which map the scenario takes place on. It will also define the factions that exist in the scenario, which cities they possess at the start of the game and which of those cities is their capital. This information that can be generated using the map editor.

Optionally, this file can also be used to define starting diplomatic relations between factions and make specific cities start the game with higher population levels and/or specific pre-built building upgrades. This additional information cannot be generated with the map editor and will always need to be put in manually in the .xml file using a plain text editor, after all of the minimum information has already been generated.

### .xml file breakdown

It is recommended to open a scenario .xml file (such as the Resources/Scenarios/Unification/Unification.xml file in your main game installation directory) and cross-reference with that file while reading the below tutorial.

If you are making a scenario on a custom map and followed the tutorial on steam and automatically generate this .xml file in the process, it is only necessary to understand the below if you are planning to add optional additional settings (regarding starting diplomatic relations or making specific cities start with higher populations and/or pre-built upgrades).

#### Main scenario node & which map to use

The scenario information is contained within a scenario node as follows:

```
<scenario map='resources/data/italy.map'>
</scenario>

```

The path to the map file on which the scenario takes place is configured here.

All of the remaining information in the .xml file are child nodes of this main scenario node.

#### Version information

The first child nodes of the main scenario node usually describes the version information of the game.

```
<vermajor>3</vermajor>
<verminor>3</verminor>
<verpatch>5</verpatch>

```

It is recommended to just set this to the most recent version of the game (3.3.5 as of this writing, as in the example above)

#### Campaign string

The campaign string should point to the name of a text string within one of the mod's or main game's .str files.

```
<campaignstring>Sandbox::Unification::NAME</campaignstring>

```

It is recommended to just use the scenario's name string here, created in this section.

#### Map mask

This points to the path of a partially transparent image that is used for defining which parts of the zoomed out 2d/strategy map view will display player colours on them (conventionally, water regions do not display these).

```
<mapmask>resources/scenarios/unification/mapmask.dds</mapmask>

```

Creating a custom mapmask file is a map modding issue and beyond the scope of this tutorial. Having a custom mapmask file can be considered optional, as several map mods opt to just re-use the vanilla mapmask file even though faction colours may not look entirely accurate on the 2d view.

#### Season

Next is usually a 'season' node with several sub-nodes.

```
<season>
  <season>2.5</season>
  <seasontarget>2.5</seasontarget>
  <seasonlength>0</seasonlength>
  <seasonmode>target</seasonmode>
  <nextstorm>0</nextstorm>
  <stormlength>0</stormlength>
</season>

```

It is not usually required to change any of this.

#### Factions

Next up is a list of several nodes, each declaring a faction that is active in the scenario.

```
<faction enttype='Independent'/>
<faction enttype='Bruttii'/>
<faction enttype='Cenomani'/>
<faction enttype='Clevsin'/>
<faction enttype='Dauni'/>

```

etc...

Each faction that can own any brigade or city at the start of the scenario must be declared here, by adding a faction node and changing the enttype to the internal name of that faction, as defined in the 'type' node of its faction entity (see Faction Modding).

Note that the 'Independent' faction will always need to be included for technical reasons (unclaimed resource buildings and such), but it isn't necessary to include the 'Indie' versions of each sandbox faction.

#### Faction diplomacy (optional)

It is possible (but not necessary) to define starting relationships between factions, by adding nodes like so:

```
<factionrelation faction1='Romeiberia' faction2='Phocaea'>
  <hostility>-0.25</hostility>
  <intimidation>-0.2</intimidation>
  <relationstate class='relationstate' type='truce'/>
  <lastchangeday>0</lastchangeday>
  <costchangeday>0</costchangeday>
  <lasthostileday>0</lasthostileday>
</factionrelation>

```

These define the starting hostility, intimidation and relation state between faction1 and faction2. Possible relationstate types are 'truce', 'atwar' and 'neutral'

You will need to add such a node for any relationship between 2 factions that you wish to not start out as the default (which is neutral at 0 hostility)

#### Cities

Each city that is meant to be active in the scenario will have a node:

```
<city id='16557688'>
</city>

```

The city is identified by its internal id number. Which city corresponds to which id can be seen by selecting cities in the map editor in building mode (for custom maps), or in-game by activating debug mode and selecting cities there (which is the only option for the vanilla map).

If a city exists on the scenario's map but does not have a node in the .xml, it will be unowned, unbuilt and inaccessible.

The city node will in turn have several sub-nodes:

##### Native Ownership

Each city will at a minimum have a sub-node defining of which faction this is a native city at the beginning of the game, like so:

```
<city id='7621360'>
  <faction>Ligures</faction>
</city>

```

##### Captor Ownership (optional)

It is possible to make a city start with a different captor faction than its native faction by adding an additional `<captorfaction>` sub-node, like so:

```
<city id='7621360'>
  <faction>Ligures</faction>
  <captorfaction>Insubres</captorfaction>
</city>

```

If no captorfaction is included, the city will start out as being controlled by its native faction by default.

##### Faction capital

One city of each faction that controls cities at the start of the game will need to be defined as that faction's capital city. This city will be the player's starting city when playing as this faction with the 'capital only' (default) starting setting (in a standard FactionScreen sandbox), and will receive an additional morale bonus.

Defining this city is done by adding an extra `<capital>true</capital>` sub-node, as below:

```
<city id='2594752'>
  <faction>Ligures</faction>
  <capital>true</capital>
</city>

```

##### Starting population (optional)

A city can be made to have a higher than normal starting population level by adding an additional `<pop>` sub-node, like so:

```
<city id='16557688'>
 <faction>Cessetani</faction>
 <pop>2</pop>
</city>

```

In the above example, the city will start with population level 2 rather than the default population level 1.

##### Starting upgrades (optional)

A city can be given starting building upgrades, by adding `<upgrade>` sub-nodes which in turn have a `<type>` sub-node with the internal name of the upgrade in question.

```
<city id='4954392'>
  <faction>Edetani</faction>
  <pop>6</pop>
  <upgrade>
    <type>wallwood</type>
  </upgrade>
  <upgrade>
    <type>battlements</type>
  </upgrade>
  <upgrade>
    <type>fisheryocean</type>
  </upgrade>
</city>

```

Above is an example of a city that starts out with a wooden wall, battlements and an ocean fishery.

When giving a city starting upgrades in this manner, it is recommended to also make sure that the city is given a starting population that is high enough to support this amount of upgrades.

Also note that these starting upgrades do still cost gold upkeep, so be careful not to make it so that a faction is immediately running a deficit at the start of the game!

#### Map bounds (optional)

Lastly, the scenario node may contain map bounds information to limit the playable area on the scenario's used map. This shows up like a red outlined shape in-game beyond which the player may not move brigades.

Here is an example of map bound information of the smaller Etruria-only sandbox of vanilla:

```
<boundary>
  <boundary>
    <pts>2032.33 1603.52</pts>
    <pts>2069.03 1599.34</pts>
    <pts>2080.7 1589.54</pts>
    <pts>2080.95 1577.81</pts>
    <pts>2085.09 1568.41</pts>
    <pts>2110.43 1524.09</pts>
    <pts>2102.00 1498.00</pts>
    <pts>2082.00 1489.5</pts>
    <pts>2056.83 1408.46</pts>
    <pts>2078.51 1310.8</pts>
    <pts>1994.15 1188.05</pts>
    <pts>1913.95 1094.5</pts>
    <pts>1685.69 1105.11</pts>
    <pts>1601.83 1336.86</pts>
    <pts>1792.81 1583.63</pts>
  </boundary>
</boundary>

```

Each `<pts>` node contains the x and y map coordinate of each corner of the outline of the playable area. You can add or remove `<pts>` notes, they do not need to be the same amount as in the example above. The red outline that delimits the playable area will connect from the coordinates of one `<pts>` node to the next, and from the last node back to the first.

To find the correct map coordinates, the coordinates where the mouse cursor is currently hovering over can be seen in several modes of the map editor, or in-game by activating debug mode

If boundary information is left out, the entirety of the map will be playable by default.

## cover.dds file

A 960\*540 cover.dds image can be added to your scenario's sub-folder to give the scenario a custom image in the scenario selection screen. This image will often be partially transparent and will be laid on top of the main game menu's background texture.

If your scenario's sub-folder does not contain a cover.dds file, the game will simply use the default scenario graphic in which 5 combatants are displayed in a small melee.