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
accel ([acceleration=1.]) | Starts accelerating the pilot. |
aim (target) | Aims at a pilot, trying to hit it rather than move to it. |
board () | Attempts to board the pilot's target. |
brake ([prefer_reverse=false]) | Brakes the pilot. |
canHyperspace () | Gets whether or not the pilot can hyperspace. |
canboard (target) | Checks to see if pilot can board the target. |
careful_face (target) | Gives the direction to follow in order to reach the target while minimizating risk. |
combat ([val=true]) | Sets the combat flag. |
dir (target) | calculates the direction that the target is relative to the current pilot facing. |
dist (pointer) | Gets the distance from the pointer. |
dist2 (pointer) | Gets the squared distance from the pointer. |
distress (msg) | Sends a distress signal. |
dock (target) | Docks the ship. |
drift_facing () | Calculate the offset between the pilot's current direction of travel and the pilot's current facing. |
face (target[, invert=false[, compensate=false]]) | Faces the target. |
face_accurate (pos, vel[, radius=0.[, angle=0.[, Kp=10.[, Kd=20.]]]]) | Computes the point to face in order to follow a moving object. |
flyby_dist (pointer) | Gets the distance from the pointer perpendicular to the current pilot's flight vector. |
follow_accurate (target[, radius=0.[, angle=0.[, Kp=10.[, Kd=20.[, method]]]]]) |
Computes the point to face in order to
|
gatherablepos (int) | Gets the pos and vel of a given gatherable. |
getBoss () | Picks a pilot that will command the current pilot. |
getenemy ([radius=nil]) | Gets the nearest enemy. |
getgatherable (float) | Gets the closest gatherable within a radius. |
getweapammo ([id]) | Gets the ammo of a weapon. |
getweaprange ([id]) | Gets the range of a weapon set. |
getweaprangemin ([id]) | Gets the minimum range of a weapon set. |
getweapspeed ([id]) | Gets the speed of a weapon. |
hasafterburners () | Does the pilot have afterburners? |
hascannons () | Does the pilot have cannons? |
hasfighterbays () | Does the pilot have fighter bays? |
haslockon () | Checks to see if pilot has a missile lockon. |
hasprojectile () | Checks to see if pilot has a projectile after him. |
hasturrets () | Does the pilot have turrets? |
hostile (target) | Sets the enemy hostile (basically notifies of an impending attack). |
hyperspace ([sys]) | Tries to enter hyperspace. |
hyperspaceAbort () | Has the AI abandon hyperspace if applicable. |
idir (target) | Calculates angle between pilot facing and intercept-course to target. |
iface (target) | Maintains an intercept pursuit course. |
instantJump () | Checks to see if pilot can instant jump. |
isally (target) | Checks to see if target is an ally. |
isbribed (target) | Checks to see if target has bribed pilot. |
isenemy (target) | Checks to see if target is an enemy. |
ismaxvel () | Checks to see if pilot is at maximum velocity. |
isstopped () | Checks to see if pilot is stopped. |
land ([pnt]) | Lands on a spob. |
landspob ([only_friend=false]) | Get a random friendly spob. |
messages () | Returns and clears the pilots message queue. |
minbrakedist (vel) | Gets the minimum braking distance. |
nearestpilot () | gets the nearest pilot to the current pilot |
nearestspob () | Get the nearest friendly spob to the pilot. |
nearhyptarget () | Gets the nearest hyperspace target. |
outfitOffAll () | Tries to turn off all outfits. |
pilot () | Gets the AI's pilot. |
popsubtask () | Pops the current running task. |
poptask () | Pops the current running task. |
pushsubtask (func[, data]) | Pushes a subtask onto the pilot's task's subtask list. |
pushtask (func[, data]) | Pushes a task onto the pilot's task list. |
refuel () | Attempts to refuel the pilot's 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 |
relsize (target) | Gets the relative size (ship mass) between the current pilot and the specified target. |
relvel () | Gets the relative velocity of a pilot. |
rndhyptarget () | Gets a random hyperspace target. |
rndpilot () | Gets a random pilot in the system. |
rndspob () | Get a random spob. |
scandone () | Checks to see if pilot has finished scanning their target. |
set_shoot_indicator () | Access the seeker shoot indicator (that is put to true each time a seeker is shot). |
set_shoot_indicator (value) | Set the seeker shoot indicator. |
setasterotarget (int, int) | Sets the pilot's asteroid target. |
setcredits (num) | Sets the pilots credits. |
sethyptarget (target) | Sets hyperspace target. |
settarget (target) | Sets the pilot's target. |
settimer (timer[, time=0]) | Sets a timer. |
spobfrompos (pos) | Get the nearest friendly spob to a given position. |
stealth ([enable=true]) | Tries to stealth or destealth the pilot. |
stop () | Completely stops the pilot if it is below minimum vel error (no insta-stops). |
subtaskdata () | Gets the pilot's subtask target. |
subtaskname () | Gets the current subtask's name. |
taskdata () | Gets the pilot's task data. |
taskname () | Gets the current task's name. |
timeup (timer) | Checks a timer. |
turn (vel) | Starts turning the pilot. |
weapset (id[, type=true]) | Sets the active weapon set, fires another weapon set or activate an outfit. |
Functions
- accel ([acceleration=1.])
-
Starts accelerating the pilot.
Parameters:
- acceleration number Fraction of pilot's maximum acceleration from 0 to 1. (default 1.)
- 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
The offset from the target aiming position (in
radians).
- board ()
-
Attempts to board the pilot's target.
Returns:
-
boolean
true if was able to board the target.
- brake ([prefer_reverse=false])
-
Brakes the pilot.
Parameters:
- prefer_reverse boolean Whether or not to prefer reverse thrusters. (default false)
Returns:
-
boolean
Whether braking is finished.
- canHyperspace ()
-
Gets whether or not the pilot can hyperspace.
Returns:
-
boolean
Whether or not the pilot can hyperspace.
- canboard (target)
-
Checks to see if pilot can board the target.
Parameters:
- target Pilot Target to see if pilot can board.
Returns:
-
boolean
true if pilot can board, false if it can't.
- 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
Angle offset in radians.
- combat ([val=true])
-
Sets the combat flag.
Parameters:
- val boolean Value to set flag to. (default true)
- 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
The facing offset to the target (in radians).
- dist (pointer)
-
Gets the distance from the pointer.
Parameters:
- pointer Vec2 or Pilot
Returns:
-
number
The distance from the pointer.
- dist2 (pointer)
-
Gets the squared distance from the pointer.
Parameters:
- pointer Vec2 or Pilot
Returns:
-
number
The squared distance from the pointer.
- distress (msg)
-
Sends a distress signal.
Parameters:
- msg string or nil Message to send or nil.
- dock (target)
-
Docks the ship.
Parameters:
- target Pilot Pilot to dock with.
- drift_facing ()
-
Calculate the offset between the pilot's current direction of travel
and the pilot's current facing.
Returns:
-
number
Offset (radians)
- 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
Absolute angle offset in radians.
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
- 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.
- flyby_dist (pointer)
-
Gets the distance from the pointer perpendicular to the current
pilot's flight vector.
Parameters:
- pointer Vec2 or Pilot
Returns:
-
number
offset_distance
- 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.
- 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.
- getBoss ()
-
Picks a pilot that will command the current pilot.
Returns:
-
Pilot or nil
- 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
- 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.
- 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
The ammo of the weapon set in the [0,1] range.
- getweaprange ([id])
-
Gets the range of a weapon set.
Parameters:
- id number Optional parameter indicating id of weapon set to get range of, defaults to selected one. (optional)
Returns:
-
number
The range of the weapon set.
- getweaprangemin ([id])
-
Gets the minimum range of a weapon set.
Parameters:
- id number Optional parameter indicating id of weapon set to get range of, defaults to selected one. (optional)
Returns:
-
number
The range of the weapon set.
- getweapspeed ([id])
-
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)
Returns:
-
number
The range of the weapon set.
- hasafterburners ()
-
Does the pilot have afterburners?
Returns:
-
boolean
True if the pilot has afterburners.
- hascannons ()
-
Does the pilot have cannons?
Returns:
-
boolean
True if the pilot has cannons.
- hasfighterbays ()
-
Does the pilot have fighter bays?
Returns:
-
boolean
True if the pilot has fighter bays.
- haslockon ()
-
Checks to see if pilot has a missile lockon.
Returns:
-
boolean
Whether the pilot has a missile lockon.
- hasprojectile ()
-
Checks to see if pilot has a projectile after him.
Returns:
-
boolean
Whether the pilot has a projectile after him.
- hasturrets ()
-
Does the pilot have turrets?
Returns:
-
boolean
True if the pilot has turrets.
- hostile (target)
-
Sets the enemy hostile (basically notifies of an impending attack).
Parameters:
- target Pilot Pilot to set hostile.
- hyperspace ([sys])
-
Tries to enter hyperspace.
Parameters:
- sys System System to jump to (optional)
Returns:
-
number or nil
Distance if too far away.
- hyperspaceAbort ()
- Has the AI abandon hyperspace if applicable.
- 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
The facing offset to intercept-course to the target (in
radians).
- iface (target)
-
Maintains an intercept pursuit course.
Parameters:
- target Pilot or Vec2 Position or pilot to intercept.
Returns:
-
number
The offset from the proper intercept course (in
radians).
- instantJump ()
-
Checks to see if pilot can instant jump.
Returns:
-
boolean
Whether the pilot can instant jump.
- isally (target)
-
Checks to see if target is an ally.
Parameters:
- target Pilot
Returns:
-
boolean
Whether the target is an ally.
- isbribed (target)
-
Checks to see if target has bribed pilot.
Parameters:
- target Pilot
Returns:
-
boolean
Whether the target has bribed pilot.
- isenemy (target)
-
Checks to see if target is an enemy.
Parameters:
- target Pilot
Returns:
-
boolean
Whether the target is an enemy.
- ismaxvel ()
-
Checks to see if pilot is at maximum velocity.
Returns:
-
boolean
Whether the pilot is at maximum velocity.
- isstopped ()
-
Checks to see if pilot is stopped.
Returns:
-
boolean
Whether the pilot is stopped.
- land ([pnt])
-
Lands on a spob.
Parameters:
- pnt Spob spob to land on (optional)
Returns:
-
boolean
Whether landing was successful.
- landspob ([only_friend=false])
-
Get a random friendly spob.
Parameters:
- only_friend boolean Only check for ally spobs. (default false)
Returns:
-
Spob or nil
- messages ()
-
Returns and clears the pilots message queue.
Returns:
-
{{},...}
Messages.
- 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.
- nearestpilot ()
-
gets the nearest pilot to the current pilot
Returns:
-
Pilot or nil
- nearestspob ()
-
Get the nearest friendly spob to the pilot.
Returns:
-
Spob or nil
- nearhyptarget ()
-
Gets the nearest hyperspace target.
Returns:
-
JumpPoint or nil
- outfitOffAll ()
- Tries to turn off all outfits.
- pilot ()
-
Gets the AI's pilot.
Returns:
-
Pilot
The AI's pilot.
- popsubtask ()
- Pops the current running task.
- poptask ()
- Pops the current running task.
- pushsubtask (func[, data])
-
Pushes a subtask onto the pilot's task's subtask list.
Parameters:
- func string Name of function to call for task.
- data Data to pass to the function. Supports any lua type. (optional)
- 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)
- refuel ()
-
Attempts to refuel the pilot's target.
Returns:
-
boolean
true if pilot has begun refueling, false if it hasn't.
- 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
A number from 0 to 1 mapping the relative DPSes.
- 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
A number from 0 to 1 mapping the relative healths.
- 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
A number from 0 to 1 mapping the relative masses.
- relvel ()
-
Gets the relative velocity of a pilot.
Returns:
-
number
Relative velocity.
- rndhyptarget ()
-
Gets a random hyperspace target.
Returns:
-
JumpPoint or nil
- rndpilot ()
-
Gets a random pilot in the system.
Returns:
-
Pilot or nil
- rndspob ()
-
Get a random spob.
Returns:
-
Spob or nil
- scandone ()
-
Checks to see if pilot has finished scanning their target.
Returns:
-
boolean
Whether the pilot has scanned their target.
- set_shoot_indicator ()
-
Access the seeker shoot indicator (that is put to true each time a
seeker is shot).
Returns:
-
boolean
true if the shoot_indicator is true.
- set_shoot_indicator (value)
-
Set the seeker shoot indicator.
Parameters:
- value boolean to set the shoot indicator to.
- 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.
- setcredits (num)
-
Sets the pilots credits. Only call in create().
Parameters:
- num number Number of credits.
- sethyptarget (target)
-
Sets hyperspace target.
Parameters:
- target Jump Hyperspace target
Returns:
-
Vec2 Where to go to jump
- settarget (target)
-
Sets the pilot's target.
Parameters:
- target Pilot to target.
- settimer (timer[, time=0])
-
Sets a timer.
Parameters:
- timer number Timer number.
- time number Number of seconds to set timer to. (default 0)
- spobfrompos (pos)
-
Get the nearest friendly spob to a given position.
Parameters:
- pos vec2 Position close to the spob.
Returns:
-
Spob or nil
- 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
Whether or not the stealthing or destealthing
succeeded.
- stop ()
- Completely stops the pilot if it is below minimum vel error (no insta-stops).
- subtaskdata ()
-
Gets the pilot's subtask target.
Returns:
-
The pilot's target ship identifier or nil if no target.
See also:
- subtaskname ()
-
Gets the current subtask's name.
Returns:
-
string
The current subtask name or nil if there are no
subtasks.
- taskdata ()
-
Gets the pilot's task data.
Returns:
-
The pilot's task data or nil if there is no task data.
See also:
- taskname ()
-
Gets the current task's name.
Returns:
-
string
The current task name or nil if there are no tasks.
- timeup (timer)
-
Checks a timer.
Parameters:
- timer number Timer number.
Returns:
-
boolean
Whether time is up.
- turn (vel)
-
Starts turning the pilot.
Parameters:
- vel number Directional velocity from -1 to 1.
- 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)