Module `ai`

Controls the Pilot AI.

AI Overview

Concept: Goal (Task) Based AI with additional Optimization

AI uses the goal (task) based AI approach with tasks scripted in Lua, additionally there is a task that is hard-coded and obligatory in any AI script, the 'control' task, whose sole purpose is to assign tasks if there is no current tasks and optimizes or changes tasks if there are.

For example: Pilot A is attacking Pilot B. Say that Pilot C then comes in the same system and is of the same faction as Pilot B, and therefore attacks Pilot A. Pilot A would keep on fighting Pilot B until the control task kicks in. Then he/she could run if it deems that Pilot C and Pilot B together are too strong for him/her, or attack Pilot C because it's an easier target to finish off then Pilot B. Therefore there are endless possibilities and it's up to the AI coder to set up.

Specification

AI will follow basic tasks defined from Lua AI script.

- if Task is NULL, AI will run "control" task
- Task is continued every frame
- Tasks can have subtasks which will be closed when parent task is dead.
-  "control" task is a special task that MUST exist in any given  Pilot

AI (missiles and such will use "seek")

- "control" task is not permanent, but transitory
- "control" task sets another task

"control" task is also run at a set rate (depending on Lua global "control_rate") to choose optimal behaviour (task)

Memory

The AI currently has per-pilot memory which is accessible as "mem". This memory is actually stored in the table pilotmem[cur_pilot->id]. This allows the pilot to keep some memory always accessible between runs without having to rely on the storage space a task has.

Garbage Collector

The tasks are not deleted directly but are marked for deletion and are then cleaned up in a garbage collector. This is to avoid accessing invalid task memory.

Note Nothing in this file can be considered reentrant. Plan accordingly.

TODO Clean up most of the code, it was written as one of the first

subsystems and is pretty lacking in quite a few aspects.

Functions

pushtask (func[, data])	Pushes a task onto the pilot's task list.
poptask ()	Pops the current running task.
taskname ()	Gets the current task's name.
taskdata ()	Gets the pilot's task data.
pushsubtask (func[, data])	Pushes a subtask onto the pilot's task's subtask list.
popsubtask ()	Pops the current running task.
subtaskname ()	Gets the current subtask's name.
subtaskdata ()	Gets the pilot's subtask target.
pilot ()	Gets the AI's pilot.
rndpilot ()	Gets a random pilot in the system.
nearestpilot ()	gets the nearest pilot to the current pilot
dist (pointer)	Gets the distance from the pointer.
dist2 (pointer)	Gets the squared distance from the pointer.
flyby_dist (pointer)	Gets the distance from the pointer perpendicular to the current pilot's flight vector.
minbrakedist (vel)	Gets the minimum braking distance.
isbribed (target)	Checks to see if target has bribed pilot.
instantJump ()	Checks to see if pilot can instant jump.
ismaxvel ()	Checks to see if pilot is at maximum velocity.
isstopped ()	Checks to see if pilot is stopped.
isenemy (target)	Checks to see if target is an enemy.
isally (target)	Checks to see if target is an ally.
haslockon ()	Checks to see if pilot has a missile lockon.
hasprojectile ()	Checks to see if pilot has a projectile after him.
scandone ()	Checks to see if pilot has finished scanning their target.
accel ([acceleration=1.])	Starts accelerating the pilot.
turn (vel)	Starts turning the pilot.
face (target[, invert=false[, compensate=false]])	Faces the target.
careful_face (target)	Gives the direction to follow in order to reach the target while minimizating risk.
aim (target)	Aims at a pilot, trying to hit it rather than move to it.
iface (target)	Maintains an intercept pursuit course.
dir (target)	calculates the direction that the target is relative to the current pilot facing.
idir (target)	Calculates angle between pilot facing and intercept-course to target.
drift_facing ()	Calculate the offset between the pilot's current direction of travel and the pilot's current facing.
brake ([prefer_reverse=false])	Brakes the pilot.
nearestspob ()	Get the nearest friendly spob to the pilot.
spobfrompos (pos)	Get the nearest friendly spob to a given position.
rndspob ()	Get a random spob.
landspob ([only_friend=false])	Get a random friendly spob.
land ([pnt])	Lands on a spob.
hyperspace ([sys])	Tries to enter hyperspace.
sethyptarget (target)	Sets hyperspace target.
nearhyptarget ()	Gets the nearest hyperspace target.
rndhyptarget ()	Gets a random hyperspace target.
canHyperspace ()	Gets whether or not the pilot can hyperspace.
hyperspaceAbort ()	Has the AI abandon hyperspace if applicable.
relvel ()	Gets the relative velocity of a pilot.
follow_accurate (target[, radius=0.[, angle=0.[, Kp=10.[, Kd=20.[, method]]]]])	Computes the point to face in order to `follow another pilot using a PD controller.`
face_accurate (pos, vel[, radius=0.[, angle=0.[, Kp=10.[, Kd=20.]]]])	Computes the point to face in order to follow a moving object.
stop ()	Completely stops the pilot if it is below minimum vel error (no insta-stops).
dock (target)	Docks the ship.
combat ([val=true])	Sets the combat flag.
settarget (target)	Sets the pilot's target.
setasterotarget (int, int)	Sets the pilot's asteroid target.
getgatherable (float)	Gets the closest gatherable within a radius.
gatherablepos (int)	Gets the pos and vel of a given gatherable.
weapset (id[, type=true])	Sets the active weapon set, fires another weapon set or activate an outfit.
hascannons ()	Does the pilot have cannons?
hasturrets ()	Does the pilot have turrets?
hasfighterbays ()	Does the pilot have fighter bays?
hasafterburners ()	Does the pilot have afterburners?
getenemy ([radius=nil])	Gets the nearest enemy.
hostile (target)	Sets the enemy hostile (basically notifies of an impending attack).
getweaprange ([id[, level=-1]])	Gets the range of a weapon.
getweapspeed ([id[, level=-1]])	Gets the speed of a weapon.
getweapammo ([id])	Gets the ammo of a weapon.
canboard (target)	Checks to see if pilot can board the target.
relsize (target)	Gets the relative size (ship mass) between the current pilot and the specified target.
reldps (target)	Gets the relative damage output (total DPS) between the current pilot and the specified target.
relhp (target)	Gets the relative health (total shields and armour) between the current pilot and the specified target
board ()	Attempts to board the pilot's target.
refuel ()	Attempts to refuel the pilot's target.
settimer (timer[, time=0])	Sets a timer.
timeup (timer)	Checks a timer.
set_shoot_indicator (value)	Set the seeker shoot indicator.
set_shoot_indicator ()	Access the seeker shoot indicator (that is put to true each time a seeker is shot).
distress (msg)	Sends a distress signal.
getBoss ()	Picks a pilot that will command the current pilot.
setcredits (num)	Sets the pilots credits.
messages ()	Returns and clears the pilots message queue.
stealth ([enable=true])	Tries to stealth or destealth the pilot.

Functions

pushtask (func[, data])

Pushes a task onto the pilot's task list.

Parameters:

func string Name of function to call for task.
data Data to pass to the function. Supports any lua type. (optional)

poptask ()

Pops the current running task.

taskname ()

Gets the current task's name.

Returns:

string

taskdata ()

Gets the pilot's task data.

Returns:

The pilot's task data or nil if there is no task data.

Parameters:

func string Name of function to call for task.
data Data to pass to the function. Supports any lua type. (optional)

popsubtask ()

Pops the current running task.

subtaskname ()

Gets the current subtask's name.

Returns:

string

subtaskdata ()

pointer Vec2 or Pilot

Returns:

number

dist2 (pointer)

Gets the squared distance from the pointer.

Parameters:

pointer Vec2 or Pilot

Returns:

number

flyby_dist (pointer)

Gets the distance from the pointer perpendicular to the current pilot's flight vector.

Parameters:

pointer Vec2 or Pilot

Returns:

number

minbrakedist (vel)

Gets the minimum braking distance.

braking vel ==> 0 = v - a*dt add turn around time (to initial vel) ==> 180.*360./cur_pilot->turn add it to general euler equation x = v * t + 0.5 * a * t^2 and voila!

I hate this function and it'll probably need to get changed in the future

Parameters:

vel number Velocity of target.

Returns:

number Minimum braking distance.
number Time it will take to brake.

isbribed (target)

Checks to see if target has bribed pilot.

Parameters:

target Pilot

Returns:

boolean

instantJump ()

Checks to see if pilot can instant jump.

Returns:

boolean

ismaxvel ()

Checks to see if pilot is at maximum velocity.

Returns:

boolean

isstopped ()

boolean

hasprojectile ()

Checks to see if pilot has a projectile after him.

Returns:

boolean

scandone ()

Checks to see if pilot has finished scanning their target.

Returns:

boolean

accel ([acceleration=1.])

Starts accelerating the pilot.

Parameters:

acceleration number Fraction of pilot's maximum acceleration from 0 to 1. (default 1.)

turn (vel)

Starts turning the pilot.

Parameters:

vel number Directional velocity from -1 to 1.

face (target[, invert=false[, compensate=false]])

Faces the target.

Parameters:

target Pilot, Vec2 or number Target to face. Can be either a pilot, position (Vec2), or an orientation (number representing angle in radians).
invert boolean Invert away from target. (default false)
compensate boolean Compensate for velocity? (default false)

Returns:

number

Usage:

```
ai.face( a_pilot ) -- Face a pilot
```

ai.face( a_pilot, true ) -- Face away from a pilot

ai.face( a_pilot, nil, true ) -- Compensate velocity facing a pilot

careful_face (target)

Gives the direction to follow in order to reach the target while minimizating risk.

This method is based on a simplified version of trajectory generation in mobile robotics using the potential method.

The principle is to consider the mobile object (ship) as a mechanical object. Obstacles (enemies) and the target exert attractive or repulsive force on this object.

Only visible ships are taken into account.

Parameters:

target Pilot, Vec2 or number Target to go to.

Returns:

number

aim (target)

Aims at a pilot, trying to hit it rather than move to it.

This method uses a polar UV decomposition to get a more accurate time-of-flight

Parameters:

target Pilot or Asteroid The pilot to aim at

Returns:

number

iface (target)

Maintains an intercept pursuit course.

Parameters:

target Pilot or Vec2 Position or pilot to intercept.

Returns:

number

dir (target)

calculates the direction that the target is relative to the current pilot facing.

Parameters:

target Pilot or Vec2 Position or pilot to compare facing to

Returns:

number

idir (target)

Calculates angle between pilot facing and intercept-course to target.

Parameters:

target Pilot or Vec2 Position or pilot to compare facing to

Returns:

number

drift_facing ()

Calculate the offset between the pilot's current direction of travel and the pilot's current facing.

Returns:

number

brake ([prefer_reverse=false])

Brakes the pilot.

Parameters:

prefer_reverse boolean Whether or not to prefer reverse thrusters. (default false)

Returns:

boolean

nearestspob ()

Get the nearest friendly spob to the pilot.

Returns:

Spob or nil

spobfrompos (pos)

Get the nearest friendly spob to a given position.

Parameters:

pos vec2 Position close to the spob.

Returns:

Spob or nil

rndspob ()

JumpPoint or nil

rndhyptarget ()

Gets a random hyperspace target.

Returns:

JumpPoint or nil

canHyperspace ()

Gets whether or not the pilot can hyperspace.

Returns:

boolean

hyperspaceAbort ()

Has the AI abandon hyperspace if applicable.

relvel ()

Gets the relative velocity of a pilot.

Returns:

number

follow_accurate (target[, radius=0.[, angle=0.[, Kp=10.[, Kd=20.[, method]]]]])

Computes the point to face in order to

    follow another pilot using a PD controller.

Parameters:

target Pilot The pilot to follow
radius number The requested distance between p and target (default 0.)
angle number The requested angle between p and target (radians) (default 0.)
Kp number The first controller parameter (default 10.)
Kd number The second controller parameter (default 20.)
method string Method to compute goal angle (optional)

Returns:

The point to go to as a vector2.

face_accurate (pos, vel[, radius=0.[, angle=0.[, Kp=10.[, Kd=20.]]]])

Computes the point to face in order to follow a moving object.

Parameters:

pos vec2 The objective vector
vel vec2 The objective velocity
radius number The requested distance between p and target (default 0.)
angle number The requested angle between p and target (radians) (default 0.)
Kp number The first controller parameter (default 10.)
Kd number The second controller parameter (default 20.)

Returns:

The point to go to as a vector2.

stop ()

Completely stops the pilot if it is below minimum vel error (no insta-stops).

dock (target)

Docks the ship.

Parameters:

target Pilot Pilot to dock with.

combat ([val=true])

Sets the combat flag.

Parameters:

val boolean Value to set flag to. (default true)

settarget (target)

Sets the pilot's target.

Parameters:

target Pilot to target.

setasterotarget (int, int)

Sets the pilot's asteroid target.

Parameters:

int ast Id of the asteroid to target.
int ast Id of the asteroid to target.

getgatherable (float)

Gets the closest gatherable within a radius.

Parameters:

float rad Radius to search in.

Returns:

int i Id of the gatherable or nil if none found.

gatherablepos (int)

Gets the pos and vel of a given gatherable.

Parameters:

int id Id of the gatherable.

Returns:

vec2 pos position of the gatherable.
vec2 vel velocity of the gatherable.

weapset (id[, type=true])

Sets the active weapon set, fires another weapon set or activate an outfit.

Parameters:

id number ID of the weapon set to switch to or fire.
type boolean true to activate, false to deactivate. (default true)

hascannons ()

Does the pilot have cannons?

Returns:

boolean

hasturrets ()

Does the pilot have turrets?

Returns:

boolean

hasfighterbays ()

Does the pilot have fighter bays?

Returns:

boolean

hasafterburners ()

Does the pilot have afterburners?

Returns:

boolean

getenemy ([radius=nil])

Gets the nearest enemy.

Parameters:

radius Vec2 Distance to search for an enemy. If not specified tries to find the nearest enemy. (default nil)

Returns:

Pilot or nil

hostile (target)

Sets the enemy hostile (basically notifies of an impending attack).

Parameters:

target Pilot Pilot to set hostile.

getweaprange ([id[, level=-1]])

Gets the range of a weapon.

Parameters:

id number Optional parameter indicating id of weapon set to get range of, defaults to selected one. (optional)
level number Level of weapon set to get range of. (default -1)

Returns:

number

getweapspeed ([id[, level=-1]])

Gets the speed of a weapon.

Parameters:

id number Optional parameter indicating id of weapon set to get speed of, defaults to selected one. (optional)
level number Level of weapon set to get range of. (default -1)

Returns:

number

getweapammo ([id])

Gets the ammo of a weapon.

Parameters:

id number Optional parameter indicating id of weapon set to get ammo of, defaults to selected one. (optional)

Returns:

number

canboard (target)

Checks to see if pilot can board the target.

Parameters:

target Pilot Target to see if pilot can board.

Returns:

boolean

relsize (target)

Gets the relative size (ship mass) between the current pilot and the specified target.

Parameters:

target Pilot The pilot whose mass we will compare.

Returns:

number

reldps (target)

Gets the relative damage output (total DPS) between the current pilot and the specified target.

Parameters:

target Pilot The pilot whose DPS we will compare.

Returns:

number

relhp (target)

Gets the relative health (total shields and armour) between the current pilot and the specified target

Parameters:

target Pilot The pilot whose health we will compare.

Returns:

number

board ()

Attempts to board the pilot's target.

Returns:

boolean

refuel ()

Attempts to refuel the pilot's target.

Returns:

boolean

settimer (timer[, time=0])

Sets a timer.

Parameters:

timer number Timer number.
time number Number of seconds to set timer to. (default 0)

timeup (timer)

Checks a timer.

Parameters:

timer number Timer number.

Returns:

boolean

set_shoot_indicator (value)

Set the seeker shoot indicator.

Parameters:

value boolean to set the shoot indicator to.

set_shoot_indicator ()

Access the seeker shoot indicator (that is put to true each time a seeker is shot).

Returns:

boolean

distress (msg)

Sends a distress signal.

Parameters:

msg string or nil Message to send or nil.

getBoss ()

Picks a pilot that will command the current pilot.

Returns:

Pilot or nil

setcredits (num)

Sets the pilots credits. Only call in create().

Parameters:

num number Number of credits.

messages ()

Returns and clears the pilots message queue.

Returns:

{{},...}

stealth ([enable=true])

Tries to stealth or destealth the pilot.

Parameters:

enable boolean Whether or not to try to stealth the pilot. (default true)

Returns:

boolean

Naev Lua API

Modules

Module ai

Functions

Functions

Parameters:

Returns:

Returns:

See also:

Parameters:

Returns:

Returns:

See also:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Parameters:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Parameters:

Parameters:

Parameters:

Returns:

Module `ai`