Formations and AI Mods by Motomataru
v. 4
08/31/12

This kit contains two minimods by motomataru. It is presented in source code for addition to larger mods.

1. A formations mod, contained in files formations_*.py, xgm_mod_options_header.py, and order_frame.brf
2. An extension mod to replace Native AI, contained in files formAI_*.py
3. Also Native 1.153 source prepped with modmerger (see below). Of course, for other M&B versions, you'll need to prep that version of Native source with modmerger yourself.

The formations mod is an extensive reworking of the original simple interface by Mirathei. At a command, infantry can form in ranks by level, ranks by shield/weapon, wedge by level, or square. Cavalry can form a wedge. Formations follow all battlefield commands. Native AI is given the ability to make the same formations.

The formations AI replaces Native AI. It makes decisions based primarily on army size rather than army composition. Each type of unit has different objectives. The intent was to make the AI smarter AND more proactive.


INSTALLATION:
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 http://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)


QUICK PLAY GUIDE:
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**


ACKNOWLEDGEMENTS:
Mirathei - for original concept and code
Caba'drin - order menu interface, conversion to slots, weapon swing strip, division typing, much more
Sphere - modmerger installation system, auto options menu, and suggestions
Rubik - portions of his Improved Autoloot
Idibil - for enthusiastically cracking the whip in order to use these mods in Brytenwalda
Othr, Dunde, Treebeard - for understanding my code well enough to fix it
Brytenwalda betatesters
HokieBT - hosting AI prototype in SWC
Many players from the forum that made great suggestions, only a small portion of which I had time to implement


CHANGE LOG:
01/03/2011
-- Add Caba'drin's F4 order interface (Warband)
01/20/2011
-- Auto adjust infantryman equipment depending on placement in formation
-- Update order interface to use Native texture (Warning: resource has been renamed from caba_order to order_frame!)
-- AI: use actual weapon lengths instead of proxies (thanks Rubik!)
02/23/2011
-- Apply formations to other divisions (thanks Caba'drin!)
06/08/2011
-- AI: Fix AI not attacking unmounted player
-- AI: Have AI take over dead player troops
-- Fix player formations running off
-- Add new argument to agent_get_ammo
-- Fix menus after ESC (thanks Dunde)
06/26/2011
-- Implement division "Hold" positioning
11/21/2011
-- Implement Hold-F1 attack function
-- Improve appearance of formation on the move (Mirathei's implementation)
-- Bunch new slots, including nearest enemy troop agent slot
-- Keep archers from overrunning enemy infantry on reinforce
-- Address Native improper implementation of delay
-- AI: Alternate against enemy (they take turns!)
-- Address Native improper implementation of troop assignments to divisions
-- Load shields at start of battle for potential shield wall
-- Consolidate triggers to avoid conflicts
-- Rethinks after divisions reform
05/24/2012
-- Finish addition of swingless version of weapons that Caba'drin started
-- Add ability for player to join a formation
-- Add auto-menu for options
-- Add option to turn off formations
-- Add ability to memorize division positions relative to player
-- Fix centering for archers in staggered line
-- Start adding MP support
-- Fix script_get_formation_destination to handle divisions not in formation
-- Add in Caba'drin non-player agent division enforcement
-- AI: Switch some bases of decisions to armor (visible to troops) from level (not visible to troops)
-- Fix script_team_get_position_of_enemies to find closest of given type
-- Fix mission trigger timing
-- Have formations form on spot instead of by player
-- Add in Caba'drin code to use agent mode to find team faction, not mean
-- Add in Caba'drin code to use Hold-Over-There code instead of additional global
-- AI: Decrease archer fidgetiness in Jockey phase
-- AI: Fix cavalry charge when no archers
06/18/2012
-- Fix bug when formation destination not updated for unformed divisions placed around player
-- Change name slot_team_d0_in_melee to slot_team_d0_is_fighting (since it is used for archers firing)
-- Have back ranks drop blocks. I.e., they only attack, relying on front rank for protection
-- Drop division maintenance from script_cf_valid_formation_member (rely on the one in script_store_battlegroup_data)
-- Add average rotation to division/team tracking in script_store_battlegroup_data and script_battlegroup_get_position
-- Follow Native's lead in switching unhorsed cavalry to Division 0 infantry (to avoid conflicts that strand agents)
-- AI: Modify default formations in light of custom battle equipment
-- AI: reassemble scattered formations (to avoid having enemy AI attack a void at division average position)
-- AI: fix separation of ally troops from dead player troops
-- Make an info page for this mod
08/31/2012
-- Add WFaS implementation
-- Refine agent rethink with new behavior_target operation
-- Reduce formation wandering on reform
-- Fix infantry formation wandering off to join unhorsed cavalry that become infantry
-- Disallow swingless weapons from being left on field for player to pick up
-- Add option for autorotate of formations
-- Add option to better performance in large (>150) battles
-- Add option to turn off AI defense
-- Have back ranks respond to incursions
-- Hard code division type only for infantry, and only when not other type of infantry
-- Fix ranging problem for wedges
-- Consider angle of target division for ranging (effects: prevents circling, battles in shape of X's)
-- AI: Add consideration of horse armor for cavalry decisions
-- AI: Add mod tweak constant "poor troop" level
-- AI: Form more manageable square above a tweakable division size
-- AI: Make AI less easily provoked out of defensive mode
-- AI: Add archer/team leader retreat when battle is lost cause
-- AI: Prevent archers from overrunning enemy infantry when enemy division split (by reinforcement, etc)
-- AI: Drop infantry bum rush: too disruptive
-- AI: Make sure infantry clear archers when setting up in front of them
-- AI: Avoid ally/dead player division rotations when closing on enemy
-- AI: Restore cavalry charge
-- AI: Restore start of battle setup