Script AI Planner

The underlying battle scripting system provides support for the creation of ai planners, which are groups of units that are given high-level orders (e.g. defend this position/attack that unit) and left to carry it out in a semi-autonomous fashion. This functionality has also been exposed to the player in the past, allowing them to farm off control of their own units to the AI.

The script ai planner is a wrapper interface for this system. It allows a scripted ai group to be created, units to be added to it, and for that group to be given high-level orders, many of which are script-level constructs (e.g. multiple "move-to-position" commands being daisychained into a "patrol" command).

As the units in the script ai planner carry out their orders they do so under AI control, so they may decide to respond to live threats and opportunities.

Loaded in Battle loaded in battle
Back to top

Creation

script_ai_planner:new(string name, object units, [boolean debug mode])
Creates a script_ai_planner object. A script ai planner must be given a string name and at least one unit in either a script_units, script_unit or table argument. This unit/these units will be placed under the control of the script_ai_planner being created.

Parameters:

1

string

Name for script ai planner.

2

object

Unit(s) to be controlled by the script ai planner. Supported types are script_unit, script_units, or a numerically-index table of script units. Units may be added or removed at a later time.

3

boolean

optional, default value=false

Activate debug mode, for more output.

Returns:

  1. script_ai_planner

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 75

Back to top

Debug mode

script_ai_planner:set_debug(boolean debug mode)
Sets debug mode on this script_ai_planner.

Parameters:

1

boolean

debug mode

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 143

Back to top

Adding and removing Scriptunits

script_ai_planner:add_sunits(object scriptunits to add)
Adds one or more script_unit objects to the script_ai_planner. Each script_unit added must be in the same alliance as those already in the script_ai_planner.

Parameters:

1

object

Scriptunits to add. Supported argument types are a single script_unit, script_units or a table of script_unit objects.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 169

script_ai_planner:remove_sunits(object scriptunits to remove)
Removes one or more script_unit objects from the script_ai_planner.

Parameters:

1

object

Scriptunits to remove. Supported argument types are a single script_unit, script_units or a table of script_unit objects.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 268

script_ai_planner:count()
Returns the number of units currently belonging to this ai planner

Returns:

  1. number count

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 331

script_ai_planner:release()
Removes all units and releases control of them to the ai/player.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 340

Back to top

Tests

script_ai_planner:any_controlled_sunit_standing()
Returns true if any controlled unit is still alive/not-routed, false otherwise.

Returns:

  1. boolean any standing

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 376

script_ai_planner:get_centre_point()
Returns a vector position of the mean centre of all units this script_ai_planner controls.

Returns:

  1. vector centre position

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 391

Back to top

Moving

script_ai_planner:move_to_position(vector position)
Instructs the script_ai_planner to move its units to a position. This will supercede any previously-issued order.

Parameters:

1

vector

position

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 460

script_ai_planner:move_to_position_of_sunit(script_unit target sunit, function rout callback)
Instructs the script_ai_planner to move its units to the position of a supplied script_unit, tracking the target as it moves. The supplied script_unit may be allied with or enemies of the units controlled by this script_ai_planner.

Parameters:

1

script_unit

Target script_unit.

2

function

Function callback to call if the target script_unit routs or dies, or if the target unit's position is reached.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 514

script_ai_planner:move_to_force(object target force)
Instructs the script_ai_planner to move its units to the position of a supplied force, tracking the target as it moves. The supplied force may be allied with or enemies of the units controlled by this script_ai_planner.

Parameters:

1

object

Target force. May be a script_units collection or a table of script_unit objects.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 591

Back to top

Defending

A script_ai_planner may be instructed to defend a position, much as it can be instructed to move. Defend orders result in different formation postures being adopted and may result in the order being carried out with a different sense of urgency, compared to move orders.

script_ai_planner:defend_position(vector position to defend, radius radius in m)
Instructs the script_ai_planner to defend a position on the battlefield. Alongside a vector position a radius must be supplied, which sets how tightly bound to the position the controlled units are.

Parameters:

1

vector

position to defend

2

radius

radius in m

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 730

script_ai_planner:defend_position_of_sunit(script_unit sunit, radius radius, function callback)
Instructs the script_ai_planner to defend the position of a target script_unit, tracking this target as it moves. Alongside a target script_unit a radius must be supplied, which sets how tightly bound to the position the controlled units are.

Parameters:

1

script_unit

Scriptunit to defend.

2

radius

Radius in m.

3

function

Function to call if position of target script_unit is reached, or if it routs or dies.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 793

script_ai_planner:defend_force(script_unit sunit, radius radius)
Instructs the script_ai_planner to defend the position of a target military force, tracking this target as it moves. Alongside a target script_unit a radius must be supplied, which sets how tightly bound to the computed position the controlled units are.

Parameters:

1

script_unit

Scriptunit to defend.

2

radius

Radius in m.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 871

script_ai_planner:set_should_reorder([boolean should reorder])
Instructs the script_ai_planner to reissue defend and movement orders every 30 seconds. By default, this behaviour is enabled. Supply false as a single argument to disable it.

Parameters:

1

boolean

optional, default value=true

should reorder

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 885

Back to top

Attacking

script_ai_planner:attack_unit(unit target unit)
Instructs the script_ai_planner to attack a target unit. The target unit must be an enemy of those controlled by the script_ai_planner.

Parameters:

1

unit

target unit

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 909

script_ai_planner:attack_force(object enemy force)
Instructs the script_ai_planner to attack a target force. The target force is supplied as a script_units collection, or as a table of script_unit objects. Each of these must be an enemy of the units controlled by the script_ai_planner.

Parameters:

1

object

Enemy force. Must be a script_units collection or a table of script_unit objects.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 937

Back to top

Merging

script_ai_planner:merge_into(script_ai_planner target ai planner)
Instructs the script_ai_planner to merge into another. This script_ai_planner instructs its units to move towards those controlled by the target planner, and when it gets close it removes units from itself and gives them to the target planner. The threshold distance is 120m.

Parameters:

1

script_ai_planner

target ai planner

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 1084

Back to top

Patrolling

script_ai_planner:patrol(table waypoint list, object enemy force, [function completion callback])
Instructs the script_ai_planner to send its units on a patrol path along a series of waypoint positions. The units will move from point to point along the path, and move to engage any of the specified enemy units they find along the path. Should the enemy units retreat far enough from the path then the subject units will resume their patrol.

Parameters:

1

table

Numerically-indexed table of vector waypoint positions.

2

object

Enemy force to engage. This can be a script_units object or a table of script_unit objects.

3

function

optional, default value=nil

Function to call when the patrol is completed.

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 1175

script_ai_planner:set_patrol_defend_radius(number radius in m)
Sets the radius at which a script_ai_planner patrol will defend each waypoint along its patrol path. This influences how tightly bound the script ai planner arranges its defensive position at each destination, which is likely to influence how it moves. The default value is 100m.

Parameters:

1

number

radius in m

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 1271

script_ai_planner:set_patrol_enemy_distance(number radius in m)
Sets the distance at which a patrol will intercept an enemy it finds on its path. The distance will be the closest distance in m between any two units in the opposing forces. Set a higher number here to make the script_ai_planner more prone to intercept enemies at a greater distance. Note that this is the distance at which the script will instruct the script_ai_planner to intercept the enemy - the AI may have already responded of its own volition. The default value is 100m.

Parameters:

1

number

radius in m

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 1284

script_ai_planner:set_patrol_waypoint_distance(number radius in m)
Sets the distance between the controlled units and a patrol waypoint at the patrol will considered to have arrived at the waypoint. Set a lower number here to bind the patrol more tightly to its waypoints. The default value is 75.

Parameters:

1

number

radius in m

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 1298

script_ai_planner:set_perform_patrol_prox_test([boolean perform proximity test])
Instructs the script_ai_planner whether to perform its enemy proximity test when on a patrol. Be default it does, and it is this that causes the script_ai_planner to engage enemies. Disable the proximity test by supplying false as an argument to this function.

Parameters:

1

boolean

optional, default value=true

perform proximity test

Returns:

  1. nil

defined in ../working_data/script/_lib/lib_battle_script_ai_planner.lua, line 1311

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