Descr formations.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.txt is used in RTW/BI and M2TW for including preset formations for human player to apply as huristic. It allows for using in 8 "general_order" which could be use as command when player selects group of units in battle.

General Order

Different from descr_formations_ai.txt, descr_formations.txt does not using purpose flag and priority but using general_order instead.

general_order is preset slot for using by player in battle, game has 8 hardcoded slots below.

 general_order Group_Formation_Single_Line
 general_order Group_Formation_Sorted_Line
 general_order Group_Formation_Double_Line
 general_order Group_Formation_Sorted_Double_Line
 general_order Group_Formation_Missile_First_3_lines
 general_order Group_Formation_Infantry_First_3_Lines
 general_order Group_Formation_Cavalry_First_3_Lines
 general_order Group_Formation_Column

All these slot have localized text could be found in battle.txt with localization entries below

 {BMT_GROUP_FORMATION_1}
 {BMT_GROUP_FORMATION_2}
 {BMT_GROUP_FORMATION_3}
 {BMT_GROUP_FORMATION_4}
 {BMT_GROUP_FORMATION_5}
 {BMT_GROUP_FORMATION_6}
 {BMT_GROUP_FORMATION_7}
 {BMT_GROUP_FORMATION_8}

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.

Different from descr_formations_ai.txt, limit units in block here has no special role in limit formation usage. But beware that if group of units could not apply to formation that select for them, game would crush to desktop upon attempt to apply it.

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, game would crush to desktop when try to deploy the formation.

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.

Hardcoded

Formation name "simple_line" is hardcoded in RTW, it requires to exist in descr_formations.txt. Without this game would crush to desktop upon attempt to access group formation menu in battle.

 begin_formation simple_line