Descr formations ai.txt

WIP adding notes as things found, please add to. All comments so far relate to RTW version of file - notes of differences for M2TW if any need to be included

Overview

descr_formations_ai.txt is used in RTW/BI and M2TW and controls the formation used by the AI throughout battles and the default formation of units set up for the human player at the start of a battle. descr_formations.txt has a similar layout but only controls the formation of groups of units, and not entire armies.

In Rome: Total War, this file (apart from export_descr_units.txt) which modder could influence AI decision in battle. In Medieval2: Total War, modder could also influence AI's battle decision through modding of battle_config.xml and config_ai_battle.xml.

Most of file usage is explained at the top of the file itself and in comments, so far only additional pieces of information are being included here.

How Formations Works for AI?

AI would never understand what and how to selection formation strategically as whole. It could not change formation based on enemy's advantage. AI could only picks formations conditioned by what they have in the stack and how much what it has fit the score and priority modifier of the formation. And AI would change formation based on purpose flag they have at that moment in battle. And AI would always picked highest priority (by compare "total formation fitting score x formation priority" between each formation it could use in that purpose) formation it allowed to picked in that situation. If score are tie, AI would always pick the first one it encounter in file among all those tie formations.

Formations not only tell AI where to put each types of units into defined blocks as formation but also tell AI to set specific behavior of those blocks such as melee state and formation each units would take as much as how wide the front it would formed too. This would override normal decision by AI but could also be overridden by order setting by battle script.

Due to this, specific use formations should work as set of formations which shared specific factions/units composition at same fixed level of priority. This kind of formations are not good when working alone or there would be problem of army reformation and swap position again and again lead to confuse operation in battle.

Formation Purposes

In simplified battlefield, purpose flag for AI would be set by where their army are in relation to enemy deployment position. AI would draw zone in battlefield similar to sport like Rugby or Football from back zone of its deployment zone to midfield of battlefield, to its enemy's deployment zone. AI will always starts it deployment as "defend" formation due to position of them in the field. From battle start AI would start it behavior of attack or defend based on what they preconditioned in strategy map mode or preset inside descr_battle.txt (it is attacker or defender), if it conditioned as attacker, it would move their force toward enemy, if not, it would prepare for enemy attack. Once AI army approach mid line, AI would first change their formation from "defend" to "attack" formation. And once it move deep into enemy's deployment zone, AI would switch to more aggressive "pursue" formation to either finished enemy off or pursue fled enemies.

AI would not understand what those formation are using for if coder not assign purpose on each formations. And apart from basic "defend", "attack", and "pursue", there are many other purpose flags which exist for engine to deploy or for AI to act on specific occasion

Here are all possible purposes flag for descr_formations_ai.txt

defend ; for deployment, AI stay put in back line/fall back

attack ; for moment AI army move out of deployment zone in simple battle

pursue ; for moment AI army push into enemy's deployment zone

march ; for regroup, reform, and move along street in settlement

crossing_assault_force ; for bridge battle

crossing_assault_cover ; for bridge battle

crossing_block ; for bridge battle

crossing_defend ; for bridge battle

wall_assault_force ; for attacking wall

breach_defense_force ; for block breached wall, first use in M2TW but also valid flag in RTW/BI/ALEX

standard_siege_attacker_deployment ; for attacker deploy in siege battle

standard_ambush_defender_deployment ; for deploy in when army is under ambushed

alternate_ambush_defender_deployment ; for deploy in when army is under ambushed, ALEX only

anti_infantry ; M2TW only

anti_cavalry ; M2TW only

crossing_assault_buffer ; M2TW only

hiding ; M2TW only

settlement ; M2TW only

artillery ; M2TW only

plaza ; M2TW only

street ; M2TW only

There is one important usage of flag need to mention. In order for reinforcement army to deploy, it need formation that available for both "attack" and "defend" purpose flags (generally termed by DarthVader as "approach"). If formations that available for such purpose not exist, game would crash to desktop in reinforcement battles.

Priority, Availability, and Grouping Set of Formations

At the beginning of each formation, below purpose flags, would contain 2 important setting, "ai_priority" and "supported_factions".

"ai_priority" is setting for modifier for AI to weight its decision. This value would be multiply to formation fitting score and highest score would be chosen for deployment at the moment.

"supported_factions" is setting for which factions could use the formation. If this is not declared, all factions could use that formation. If which purpose flag has no formation available for that faction to deploy (either due to no such formation purposes declared in file or all of those formations with right purpose flag limited/blocked by "support_factions", game would crash to desktop.

Due to how formations operate, complicate battle formations with a lot of requirement or specific deployment would work well if formations grouping as swap set ("defend"/"approach"/"attack"/"pursue"/"march") with the same "ai_priority", "supported_factions" (more complicate formation set with different of those factors are possible but that only for those which have advanced understanding on how formation works) and similar "block specifications" pattern (see detail below). This to reduce or get rid of chance for AI to go into messy formation reform and disrupted formations and line as whole. Group compatibility could be test by deploy AI army as attacker with that specific formations set in custom battle while player army stand still wait for AI to approach your army AI would march toward player army and change formation along the way along sequence of "defend/approach (deploy)" -> attack -> pursue (if player stay in deployment area). If transition is not smooth means formation need to fix in some way or another.

Block Specifications

Note that blocks must start numbered 0 and be numbered consecutively, missing or re-using number causes message-less CTD when entering battle. This is quite easy to do accidentally so make sure you've set your formation to high priority and seen it working in battle before moving on to next one.

min_units and max_units

These conditions are to set minimum units and maximum units which required for the formation.

Although this setting is as simple as it is, It is important in case your mod has several available formation sets for each situation, number of units of specific type is important for limit condition for deployment of such formations so that other formations could be uses under other conditions. The biggest example of this is Sinuhet's formations system which majority part of right deployment depend on selecting formation to use based on number of spearmen or phalangites units exist in army in order to pick number choose deployment of single/double/triple line formations.

unit_type

unit_type		<UNIT_CLASS> <UNIT_ABILITY> <UNIT_CATEGORY> <PRIORITY>

Setting for unit types which could be used to fill into this box.

Available <UNIT_CLASS> (as defined in export_descr_units.txt)

light

heavy

spearmen

skirmish

Available <UNIT_ABILITY> (as we known valid for descr_formations_ai.txt)

phalanx (only phalanx capable units)

shield_wall (only shield_wall capable units)

general_unit (only general bodyguard units)

Available <UNIT_CATEGORY> ( as defined in export_descr_units.txt)

infantry

cavalry

siege

handler

ship

non_combatant

Available special unit types which not know for able to combined with other category (stand alone unit_type).

any (any unit, not restrict but require to declare as it could not empty)

non_phalanx_spear (only spearmen units which could not formed phalanx formation)

ranged_missile_infantry (only infantry which range attack ranged more than 75 in export_descr_units.txt)

chanting_screeching (only chanting or screeching capable units)

elephants (only elephants)

chariots (only chariots, regardless class)

heavy_chariots (only heavy class chariots)

light_pilum_infantry (only light infantry with precursor attack)

heavy_pilum_infantry (only heavy infantry with precursor attack)

spearmen_pilum_infantry (only spearmen infantry with precursor attack)

<PRIORITY> Priority for unit of this type to be fill in this block to fulfilled quota, higher priority mean more likely for this kind of units to be picked for this block than other type. It also influence to final priority score after when combine whole formation to compare with other formations. Priority could be set to be more than 1, and priority 0 here mean only dump this kind of units when no where else left to put them into.

More complex formations could have very specific requirement for each block but it is requirement for each formation to able to able to put every type of units into formation on paper. Could not fulfilled this condition would lead to exit with error during game start.

NOTE: Wrong setting of priority and sequence number of block between formation within its swap set could lead to cavalry on the wing to cut across main body of formation to reposition itself or units try to move to different block which lead to formation mess up and weaken formation solidarity.

default_melee_state

default_melee_state		<MELEE_STATE>

Setting of melee state of this block in formation. It could be overridden with command from battle script and specific AI order for unit but AI rarely change melee state on its own.

Possible basic commands, with effect if used on their own;

• skirmish - enables skirmish mode by default for any unit with the ability (missile and skirmish class units). Turns off fire_at_will default setting on archers.
• defend - sets units on guard mode, which also disables skirmish and fire at will setting for archers
• fire_at_will - units use fire_at_will (as usual) but archers are not on skirmish setting by default
• hold_fire - turns skirmish and fire at will off by default.
• engage_at_will - turns skirmish and fire at will off by default. Not sure of usage but it does seem to be a valid command see below.

Beware of inventing things:

• skirmish_off - also turns skirmish and fire at will off by default.. But so does:

			default_melee_state	blahblah

So unless CA actually coded in blahblah somewhere, that might just be games response to adding in things it doesn't understand, anything without clearly observable result needs careful checking to see if it is actually doing anything! Unlike those examples though hold_fire and engage_at_will do seem to work in combination, see below. Putting blahblah in combination with fire at will, stops the whole combined command working, eg fire at will stops working if used in combination with an invalid command.

Combinations:
Combining by use of commas or space separated commands does not work, however the following commands are visibly present in M2TW, showing that some commands combine two or more settings:

fire_at_will_and_defend_and_skirmish    
fire_at_will_and_engage_at_will_and_skirmish    
fire_at_will_and_skirmish   
fire_at_will_and_defend 
fire_at_will_and_engage_at_will 
defend_and_skirmish
hold_fire  
hold_fire_and_defend_and_skirmish    
hold_fire_and_engage_at_will_and_skirmish  
hold_fire_and_skirmish 
hold_fire_and_defend    
hold_fire_and_engage_at_will 
engage_at_will  
engage_at_will_and_skirmish 

Brief testing of some of the functions shows:

• fire_at_will_and_skirmish - works as expected and skirmish units appear with skirmish setting on by default and archers have fire_at_will default by on.
• fire_at_will_and_defend - also produces clearly observable result of fire at will and guard mode being selected by default.
• hold_fire_and_skirmish - clearly works as fire at will defaults off and skirmish on.
• fire_at_will_and_engage_at_will - gives fire at will on by default and skirmish off, but without guard mode activated. (Not sure what difference that generates over fire_at_will on its own).

unit_formation

unit_formation		<FORMATION>

Order units in the block to use formation as prescribe if they could. If unit could not use that formation, it would not change formation.

Available <FORMATION>

square

horde

schiltrom

shield_wall

phalanx

testudo

wedge

cantabrian_circle is not considered as formation but considered as unit ability so it could not use.

unit_density

unit_density		<close/loose>

Setting for density of units in this block.

min_unit_width and max_unit_width

min_unit_width		<width>
max_unit_width		<width>

Setting for minimum and maximum unit width in the block.

Note: min_unit_width is considered one of formation limitation condition. It could also lead to crash to desktop during loading of battle if unit could not find fitting formation which it could deploy due to min_unit_width limitation.

block_formation

block_formation		<square/column/line>

Setting for how unit line-up in the block. "line" is to line up along left-right axis. "column" is to line up along front-back axis. "Square" is to packing together in square shape.

Block Position

Normalized position mode

normalised_pos		<x,y>
normalised_rot		<degree>

Relative position mode

block_relative_pos		<block> <X axis distance(metre)>  <Z axis distance(metre)>

Setting of block position in formation's template could use either normalised mode or block relative position mode but could not mixed both positioning system together (you could not rotate block which deploy based on relative positioning).

NOTE: If deployment of block fall outside template, these problem could occurred. - Formation break down, unit operated individually, and general/cavalry units commit suicide by charge into main line of enemy (happened when formation switch during battle)

- Relative position must reference to its position to block that not empty, if it reference to empty block, it may lead to unit in that block breaking formation and attack/suicide into enemy's line too.

- Deployment phase error with units packing together at furthest front and those units could not move and units which could not deploy (as it stop at error point) would line up in column at the corner outside deployment zone (occurred if units could not deploy either on X axis or Z axis but general unit's block still able to deploy inside deployment zone.)

- Deployment phase error with camera fly off battlefield border instead zoom to the general and cause buggy skyward screen. (occurred if general unit's block fall outside deployment zone)

block_formation

inter_unit_spacing		<SPACING>

Setting of space between units within the block. Unit of spacing is in metre.

Block's Priority

priority		<PRIORITY>

Setting priority of the block inside formation. Units would be put into block with highest priority first and then follow up hierarchy based on priority of the block inside the formation.

Dummy Block

Apart from block setting by filling units, block could also able to formed virtually by set empty space to act as block for reference or put other blocks (up to 15 blocks) into single reference block.

External Links

• Modifying Formation AI version 2 comprehensive tutorial on modding formations by DARTH VADER
• Post explaining default melee tag by Sinuhet