AI Planners

AI planners give battle scripts the ability to group units together under AI control, and to give that group high-level orders such as ai_planner:defend_position or ai_planner:attack_unit and have those units work together to intelligently carry out the order.

This code interface is wrapped in script by the script_ai_planner interface, and it is recommended that client scripts use that interface rather than this one as it provides some ease-of-use improvements and additional wrapped behaviours.        

It is not recommended to try and use ai planners during siege battles, as the siege battle ai system has a tendency to override unit behaviour - see a battle ai programmer for more details.

Loaded in Battle loaded in battle
Back to top

Creation

AI planners are created with the alliance:create_ai_unit_planner function call on the alliance interface. Once one is created and returned, units belonging to that alliance may be added to it and orders issued to them with the functions below.

Back to top

Adding and Removing Units

ai_planner:add_units(... units)
Adds units to the ai planner. One or more unit objects may be specified as arguments. Each unit specified must belong to the alliance from which the planner was created. If units are added to the planner after an order has been issued then those units will start following that order automatically.

Parameters:

1

...

One or more unit objects.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptAIObjective.cpp, line 141

ai_planner:remove_units(... units)
Removes units from the ai planner. One or more unit objects may be specified as arguments. Each unit specified must have previously been added to the planner with ai_planner:add_units.

Parameters:

1

...

One or more unit objects.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptAIObjective.cpp, line 180

Back to top

Orders

ai_planner:defend_position(battle_vector position, number radius)

Instructs units in the ai planner to adopt a defensive formation, then move to and defend a specified position from any enemies, staying within a specified radius.

Parameters:

1

battle_vector

Position which the units will defend.

2

number

Radius in m around the position in which the units will roam.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptAIObjective.cpp, line 216

ai_planner:attack_unit(unit target)

Instructs units in the ai planner to adopt an offensive formation and then attack a specified unit and any other nearby enemies. Other enemies encountered along the way will be intelligently reacted to.

Parameters:

1

unit

target

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptAIObjective.cpp, line 249

ai_planner:move_to_position(battle_vector position)

Instructs units in the ai planner to adopt an movement formation and then move to a specified position.

Parameters:

1

battle_vector

position

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptAIObjective.cpp, line 278

ai_planner:clear_objective()
Clears the current order of the ai planner.

Returns:

  1. nil

defined in ../../common/EmpireBattle/Source/BattleScript/BattleScriptAIObjective.cpp, line 308

Last updated 25/08/2021 12:07:51