Modding Tutorial No. 2: Stances

Welcome to the second 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.

In our last post, we went over the basics of creating a mod folder and a few basics on editing .xnt and .str files. We'll need these skills to create any new objects in the game. Today I'll be going over creating new stances.

For this example, we'll be creating a new stance for ranged units that extends their range but reduces their damage inflicted. To add new stances, we'll need to create new .xnt files in our MoreRangedStances/Resources folder. Defining a new entity isn't that different from merging data into an old one, like we did last week; just remove the modtechnique="merge", and you're defining a new entity (in our case a stance). Here's what the current "Ranged Support" stance looks like:

```
<entity>
       <type>rangedsupport</type>
       <class>brigadestance</class>

       <article>Stances::RangedSupport</article>

       <objtype>brigade</objtype>
       <sortorder>30</sortorder>

       <brigadestanceclass>legion</brigadestanceclass>
       <brigadestanceclass>javelineer</brigadestanceclass>
       <brigadestanceclass>rangedinfantry</brigadestanceclass>

       <combatmovement>skirmish</combatmovement>
       <attackstyle>ranged</attackstyle>

       <grouprowscore>40</grouprowscore>
       <groupcolumnscore>100</groupcolumnscore>

       <attribute attrtype="speed" op="mult">0.25</attribute>

       <buttonactive atlas="buttons" sprite="stanceranged"/>
       <buttoninactive atlas="buttons" sprite="stanceranged_off"/>

       <formationent class="formationbox">
               <mincolspacing>1.3</mincolspacing>
               <maxcolspacing>1.8</maxcolspacing>
               <rowspaceratio>1.2</rowspaceratio>

               <tolerance>0.15</tolerance>
               <random>0.1 0.1</random>

               <minrows>4</minrows>
               <staggered>true</staggered>
               <shape>square</shape>
       </formationent>
</entity>

```

That's a fair amount of data! We'll copy it all into the new .xnt; since we're defining a new entity, we can't rely on the default entity's data the way we did last week. So what does it all do?

* "type" is the unique name that belongs to this stance and only this stance; when we create a new stance, we'll want to give it its own name. We'll call it the "longrangedsupport" stance.
* "class" tells the game what sort of being it is, whether it's a brigade or city or stance. There happens to be more than one type of stance class! The valid stance classes are "ambushstance", "battlelinestance", "brigadestance" and just "stance". All brigades need to be in one of the first three (probably the third if you don't want special ambush or battleline behaviours); if you're making a city or building stance, just go with stance. In our case, we're making a fairly standard brigade stance, so we'll keep it as "brigadestance". You may recognize this and type from last week, where they were attributes of the entity tag. They can be either attributes or their own sub-tags, depending on preference.
* "article" is the name of the string base for our stance. We'll want to create new strings for this so that we can differentiate between this stance and other ones. We could theoretically add them to cover.str, but it is recommended to create a seperate .str file in your mod's Resources/ folder for other strings than the cover to prevent them being loaded when the mod is disabled. So we'll create a seperate rangedstances.str, and in it put a `Stances::LongRangedSupport::NAME` and a `Stances::LongRangedSupport::TOOLTIP` string. Make sure to change our new .xnt's article tag to `Stances::LongRangedSupport` afterwards; it will look for the NAME and TOOLTIP substrings of the article's definition afterwards
* "objtype" is what type of object this is a stance for, brigades, forts, cities, cattlefarms, mines or farms. Note that "farm" here includes every resource building other than mines and cattlefarms!
* "sortorder" defines where this stance appears in the stance select menu. If you want it to be one of the first stances, have the number closer to 0; if you want it to be one of the last, have it higher. We want ours to be just after the default ranged stance, so we'll add 1 to it. Most default stances are in multiples of 10, allowing modded ones to easily find a gap to fit between.
* Each brigade has a stanceclass tag in its definition. Our stance's "brigadestanceclass" tags will look for any brigade with a matching stanceclass. For our example, we know that while brigades with the legion stance class have ranged abilities, they're primarily about melee, so we won't give them what we consider to be specialty ranged brigade behaviour. You can have as many or as few brigadestanceclass definitions as needed (it's recommended to have at least one if you want your stance to appear though!)
* "combatmovement" determines how the unit moves when engaged in melee combat. If the value is "skirmish" then they will always move towards the center of the enemy, while if the value is "formation" then the unit will try to advance forward only once it engages the enemy (generally used in battleline and phalanx stances).
* "attackstyle" determines if units in this stance close to fight in melee ("melee"), attack at a range ("ranged"), or attack at a range while moving ("rangedmobile").
* "grouprowscore" and "groupcolumnscore" control the order of units when automatically arranged into a group by the AI or when you select multiple units and drag out a formation. Units with a higher column score will be placed towards the centre of the group while units with higher row scores will be placed in the front of the group if there is more than one row.
* Each "attribute" defines a kind of bonuses this stance gets. An attribute definition (valid in stances, upgrades and in factions) consists of three basic parts; the attribute type, the operation, and the bonus. The attribute type is the attrtype attribute of the tag, and it says what it's a bonus to: there are a lot of types to choose from! You can find a full list in your game's Mod folder or here. The operation is the "op" attribute, which can be "add", "mult" or "bool". "add" adds a flat number to the stat, "mult" multiplies the stat by 1 + a number (so that 0.5 is +50%, or -0.1 is -10%) and bool is used to enable or disable certain global variables (more often in faction skills or upgrades to unlock certain options than in stances). We can have more (or less) than one "attribute" tag; in our case, let's get rid of the speed bonus to make units with this stance move a little slower, then add

```
<attribute attrtype="missilerange" op="mult">0.4</attribute>

```

to increase the range by 40%, and

```
<attribute attrtype="missiledamage" op="mult">-0.3/attribute>

```

to reduce the damage by 30%. Note that multipliers add with other multipliers; if you had an upgrade that increased ranged damage by 25%, the stance and the upgrade together would add together to have a total change of 5% rather than have the damage get multiplied by both 0.8 and 1.25.

* "buttonactive" and "buttoninactive" are atlas definitions like we saw the Histri's flag and logo were before, and can be made to point to a file in the same way. I've created some quick buttons for the new stance and will be editing them to `atlas="FILE:" sprite="Resources/longrange.png"` and `atlas="FILE:" sprite="Resources/longrange_off.png"`.
* "formationent" contains a lot of information on where the units in the brigade stand next to eachother; we don't particularly need to play with them here, but it's handy if you want to control how tightly-packed or spread out a brigade is.
* "reqattribute" isn't shown here, but would look like `"<reqattribute>stancesiege</reqattribute>"`. This is an attribute that the stance needs the object to have at non-zero (usually a boolean one unlocked by a faction skill) before it can be activated.

Those are all the changes I think we'll need for our mod. The final mod has two button images, a string file with `Stances::LongRangedSupport::NAME` and `Stances::LongRangedSupport::TOOLTIP` inside, and a .xnt that looks like this:

```
<entity type="longrangedsupport" class="brigadestance">

       <article>Stances::LongRangedSupport</article>

       <objtype>brigade</objtype>
       <sortorder>31</sortorder>

       <brigadestanceclass>javelineer</brigadestanceclass>
       <brigadestanceclass>rangedinfantry</brigadestanceclass>

       <combatmovement>skirmish</combatmovement>
       <attackstyle>ranged</attackstyle>

       <grouprowscore>40</grouprowscore>
       <groupcolumnscore>100</groupcolumnscore>

       <attribute attrtype="missilerange" op="mult">0.4</attribute>
       <attribute attrtype="missiledamage" op="mult">-0.3</attribute>

       <buttonactive atlas="FILE:" sprite="Resources/longrange.png"/>
       <buttoninactive atlas="FILE:" sprite="Resources/longrange_off.png"/>

       <formationent class="formationbox">
               <mincolspacing>1.3</mincolspacing>
               <maxcolspacing>1.8</maxcolspacing>
               <rowspaceratio>1.2</rowspaceratio>

               <tolerance>0.15</tolerance>
               <random>0.1 0.1</random>

               <minrows>4</minrows>
               <staggered>true</staggered>
               <shape>square</shape>
       </formationent>
</entity>

```

Hopefully you have a good idea what all that does now and are ready to experiment with your own stances!