Module `pilot`

Lua bindings to interact with pilots.

This will allow you to create and manipulate pilots in-game.

An example would be:

 p = pilot.add( "Llama", "Miner" ) -- Create a Miner Llama
 p:setFriendly() -- Make it friendly

Functions

__eq (p, comp)	Checks to see if pilot and p are the same.
__tostring (p)	Gets the pilot's current (translated) name or notes it is inexistent.
accel (p)	Gets the accel of a pilot.
actives (p[, sort=false])	Gets the active outfits and their states of the pilot.
add (shipname, stringfaction, param[, pilotname[, parameters]])	Adds a ship with an AI and faction to the system (instead of a predefined fleet).
addEnergy (p, energy)	Adds (or subtracts) energy to a pilot.
addHealth (p[, armour=0.[, shield=0.]])	Adds health to a pilot.
ai (p)	Gets the pilot's AI.
ainame (p)	Gets the name of the task the pilot is currently doing.
areAllies (p, t)	Checks to see if two pilots are allies.
areEnemies (p, t)	Checks to see if two pilots are enemies.
armour (p[, absolute=false])	Gets the pilot's armour.
attack (p[, pt])	Makes the pilot attack another pilot.
autoweap (p)	Gets if a pilot is using automatically set weapon sets.
board (p, pt)	Makes the pilot board another pilot.
brake (p)	Makes the pilot brake.
broadcast (p, msg[, ignore_int=false])	Makes the pilot broadcast a message.
calcStats (p)	Forces a recomputation of the pilots' stats.
canHyperspace (p)	Checks to see if the pilot can currently hyperspace (as in has target jump and is in range).
canSpawn ()	Returns if pilots can can spawn naturally in the current system.
cargoAdd (p, cargo, quantity)	Tries to add cargo to the pilot's ship.
cargoFree (p)	Gets the free cargo space the pilot has.
cargoHas (p, cargo)	Checks to see how many tonnes of a specific type of cargo the pilot has.
cargoJet (p, cargo, quantity)	Tries to remove a cargo from a pilot's ship and jet it into space.
cargoList (p)	Lists the cargo the pilot has.
cargoRm (p, cargo, quantity)	Tries to remove cargo from the pilot's ship.
changeAI (p, newai)	Changes the pilot's AI.
choosePoint (f[, i=false[, g=false]])	Returns a suitable jumpin spot for a given pilot.
clear ()	Clears the current system of pilots.
clearSelect (fac)	Removes all pilots belonging to a faction from the system.
clone (p)	Clones a pilot.
collisionTest (p, t)	Tests to see if two ships collide.
colour (p)	Gets the pilot's colour based on hostility or friendliness to the player.
colourChar (p)	Gets the pilot's colour character based on hostility or friendliness to the player.
comm (p, target, msg[, param1=false[, raw=false]])	Sends a message to the target or player if no target is passed.
control (p[, enable=true[, Whether=true if changing modes]])	Sets manual control of the pilot.
cooldown (p)	Gets a pilot's cooldown state.
cooldownCycle (p)	Makes the pilot do an instant full cooldown cycle.
credits (p[, cred=0])	Handles the pilots credits
damage (p, dmg[, disable=0.[, penetration=0.[, type="raw"[, shooter=nil]]]])	Damages a pilot.
destealth (p)	Tries to make the pilot stealth.
detectedDistance (p)	Gets the distance that a pilot can be currently detect at.
dir (p)	Gets the pilot's direction.
disabled (p)	Gets the disabled state of a pilot.
distress (p, attacker)	Sends a distress single from the pilot.
effectAdd (p, name[, Duration=-1[, Scaling=1]])	Adds an effect to a pilot.
effectClear (p, keepdebuffs, keepbuffs, keepothers)	Clears the effect on a pilot.
effectHas (p, Name)	Checks to see if a player has an instance of an effect active.
effectRm (p, name, all)	Removes an effect from the pilot.
effects (p)	Gets the effects on a pilot.
energy (p[, absolute=false])	Gets the pilot's energy.
exists (p)	Checks to see if pilot is still in the system and alive.
explode (p)	Removes a pilot as if it exploded.
face (p, target[, towards=false])	Makes the pilot face a target.
faction (p)	Gets the pilot's faction.
fillAmmo (p)	Fills up the pilot's ammo.
flags (p[, name])	Gets the pilot's flags.
follow (p, pt[, accurate=false])	Makes the pilot follow another pilot.
followers (p, hidefighters)	Get all of a pilots followers.
fuel ()	Gets the amount of fuel the pilot has.
gather ()	Makes the pilot gather stuff.
get (factions[, disabled=false])	Gets the pilots available in the system by a certain criteria.
getAllies (pilot[, dist=infinity[, pos=pilot.pos[, ignore_range=false[, disabled=false[, fighters=false]]]]])	Gets friendly pilots to a pilot (or faction) within a certain distance.
getEnemies (pilot[, dist=infinity[, pos=pilot.pos[, ignore_range=false[, disabled=false[, fighters=false]]]]])	Gets hostile pilots to a pilot (or faction) within a certain distance.
getInrange (pos, d[, disabled=false])	Gets visible pilots to a pilot within a certain distance.
getVisible (pilot[, disabled=false])	Gets visible pilots to a pilot.
hailPlayer (p[, enable=true])	Marks the pilot as hailing the player.
hasIllegal (p, f)	Checks to see if the pilot has illegal stuff to a faction.
health (p[, absolute=false])	Gets the pilot's health.
hookClear (p)	Clears the pilot's hooks.
hostile (p)	Returns whether the pilot is hostile to the player.
hyperspace (p[, sys[, noshoot=false]])	Tells the pilot to hyperspace.
id (p)	Gets the ID of the pilot.
idle (p)	Checks to see if the pilot is idle.
inrange (p, target)	Checks to see if a target pilot is in range of a pilot.
intrinsicGet (p[, name=nil][, internal=false], Value)	Allows getting an intrinsic stats of a pilot, or gets all of them if name is not specified.
intrinsicReset ()	Resets the intrinsic stats of a pilot.
intrinsicSet (p, name, value, replace)	Allows setting intrinsic stats of a pilot.
invincible (p)	Gets whether or not a pilot is invincible.
isStopped (p)	Checks to see if a pilot is stopped.
kill (p)	Kills a pilot.
knockback (p, m, v[, p=p:pos()[, e=1.]])	Knocks back a pilot.
land (p[, spob[, noshoot=false]])	Tells the pilot to land
leader (p)	Gets a pilots leader.
lockon (p)	Gets the lockons on the pilot.
mass (p)	Gets the mass of a pilot.
memory (p)	Gets a pilots memory table.
mothership (p)	Gets a pilots mothership (only exists for deployed pilots).
moveto (p, v[, brake=1[, compensate=1]])	Makes the pilot move to a position.
msg (p, receiver, type[, data])	Sends a message to another pilot.
name (p)	Gets the pilot's current (translated) name.
nav (p)	Gets the nav target of the pilot.
navJump (p)	Gets the nav jump target of the pilot.
navJumpSet (p, jp)	Sets the hyperspace navigation target for the pilot.
navSpob (p)	Gets the nav spob target of the pilot.
navSpobSet (p, spb)	Sets the spob target for the pilot.
outfitAdd (p, outfit[, q=1[, bypass_cpu=false[, bypass_slot=false]]])	Adds an outfit to a pilot.
outfitAddIntrinsic (p, o)	Adds an intrinsic outfit to the pilot.
outfitAddSlot (p, outfit, slot[, bypass_cpu=false[, bypass_slot=false]])	Adds an outfit to a pilot by slot name.
outfitGet (p, id)	Gets a pilot's outfit by ID.
outfitHasSlot (p, name)	Checks to see if a pilot has a specific named slot.
outfitInitSlot (p, slot)	Makes an outfit run its initialization script.
outfitMessageSlot (p, slot, type[, data])	Sends a message to an outfit.
outfitReady (p, id)	Sees if an outfit is ready to use.
outfitRm (p, outfit, q)	Removes an outfit from a pilot.
outfitRmIntrinsic (p, o)	Removes an intrinsic outfit from the pilot.
outfitRmSlot (p, slot)	Removes an outfit from a pilot's named slot.
outfitSlot (p, slot)	Checks to see outfit a pilot has in a slot.
outfitToggle (p, id[, activate=false])	Toggles an outfit.
outfits (p)	Gets a mapping of outfit slot IDs and outfits of a pilot.
outfitsEquip (p, o, Whether)	Equips a pilot with a set of outfits.
outfitsList (p[, What=nil[, skip_locked=false]])	Gets the outfits of a pilot.
outfitsReset (p)	Resets the pilot's outfit and timers.
points (p)	Gets the points the pilot costs.
poptask (p)	Pops the current task from the pilot's AI.
pos (p)	Gets the pilot's position.
pushtask (p, func, data)	Pushes a new task to the pilot's AI.
radius (p)	Gets the rough radius of the ship, useful for collision stuff.
refuel (p, target[, amount=100])	Tries to refuel a pilot.
rename (p, name)	Changes the pilot's name.
render (p)	Renders the pilot to a canvas
renderTo (p, The)	Renders the pilot to a canvas
reputation (p)	Get the reputation the player has with the pilot's faction.
rm (p)	Removes a pilot without explosions or anything.
runaway (p, tp[, destination.=false])	Makes the pilot runaway from another pilot.
scandone ()	Checks to see if a pilot is done scanning its target.
setActiveBoard (p[, state=true])	Allows the pilot to be boarded when not disabled.
setBribed (p[, state=true])	Makes pilot act as if bribed by the player.
setCooldown (p[, state=true])	Starts or stops a pilot's cooldown mode.
setDir (p, dir)	Sets the pilot's direction.
setDisable (p[, nopermanent=false])	Disables a pilot.
setEnergy (p, energy[, absolute=false])	Sets the energy of a pilot.
setFaction (p, faction)	Sets the pilot's faction.
setFriendly (p[, state=true])	Controls the pilot's friendliness towards the player.
setFuel (p, f)	Sets the fuel of a pilot.
setHealth (p[, armour=current armour[, shield=current shield[, stress=0]]])	Sets the health of a pilot.
setHealthAbs (p[, armour=current armour[, shield=current shield[, stress=current stress]]])	Sets the health of a pilot in absolute value.
setHide (p, state)	Sets the pilot's hide status.
setHilight (p[, state=true])	Makes pilot stand out on radar and the likes.
setHostile (p[, state=true])	Controls the pilot's hostility towards the player.
setInvincPlayer (p[, state=true])	Sets the pilot's invincibility status towards the player.
setInvincible (p[, state=true])	Sets the pilot's invincibility status.
setInvisible (p, state)	Sets the pilot's invisibility status.
setLeader (p, leader)	Set a pilots leader.
setNoBoard (p[, noboard=true])	Sets the ability to board the pilot.
setNoClear (p[, state])	Enables or disables making the the pilot exempt from pilot.clear().
setNoDeath (p[, state=true])	Makes it so the pilot never dies, stays at 1.
setNoDisable (p[, disable=true])	Sets the ability of the pilot to be disabled.
setNoJump (p[, state=true])	Enables or disables a pilot's hyperspace engine.
setNoLand (p[, state])	Enables or disables landing for a pilot.
setNoRender (p, state)	Sets the pilot's norender status.
setPos (p, pos)	Sets the pilot's position.
setSpeedLimit (p, speed)	Limits the speed of a pilot.
setTarget (p, t)	Sets the pilot target of the pilot.
setTargetAsteroid (p, a)	Sets the pilot's asteroid target.
setVel (p, vel)	Sets the pilot's velocity.
setVisible (p[, state=true])	Marks the pilot as always visible for other pilots.
setVisplayer (p[, state=true])	Marks the pilot as always visible for the player.
shield (p[, absolute=false])	Gets the pilot's shield.
ship (p)	Gets the pilot's ship.
shipMemory (p)	Gets a pilots ship memory table.
shippropGet (p[, name=nil][, internal=false], Value)	Allows getting an ship property stats of a pilot, or gets all of them if name is not specified.
shippropReset ()	Resets the ship property stats of a pilot.
shippropSet (p, name, value)	Allows setting ship property stats of a pilot.
shipstat (p[, name=nil[, internal=false]])	Gets a shipstat from a Pilot by name, or a table containing all the ship stats if not specified.
shipvarPeek (p, varname[, shipname])	Peeks at a ship variable.
shipvarPop (p, varname)	Pops a ship variable.
shipvarPush (p, varname, val)	Pushes a ship variable.
signature (p)	Gets the pilot's signature range.
spaceworthy (p)	Checks the pilot's spaceworthiness.
speed (p)	Gets the speed of a pilot.
speedMax (p)	Gets the maximum speed of a pilot.
stats (p)	Gets stats of the pilot.
stealth (p)	Tells the pilot to try to stealth.
stealthRange (p)	Gets the pilot's stealth range.
stress (p[, absolute=false])	Gets the pilot's stress.
target (p)	Gets the pilot target of the pilot.
targetAsteroid (p)	Gets the asteroid target of the pilot.
task (p)	Gets the name and data of a pilot's current task.
taskClear (p)	Clears all the tasks of the pilot.
taskdata (p)	Gets the data of the task the pilot is currently doing.
taskname (p)	Gets the name of the task the pilot is currently doing.
taskstack (p)	Gets the name of all the pilot's current tasks (not subtasks).
toggleSpawn ([fac[, enable=false]])	Disables or enables pilot spawning in the current system.
tryStealth (p)	Tries to make the pilot stealth.
turn (p)	Gets the turn of a pilot.
vel (p)	Gets the pilot's velocity.
weapset (p[, id=all])	Gets the weapset weapon of the pilot.
weapsetAdd (p, id, slot)	Adds an outfit to a pilot's weapon set.
weapsetAddType (p, id, slot)	Adds an outfit to a pilot's weapon set.
weapsetAmmo (p[, id], level)	Gets the ammo left of a weapon set.
weapsetAuto (p)	Makes the pilot's weapons get automatically set.
weapsetCleanup (p[, id])	Cleans up a weapon set.
weapsetList (p, id)	Get a list of all the outfits in a weapon set.
weapsetRm (p, id, slot)	Removes an outfit from a pilot's weapon set.
weapsetSetInrange (p[, id=nil], docheck)	Sets whether a pilot's weapon set does inrange checks.
weapsetType (p, id, type)	Sets the type of a weapon set for a pilot.
withPlayer (p)	Checks to see if pilot is with player.
worth (p[, count_unique=false])	Gets the worth of a pilot (total value of ship and outfits).

Functions

__eq (p, comp)

Checks to see if pilot and p are the same.

Parameters:

p Pilot Pilot to compare.
comp Pilot Pilot to compare against.

Returns:

boolean

Usage:

if p == p2 then -- Pilot 'p' and 'p2' match.

__tostring (p)

Gets the pilot's current (translated) name or notes it is inexistent.

Parameters:

p Pilot Pilot to convert to string.

Returns:

string

Usage:

tostring(p)

accel (p)

Gets the accel of a pilot.

Parameters:

p Pilot Pilot to get accel of.

Returns:

number

actives (p[, sort=false])

Gets the active outfits and their states of the pilot.

The active outfits have the following structure:

outfit: The outfit.
slot: The slot the outfit is in.
active: Whether or not the outfit is active at the current time.
weapset: The first weapon set that the outfit appears in, if any.
state: State of the outfit, which can be one of { "off", "warmup", "on", "cooldown" }.
duration: Set only if state is "on". Indicates duration value (0 = just finished, 1 = just on).
cooldown: Set only if state is "cooldown". Indicates cooldown value (0 = just ending, 1 = just started cooling down).

An example would be:

 actoutfits = p:actives()
 print( "Weapnset Name: " .. wsname )
 for i, o in ipairs(act_outfits) do
print( "Name: " .. o.name )
print( "State: " .. o.state )

 end

Parameters:

p Pilot Pilot to get active outfits of.
sort boolean Whether or not to sort the outfits. (default false)

Returns:

table

Usage:

act_outfits = p:actives() -- Gets the table of active outfits

add (shipname, stringfaction, param[, pilotname[, parameters]])

Adds a ship with an AI and faction to the system (instead of a predefined fleet).

Parameters:

shipname Ship or string Name of the ship to add.
stringfaction Faction Faction to give the pilot.
param System, Spob or Vec2 Position to create pilot at, if it's a system it'll try to jump in from that system, if it's a spob it'll try to take off from it.
pilotname string Name to give the pilot. Defaults to shipname. (optional)
parameters table Table of extra keyword arguments. Supported arguments: "ai" (string): AI to give the pilot. Defaults to the faction's AI. "naked" (boolean): Whether or not to have the pilot spawn without outfits. Defaults to false. "stealth" (boolean): Whether or not to have the pilot spawn in stealth mode. Defaults to false. (optional)

Returns:

Pilot

Usage:

p = pilot.add( "Empire Shark", "Empire" ) -- Creates a standard Empire
 Shark.

p = pilot.add( "Pirate Hyena", "Pirate", _("Blackbeard") ) -- Just
 adds the pilot (will jump in or take off).

p = pilot.add( "Llama", "Trader", nil, _("Trader Llama"), {ai="dummy"}
 ) -- Overrides AI with dummy ai.

p = pilot.add( "Gawain", "Civilian", vec2.new( 1000, 200 ) ) -- Pilot
 won't jump in, will just appear.

p = pilot.add( "Empire Pacifier", "Empire", system.get("Goddard") ) --
 Have the pilot jump in from the system.

p = pilot.add( "Goddard", "Goddard", spob.get("Zhiru") , _("Goddard
Goddard") ) -- Have the pilot take off from a spob.

How param works (by type of value passed): <br/>
 - nil: spawns pilot randomly entering from jump points with presence of
their faction or taking off from non-hostile spobs <br/>
 - spob: pilot takes off from the spob <br/>
 - system: jumps pilot in from the system <br/>
 - vec2: pilot is created at the position (no jump/takeoff) <br/>
 - true: Acts like nil, but does not avoid jump points with no presence <br/>

addEnergy (p, energy)

Adds (or subtracts) energy to a pilot.

Parameters:

p Pilot Pilot to set energy of.
energy number Energy value to add.

addHealth (p[, armour=0.[, shield=0.]])

Adds health to a pilot.

Does not revive dead pilots, use setHealth for that.

Parameters:

p Pilot Pilot to add health to.
armour number Armour to add. (default 0.)
shield number Shield to add. (default 0.)

ai (p)

Gets the pilot's AI.

Parameters:

p Pilot Pilot to get AI of.

Returns:

string

ainame (p)

Gets the name of the task the pilot is currently doing.

Parameters:

p Pilot Pilot to get task name of.

Returns:

string

areAllies (p, t)

Checks to see if two pilots are allies.

Parameters:

p Pilot Pilot to check.
t Pilot Target pilot to check.

Returns:

boolean

areEnemies (p, t)

Checks to see if two pilots are enemies.

Parameters:

p Pilot Pilot to check.
t Pilot Target pilot to check.

Returns:

boolean

armour (p[, absolute=false])

Gets the pilot's armour.

Parameters:

p Pilot Pilot to get armour of.
absolute boolean Whether or not it shouldn't be relative and be absolute instead. (default false)

Returns:

number

Usage:

armour = p:armour()

attack (p[, pt])

Makes the pilot attack another pilot.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to attack another pilot.
pt Pilot Target pilot to attack (or nil to attack nearest enemy). (optional)

Usage:

p:attack( another_pilot ) -- Attack another pilot

```
p:attack() -- Attack nearest pilot.
```

autoweap (p)

Gets if a pilot is using automatically set weapon sets.

Parameters:

p Pilot Pilot to get whether or not is using automatic weapon sets.

Returns:

boolean

board (p, pt)

Makes the pilot board another pilot.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to board another pilot.
pt Pilot Target pilot to board

Usage:

p:board( another_pilot ) -- Attack another pilot

brake (p)

Makes the pilot brake.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to brake.

Parameters:

p Pilot or string Pilot to broadcast the message, or string to use as a fictional pilot name. In the case of a string, interference is always ignored, and instead of the ignore_int parameter, a colour character such as 'F' or 'H' can be optionally passed.
msg string Message to broadcast.
ignore_int boolean Whether or not it should ignore interference. (default false)

Usage:

p:broadcast(_("Mayday! Requesting assistance!"))

p:broadcast(_("Help!"), true ) -- Will ignore interference

pilot.broadcast( _("Message Buoy"), _("Important annauncement") ) --
Messages player ignoring interference

calcStats (p)

Forces a recomputation of the pilots' stats.

Parameters:

p Pilot Pilot to recalculate stats of.

canHyperspace (p)

Checks to see if the pilot can currently hyperspace (as in has target jump and is in range).

Parameters:

p Pilot Pilot to check if they can hyperspace.

Returns:

boolean

canSpawn ()

Returns if pilots can can spawn naturally in the current system.

Returns:

boolean

cargoAdd (p, cargo, quantity)

Tries to add cargo to the pilot's ship.

Parameters:

p Pilot The pilot to add cargo to.

cargo Commodity or string

Type of cargo to add, either as

   a Commodity object or as the raw (untranslated) name of a
   commodity.

quantity number Quantity of cargo to add.

Returns:

number

Usage:

n = pilot.cargoAdd( player.pilot(), "Food", 20 )

cargoFree (p)

Gets the free cargo space the pilot has.

Parameters:

p Pilot The pilot to get the free cargo space of.

Returns:

number

cargoHas (p, cargo)

Checks to see how many tonnes of a specific type of cargo the pilot has.

Parameters:

p Pilot The pilot to get the cargo count of.

cargo Commodity or string

Type of cargo to check, either

   as a Commodity object or as the raw (untranslated) name of a
   commodity.

Returns:

number

cargoJet (p, cargo, quantity)

Tries to remove a cargo from a pilot's ship and jet it into space.

Parameters:

p Pilot The pilot to remove cargo from.

cargo Commodity or string

Type of cargo to remove, either

   as a Commodity object or as the raw (untranslated) name of a
   commodity. You can also pass the special value "all" to
   remove all cargo from the pilot, except for mission cargo.

quantity number Quantity of the cargo to remove.

Returns:

number

cargoList (p)

Lists the cargo the pilot has.

The list has the following members:

name: raw (untranslated) name of the cargo (equivalent to the output of commodity.nameRaw()).
c: the cargo commodity.
q: quantity of the cargo.
m: true if cargo is for a mission.

Parameters:

p Pilot Pilot to list cargo of.

Returns:

table

Usage:

for i, v in ipairs(pilot.cargoList(player.pilot())) do print(
string.format("%s: %d", v.name, v.q ) ) end

cargoRm (p, cargo, quantity)

Tries to remove cargo from the pilot's ship.

Parameters:

p Pilot The pilot to remove cargo from.

cargo Commodity or string

Type of cargo to remove, either

   as a Commodity object or as the raw (untranslated) name of a
   commodity. You can also pass the special value "all" to
   remove all cargo from the pilot, except for mission cargo.

quantity number Quantity of the cargo to remove.

Returns:

number

Usage:

n = pilot.cargoRm(player.pilot(), "Food", 20)

n = pilot.cargoRm(player.pilot(), "all") -- Removes all cargo from the
player

changeAI (p, newai)

Changes the pilot's AI.

Parameters:

p Pilot Pilot to change AI of.
newai string Name of Ai to use.

Usage:

p:changeAI( "empire" ) -- set the pilot to use the Empire AI

choosePoint (f[, i=false[, g=false]])

Returns a suitable jumpin spot for a given pilot.

Parameters:

f Faction Faction the pilot will belong to.
i boolean Whether to ignore rules. (default false)
g boolean Whether to behave as guerilla (spawn in deep space) (default false)

Returns:

Spob, Vec2 or Jump

Usage:

point = pilot.choosePoint( f, i, g )

clear ()

Clears the current system of pilots. Used for epic battles and such.

Be careful with this command especially in big systems. It will most likely cause issues if multiple missions are in the same system.

Note Clears all global pilot hooks too.

Usage:

pilot.clear()

clearSelect (fac)

Removes all pilots belonging to a faction from the system.

Parameters:

fac Faction or table Faction name/object or table of faction name/objects to selectively clear.

Usage:

pilot.clearSelect("Empire")

clone (p)

Clones a pilot. It will share nearly all properties including outfits.

Parameters:

p Pilot Pilot to clone.

Returns:

Pilot

collisionTest (p, t)

Tests to see if two ships collide.

Parameters:

p Pilot First pilot to check.
t Pilot or Asteroid Second object to check.

Returns:

Vec2 or nil

colour (p)

Gets the pilot's colour based on hostility or friendliness to the player.

Parameters:

p Pilot Pilot to get the colour of.

Returns:

Colour

Usage:

p:colour()

colourChar (p)

Gets the pilot's colour character based on hostility or friendliness to the player. For use with functions that print to the screen.

Parameters:

p Pilot Pilot to get the colour of.

Returns:

string

comm (p, target, msg[, param1=false[, raw=false]])

Sends a message to the target or player if no target is passed.

Parameters:

p Pilot or string Pilot to message the player, or string to use as a fictional pilot name. In the case of a string, interference is always ignored, and instead of ignore_int, a colour character such as 'F' or 'H' can be passed.
target Pilot Target to send message to.
msg string Message to send.
param1 boolean or colour Whether or not it should ignore interference in the case a pilot is being used, otherwise it is a colour string such as 'N' that can be used to colour the text.. (default false)
raw boolean Whether or not to just display the raw text without quotation marks instead of a "message". (default false)

Usage:

p:comm( _("How are you doing?") ) -- Messages the player

p:comm( _("You got this?"), true ) -- Messages the player ignoring
 interference

p:comm( target, _("Heya!") ) -- Messages target

p:comm( target, _("Got this?"), true ) -- Messages target ignoring
 interference

pilot.comm( _("Message Buoy"), _("Important information just for
you!") ) -- Messages player ignoring interference

control (p[, enable=true[, Whether=true if changing modes]])

Sets manual control of the pilot.

Note that this will reset the pilot's current task when the state changes. In the case of the player, it will also clear autonav.

Parameters:

p Pilot Pilot to change manual control settings.
enable boolean If true or nil enables pilot manual control, otherwise enables automatic AI. (default true)
Whether boolean or not to clear the tasks for the pilot. Defaults to true when changing from manual to normal mode or viceversa. (default true if changing modes)

Usage:

p:control() -- Same as p:control(true), enables manual control of the
 pilot

p:control(false) -- Restarts AI control of the pilot

p:control( true, true ) -- Enables manual control of the pilot and
resets tasks.

cooldown (p)

Gets a pilot's cooldown state.

Parameters:

p Pilot Pilot to check the cooldown status of.

Returns:

boolean Cooldown status.
boolean Cooldown braking status.

Usage:

cooldown, braking = p:cooldown()

cooldownCycle (p)

Makes the pilot do an instant full cooldown cycle.

Parameters:

p Pilot Pilot to perform cycle.

credits (p[, cred=0])

Handles the pilots credits

Parameters:

p Pilot Pilot to manipulate credits of.
cred number Credits to give to the pilot. (default 0)

Returns:

number

damage (p, dmg[, disable=0.[, penetration=0.[, type="raw"[, shooter=nil]]]])

Damages a pilot.

Parameters:

p Pilot Pilot being damaged.
dmg number Damage being done.
disable number Disable being done. (default 0.)
penetration number Penetration (in %). (default 0.)
type string Damage type being done. (default "raw")
shooter Pilot Pilot doing the damage. (default nil)

Returns:

number

destealth (p)

Tries to make the pilot stealth.

Parameters:

p Pilot Pilot to try to make stealth.

Returns:

boolean

detectedDistance (p)

Gets the distance that a pilot can be currently detect at.

Parameters:

p Pilot Pilot to get the distance they can be detected at.

dir (p)

Gets the pilot's direction.

Parameters:

p Pilot Pilot to get the direction of.

Returns:

number

Usage:

d = p:dir()

disabled (p)

Gets the disabled state of a pilot.

Parameters:

p Pilot Pilot to get disabled state of.

Returns:

boolean

distress (p, attacker)

Sends a distress single from the pilot.

Does not cause a faction hit.

Parameters:

p Pilot Pilot to send a distress signal.
attacker Pilot Pilot to be distressing about.

effectAdd (p, name[, Duration=-1[, Scaling=1]])

Adds an effect to a pilot.

Parameters:

p Pilot Pilot to add effect to.
name string Name of the effect to add.
Duration duration of the effect or set to negative to be default. (default -1)
Scaling scale factor. (default 1)

Returns:

boolean

effectClear (p, keepdebuffs, keepbuffs, keepothers)

Clears the effect on a pilot.

Parameters:

p Pilot Pilot to clear effects of.
keepdebuffs boolean Whether or not to keep debuffs.
keepbuffs boolean Whether or not to keep buffs.
keepothers boolean Whether or not to keep others.

effectHas (p, Name)

Checks to see if a player has an instance of an effect active.

Parameters:

p Pilot Pilot to check.
Name string of the effect to check.

Returns:

boolean

effectRm (p, name, all)

Removes an effect from the pilot.

Parameters:

p Pilot Pilot to remove effect from.
name string or integer Name of the effect to add or index in the case of being a number.
all boolean Remove all instances of the effect or only the most first instance. Only valid in the case the name is specified as a string.

effects (p)

Gets the effects on a pilot.

Parameters:

p Pilot Pilot to get effects of.

Returns:

table

energy (p[, absolute=false])

Gets the pilot's energy.

Parameters:

p Pilot Pilot to get energy of.
absolute boolean Whether or not to return the absolute numeric value instead of the relative value. (default false)

Returns:

number

Usage:

energy = p:energy()

exists (p)

Checks to see if pilot is still in the system and alive.

Pilots cease to exist if they die or jump out.

Parameters:

p Pilot Pilot to check to see if is still exists.

Returns:

boolean

Usage:

if p:exists() then -- Pilot still exists

explode (p)

Removes a pilot as if it exploded.

Note that this triggers the exploded hook which can cause the explosion to fail unlike pilot.rm.

Parameters:

p Pilot Pilot to remove.

Returns:

boolean

Usage:

p:exploded() -- pilot will be destroyed

face (p, target[, towards=false])

Makes the pilot face a target.

Parameters:

p Pilot Pilot to add task to.
target Vec2 or Pilot Target to face.
towards boolean Makes the task end when the target is faced (otherwise it's an enduring state). (default false)

Usage:

p:face( enemy_pilot ) -- Face enemy pilot

p:face( vec2.new( 0, 0 ) ) -- Face origin

p:face( enemy_pilot, true ) -- Task lasts until the enemy pilot is
faced

faction (p)

Gets the pilot's faction.

Parameters:

p Pilot Pilot to get the faction of.

Returns:

Faction

Usage:

f = p:faction()

fillAmmo (p)

Fills up the pilot's ammo.

Parameters:

p Pilot Pilot to fill ammo.

flags (p[, name])

Gets the pilot's flags.

Valid flags are:

hailing: pilot is hailing the player.
boardable: pilot is boardable while active.
nojump: pilot cannot jump.
noland: pilot cannot land.
nodeath: pilot cannot die.
nodisable: pilot cannot be disabled.
escort: pilot is an escort.
visible: pilot is always visible.
visplayer: pilot is always visible to the player.
hilight: pilot is hilighted on the map.
stealth: pilot is in stealth mode.
invisible: pilot is not displayed.
invincible: pilot cannot be hit.
invinc_player: pilot cannot be hit by the player.
friendly: pilot is friendly toward the player.
hostile: pilot is hostile toward the player.
refueling: pilot is refueling another pilot.
disabled: pilot is disabled.
landing: pilot is currently landing.
takingoff: pilot is currently taking off.
manualcontrol: pilot is under manual control.
combat: pilot is engaged in combat.
carried: pilot came from a fighter bay.

Parameters:

p Pilot Pilot to get flags of.
name string If provided, return only the individual flag. (optional)

Returns:

table

follow (p, pt[, accurate=false])

Makes the pilot follow another pilot.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to follow another pilot.
pt Pilot Target pilot to follow.

accurate boolean

If true, use a PD controller which

          parameters can be defined using the pilot's memory.

(default false)

Parameters:

p Pilot Pilot to get the followers of.
hidefighters boolean Whether or not to ignore deployed fighters.

Returns:

{Pilot,...}

fuel ()

Gets the amount of fuel the pilot has.

Returns:

number

gather ()

Makes the pilot gather stuff.

Usage:

p:gather( ) -- Try to gather stuff

get (factions[, disabled=false])

Gets the pilots available in the system by a certain criteria.

Parameters:

factions Faction or {Faction,...} If f is a table of factions, it will only get pilots matching those factions. Otherwise it gets all the pilots.
disabled boolean Whether or not to get disabled ships. (default false)

Returns:

{Pilot,...}

Usage:

```
p = pilot.get() -- Gets all the pilots
```

p = pilot.get( { faction.get("Empire") } ) -- Only gets empire pilots.

p = pilot.get( nil, true ) -- Gets all pilots including disabled

p = pilot.get( { faction.get("Empire") }, true ) -- Only empire pilots
with disabled

getAllies (pilot[, dist=infinity[, pos=pilot.pos[, ignore_range=false[, disabled=false[, fighters=false]]]]])

Gets friendly pilots to a pilot (or faction) within a certain distance.

Parameters:

pilot Pilot or faction Pilot or to get allies of.
dist number Distance to look for allies. (default infinity)
pos Vec2 Position to check from. (default pilot.pos)
ignore_range boolean Whether or not to only check for pilots in range (only in the case of pilot, not faction) (default false)
disabled boolean Whether or not to count disabled pilots. (default false)
fighters boolean Whether or not to count deployed fighters. (default false)

Returns:

{Pilot,...}

Usage:

p:getAllies( 5000 ) -- get allies within 5000

pilot.getAllies( faction.get("Pirate"), 5000, vec2.new(0,0) ) -- Got
allies of "Pirate" faction 5000 units from origin

getEnemies (pilot[, dist=infinity[, pos=pilot.pos[, ignore_range=false[, disabled=false[, fighters=false]]]]])

Gets hostile pilots to a pilot (or faction) within a certain distance.

Parameters:

pilot Pilot or faction Pilot or to get hostiles of.
dist number Distance to look for hostiles. (default infinity)
pos Vec2 Position to check from. (default pilot.pos)
ignore_range boolean Whether or not to ignore checks for pilots in range (only in the case of pilot, not faction) (default false)
disabled boolean Whether or not to count disabled pilots. (default false)
fighters boolean Whether or not to count deployed fighters. (default false)

Returns:

{Pilot,...}

Usage:

p:getEnemies( 5000 ) -- get hostiles within 5000

pilot.getEnemies( faction.get("Pirate"), 5000, vec2.new(0,0) ) -- Got
hostiles of "Pirate" faction 5000 units from origin

getInrange (pos, d[, disabled=false])

Gets visible pilots to a pilot within a certain distance.

Parameters:

pos vec2 Position to get pilots in range of.
d number Distance to get pilots in.
disabled boolean Whether or not to count disabled pilots. (default false)

Returns:

{Pilot,...}

getVisible (pilot[, disabled=false])

Gets visible pilots to a pilot.

Note This function can not use quadtrees and is much slower than getEnemies, getAllies, or getInrange.

Parameters:

pilot Pilot Pilot to get visible pilots of.
disabled boolean Whether or not to count disabled pilots. (default false)

Returns:

{Pilot,...}

hailPlayer (p[, enable=true])

Marks the pilot as hailing the player.

Automatically deactivated when pilot is hailed.

Parameters:

p Pilot Pilot to hail the player.
enable boolean If true hails the pilot, if false disables the hailing. (default true)

Usage:

p:hailPlayer() -- Player will be informed he's being hailed and pilot
 will have an icon

hasIllegal (p, f)

Checks to see if the pilot has illegal stuff to a faction.

Parameters:

p Pilot Pilot to check.
f Faction Faction to see if it is illegal to.

health (p[, absolute=false])

Gets the pilot's health.

Parameters:

p Pilot Pilot to get health of.
absolute boolean Whether or not it shouldn't be relative and be absolute instead. (default false)

Returns:

number The armour in % [0:100] if relative or absolute value otherwise.
number The shield in % [0:100] if relative or absolute value otherwise.
number The stress in % [0:100].
boolean Indicates if pilot is disabled.

Usage:

armour, shield, stress, dis = p:health()

hookClear (p)

Clears the pilot's hooks.

Clears all the hooks set on the pilot.

Parameters:

p Pilot Pilot to clear hooks.

Usage:

p:hookClear()

hostile (p)

Returns whether the pilot is hostile to the player.

Parameters:

p Pilot Pilot to get the hostility of.

Returns:

boolean

Usage:

p:hostile()

hyperspace (p[, sys[, noshoot=false]])

Tells the pilot to hyperspace.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to hyperspace.
sys System or Jump Optional System to jump to, uses random if nil. (optional)
noshoot boolean Forbids to shoot at targets with turrets while running away. (default false)

Parameters:

p Pilot Pilot to get the ID of.

Returns:

number The ID of the current pilot.

Usage:

id = p:id()

idle (p)

Checks to see if the pilot is idle.

Parameters:

p Pilot Pilot to check to see if is idle.

Returns:

boolean

Usage:

idle = p:idle() -- Returns true if the pilot is idle

inrange (p, target)

Checks to see if a target pilot is in range of a pilot.

TODO add supports for spobs and jump points.

Parameters:

p Pilot Pilot to see if another pilot is in range.
target Pilot, Asteroid or Vec2 Target pilot or asteroid to check if in range.

Returns:

boolean True if the pilot is visible at all.
boolean True if the pilot is visible and well-defined (not fuzzy). Always true if target is not a Pilot.

Usage:

detected, scanned = p:inrange( target )

intrinsicGet (p[, name=nil][, internal=false], Value)

Allows getting an intrinsic stats of a pilot, or gets all of them if name is not specified.

Parameters:

p Pilot Pilot to get stat of.
name string Name of the stat to get. It is the same as in the xml. If nil, returns a table containing all the shipstats. (default nil)
internal boolean Whether or not to use the internal representation. (default false)
Value of the stat or a table containing all the stats if name is not specified.

intrinsicReset ()

Resets the intrinsic stats of a pilot.

intrinsicSet (p, name, value, replace)

Allows setting intrinsic stats of a pilot.

Parameters:

p Pilot Pilot to set stat of.
name string Name of the stat to set. It is the same as in the xml.
value number Value to set the stat to.
replace boolean Whether or not to add to the stat or replace it.

Usage:

p:intrinsicSet( "turn", -50 ) -- Lowers p's turn by 50%

invincible (p)

Gets whether or not a pilot is invincible.

Parameters:

p Pilot Pilot to check to see if is invincible.

Returns:

boolean

isStopped (p)

Checks to see if a pilot is stopped.

Parameters:

p Pilot Pilot to get the velocity of.

Returns:

boolean

Usage:

if p:isStopped() then ... end

kill (p)

Kills a pilot.

Can fail to kill a pilot if they have a hook that regenerates them.

Parameters:

p Pilot Pilot to kill.

knockback (p, m, v[, p=p:pos()[, e=1.]])

Knocks back a pilot. It can either accept two pilots, or a pilot and an element represented by mass, velocity, and position.

Parameters:

p Vec2 Position of the object knocking back the pilot. (default p:pos())
m number Mass of object knocking back pilot.
v Vec2 Velocity of object knocking back pilot.
p Vec2 Position of the object knocking back the pilot. (default p:pos())
e number Coefficient of restitution. Use 1. for elastic collisions, and 0. for inelastic collisions. (default 1.)

Usage:

pilota:knockback( pilotb, 0. ) -- Inelastic collision between pilota
 and pilotb

pilota:knockback( 100, vec2.new(0,0) ) -- Elastic collision between a
100 mass object with no velocity and pilota

land (p[, spob[, noshoot=false]])

Tells the pilot to land Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to land.
spob Spob Spob to land on, uses random if nil. (optional)
noshoot boolean Forbids to shoot at targets with turrets while running away. (default false)

Parameters:

p Pilot Pilot to get the leader of.

Returns:

Pilot or nil

lockon (p)

Gets the lockons on the pilot.

Parameters:

p Pilot Pilot to get lockons of.

Returns:

number

Usage:

lockon = p:lockon()

mass (p)

Gets the mass of a pilot.

Parameters:

p Pilot Pilot to get mass of.

Returns:

number

Usage:

m = p:mass()

memory (p)

Gets a pilots memory table.

The resulting table is indexable and mutable.

Parameters:

p Pilot Pilot to read memory of.

Usage:

```
aggr = p:memory().aggressive
```
```
p:memory().aggressive = false
```

mothership (p)

Gets a pilots mothership (only exists for deployed pilots). Guaranteed to exist or will be nil.

Parameters:

p Pilot Pilot to get the mothership of.

Returns:

Pilot or nil

moveto (p, v[, brake=1[, compensate=1]])

Makes the pilot move to a position.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to go to a position.
v Vec2 Vector target for the pilot.
brake boolean If true (or nil) brakes the pilot near target position, otherwise pops the task when it is about to brake. (default 1)
compensate boolean If true (or nil) compensates for velocity, otherwise it doesn't. It only affects if brake is not set. (default 1)

Usage:

p:moveto( v ) -- Goes to v precisely and braking

p:moveto( v, true, true ) -- Same as p:moveto( v )

p:moveto( v, false ) -- Goes to v without braking compensating
 velocity

p:moveto( v, false, false ) -- Really rough approximation of going to
v without braking

msg (p, receiver, type[, data])

Sends a message to another pilot.

Do not confuse with pilot.comm! This is meant to be used by AI and other scripts.

Parameters:

p Pilot Pilot to send message.
receiver Pilot or {Pilot,...} Pilot(s) to receive message.
type string Type of message.
data Data to send with message. (optional)

name (p)

Gets the pilot's current (translated) name.

Parameters:

p Pilot Pilot to get the name of.

Returns:

string

Usage:

name = p:name()

nav (p)

Gets the nav target of the pilot.

Parameters:

p Pilot Pilot to get nav info of.

Returns:

Spob or nil The pilot's spob target.
System or nil The pilot's hyperspace target.

Usage:

spob, hyperspace = p:nav()

navJump (p)

Gets the nav jump target of the pilot.

Parameters:

p Pilot Pilot to get nav info of.

Returns:

Jump or nil

navJumpSet (p, jp)

Sets the hyperspace navigation target for the pilot.

Parameters:

p Pilot Pilot to set hyperspace navigation target for.
jp Jump or nil Jump point to set as navigation target or nil to disable.

navSpob (p)

Gets the nav spob target of the pilot.

Parameters:

p Pilot Pilot to get nav info of.

Returns:

Spob or nil

navSpobSet (p, spb)

Sets the spob target for the pilot.

Parameters:

p Pilot Pilot to set spob target for.
spb Spob or nil Spob to set as target or nil to disable.

outfitAdd (p, outfit[, q=1[, bypass_cpu=false[, bypass_slot=false]]])

Adds an outfit to a pilot.

This by default tries to add them to the first empty or defaultly equipped slot. Will not overwrite existing non-default outfits.

This will also not add outfits to locked slots. Please use outfitAddSlot for that.

Parameters:

p Pilot Pilot to add outfit to.
outfit string or outfit Outfit or name of the outfit to add.
q number Quantity of the outfit to add. (default 1)
bypass_cpu boolean Whether to skip CPU checks when adding an outfit. (default false)
bypass_slot boolean Whether or not to skip slot size checks before adding an outfit. Not that this implies skipping the CPU checks. (default false)

Returns:

number The number of outfits added.
number The id of the slot of the first outfit added if applicable.

Usage:

added = p:outfitAdd( "Laser Cannon", 5 ) -- Adds 5 laser cannons to p

outfitAddIntrinsic (p, o)

Adds an intrinsic outfit to the pilot.

Intrinsic outfits are outfits that are associated with a ship, but not their slots.

Parameters:

p Pilot Pilot to add intrinsic outfit to.
o Outfit Outfit to add as intrinsic outfit (must be modifier outfit).

outfitAddSlot (p, outfit, slot[, bypass_cpu=false[, bypass_slot=false]])

Adds an outfit to a pilot by slot name.

Parameters:

p Pilot Pilot to add outfit to.
outfit string or outfit Outfit or name of the outfit to add.
slot string or integer Slot to add to. Can be passed as a slot name (string) or slot id (integer).
bypass_cpu boolean Whether to skip CPU checks when adding an outfit. (default false)
bypass_slot boolean or string Whether or not to skip slot size checks before adding an outfit. Not that this implies skipping the CPU checks. In the case bypass_slot is a string, the outfit gets added to the named slot if possible (no slot check). (default false)

Returns:

boolean

outfitGet (p, id)

Gets a pilot's outfit by ID.

Parameters:

p Pilot Pilot to get outfit of.
id number ID of the outfit to get.

Returns:

Outfit or nil

outfitHasSlot (p, name)

Checks to see if a pilot has a specific named slot.

Parameters:

p Pilot Pilot to check.
name string Name of the slot to check.

Returns:

boolean

outfitInitSlot (p, slot)

Makes an outfit run its initialization script.

Parameters:

p Pilot Pilot to initialize outfit.
slot string or integer Slot to initialize. Can be passed as a slot name (string) or slot id (integer).

outfitMessageSlot (p, slot, type[, data])

Sends a message to an outfit. nil if not applicable.

Parameters:

p Pilot Pilot containing the outfit to send a message to.
slot string or integer Slot to send a message to. Can be passed as a slot name (string) or slot id (integer).
type string Type of message.
data Data to send with message. (optional)

Returns:

message

outfitReady (p, id)

Sees if an outfit is ready to use.

Parameters:

p Pilot Pilot to toggle outfit of.
id integer ID of the pilot outfit.

Returns:

boolean

outfitRm (p, outfit, q)

Removes an outfit from a pilot.

"all" will remove all outfits except cores, locked outfits, and intrinsic outfits. "cores" will remove all cores, but nothing else. "intrinsic" will remove all intrinsic outfits.

Parameters:

p Pilot Pilot to remove outfit from.
outfit string or outfit Outfit or name of the outfit to remove.
q number Quantity of the outfit to remove.

Returns:

number

Usage:

p:outfitRm( "all" ) -- Leaves the pilot naked (except for cores and
 locked outfits).

p:outfitRm( "cores" ) -- Strips the pilot of its cores, leaving it
 dead in space.

p:outfitRm( "intrinsic" ) -- Removes all the intrinsic outfits of the
 ship.

p:outfitRm( "Neutron Disruptor" ) -- Removes a neutron disruptor.

p:outfitRm( "Neutron Disruptor", 2 ) -- Removes two neutron disruptor.

outfitRmIntrinsic (p, o)

Removes an intrinsic outfit from the pilot.

Intrinsic outfits are outfits that are associated with a ship, but not their slots.

Parameters:

p Pilot Pilot to remove intrinsic outfit from.
o Outfit Outfit to remove from intrinsic outfits.

Returns:

boolean

outfitRmSlot (p, slot)

Removes an outfit from a pilot's named slot.

Note that this only works with the name="foo" property of slots. It is not meant to be used with unnamed slots. By default all slots are unnamed unless specified.

Parameters:

p Pilot Pilot to remove outfit from.
slot string or integer Slot to remove from. Can be passed as a slot name (string) or slot id (integer).

Returns:

boolean

outfitSlot (p, slot)

Checks to see outfit a pilot has in a slot.

Parameters:

p Pilot Pilot to check outfit slot of.
slot string or integer Slot to check. Can be passed as a slot name (string) or slot id (integer).

Returns:

Outfit or nil

outfitToggle (p, id[, activate=false])

Toggles an outfit.

Parameters:

p Pilot Pilot to toggle outfit of.
id table or integer ID of the pilot outfit, or table of pilot outfit ids.
activate boolean Whether to activate or deactivate the outfit. (default false)

Returns:

boolean

outfits (p)

Gets a mapping of outfit slot IDs and outfits of a pilot.

Note The index value can be used as a slot identifier.

Parameters:

p Pilot Pilot to get outfits of.

Returns:

table

outfitsEquip (p, o, Whether)

Equips a pilot with a set of outfits.

Will unequip outfits if the slot is set to false.

Parameters:

p Pilot Pilot to set equipment of.
o table Table of outfits to equip the pilot (should be likely taken from pilot.outfits). The key should be the slot id and the value should be the outfit or false if there is no outfit in that slot and it should be removed if necessary.
Whether noremove or not it should not remove outfits if false.

Returns:

boolean

outfitsList (p[, What=nil[, skip_locked=false]])

Gets the outfits of a pilot.

Parameters:

p Pilot Pilot to get outfits of.
What string slot type to get outfits of. Can be either nil, "weapon", "utility", "structure", "intrinsic", or "all". nil implies returning all non-intrinsic outfits. (default nil)
skip_locked boolean Whether or not locked outfits should be ignored. (default false)

Returns:

table

outfitsReset (p)

Resets the pilot's outfit and timers.

Parameters:

p Pilot Pilot to reset.

points (p)

Gets the points the pilot costs.

Note currently equivalent to p:ship():points().

Parameters:

p Pilot Pilot to get points of.

Returns:

number

poptask (p)

Pops the current task from the pilot's AI.

Equivalent to ai.poptask().

Parameters:

p Pilot Pilot to pop task from.

pos (p)

Gets the pilot's position.

Parameters:

p Pilot Pilot to get the position of.

Returns:

Vec2

Usage:

v = p:pos()

pushtask (p, func, data)

Pushes a new task to the pilot's AI.

Equivalent to ai.pushtask()

Parameters:

p Pilot Pilot to push task to.
func string Name of the function to be run.
data any Data to be passed to the function.

radius (p)

Gets the rough radius of the ship, useful for collision stuff.

Parameters:

p Pilot Pilot to get radius of.

Returns:

number

refuel (p, target[, amount=100])

Tries to refuel a pilot.

Parameters:

p Pilot Pilot to do the refueling.
target Pilot Target pilot to give fuel to.
amount number Amount to refuel. (default 100)

rename (p, name)

Changes the pilot's name.

Parameters:

p Pilot Pilot to change name of.
name string Name to change to.

Usage:

p:rename( _("Black Beard") )

render (p)

Renders the pilot to a canvas

Parameters:

p Pilot Pilot whose ship is being rendered.

Returns:

Canvas

renderTo (p, The)

Renders the pilot to a canvas

Parameters:

p Pilot Pilot whose ship is being rendered.
The Canvas canvas to draw to (uses bottom-left corner).

Returns:

number Width drawn.
number Height drawn.

reputation (p)

Get the reputation the player has with the pilot's faction.

Parameters:

p Pilot Pilot to get the reputation with.

Returns:

number

rm (p)

Removes a pilot without explosions or anything.

Does nothing if the pilot does not exist.

Parameters:

p Pilot Pilot to remove.

Usage:

p:rm() -- pilot will be destroyed

runaway (p, tp[, destination.=false])

Makes the pilot runaway from another pilot.

By default the pilot tries to jump when running away. Third argument is destination: if false or nil, destination is automatically chosen. If true, the pilot does not jump nor land and stays in system. If Jump is given, the pilot tries to use this jump to go hyperspace. If Spob is given, the pilot tries to land on it.

Parameters:

p Pilot Pilot to tell to runaway from another pilot.
tp Pilot Target pilot to runaway from.
destination. boolean, Jump or Spob (default false)

Usage:

p:runaway( p_enemy ) -- Run away from p_enemy

p:runaway( p_enemy, true ) -- Run away from p_enemy but do not jump

scandone ()

Checks to see if a pilot is done scanning its target.

Returns:

boolean

setActiveBoard (p[, state=true])

Allows the pilot to be boarded when not disabled.

Parameters:

p Pilot Pilot to set boardability of.
state boolean State to set boardability. (default true)

Usage:

p:setActiveBoard( true )

setBribed (p[, state=true])

Makes pilot act as if bribed by the player.

Parameters:

p Pilot Pilot to set bribed status of.
state boolean State to set bribed. (default true)

Usage:

p:setBribed( true )

setCooldown (p[, state=true])

Starts or stops a pilot's cooldown mode.

Parameters:

p Pilot Pilot to modify the cooldown status of.
state boolean Whether to enable or disable cooldown. (default true)

Usage:

p:setCooldown( true )

setDir (p, dir)

Sets the pilot's direction.

Note Right is 0, top is math.pi/2, left is math.pi, bottom is 3*math.pi/2.

Parameters:

p Pilot Pilot to set the direction of.
dir number Direction to set, in radians.

Usage:

p:setDir( math.pi/2 )

setDisable (p[, nopermanent=false])

Disables a pilot.

Parameters:

p Pilot Pilot to disable.
nopermanent boolean Whether or not the disable should be not permanent. (default false)

Usage:

p:disable()

setEnergy (p, energy[, absolute=false])

Sets the energy of a pilot.

Parameters:

p Pilot Pilot to set energy of.
energy number Value to set energy to, should be double from 0-100 (in percent).
absolute boolean Whether or not it is being set in relative value or absolute. (default false)

Usage:

p:setEnergy( 100 ) -- Sets pilot to full energy.

p:setEnergy(  70 ) -- Sets pilot to 70% energy.

setFaction (p, faction)

Sets the pilot's faction.

Parameters:

p Pilot Pilot to change faction of.
faction Faction Faction to set by name or faction.

Usage:

```
p:setFaction( "Empire" )
```

p:setFaction( faction.get( "Dvaered" ) )

setFriendly (p[, state=true])

Controls the pilot's friendliness towards the player.

Parameters:

p Pilot Pilot to set the friendliness of.
state boolean Whether to set or unset friendly. (default true)

Usage:

p:setFriendly() -- Pilot is now friendly.

p:setFriendly(false) -- Make pilot non-friendly.

setFuel (p, f)

Sets the fuel of a pilot.

Parameters:

p Pilot Pilot to set fuel of.
f boolean or number true sets fuel to max, false sets fuel to 0, a number sets fuel to that amount in units.

Returns:

number

Usage:

p:setFuel( true ) -- Sets fuel to max

setHealth (p[, armour=current armour[, shield=current shield[, stress=0]]])

Sets the health of a pilot.

This recovers the pilot's disabled state, although they may become disabled afterwards.

Parameters:

p Pilot Pilot to set health of.
armour number Value to set armour to, should be double from 0-100 (in percent). (default current armour)
shield number Value to set shield to, should be double from 0-100 (in percent). (default current shield)
stress number Value to set stress (disable damage) to, should be double from 0-100 (in percent of current armour). (default 0)

Usage:

p:setHealth( 100, 100 ) -- Sets pilot to full health

p:setHealth(  70,   0 ) -- Sets pilot to 70% armour

p:setHealth( 100, 100, 0 ) -- Sets pilot to full health and no stress

setHealthAbs (p[, armour=current armour[, shield=current shield[, stress=current stress]]])

Sets the health of a pilot in absolute value.

This recovers the pilot's disabled state, although they may become disabled afterwards.

Parameters:

p Pilot Pilot to set health of.
armour number Value to set armour to, in absolute value. (default current armour)
shield number Value to set shield to, in absolute value (default current shield)
stress number Value to set stress (disable damage) to, in absolute value. (default current stress)

setHide (p, state)

Sets the pilot's hide status.

A hidden pilot is neither updated nor drawn. It stays frozen in time until the hide is lifted.

Parameters:

p Pilot Pilot to set hidden status of.
state boolean State to set hide.

Usage:

```
p:setHide() -- p will disappear
```
```
p:setHide(true) -- p will disappear
```

p:setHide(false) -- p will appear again

setHilight (p[, state=true])

Makes pilot stand out on radar and the likes.

This makes the pilot stand out in the map overlay and radar to increase noticability.

Parameters:

p Pilot Pilot to set hilight status of.
state boolean State to set hilight. (default true)

Usage:

p:setHilight( true )

setHostile (p[, state=true])

Controls the pilot's hostility towards the player.

Parameters:

p Pilot Pilot to set the hostility of.
state boolean Whether to set or unset hostile. (default true)

Usage:

p:setHostile() -- Pilot is now hostile.

p:setHostile(false) -- Make pilot non-hostile.

setInvincPlayer (p[, state=true])

Sets the pilot's invincibility status towards the player.

Parameters:

p Pilot Pilot to set invincibility status of (only affects player).
state boolean State to set invincibility. (default true)

Usage:

p:setInvincPlayer() -- p can not be hit by the player anymore

p:setInvincPlayer(true) -- p can not be hit by the player anymore

p:setInvincPlayer(false) -- p can be hit by the player again

setInvincible (p[, state=true])

Sets the pilot's invincibility status.

Parameters:

p Pilot Pilot to set invincibility status of.
state boolean State to set invincibility. (default true)

Usage:

p:setInvincible() -- p can not be hit anymore

p:setInvincible(true) -- p can not be hit anymore

p:setInvincible(false) -- p can be hit again

setInvisible (p, state)

Sets the pilot's invisibility status.

An invisible pilot is not shown on the radar nor targettable, however, it renders and updates just like normal.

Parameters:

p Pilot Pilot to set invisibility status of.
state boolean State to set invisibility.

setLeader (p, leader)

Set a pilots leader.

If leader has a leader itself, the leader will instead be set to that pilot's leader. The leader can not be set for deployed fighters or members of the player's fleet.

Parameters:

p Pilot Pilot to set the leader of.
leader Pilot or nil Pilot to set as leader.

setNoBoard (p[, noboard=true])

Sets the ability to board the pilot.

No parameter is equivalent to true.

Parameters:

p Pilot Pilot to set disable boarding.
noboard number If true it disallows boarding of the pilot, otherwise it allows boarding which is the default. (default true)

Usage:

p:setNoBoard( true ) -- Pilot can not be boarded by anyone

setNoClear (p[, state])

Enables or disables making the the pilot exempt from pilot.clear().

Parameters:

p Pilot Pilot to modify.
state boolean true or false (optional)

Usage:

p:setNoClear( true )

setNoDeath (p[, state=true])

Makes it so the pilot never dies, stays at 1. armour.

Parameters:

p Pilot Pilot to set never die state of.
state boolean Whether or not to set never die state. (default true)

Usage:

p:setNoDeath( true ) -- Pilot will never die

setNoDisable (p[, disable=true])

Sets the ability of the pilot to be disabled. Pilots that can't be disabled will blow up instead when they would be disabled.

No parameter is equivalent to true.

Parameters:

p Pilot Pilot to set disable disabling.
disable boolean If true it disallows disabled of the pilot, otherwise it allows disabling which is the default. (default true)

Usage:

p:setNoDisable( true ) -- Pilot can not be disabled anymore.

setNoJump (p[, state=true])

Enables or disables a pilot's hyperspace engine.

Parameters:

p Pilot Pilot to modify.
state boolean true or false (default true)

Usage:

p:setNoJump( true )

setNoLand (p[, state])

Enables or disables landing for a pilot.

Parameters:

p Pilot Pilot to modify.
state boolean true or false (optional)

Usage:

p:setNoLand( true )

setNoRender (p, state)

Sets the pilot's norender status.

The pilot still acts normally but is just not visible and can still take damage. Meant to be used in conjunction with other flags like "invisible".

Parameters:

p Pilot Pilot to set norender status of.
state boolean State to set norender.

setPos (p, pos)

Sets the pilot's position.

Parameters:

p Pilot Pilot to set the position of.
pos Vec2 Position to set.

Usage:

p:setPos( vec2.new( 300, 200 ) )

setSpeedLimit (p, speed)

Limits the speed of a pilot.

Note Can increase the pilot's speed limit over what would be physically possible.

Parameters:

p pilot Pilot to set speed of.
speed number Value to set speed to.

Usage:

p:setSpeedLimit( 100 ) -- Sets maximumspeed to 100px/s.

p:setSpeedLimit( 0 ) removes speed limit.

setTarget (p, t)

Sets the pilot target of the pilot.

Parameters:

p Pilot Pilot to get target of.
t Pilot or nil Pilot to set the target to or nil to set no target.

setTargetAsteroid (p, a)

Sets the pilot's asteroid target.

Parameters:

p Pilot Pilot to set asteroid target of.
a Asteroid Asteroid to set pilot's target to.

setVel (p, vel)

Sets the pilot's velocity.

Parameters:

p Pilot Pilot to set the velocity of.
vel Vec2 Velocity to set.

Usage:

p:setVel( vec2.new( 300, 200 ) )

setVisible (p[, state=true])

Marks the pilot as always visible for other pilots.

This cancels out ewarfare visibility ranges and affects every pilot.

Parameters:

p Pilot Pilot to set visibility status of.
state boolean State to set visibility. (default true)

Usage:

p:setVisible( true )

setVisplayer (p[, state=true])

Marks the pilot as always visible for the player.

This cancels out ewarfare visibility ranges and only affects the visibility of the player.

Parameters:

p Pilot Pilot to set player visibility status of.
state boolean State to set player visibility. (default true)

Usage:

p:setVisplayer( true )

shield (p[, absolute=false])

Gets the pilot's shield. If no shields, it returns 1. in relative mode.

Parameters:

p Pilot Pilot to get shield of.
absolute boolean Whether or not it shouldn't be relative and be absolute instead. (default false)

Returns:

number

Usage:

shield = p:shield()

ship (p)

Gets the pilot's ship.

Parameters:

p Pilot Pilot to get ship of.

Returns:

Ship

Usage:

s = p:ship()

shipMemory (p)

Gets a pilots ship memory table.

The resulting table is indexable and mutable.

Parameters:

p Pilot Pilot to get ship memory of.

shippropGet (p[, name=nil][, internal=false], Value)

Allows getting an ship property stats of a pilot, or gets all of them if name is not specified.

Parameters:

p Pilot Pilot to get stat of.
name string Name of the stat to get. It is the same as in the xml. (default nil)
internal boolean Whether or not to use the internal representation. (default false)
Value of the stat or a table containing all the stats if name is not specified.

shippropReset ()

Resets the ship property stats of a pilot.

shippropSet (p, name, value)

Allows setting ship property stats of a pilot.

Parameters:

p Pilot Pilot to set stat of.
name string Name of the stat to set. It is the same as in the xml.
value number Value to set the stat to.

Usage:

p:shippropSet( "turn", -50 ) -- Lowers p's turn by 50%

shipstat (p[, name=nil[, internal=false]])

Gets a shipstat from a Pilot by name, or a table containing all the ship stats if not specified. if name is not specified.

Parameters:

p Pilot Pilot to get ship stat of.
name string Name of the ship stat to get. (default nil)
internal boolean Whether or not to use the internal representation. (default false)

Returns:

Value of the ship stat or a table containing all the ship stats

Usage:

local mod = p:shipstat("tur_damage",true) -- Gets turret damage bonus
with internal representation

shipvarPeek (p, varname[, shipname])

Peeks at a ship variable.

Parameters:

p Pilot Pilot whose ship variable is being manipulated.
varname string Name of the variable to check value of.
shipname string Name of the ship to check variable of. Defaults to pilot's current ship. (optional)

Usage:

local exp = p:shipvarPeek( "exp" ) -- Checks the value of the "exp"
ship var on the player's current ship

shipvarPop (p, varname)

Pops a ship variable.

Parameters:

p Pilot Pilot whose ship variable is being manipulated.
varname string Name of the variable to pop.

shipvarPush (p, varname, val)

Pushes a ship variable.

Parameters:

p Pilot Pilot whose ship variable is being manipulated.
varname string Name of the variable to set value of.
val Value to push.

signature (p)

Gets the pilot's signature range.

Parameters:

p Pilot Pilot to get the signature of.

Returns:

number

Usage:

d = p:signature()

spaceworthy (p)

Checks the pilot's spaceworthiness.

Message can be non-null even if spaceworthy.

Parameters:

p Pilot Pilot to get the spaceworthy status of.

Returns:

boolean Whether the pilot's ship is spaceworthy.
string Reason why the pilot is not spaceworthy.

Usage:

spaceworthy = p:spaceworthy()

speed (p)

Gets the speed of a pilot.

Note that this is not current velocity.

Parameters:

p Pilot Pilot to get speed of.

Returns:

number

speedMax (p)

Gets the maximum speed of a pilot.

Parameters:

p Pilot Pilot to get maximum speed of.

Returns:

number

stats (p)

Gets stats of the pilot.

Some of the stats are:

cpu
cpu_max
crew
fuel
fuel_max
fuel_consumption
mass
accel
speed
speed_max
turn
absorb
armour
shield
energy
armour_regen
shield_regen
energy_regen
jump_delay
jumps

Parameters:

p Pilot Pilot to get stats of.

Returns:

table

Usage:

stats = p:stats() print(stats.armour)

stealth (p)

Tells the pilot to try to stealth.

Pilot must be under manual control for this to work.

Parameters:

p Pilot Pilot to tell to try to stealth.

Parameters:

p Pilot Pilot to get the stealth range of.

Returns:

number

stress (p[, absolute=false])

Gets the pilot's stress.

Parameters:

p Pilot Pilot to get stress of.
absolute boolean Whether or not it shouldn't be relative and be absolute instead. (default false)

Returns:

number

Usage:

stress = p:stress()

target (p)

Gets the pilot target of the pilot.

Parameters:

p Pilot Pilot to get target of.

Returns:

Pilot or nil

Usage:

target = p:target()

targetAsteroid (p)

Gets the asteroid target of the pilot.

Parameters:

p Pilot Pilot to get asteroid target of.

Returns:

table or nil

Usage:

target = p:targetAsteroid()

task (p)

Gets the name and data of a pilot's current task.

Parameters:

p Pilot Pilot to get task data of.

Returns:

string Name of the task.
Data of the task.

taskClear (p)

Clears all the tasks of the pilot.

Parameters:

p Pilot Pilot to clear tasks of.

Usage:

p:taskClear()

taskdata (p)

Gets the data of the task the pilot is currently doing.

Parameters:

p Pilot Pilot to get task data of.

Returns:

Data of the task.

taskname (p)

Gets the name of the task the pilot is currently doing.

Parameters:

p Pilot Pilot to get task name of.

Returns:

string Name of the task.
string or nil Name of the subtask if applicable, or nil otherwise.

taskstack (p)

Gets the name of all the pilot's current tasks (not subtasks).

Parameters:

p Pilot Pilot to get task stack of.

toggleSpawn ([fac[, enable=false]])

Disables or enables pilot spawning in the current system.

If player jumps the spawn is enabled again automatically. Global spawning takes priority over faction spawning.

Parameters:

fac Faction or table Faction or table of factions to enable or disable spawning off. If ommited it works on global spawning. (optional)
enable boolean true enables spawn, false disables it. (default false)

Returns:

boolean

Usage:

pilot.toggleSpawn() -- Defaults to disabling global spawning

pilot.toggleSpawn( false ) -- Disables global spawning

pilot.toggleSpawn( "Pirate" ) -- Defaults to disabling pirate spawning

pilot.toggleSpawn( "Pirate", true ) -- Turns on pirate spawning

tryStealth (p)

Tries to make the pilot stealth.

Parameters:

p Pilot Pilot to try to make stealth.

Returns:

boolean

turn (p)

Gets the turn of a pilot.

Parameters:

p Pilot Pilot to get turn of.

Returns:

number

vel (p)

Gets the pilot's velocity.

Parameters:

p Pilot Pilot to get the velocity of.

Returns:

Vec2

Usage:

vel = p:vel()

weapset (p[, id=all])

Gets the weapset weapon of the pilot.

The weapon sets have the following structure:

outfit: the outfit.
cooldown: [0:1] value indicating if ready to shoot (1 is ready).
charge: [0:1] charge level of beam weapon (1 is full).
left: Absolute ammo left or nil if not applicable.
left_p: Relative ammo left [0:1] or nil if not applicable
lockon: Lock-on [0:1] for seeker weapons or nil if not applicable.
in_arc: Whether or not the target is in targeting arc or nil if not applicable.
active: Whether or not the weapon is currently active.
type: Type of the weapon.
dtype: Damage type of the weapon.
track: Tracking level of the weapon.

An example would be:

 wsname, ws = p:weapset( true )
 print( "Weapnset Name: " .. wsname )
 for i, w in ipairs(ws) do
print( "Name: " .. w.name )
print( "Cooldown: " .. tostring(w.cooldown) )

 end

Parameters:

p Pilot Pilot to get weapset weapon of.
id number ID of the set to get information of. Defaults to currently active set. (default all)

Returns:

string The name of the set.
table A table with each slot's information.

Usage:

set_name, slots = p:weapset() -- Gets info for all active
 weapons

set_name, slots = p:weapset( 5 ) -- Get info about the set number 5

weapsetAdd (p, id, slot)

Adds an outfit to a pilot's weapon set.

Parameters:

p Pilot Pilot to remove weapon from weapon set.
id integer ID of the weapon set as shown in game (from 0 to 9).
slot string or integer Slot to add to weapon set. Can be passed by either id or name.

weapsetAddType (p, id, slot)

Adds an outfit to a pilot's weapon set.

Parameters:

p Pilot Pilot to remove weapon from weapon set.
id integer ID of the weapon set as shown in game (from 0 to 9).
slot string or integer Slot to add to weapon set. Can be passed by either id or name.

weapsetAmmo (p[, id], level)

Gets the ammo left of a weapon set.

Parameters:

p Pilot Pilot to get weapon set ammo for.
id number Optional parameter indicating id of weapon set to get ammo of. (optional)
level number Level of weapon set to get range of.

Returns:

number

weapsetAuto (p)

Makes the pilot's weapons get automatically set.

Parameters:

p Pilot Pilot to automatically handle weapon sets for.

weapsetCleanup (p[, id])

Cleans up a weapon set. This removes all properties of the weapon set and resets it.

Parameters:

p Pilot Pilot to remove weapon from weapon set.
id integer ID of the weapon set as shown in game (from 0 to 9). Cleans them all up if set to nil or not set. (optional)

weapsetList (p, id)

Get a list of all the outfits in a weapon set.

Parameters:

p Pilot Pilot to set weapon set outfit list of.
id integer ID of the weapon set as shown in game (from 0 to 9).

Returns:

table

weapsetRm (p, id, slot)

Removes an outfit from a pilot's weapon set.

Parameters:

p Pilot Pilot to remove weapon from weapon set.
id integer ID of the weapon set as shown in game (from 0 to 9).
slot string or integer Slot to remove from weapon set. Can be passed by either id or name.

weapsetSetInrange (p[, id=nil], docheck)

Sets whether a pilot's weapon set does inrange checks.

Parameters:

p Pilot Pilot to get weapset weapon of.
id number ID of the weapon set to set inrange check status, or nil for all. (default nil)
docheck boolean Whether or not to do inrange checks.

weapsetType (p, id, type)

Sets the type of a weapon set for a pilot.

Parameters:

p Pilot Pilot to set weapon set type of.
id integer ID of the weapon set as shown in game (from 0 to 9).
type string Type of the weapon set. Can be either "toggle", or "hold".

withPlayer (p)

Checks to see if pilot is with player.

Parameters:

p Pilot Pilot to check to see if is with player.

Returns:

boolean

worth (p[, count_unique=false])

Gets the worth of a pilot (total value of ship and outfits).

Parameters:

p Pilot Pilot to get worth of.
count_unique boolean Whether or not to count unique outfits too. (default false)

Returns:

number

Naev Lua API

Modules

Module pilot

Functions

Functions

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

See also:

Usage:

Parameters:

Returns:

Parameters:

See also:

Usage:

Parameters:

See also:

Parameters:

Usage:

Parameters:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Module `pilot`