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

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

Functions

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 )

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/>

clone (p)

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

Parameters:

p Pilot Pilot to clone.

Returns:

Pilot

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

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

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")

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()

canSpawn ()

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

Returns:

boolean

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

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

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,...}

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,...}

__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)

name (p)

Gets the pilot's current (translated) name.

Parameters:

p Pilot Pilot to get the name of.

Returns:

string

Usage:

name = p:name()

id (p)

Gets the ID of the pilot. Guaranteed to be unique per pilot and not repeating over time (with the exception of the player).

Parameters:

p Pilot Pilot to get the ID of.

Returns:

number The ID of the current pilot.

Usage:

id = p:id()

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

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()

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.

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()

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.

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 )

scandone ()

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

Returns:

boolean

withPlayer (p)

Checks to see if pilot is with player.

Parameters:

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

Returns:

boolean

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()

navSpob (p)

Gets the nav spob target of the pilot.

Parameters:

p Pilot Pilot to get nav info of.

Returns:

Spob or nil

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.

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

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.
heat: Heat level of the weapon where 1 is normal and 0 is overheated.
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

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

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".

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.

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.

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.

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)

weapsetHeat (p[, id])

Gets heat information for a weapon set.

Heat is a 0-2 value that corresponds to three separate ranges:

0: Weapon set isn't overheating and has no penalties.
0-1: Weapon set has reduced accuracy.
1-2: Weapon set has full accuracy penalty plus reduced fire rate.

Parameters:

p Pilot Pilot to get weapset weapon of.
id number ID of the set to get information of. Defaults to all weapon sets. (optional)

Returns:

number Mean heat.
number Peak heat.

Usage:

hmean, hpeak = p:weapsetHeat() -- Gets info for all active
 weapons

hmean, hpeak = p:weapsetHeat( 5 ) -- Get info about the set number 5

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.

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.

actives (p[, sort=false])

Gets the active outfits and their states of the pilot.

The active outfits have the following structure:

outfit: The outfit.
type: Type of the outfit.
active: Whether or not the outfit is active at the current time.
heat: The heat of the outfit's slot. A value between 0 and 1, where 0 is fully overheated, and 1 is normal.
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

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

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)

Equips a pilot with a set of outfits.

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.

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

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 or not to activate or deactivate the outfit. (default false)

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

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") )

pos (p)

Gets the pilot's position.

Parameters:

p Pilot Pilot to get the position of.

Returns:

Vec2

Usage:

v = p:pos()

vel (p)

Gets the pilot's velocity.

Parameters:

p Pilot Pilot to get the velocity of.

Returns:

Vec2

Usage:

vel = p:vel()

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

signature (p)

Gets the pilot's signature.

Parameters:

p Pilot Pilot to get the signature of.

Returns:

number

Usage:

d = p:signature()

dir (p)

Gets the pilot's direction.

Parameters:

p Pilot Pilot to get the direction of.

Returns:

number

Usage:

d = p:dir()

temp (p)

Gets the temperature of a pilot.

Parameters:

p Pilot Pilot to get temperature of.

Returns:

number

Usage:

t = p:temp()

mass (p)

Gets the mass of a pilot.

Parameters:

p Pilot Pilot to get mass of.

Returns:

number

Usage:

m = p:mass()

accel (p)

Gets the accel of a pilot.

Parameters:

p Pilot Pilot to get accel of.

Returns:

number

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

turn (p)

Gets the turn of a pilot.

Parameters:

p Pilot Pilot to get turn of.

Returns:

number

faction (p)

Gets the pilot's faction.

Parameters:

p Pilot Pilot to get the faction of.

Returns:

Faction

Usage:

f = p:faction()

reputation (p)

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

Parameters:

p Pilot Pilot to get the reputation with.

Returns:

number

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

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

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()

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 ) )

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 ) )

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 )

broadcast (p, msg[, ignore_int=false])

Makes the pilot broadcast a message.

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

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

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" ) )

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.

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.

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

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

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

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.

setInvisible (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.

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 )

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 )

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 )

setHilight (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 )

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 )

disabled (p)

Gets the disabled state of a pilot.

Parameters:

p Pilot Pilot to get disabled state of.

Returns:

boolean

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

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()

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()

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 )

cooldownCycle (p)

Makes the pilot do an instant full cooldown cycle.

Parameters:

p Pilot Pilot to perform cycle.

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 )

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 )

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.

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

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

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

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.

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

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).

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

fuel ()

Gets the amount of fuel the pilot has.

Returns:

number

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

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%

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.

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%

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.

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.

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

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.

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

effects (p)

Gets the effects on a pilot.

Parameters:

p Pilot Pilot to get effects of.

Returns:

table

ai (p)

Gets the pilot's AI.

Parameters:

p Pilot Pilot to get AI of.

Returns:

string

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

setTemp (p, temp[, noslots=false])

Sets the temperature of a pilot.

All temperatures are in Kelvins. Note that temperatures cannot go below the base temperature of the Naev galaxy, which is 250K.

Parameters:

p Pilot Pilot to set health of.
temp number Value to set temperature to. Values below base temperature will be clamped.
noslots boolean Whether slots should also be set to this temperature. (default false)

Usage:

p:setTemp( 300, true ) -- Sets ship temperature to 300K, as well as
 all outfits.

p:setTemp( 500, false ) -- Sets ship temperature to 500K, but leaves
 outfits alone.

p:setTemp( 0 ) -- Sets ship temperature to the base temperature, as
well as all outfits.

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

setHealth (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)

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.)

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.

addEnergy (p, energy)

Adds (or subtracts) energy to a pilot.

Parameters:

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

fillAmmo (p)

Fills up the pilot's ammo.

Parameters:

p Pilot Pilot to fill ammo.

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

setNoDisable (p[, disable=true])

Sets the ability of the pilot to 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.

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.

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()

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()

shield (p[, absolute=false])

Gets the pilot's shield.

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()

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()

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()

lockon (p)

Gets the lockons on the pilot.

Parameters:

p Pilot Pilot to get lockons of.

Returns:

number

Usage:

lockon = p:lockon()

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)

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

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.

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

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 )

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

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

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

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

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()

colour (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

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()

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

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.

ship (p)

Gets the pilot's ship.

Parameters:

p Pilot Pilot to get ship of.

Returns:

Ship

Usage:

s = p:ship()

radius (p)

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

Parameters:

p Pilot Pilot to get radius of.

Returns:

number

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

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

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.

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
```

memory (p)

Gets a pilots ship memory table.

The resulting table is indexable and mutable.

Parameters:

p Pilot Pilot to get ship memory of.

ainame (p)

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

Parameters:

p Pilot Pilot to get task name of.

Returns:

string

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.

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.

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.

taskClear (p)

Clears all the tasks of the pilot.

Parameters:

p Pilot Pilot to clear tasks of.

Usage:

p:taskClear()

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.

poptask (p)

Pops the current task from the pilot's AI.

Equivalent to ai.poptask().

Parameters:

p Pilot Pilot to pop task from.

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)

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

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

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 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 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.
```

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

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

gather ()

Makes the pilot gather stuff.

Usage:

p:gather( ) -- Try to gather stuff

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

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 tell to try to stealth.

Parameters:

p Pilot Pilot to try to make stealth.

Returns:

boolean

destealth (p)

Tries to make the pilot stealth.

Parameters:

p Pilot Pilot to try to make stealth.

Returns:

boolean

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 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

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)

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

leader (p)

Gets a pilots leader. Guaranteed to exist or will be nil.

Parameters:

p Pilot Pilot to get the leader of.

Returns:

Pilot or nil

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.

followers (p, hidefighters)

Get all of a pilots followers.

Parameters:

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

Returns:

{Pilot,...}

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()

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

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

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

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.

calcStats (p)

Forces a recomputation of the pilots' stats.

Parameters:

p Pilot Pilot to recalculate stats of.

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

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.

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.

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.

Naev Lua API

Modules

Module pilot

Functions

Functions

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Usage:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Module `pilot`