Modding Tutorial No. 6: Brigades

Hi everyone, welcome to the sixth entry of our modding blog, taking you through the creation of a new mod every week. Today we'll be going over new soldier types by giving the Illyric factions a melee cavalry unit to charge the enemy lines with, since by default they only have javelineer cavalry.

There are two entities involved in soldiers; the brigade and the unit. The brigade is the collection, the unit is the individual there are 40 of within that. Pretty much all gameplay-related stats are handled by the brigade; the unit stores the model, texture and animation references. Given that, we'll only need to be editing brigades to do our mod, using already-existing unit definitions to do it.

So for our example, we will go to https://pub.longbowgames.com/hegemony3/ and download a default brigade to use as a base. We'll copy brigade_gallic_cavalry.xnt into our new mod's Resources/ folder, rename it brigade_illyric_cavalry.xnt, and have a look inside. gallicLightCavalry brigade <!- stats -> 14 <!- xp award per unit killed (divided amongst its attackers when the unit routs or is completely killed) -> 100 <!- hitpoints per unit -> 20 <!- view distance in km (is doubled with full initiative) -> 60 <!- melee damage per day -> 0.4 <!- percentage defence against missile damage e.g. damage = missiledamage * (1 - missiledefence) -> 70        15         0         30         1.5 <!- tons of cargo carried per unit (for food or ore) -> 5 <!- number of days to recruit/replace the whole brigade -> 2 <!- number recruits needed from their home city to add a man to the unit -> 50 <!- cost per day while in a city/fort -> 8        18         Units::CavalryLight   80         50        gaul buildcavalry gaul latin etruscan greek sabellic illyric infantry <!- formation/stances -> cavalry  0.3 0.3        <!- size of the brigade -> 40         1.0        <!- brigade unit composition -> <!- format: unitclass, min, max, percentage -> 0 0 50 That's a lot of data! A lot of their functions can be guessed just by reading them, but we'll have to go through them all and tweak them to make what we want. gaul illyric and both will be able to build it. In our case, we only want the illyric factiongroup to be able to build these. buildcavalry buildheavy and we'd only be able to build if we had a stables AND a barracks, but I don't see that necessary for this particular mod. And that's all the tags we need to edit for our Illyric cavalry! More tags than the ones in this are possible in brigades: you can add  to make the unit move on water instead of land,   to make the unit unable to gain experience, or add ,   and   tags to give it a ranged attack (you can get a full list of tags at Brigade_Modding, but we're done with the current mod's brigade xnt.
 * "type" and "class" we've seen before, every entity needs this: type is the unique name of our new entity, we'll change that to "illyricCavalry", "class" is what lets the game know it's a brigade rather than a faction or a type of farm.
 * "constxpdefeat" is how much xp another brigade will get for defeating units in this brigade; this is on a per-unit basis, so if your brigade has 30 units in it, opponents could get up to 30 times the amount you enter here!
 * "consthitpoints" is how much damage a unit in this brigade will be able to take before dying. Since the illyrics were pretty good horsemen, I feel comfortable bumping it up a little over their etruscan counterparts.
 * "constviewrange" says how far the brigade can see.
 * "constmeleedamageperday" how much damage the brigade inflicts per week in combat ("perday" is a holdover from previous games, now it means "per week"). We'll reduced it a bit, for variety among units.
 * "constmissiledefence" what percent of missile damage is ignored; 0 means full damage, 0.5 means half damage, 1.0 means the unit is immune to missile damage. We'll reduce it a little to help balance the extra hitpoints.
 * "constchargestrength" and "constchargeblock" are numbers related to charging; the math about what these do will change in the next patch. For now, we'll strengthen charge strength a little to make up for the lost melee damage.
 * "constambush" and "constrecon" are about spotting or hiding from enemies, and will actually be REMOVED next patch, with new stats taking their place.
 * "constcargocapacityperunit" how much food each unit in the brigade can carry.
 * "constrecruitdays" and "constrecruitsperunit" are, when the brigade's still recruiting, how long it takes to get one unit and how many recruits it takes to do.
 * "constcostperday" how much gold per week keeping this brigade costs.
 * "constwalkspeed" and "construnspeed" how quickly the brigade moves.
 * "article" is the base for strings about this brigade; a ::TYPE is needed for the name of the brigade we usually see, and a ::TOOLTIP to describe it. This doesn't need to be unique, the game will automatically put the factiongroup before it when needed, so we can leave it at Units::LightCavalry and still get relevent strings.
 * "portrait" and "tagsprite" are references to images used for the unit's portrait and for the coloured tag that floats above their head when you look at them in the map; ordinarily I'd recommend a new portrait, which you can do by changing atlas to "FILE:" and sprite to the filename, but the gallic cavalry one still works here, considering we'll mostly be using mostly the same units.
 * "containerorder" determines whether these brigades will show up near the top or bottom of the list of brigades inside a city or fort you see when you look in that city or fort's unit tab; 0 shows up at the front, higher numbers show up later.
 * "buildbutton" is the image used in the build menu for this; again, normally it'd be wise to point to a new one, but the default gallic cavalry works here.
 * "buildmenuorder" is similar to containerorder, but for buttons in the build menu. Again, 0 for the front, higher numbers go later.
 * "buildfactiongroup" is a factiongroup able to recruit this brigade. You can have as few or as many as you like; the worker brigade is buildable by every playable faction group, while generals can't be built by any. If you want more than one buildfactiongroup, just have multiple tags, as follows:
 * "buildattribute" is the name of an attribute the city will need to have at above zero to recruit one of this brigade, in this case buildcavalry, an attribute given out by the Stables upgrade. Again, you can have as many as you like; if we wanted, we could add
 * "mercfactiongroup" determines which factiongroups this appears available as a mercenary for, and how likely it is to appear for each. The higher the weight, the better the odds that it'll appear instead of another brigade type. We'll leave all the factiongroups in so anyone can still hire illyricCavalry as mercenaries, but we should overhaul the weights to make them more likely to appear to illyrics and those near them and less likely to appear for more distant faction groups.
 * "soundstyle" determines what type of sounds this unit makes when fighting, moving, or just standing idle. It can be infantry, cart, ship, catapult, or cavalry. We'll want to change it to cavalry.
 * "stanceclass" will determine what stances are available to this brigade, only ones that match this stanceclass will appear.
 * "defaultstance" is the type of stance brigades have when first recruited.
 * "formationspace" is how much space each unit in this brigade needs.
 * "basenumunits" is how many units there are in a full brigade of this type. We'll lower this to 30 to keep the illyrics somewhat focused on mounted javelineers for their cavalry.
 * "miniatureent" is a reference to the mesh entity this brigade uses for a miniature. There's really only the one horse miniature, so we'll stick with that.
 * "miniatureradius" how big the mini is, no reason to change that either.
 * "unit" is a reference to which units are in this brigade, the type attribute saying which unit type the tag refers to. There can be more than one! If there is, the game will randomly decide each time it adds a unit to the brigade which of the sort it will look like. Having more than one unit is what gives us variety among certain brigades, such as the workers who are typically around 50% man, 40% woman and 10% horse (gender unspecified). The first number is a minimum number of such units required to be in the brigade; the second is a maximum that it'll refuse to create more than, and the third is the relative chance of each unit being this unit type.

So what remains? Nothing but setting up the mod's title and cover and uploading it! Settling on a brigade's stats is the only thing needed for a new brigade (assuming you rip off another's name and image files), so our mod doesn't need more than one file in the Resources/ folder.