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 Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation

AI planners are created with the alliance:create_ai_unit_planner function call on the battle_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 battle_unit objects may be specified as arguments. Each unit specified must belong to the battle_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 battle_unit objects.

Returns:

  1. nil

ai_planner:remove_units(... units)
Removes units from the ai planner. One or more battle_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 battle_unit objects.

Returns:

  1. nil
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

ai_planner:rush_position(battle_vector position, number radius)

Instructs units in the ai planner to move to and then 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

ai_planner:attack_unit(battle_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

battle_unit

target

Returns:

  1. nil

ai_planner:rush_unit(battle_unit target)

Instructs units in the ai planner to attack a specified unit and any other nearby enemies, without too much reforming. Other enemies encountered along the way will be intelligently reacted to.

Parameters:

1

battle_unit

target

Returns:

  1. nil

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

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

Returns:

  1. nil
Last updated 7/9/2024 11:45:05 AM