A guide to the export_descr_units.txt file
By Mythic Commodore
This guide assumes that you have unpacked the data files using the method found here.
Once you have successfully unpacked the game's files, you may be wondering where to begin. A good starting point is the export_descr_unit file, or EDU. Here you will find the definitions that tell the game about all of the different soldiers and ships that you will encounter. First, a sample. We will be using Swiss Pikemen as our example. Here is the code which defines Swiss Pikemen:
type Swiss Pikemen dictionary Swiss_Pikemen ; Swiss Pikemen category infantry class spearmen voice_type Heavy accent German banner faction main_spear banner holy crusade soldier Swiss_Pikemen, 60, 0, 1 attributes sea_faring, hide_forest, very_hardy, can_withdraw, pike formation 1.2, 1.2, 2.4, 2.4, 8, square, phalanx stat_health 1, 0 stat_pri 14, 4, no, 0, 0, melee, melee_blade, piercing, spear, 25, 1 ;stat_pri_ex 0, 0, 0 stat_pri_attr spear, long_pike, spear_bonus_8 stat_sec 13, 3, no, 0, 0, melee, melee_blade, piercing, sword, 25, 1 ;stat_sec_ex 0, 0, 0 stat_sec_attr no stat_pri_armour 0, 5, 0, flesh ;stat_armour_ex 0, 0, 0, 0, 5, 0, 0, flesh stat_sec_armour 0, 0, flesh stat_heat 2 stat_ground 1, -2, 3, 2 stat_mental 11, impetuous, highly_trained stat_charge_dist 40 stat_fire_delay 0 stat_food 60, 300 stat_cost 1, 470, 185, 115, 90, 470, 4, 110 armour_ug_levels 0 armour_ug_models Swiss_Pikemen ownership slave ;unit_info 14, 0, 5
Looks daunting, huh? ;)
In reality, the file is simple once it gets broken down with each line being analysed. This guide is mainly a line-by-line breakdown, with a brief final section about the file and its limitations.
Part I - The Line-by-Line Breakdown
This part is intended to be more of a reference than anything else. It is not essential for anyone to know what each line does but it helps.
type Swiss Pikemen
type - This line defines the unit's internal lookup name, which is the name that the game uses in its files whenever it refers to a unit. Note that there are two internal lookup names, the other one being defined by the dictionary line. Each one is used in different applications but the names are usually identical, except for where the type line uses spaces, the dictionary line uses underscores. Which files use the type name?
These are the primary examples. As a general rule, if you see a file which references units and no underscores are used, then you must use the type name.
dictionary Swiss_Pikemen ; Swiss Pikemen
dictionary - This line defines the unit's other name, which is the name used in some other applications, including creating unit cards. Note the second part with the semicolon. A semicolon is called a comment. What putting a semicolon into your code will do is tell the game to ignore the rest of that line. So although we see:
- dictionary Swiss_Pikemen ; Swiss Pikemen
- dictionary Swiss_Pikemen
This is useful for inserting comments. In this case, the developers used it to tell you what the name of the unit is. It may seem self-explanatory, but some units have names which are not the same in the game's files as they are in-game. Retinue Longbowmen and Unhorsed Knights are good examples. Retinue Longbowmen are referred to as Dismounted Longbowmen, while Unhorsed Knights are Dismounted Crusader Knights. In that case, comments are useful.
category - This tells the game what troop type this particular unit is. This should be fairly self-explanatory. Options include:
Note that "wagons" like the Great Cross and the Carroccio Standard fall under the siege class. Although the game lists handler and non_combatant as also being options, those are most likely relics from Rome: Total War days, which should not work.
class - This tells the game what particular type of unit it is. Options include:
- light (used with infantry, cavalry, and ships)
- heavy (used with infantry, cavalry, and ships)
- missile (used with infantry, cavalry, and siege)
- spearmen (used with infantry)
Note that if you want to create a "wagon" like the Great Cross, you would have light as the class - an exception to the other members of the siege category, which only use the missile class.
voice_type - This determines the type of voice used by the unit. The options are:
- Light - Use this for ships or for troops that need a weaker-sounding voice (like Peasants)
- Heavy - Use this for troops requiring a stronger voice (like Feudal Knights)
- General - Use this for a general's bodyguard.
accent - This optional line will tell the unit to always speak with a particular accent. If this line is not present, then the unit will speak using the accent of the owning faction e.g. if it is owned by England, it will have an English accent. However, because of this line, Swiss Pikemen owned by England will have a German accent. Accents are described in the descr_sounds_accents.txt file and include:
banner faction main_spear
banner faction - This tells the game what sort of banner the unit is to use as its main banner - the really big one. The main banner also specifies the "mini banners" that show on the unit once you get experience, armour, and weapons upgrades. The available banners are described in the descr_banners_new.xml file and include:
Basically, the banner corresponds to the unit type. Of course, you are free to use whichever one you want since the only effect of this line is the banner of the unit. Note that since ships never appear on the battlefield, they do not have this line in their entries.
banner holy crusade
banner holy - A unit will have any of a number of secondary banners which indicate various things. For example, the king will have a "royal banner". This optional line defines whether or not the unit will have a secondary banner to indicate that it is on a holy war. Again, this is defined in the descr_banners_new.xml file If this line is present, then the unit will use the indicated banner as a secondary banner on a holy war. The options that you would probably want to use are:
If you do not include this line, then the unit will have no secondary banner when on a holy war.
soldier Swiss_Pikemen, 60, 0, 1
soldier - This is the first line with multiple values. They are all separated by commas and do different things. The first value (Swiss_Pikemen, 60, 0, 1) is the soldier model to use. This references an entry in the battle_models.modelsdb file, which determines how the unit looks. Changing this to a different entry will change the look. The second value (Swiss_Pikemen, 60, 0, 1) is the number of men in the unit. This is affected by your size settings in the options page. The smallest possible is 4, while the largest is 60. In the Kingdoms expansion, however, unit sizes can be increased up to 100! The third value (Swiss_Pikemen, 60, 0, 1) is used only with units with "extras" such as siege equipment. It tells the game how many of those to have. Here is an example from the Trebuchet line:
- soldier NE_Trebuchet_Crew, 16, 2, 1
The bolded 2 tells the game that there are 2 Trebuchets in a unit.
The fourth and final value (Swiss_Pikemen, 60, 0, 1) tells the mass of the soldiers. 1 is normal. Note that this does not affect cavalry, as their mass is determined by their mount. More on that later. What this means is the higher the number, the more your troops weigh. Troops with a higher mass may blast people back on the charge like cavalry do. While funny and good for supermen, you may want to leave your mass at 1.
attributes sea_faring, hide_forest, very_hardy, can_withdraw, pike
attributes - This line gives any special attributes that the unit may have. They can affect all sorts of things about the unit and what it does. Here is a list:
- sea_faring - This unit can board ships and cross the water. It does not affect the unit's ability to take advantage of landbridges. Also given to ships.
- hide_forest\hide_improved_forest - Allows the unit to hide in forests. Whether or not you include improved determines how good the unit is at hiding. This also has effects on the campaign map.
- hide_anywhere - The unit can hide anywhere on the battlefield, like Hashashim or Battlefield Assassins. This does not seem to affect the ability to hide on the campaign map.
- frighten_foot - The unit frightens foot soldiers.
- frighten_mounted - The unit frightens mounted soldiers.
- can_run_amok - The unit can "go crazy" like Elephants. It only works with mounted units.
- general_unit - The unit can be used as a general's bodyguard.
- general_unit_upgrade - Used in the Late General's Bodyguards. Of course, they never show up, so this seems to be useless.
- cantabrian_circle - The unit has the "Circle and Shoot" special ability. Note that a unit may only have one special ability.
- no_custom - The unit cannot be selected in custom battles, like Mounted Longbowmen.
- command - The unit provides a morale bonus to nearby units. I am unsure whether it works properly.
- mercenary_unit - This has two effects - the unit will only use the "merc" version of its model. This means that if I were to allow the French to train Swiss Pikemen, since they have this attribute, they would not wear the French blue and white unless I removed the attribute (or the grayish colouring that they usually have). The second effect is that the unit can now be hired as a mercenary - which is referenced in the descr_mercenaries.txt file.
- is_peasant - This unit only counts as half for public order purposes. This means that if I had a unit of 150 Swiss Pikemen but they had this trait, then they would only count as a garrison of 75 for the purpose of counting public order in the settlement.
- druid - The unit has the ability to chant. This raises your morale and lowers the enemy's morale.
- power_charge - Seems to improve the charging ability of a unit.
- free_upkeep_unit - The unit can be supported for free in a city, like militia.
- can_withdraw - The unit can withdraw from battles.
- hardy\very_hardy - The unit has more stamina than normal.
- can_formed_charge - The unit can form up and charge, like Mailed Knights.
- knight - The unit is a knight. This means that they get bonuses from the Jousting Lists and Tourney Field.
- gunpowder_unit - The unit uses a gunpowder weapon.
- start_not_skirmishing - Only for missile units. The unit has skirmish mode off by default instead of on.
- stakes - The unit can lay stakes before battle, like Longbowmen.
- fire_by_rank - They fire and rotate like Musketeers.
- cannot_skirmish - I think that this is Kingdoms-only. Disables skirmish for a missile unit.
- There are also various AI labels. These tell the computer how to use these units and are optional. The AI labels are - guncavalry, crossbow, gunmen, peasant, pike, incendiary (used on Naffatun), artillery, cannon, rocket, mortar, explode, standard (like Great Cross) and wagon_fort (which seems to be unused).
formation 1.2, 1.2, 2.4, 2.4, 8, square, phalanx
formation - The first two values are about formation spacing in close formation. The first one (1.2, 1.2, 2.4, 2.4, 8, square, phalanx) is the distance in meters side to side in close formation, and the other (1.2, 1.2, 2.4, 2.4, 8, square, phalanx) is front to back.
The next two numbers (1.2, 1.2, 2.4, 2.4, 8, square, phalanx) are the side-to-side and front-to-back spacing numbers in loose formation.
The fifth number (1.2, 1.2, 2.4, 2.4, 8, square, phalanx) shows the number of ranks by default. So Swiss Pikemen have 8 ranks by default.
The next two values (1.2, 1.2, 2.4, 2.4, 8, square, phalanx) are the formations. The first one is the default. The other one is the one that they can switch into. If there are two formations defined on this line, then one must be either square or horde (circle) and the other must be shield_wall, phalanx (Spear Wall), schiltrom, or wedge.
stat_health 1, 0
stat_health - The first value (1, 0) shows the number of hitpoints. Basically, units with x hitpoints must be dealt a killing blow x number of times. The second number (1, 0) is no longer used for anything.
stat_pri 14, 4, no, 0, 0, melee, melee_blade, piercing, spear, 25, 1
stat_pri - This details the character's primary weapon. If the unit has a missile weapon, then it is the primary weapon. The exception is artillery, where the crew's weapons are the primary weapon. The first number (14, 4, no, 0, 0, melee, melee_blade, piercing, spear, 25, 1) is the amount of damage that the weapon deals, which is capped at 63. The next number (14, 4, no, 0, 0, melee, melee_blade, piercing, spear, 25, 1) is the unit's charge bonus, extra damage dealt when charging. The next value (14, 4, no, 0, 0, melee, melee_blade, piercing, spear, 25, 1) is the type of ammunition that the unit fires. They are listed in descr_projectile.txt. Options include:
;stat_pri_ex 0, 0, 0
Lines with semicolons in front - Just ignore them. The game does.
stat_pri_attr spear, long_pike, spear_bonus_8
stat_pri_attr - This sets any special attributes of the primary weapon. If it does not have any, type "no". The available options are:
- ap - Armor piercing. Only counts half of the target's armor.
- thrown - The weapon is thrown
- area - The attack affects an area rather than a single target.
- launching - The attack launches people into the air.
- bp - Only valid for missile weapons. The attack can pass through people.
- spear - Gives bonuses against cavalry and bracing bonuses (is better on defense) but penalties against infantry.
- light_spear - Gives a bracing bonus.
- long_pike - Just put this in for any pike unit.
- spear_bonus_x - An attack bonus against cavalry. x = 2, 4, 6, 8, 10, or 12
- prec - This relic from Rome: Total War surprisingly seems to be totally functional. You add this to a missile unit's primary weapon to allow it to throw one volley to weaken the enemy and then charge into melee, like the Legionaries of Rome: Total War.
stat_sec 13, 3, no, 0, 0, melee, melee_blade, piercing, sword, 25, 1
;stat_sec_ex 0, 0, 0
stat_sec - This is for the unit's secondary weapon, if it has one. Use it just like the stat_pri section. If the unit doesn't have a secondary weapon, then do this:
stat_sec 0, 0, no, 0, 0, no, melee_simple, blunt, none, 25, 1
;stat_sec_ex 0, 0, 0
The game recognizes this as meaning that it has no secondary weapon.
stat_pri_armour 0, 5, 0, flesh
stat_pri_armour - This line defines the unit's armor. The first value (0, 5, 0, flesh) is the unit's armor rating. The second (0, 5, 0, flesh) is defense skill and the third (0, 5, 0, flesh) is shield. The last value (0, 5, 0, flesh) is all about the sound that a weapon makes when impacting the armor. Options are:
stat_sec_armour 0, 0, flesh
stat_sec_armour - This details the defense of any attached vehicles (artillery or wagons). The first value (0, 0, flesh) is the vehicle's armor rating, the second (0, 0, flesh) is the defense skill (weird, I know) and the third (0, 0, flesh) is the sound type. If it has no attached vehicle, then use the one here (flesh).
stat_heat - This is any extra fatigue that the unit gets in hot climates. The higher the number, the more fatigued the unit gets.
stat_ground 1, -2, 3, 2
stat_ground - This shows the unit's attack bonuses (or penalties) in certain climates. The first value (1, -2, 3, 2) is the modifier in scrub. The second (1, -2, 3, 2) is sand. The third (1, -2, 3, 2) is forest, and the fourth (1, -2, 3, 2) is snow.
stat_mental 11, impetuous, highly_trained
stat_mental - This details the mindset of the unit. The first value (11, impetuous, highly_trained) is the base morale level. The higher the number, the higher the base morale. The second value (11, impetuous, highly_trained) is the discipline. This is how well the unit responds to hits to their morale (a charge from the rear, the general's death, etc.) The higher the discipline, the better they respond. The available options are:
- 11, impetuous, highly_trained, lock_morale
stat_charge_dist - This is the distance at which a unit begins a charge. A larger number means a charge from farther away.
stat_fire_delay - In ranged units, the delay between volleys. A larger number means a larger delay.
stat_food 60, 300
stat_food - Obsolete
stat_cost 1, 470, 185, 115, 90, 470, 4, 110
stat_cost - This line determines all of the different florin values that the unit costs. The first value (1, 470, 185, 115, 90, 470, 4, 110) is how many turns the unit takes to build. The second (1, 470, 185, 115, 90, 470, 4, 110) is how many florins the unit costs in the campaign game. This does not affect how many florins it takes to recruit mercenaries. The third (1, 470, 185, 115, 90, 470, 4, 110) is how many florins per turn upkeep costs. The fourth (1, 470, 185, 115, 90, 470, 4, 110) is how much it costs to upgrade the unit's weapons. The fifth (1, 470, 185, 115, 90, 470, 4, 110) is how much it costs to upgrade the unit's armor. The sixth (1, 470, 185, 115, 90, 470, 4, 110) is the cost in custom battles. The seventh (1, 470, 185, 115, 90, 470, 4, 110) tells how many times you must purchase a unit in a custom battle before the price goes up. The last value (1, 470, 185, 115, 90, 470, 4, 110) tells the game how much it goes up by.
armour_ug_levels - This tells the game what the armor upgrades are. The Swiss Pikemen don't have any, so our example will be from one that does - Viking Raiders.
armour_ug_levels 0, 1, 2, 3
The first value is the default armor level. The next are ones that can be upgraded. This is by smithy level. So Viking Raiders can be upgraded at smithy levels 1-3. Fairly simple.
armour_ug_models - Fairly simple. Each value corresponds to an armor upgrade level and a model in the battle_models.modelsdb. For example, armour_ug_models Viking_Raiders, Viking_Raiders_ug1, Viking_Raiders_ug2, Viking_Raiders_ug3 Each of those means a different look for the unit at every one of the armor upgrade levels in the battle_models.modelsdb.
ownership - Basically, you can list factions or cultures here. Any faction or culture listed here can purchase the unit in "All" era custom battles. In addition, if you try to give a faction the ability to train a unit without giving it ownership, it will not work.
There are some lines that Swiss Pikemen do not have, because they do not need them. A quick guide on those:
officer - Another relic of Rome: Total War that works fine. Officer lines are put right after the soldier lines. You can have up to three. Each line adds an officer. Basically, an officer is an extra soldier. The way that it works is by referencing the battle_models.modelsdb for a model, for example, Catalans. If I was to add the line
- officer Catalans
after the soldier entry for Swiss Pikemen, so that it looked like:
type Swiss Pikemen
dictionary Swiss_Pikemen ; Swiss Pikemen category infantry class spearmen voice_type Heavy accent German banner faction main_spear banner holy crusade soldier Swiss_Pikemen, 60, 0, 1 officer Catalans attributes sea_faring, hide_forest, very_hardy, can_withdraw, pike formation 1.2, 1.2, 2.4, 2.4, 8, square, phalanx stat_health 1, 0 stat_pri 14, 4, no, 0, 0, melee, melee_blade, piercing, spear, 25, 1 ;stat_pri_ex 0, 0, 0 stat_pri_attr spear, long_pike, spear_bonus_8 stat_sec 13, 3, no, 0, 0, melee, melee_blade, piercing, sword, 25, 1 ;stat_sec_ex 0, 0, 0 stat_sec_attr no stat_pri_armour 0, 5, 0, flesh ;stat_armour_ex 0, 0, 0, 0, 5, 0, 0, flesh stat_sec_armour 0, 0, flesh stat_heat 2 stat_ground 1, -2, 3, 2 stat_mental 11, impetuous, highly_trained stat_charge_dist 40 stat_fire_delay 0 stat_food 60, 300 stat_cost 1, 470, 185, 115, 90, 470, 4, 110 armour_ug_levels 0 armour_ug_models Swiss_Pikemen ownership slave ;unit_info 14, 0, 5
There would be a Catalan with every unit of Swiss Pikemen, sort of like a mini-captain for that unit but without any morale consequences if he dies. You can have up to three officers per unit.
ship heavy warship
ship - This is only used for ships. The line goes right after the soldier line and is used to classify the ship. The available ship types are listed in descr_ship.txt and are:
- heavy warship
- light warship
engine - This tells the game what type of siege engine the unit has. The options are listed in descr_engines.txt and include:
mount heavy horse
mount - This tells the game what type of mount the animal uses. The available mounts are listed in descr_mount.txt and include:
- eastern armoured horse
- armoured horse
- barded horse
- mailed horse
- fast pony
- heavy horse
mount_effect elephant -4, camel -4
mount_effect - This lists the unit's attack bonuses (or penalties) against specific mount types. You may either list a specific mount (e.g. mailed horse) or a mount type (camel, elephant, or horse). Keep in mind that each unit may only have up to three mount effects.
stat_ter 12, 3, cow_carcass, 215, 3, siege_missile, artillery_mechanical, blunt, none, 25, 1
;stat_ter_ex 0, 0, 0
stat_ter_attr ap, bp, launching,
stat_ter - Use this just like you would stat_pri or stat_sec, but keep in kind that it is completely optional. In the game, the only use of this is to give the Trebuchets the ability to fire rotten cow carcasses.
era 0 england, scotland, france, hre, spain, portugal, milan, venice, papal_states, sicily,
era 1 england, scotland, france, hre, spain, portugal, milan, venice, papal_states, sicily,
era 2 scotland
era x - This allows you to put the unit on the custom battle rosters for different factions by era. Era 0 is Early, Era 1 is High, and Era 2 is Late. In this example, the unit is available to England, Scotland, France, The Holy Roman Empire, Spain, Portugal, Milan, Venice, The Papal States and Sicily in the Early and High Eras, but is only available to Scotland in the Late Era.
recruit_priority_offset - This Kingdoms-only line allows you to tell the AI how often to recruit this unit. A higher number means that the AI will "want" to recruit it more. It goes at the end of a definition.
move_speed_mod - This Kingdoms-only line allows you to set the unit's speed. Normally this is defined by the "skeleton" of the unit, which is basically the fighting style. But you can use this to modify the speed. A number above 1 means faster, and one below means slower.
Part II - Notes on the file
The EDU itself has limitations as well. One of these is that you can only have 500 units in the file at any given time. However if you run out of space, then here are some suggestions:
- There is a useless unit called Mounted Longbowmen. It is basically an English version of French Mounted Archers. Either enable it or delete it.
- Delete CE Wagon Fort and Gulay Gorod. They don't work at all.
- If you know how to edit the historical battles that came with the game, then you can take out the useless historical generals and replace them in the historical battles with generic generals.
- The following units have two identical versions. Delete the entries that are listed:
Note that for last method you will have to edit the descr_strat.txt as well as the descr_rebel_factions.txt and that this will corrupt all of your saves, so it really is a last resort.
If you are curious how to use this file to actually make new units, then keep an eye out for my
How to Make New Units.