The source files here are prepped for use with modmerger by sphere. I provide alternative instructions in case a modder wishes to install by manual edit.

In either case, for Warband you need to place the order_frame.brf file in the the "resource" INSTALL subdirectory for the mod you are adding these files to. Then add the line "load_module_resource order_frame" to the module.ini in the main install directory.

Modmerger
1. If you wish to start using modmerger, obtain if from https://www.mbrepository.com/file.php?id=2151. Install it according to the directions in its readme file.
2. Copy the formations_*.py, xgm_mod_options_header.py, and formAI_*.py files to the compile directory (where you installed modmerger).
3. Update the modmerger_options.py file as follows:
- change "version" to 1011 ONLY IF you are installing for M&B 1.011
- change "version" to 1143 ONLY IF you are installing for WFaS 1.143
- add "formations" and (if desired) "formAI" to the mods_active list. See included version of this file for a sample mods_active list.
4. Comment out Native AI from module_mission_templates if you are using formAI. See notes at start of formAI_missions_templates_*.py files. Plans now are to install an in-game switch to do this, but for now, you must edit.
5. Run build_module!

For updates to either mod, simply replace the formations_*.py or formAI_*.py files.


Manual Install
1. Append the constants listed in form*_constants.py files to module.constants.py.

2. Add the scripts from form*_scripts.py to module_scripts.py.

For the two battle_tactic* functions listed, you'll have to change the name of the originals by prefixing them with "orig_". That, is, they should end up named "orig_battle_tactic_init_aux" and "orig_battle_tactic_apply_aux".

Then add the line
(call_script, "script_player_order_formations", ":order"),#for formations
before the last command of the existing team_give_order_from_order_panel script (i.e. before the set_show_messages call).

3. For formations_presentations, add the "order_display" presentation to module_presentations.

Then place the contents of code_block1 before the call to script_update_order_flags_on_map for the "battle" presentation. As of version 1.143, this was line 10054.

4. Add to module_meshes the line
("order_frame", 0, "order_frame", 0, 0, 0, 0, 0, 0, 1, 1, 1)

5. Add the lists of triggers from form*_mission_templates.py to module_mission_templates.py right before the list of mission templates (i.e., right above where it says "mission_templates = [").

The formations triggers can then be added to any mission template by "adding" them to the end of the triggers list for that template, like so:
" ] + formations_triggers + AI_triggers"

6. If you use the AI in a mission template, comment out any competing Native AI triggers. In the lead_charge template, for example, there are two of them, but DO NOT comment out the morale/courage triggers inserted between them! See top of formAI_mission_templates_*.py for example.

For updates to either mod, you'll have to manually replace these code sections.


KNOWN CONFLICTS:
Player's initial formation conflicts with Caba'drin's prebattle orders. Comment out the section starting with message "Forming Ranks" in formations_mission_templates.

The Warband order menu extension is actually a presentation, so does not work with the battle display presentation. The one blanks out the other.


TWEAKS:
The constants source files conveniently have a number of settings that you can tweak. I recommend SAVING a copy of your tweaks against having them overwritten by a mod update.

formations_constants.py
formation_minimum_spacing: minimum number of centimeters between troops in formation
formation_minimum_spacing_horse_length: minimum number of centimeters between cavalry in formation
formation_minimum_spacing_horse_width: minimum number of centimeters between cavalry in formation
formation_start_spread_out: number of half-meters to add between troops in a NEW formation (for ease of maneuvering). Set to 0, all spreading out and coming together must be done by the player
formation_min_foot_troops: minimum number of troops for anything but cavalry formation
formation_min_cavalry_troops: minimum number of troops for cavalry formation
formation_native_ai_use_formation: set to 1 for Native AI to use formations, 0 otherwise
formation_delay_for_spawn: for use by M&B 1.011 which lacks ti_after_battle_start trigger
formation_reequip: flag TRUE to have troops reassess equipment when making a formation (may conflict with other autoequips in your mod)
formation_reform_interval: amount of time before formation adjusts for casualties, etc. Not working for longer intervals due to difficulty assessing division movement rates.
formation_rethink_for_formations_only: flag whether or not the rethink based on closest enemy will be restricted to agents in formation
command keys (M&B): keys for specifying each formation (or none/unform)
Third_Max_Weapon_Length: should be 1/3 of the length of the longest weapon in your mod
slots and positions: make sure they don't conflict with others used by your mod

formAI_constants.py
AI_long_range: centimeters archers will first set up position
AI_firing_distance: centimeters archers will try to maintain to target
AI_charge_distance: centimeters under which melee troops consider themselves under attack
AI_for_kingdoms_only: set to 1 for AI for kingdoms and deserters only, 0 otherwise
Percentage_Cav_For_New_Dest: percent of formation at destination required to select a new one. The higher you make this, the more cavalry will wait to form up before next action.
Hold_Point: ratio compared to largest team under which AI will take defensive
AI_Max_Reinforcements: number of waves of reinforcements your mod allows
AI_Replace_Dead_Player: flag TRUE to have AI take over player troops after player dies (if your mod allows the battle to continue)
AI_Poor_Troop_Level: level under which troops are considered "poor"
AI_Max_Size_Oblong_Formations: size over which division will form a square for maneuverability

positions: chosen for lack of use in Native scripts, but you may want to double-check that the longer-term ones don't conflict with any others in your specific mod.

In formations_scripts.py, you may want to change the switch in script_get_default_formation to change default formations (or add new ones for mod factions)

For Hold and Follow commands, default division placement around the player is: infantry to the left, cavalry to the right, and archers up front. Additional infantry divisions set up further left, additional cavalry further right, and additional ranged further forward. So, for example, if you would like TWO ranged divisions and want the one with thrown weapons further forward, make sure the archers are in Division 3 and the skirmishers in a Division 4-9.

Troop divisions that for whatever reason are NOT in formation will attempt to integrate with the other divisions in the "Hold" position. These divisions will maintain the same FACING that the player had unless the player checks the autorotate option in the Formations Options Menu under the Camp Menu.

The player may override default placement through the additional F2 Menu command to memorize division(s) placement relative to the player. So if you prefer, for example, your cavalry in front and your archers behind, rearrange these divisions during a quiet battle and then press F2-F7. Just make sure to stand toward the rear when memorizing and pad your new arrangement with plenty of space, as changes in division sizes, position rotations, and map borders affect the precision of memorized placement.

Player troops start every battle in Hold position around the player, utilizing either default or memorized placement and formation.

Placement is overridden for any division the player chooses to personally head through the Formations Options menu.

There are no assumptions about division type beyond the first (infantry). The system types them as the following:

- majority HEROES: majority skilled, Support; otherwise Bodyguard

- majority HORSES: majority with bows, Mounted Archers; otherwise regular Cavalry

- majority RANGED: with thrown weapon, Skirmishers; otherwise regular Ranged

- none of the above: majority with polearms, Polearms; otherwise regular Infantry

You have to bear this typing scheme in mind when composing divisions; otherwise an additional Infantry division may suddenly become some sort of Ranged. Also be aware that certain mods autoequip troops at the start of battle, thereby changing their type.

Hero-type divisions and more notably Skirmishers make infantry-type formations. Skirmishers will revert to type Infantry (and change default placement on "Hold" to the players LEFT instead of FORWARD) when they use up their ammunition.

Whenever a unit first forms a particular formation, troops may spread out for ease of forming up (depending on mod design). They may also change weapons as befitting their new positions within their formation. The mod also strips swing capability from stabbing weapons for infantry in formation, the better to use in close quarters. You may wish to experiment with formation spacing to see which works best for its majority weapon. Rhodoks with glaives, for example, benefit from a couple extra spaces to swing in.

The "ranks" command for archers puts them in a staggered line.

Cavalry will not make any formation other than the wedge.

Charge (and Dismount for cavalry) will undo a formation. The player may Advance multiple times to have a formation move toward the average position of the enemy. Or use the order panel or Hold-F1 to place them (or sweep them across the enemy in the case of the cavalry wedge).

Speaking of which, the Hold-F1 command has been expanded: when done on an enemy formation, player divisions will attack it. Infantry formations will advance into melee without breaking formation, cavalry will revert into a Native style charge after closing, and archers will advance until they start shooting. In any case, if the target is wiped out, the player division will return to the player.

If the player increases battle size beyond the WB maximum, there's a good chance large battles will stutter every second. The player may remove the stutter (and some AI functionality) on the mod option menu.


DETAILS:
Formations v. 4

1. Make level a multiplier rather than a bump?
2. Test if all cavalry unhorsed at start of mission**DEPRECATED BY DIVISION TYPING**
3. Complete design and implementation of battlegroup globals **DONE**
4. Infantry during setup move directly to destination**DONE**
5. Implement sphere's auto-options page**DONE**
6. Improve infantry stand under cavalry attack**DROPPED -- MAKES THINGS WORSE**
7. Infantry does not move on if # in melee a significant % of #infantry**DROPPED -- MAKES THINGS WORSE**
8. Look into setting stab-only in close formations**DONE**
9. Have player Charge use AI functions for attacking other battlegroups (w/o target acquisition for Cavalry)**DROPPED**
10. Have Hold-F1 select a target battlegroup over that spot**DONE**
11. Back to Mirathei formation implementation for aesthetics (continual form-up (sep trigger) around form leader (but keep rot), who alone has dest) **DONE**
12. Expand formations to all battlegroups **DONE**
13. Add formations to battle menu**DROPPED**
14. Bind formations to F4 key **DONE**