Modding Tutorial No. 3: New Factions in a New Sandbox

Welcome to the third entry of our modding blog where we'll be posting a new mod every week along with a step-by-step walkthrough on how you can make a similar mod of your own. As before, if something is unclear or if there is another type of mod you really want us to ask about, please leave a post and we'll get back to you.

By now, we should be familiar with creating a new mod and with creating and editing entities and strings. For this week's mod, we're going to look into defining a new scenario with a new faction defined. We'll start with the more familiar part of that, defining the faction entity. For this mod, we'll be splitting off some of the Roman territory into the territory of the Hernici, a Sabellic tribe that occupied part of Latium.

Factions are similarly to any other entity we've defined. Here's a default faction's .xnt: faction Rome latin Factions::Rome   #a6002c #a6002c     0.4 0.2 faction RomeIndie latin Factions::RomeIndie false   #bb8493 #bb8493    

One oddity you might notice here is that there're actually two factions defined; Rome and RomeIndie. RomeIndie is the independent version that starts with all cities but your capital (assuming you didn't turn off the capital-only start when you started a new game); one is needed for every playable faction. It doesn't have to be in the same file; if you wanted a seperate Hernici.xnt and HerniciIndie.txt that's perfectly valid, but somewhere there needs to be a faction that has the same type name as the one we're adding, but with "Indie" added at the end. Note that this only applies if you're defining a new faction that you intend to be playable in a default Unification-style sandbox. If your scenario bypasses sandbox mechanics altogether like Hegemony Rome's campaigns did, or if you're defining a non-playable faction like the raiders, you can get away without an indie version (and if you look in the default faction files downloadable here, you'll see indeed there is no RaidersIndie), but if you intend to add a playable faction to a sandbox scenario make sure you define another faction entity and shove "Indie" at the end of the name.

So with that out of the way, let's look at the faction entities themselves.
 * "type" and "class" we've already seen in other entities. We'll just leave "class" as faction" on both entities, and set the types to "Hernici" and "HerniciIndie".
 * "factiongroup" declares what group the faction is in; this controls which units and skill trees it has access to, as well as affecting starting diplomatic state slightly. The default options are "etruscan", "gaul", "greek", "illyric", "independent", "latin", "raider", "sabellic" and "slave"; of these, "independent" and "slave" serve special purposes in code and should not be considered playable. "raider" is entirely playable, though the complete lack of worker units or gold/recruit costs to its units might throw the experience off a bit. Since the Hernici historically were sabellic, we'll set them and their indie to the sabellic factiongroup. Note that it's entirely possible to define your own factiongroups; the default ones are available for reference here
 * "article" is the base string for this faction. You'll need to create a few different strings that start with this for a faction to work; if the faction isn't meant to be playable, like the HerniciIndie, you only need to define three strings. We'll set HerniciIndie's article to, which'll mean we need to define  , Factions::HerniciIndie::BRIGADETITLE, and Factions::HerniciIndie::NAME strings. Since we intend the Hernici to be playable, they're gonna need five strings. When we set Hernici's article to  , we're going to want to define  ,  ,  ,   and   strings. The   strings will appear when the faction's name is being used as an adjective; we're going to want "Hernici" here, and "Independent Hernican" for the indie version.   has the formatting used for brigades; it'll look something like  .   will be replaced by I or IV or XII or something depending on how many of that brigade there are,   will be the type of the brigade, and if the brigade's from a non-native faction   will be replaced by the brigade's native faction, giving us e.g. "II Roman Leves of the Hernici" were we to recruit a second brigade of leves from a Roman city.   is just the name and   is a small paragraph on the history or characteristics of the faction to give flavour for the curious.
 * "flag" and "logo" we've already covered in the Blue Histri tutorial; we're going to want to follow its lead for the main Hernici and have them point to new image files created for the mod. For the HerniciIndie, though, this isn't necessary; we can leave them as blank, to fit with all the other factions' indie variants.
 * "guicolour" and "unitcolour" we've also covered in the Blue Histri. We'll tweak them to a shade of gray to fit with the Hernici's historical mountainous themes and give them a colour distinct from most surrounding factions. The indie is usually a paler variant of the playable version's.
 * "unitshield" is similar to flag and logo; it points to an image that gets placed on units' shields. There are two things strange about it: first, it has an extra "shieldtype" attribute saying what shape of shield the image is designed to fit on. You can have different images for different shapes if you so choose; many factions have a different rectangular one, twice as tall as it is wide, so the shield image doesn't get distorted by the longer rectangular shields. You can also have more than one shield defined for the same type; each unit will randomly pick which shield of the appropriate shape to take if there's more than one.
 * "attribute" is the fun part, defining what this faction's special bonuses are. They work the exact same for factions as they do for stances, down to having as many as you want. We'll give the Hernici a bonus to mine output and missile damage, because they were in the mountains and I like missile damage.

So we have our Hernici entities defined. Unfortunately, they aren't currently in either the Unification nor Etruria sandboxes. Rather than overwrite the default scenarios, let's create a new scenario with the Hernici in them. Creating a scenario is unlike creating an entity, string or image in that it matters what folder the scenario is defined in. We need to create a Scenarios/ folder inside your mod's Resources/ folder, and in the Scenarios folder we'll need a folder for our scenario. Rather than create our scenario from scratch, it'll be easier to copy over the unification scenario from the default game and modify it; navigate to the base game's Resources/Scenarios/ folder and copy Unification into your mod's Resources/Scenarios/ folder, then rename it Hernici. In your mod's Resources/Scenarios/Hernici/ folder, you can delete mapmask.dds and unification.fi: we won't be using them. That leaves three files, config.xnt, start.lua and unification.xml (which we can rename to hernici.xml for clarity's sake).

config.xnt includes the sortorder for the scenario, the higher it is, the closer to the end it is. The default scenarios are 1 and 2 for Unification and Etruria respectively. Decimals are invalid, so we can't put our scenario in-between them using sortorder along, though we could tie either of them and have it order the tied scenarios alphabetically (I'm looking into improving this system for Update 4). We'll set ours to 50 to put it at the end.

start.lua is a script file that runs when the scenario is started. We don't need to change much in it since we want our game to run more or less the same as the unification sandbox, just open another file. We'll want to change the first line, which currently says local	sCampaignName = getstring("PH", "Scenario::Unification::NAME"); and have it point to the Scenario::Hernici::NAME string (make sure you keep the quotes!) and change the last line, which currently reads loadgame("Resources/Scenarios/Unification/unification.fi", false, sStartScript, true); to point to the .xml file in our scenario folder, so instead of "Resources/Scenarios/Unification/unification.fi" it should read "Resources/Scenarios/Hernici/hernici.xml" or "Resources/Scenarios/Hernici/unification.xml" depending on whether you renamed the .xml or not.

The last file is the .xml file, which we're storing our scenario data in. A scenario file has one main scenario block with a map attribute telling it which map it's a scenario for (in this case, italy.map) and six types of subtag.  to the list. true to either city (in this case to Anagnia, or id='3574536').
 * "vermajor" and "verminor" are what version of the game this is for, mostly to stop previous patches from trying to load it. They can be ignored.
 * "campaignstring" is from an old feature that once told the game what string to use on the savegame menus to let the user know it's this scenario. This was removed when we went to the new format of savegame menu and thus can be ignored.
 * "season" contains a series of stats on what season the game starts at and how long each season is. Feel free to tweak them if you wish, but it's not relevent to adding in a new faction.
 * "faction" tags list every faction available in this scenario. Note that the first faction in this list must ALWAYS be Independent. Beyond that, you can list as few or as many as you like; any faction listed here will be made playable. You may notice that the raiders, the indie factions, and the senones are missing from this; they aren't supposed to be playable, so they aren't listed here. Any faction listed here MUST have an indie variant. We want to add the Hernici from the beginning as a playable faction, and have defined the entity and its indie version already, so we'll add
 * "city" defines the faction of every city in the scenario. The cities are listed by their IDs; any city not listed will be inactive through the game. To find any specific city, we'll have to launch the game. When you have a game running in the Unification sandbox, enter some script commands from the console. The console can be opened with the  button; from there, we can type in   and hit enter.   turns off the fog and   will put object's numeric ids in their tooltips. Using this, we can find out that Anagnia's id is 3574536 and Carsioli's is 11988312; back in the .xml file, using ctrl-f to search for id='3574536' and id='11988312' will bring us to the cities' tags. Change their factions to Hernici. We still need to define a capital; this is done by simply adding
 * "boundary" defines the playable boundary on the map. Making this larger than the Unification default won't do anything, since the map would still need to have more terrain or path regions defined to make more areas playable, and we don't really want to shrink it.

In addition to the three files in any scenario, there're two strings needed. Create a  and   string for the Scenarios menu; the NAME will be the title and the DESC will be the text beneath it describing the scenario.

And that's everything you need to do to create a new scenario with a new faction in it! If you launch the game with your scenario folder and the faction entity, you should see a new dot in the list of scenarios and a new faction ready for the picking on the following menu!