Module `player`

Lua bindings to interact with the player.

These bindings let you modify stuff about the player and find out special information. General usage would be calls like:

 pname = player.name()
 shipname = player.ship()

Functions

name ()	Gets the player's name.
ship ()	Gets the player's ship's name (given by the player).
pay (amount[, nohooks])	Pays the player an amount of money.
credits ([decimal])	Gets how many credits the player has on him.
wealth ([decimal])	Gets how many credits the player owns both directly, and in the form of assets (ships, outfits, ...).
msg (message[, display=false])	Sends the player an in-game message.
msgClear ()	Clears the player's message buffer.
msgToggle (boolean)	Clears the player's message buffer.
omsgAdd (msg[, duration=10[, fontsize=16[, col=white]]])	Adds an overlay message.
omsgChange (id, msg, duration)	Changes an overlay message.
omsgRm (id)	Removes an overlay message.
allowSave ([b=true])	Sets player save ability.
pos ()	Gets the player's position.
pilot ()	Gets the player's associated pilot.
jumps ()	Gets a player's jump range based on their remaining fuel.
fuel ()	Gets the amount of fuel a player has.
refuel ([fuel])	Refuels the player.
autonav ()	Checks to see if the player has autonav enabled.
autonavSetTarget (sys, add)	Set the autonav target system to travel to.
autonavSetPos (pos)	Indicates the player where their autonav target position is.
autonavDest ()	Gets the player's long term autonav destination.
autonavRoute ()	Gets the player's autonav route.
autonavAbort ([msg])	Stops the players autonav if active.
autonavReset ([timer=0.])	Resets the game speed without disabling autonav.
autonavEnd ()	Ends the autonav system.
dt_defaults ()	Gets the current time modifier for the player.
sped ()	Gets the current speed of the player.
setSpeed (speed[, sound=speed[, noset=false]])	Sets the game speed directly.
cinematics (enable, options)	Puts the game in cinematics mode or back to regular mode.
damageSPFX (mod)	Applies the damage effects to the player.
screenshot ()	Takes a screenshot (same as the keyboard action).
tryBoard (noisy)	Tries to make the player board their target.
unboard ()	Unboards the player from its boarded target.
isLanded ()	Checks to see if the player is landed or not.
takeoff ()	Forces the player to take off if they are landed.
tryBoard (noisy)	Tries to make the player land.
land (spb)	Automagically lands the player on a spob.
landAllow ([b=true[, msg]])	Allows or disallows the player to land.
landWindow (winname)	Sets the active land window.
commOpen (Target)	Opens communication with a pilot or spob.
commClose ()	Forces the player to close comm if they are chatting.
shipvarPeek (varname[, shipname])	Peeks at a ship variable.
shipvarPush (varname, val[, shipname])	Pushes a ship variable.
shipvarPop (varname[, shipname])	Pops a ship variable.
ships ()	Gets the names of the player's ships.
shipOutfits (name)	Gets the outfits for one of the player's ships.
shipMetadata (name)	Gets meta-data about one of the player's ships.
shipDeploy (shipname[, deploy=false])	Sets the deployed status of a player's ship.
outfits ([unequipped_only=false])	Gets all the outfits the player owns.
outfitNum (name[, unequipped_only=false])	Gets the number of outfits the player owns in their list (excludes equipped on ships).
outfitAdd (name[, q=1])	Adds an outfit to the player's outfit list.
outfitRm (name[, q])	Removes an outfit from the player's outfit list.
shipAdd (ship[, name=ship.get(ship):name()[, acquired[, noname=false]]])	Gives the player a new ship.
shipSwap (ship[, ignore_cargo=false[, remove=false]])	Swaps the player's current ship with a ship they own by name.
missions ()	Gets the list of the player's active missions.
misnActive (name)	Checks to see if the player has a mission active.
misnDone (name)	Checks to see if player has done a mission.
misnDoneList ()	Gets a list of all the missions the player has done.
evtActive (name)	Checks to see if the player has an event active.
evtDone (name)	Checks to see if player has done an event.
evtDoneList ()	Gets a list of all the events the player has done.
gui ()	Gets the player's current GUI.
guiList ()	Lists the GUIs the player can use.
guiSet ()	Sets the player's GUI.
fleetList ()	Lists the ships in the player's fleet.
fleetCargoFree ()	Gets the amount of cargo space free in the player's fleet.
fleetCargoMissionFree ()	Gets the free space for mission cargos on the player's ship.
fleetCargoUsed ()	Gets the amount of cargo space used in the player's fleet.
fleetCargoOwned (c)	Gets the amount of cargo space used by a specific commodity in the player's fleet.
fleetCargoAdd (c, q)	Tries to add an amount of commodity to the player's fleet.
fleetCargoRm (c, q)	Tries to remove an amount of commodity to the player's fleet.
fleetCargoJet (c, q)	Tries to remove an amount of commodity to the player's fleet and jettisons it into space.
fleetCargoList ()	Gets the list of all the cargos in the player's fleet.
inventory ()	Gets the contents of the player's inventory.
inventoryAdd (name, quantity)	Adds an item to the player's in-game inventory.
inventoryAdd (name, quantity)	Removes an item to the player's in-game inventory.
inventoryAdd (name)	Checks to see how much of an item the player has in their inventory.
teleport (dest[, no_simulate=false[, silent=false]])	Teleports the player to a new spob or system (only if not landed).
dt_mod ()	Gets the dt_mod of the player, which multiplies all time stuff.
fleetCapacity ()	Gets the fleet capacity (and used) of the player.
fleetCapacitySet (capacity)	Sets the fleet capacity of the player.
chapter ()	Gets the player's current chapter.
chapterSet (chapter)	Sets the player's current chapter.
infoButtonRegister (caption, func[, priority[, key]])	Registers a button in the info window.
infoButtonUnregister (ID)	Unregisters a button in the info window.
canDiscover ([or=false])	Global toggle to whether or not the player can discover space objects and jumps.
save ([name="autosave"[, Spob=nil]])	Saves the game.
saveBackup (name)	Backs up the player's last autosave with a custom name.
gameover ()	Gives the player a game over message.
start ()	Gets information about the player's starting point.

Functions

name ()

Gets the player's name.

Returns:

string

ship ()

Gets the player's ship's name (given by the player).

Note Not to be confused with getting the player's ship that can be done with player.pilot():ship().

Returns:

string

pay (amount[, nohooks])

Pays the player an amount of money.

Parameters:

amount number Amount of money to pay the player in credits.
nohooks boolean or string Set to true to not trigger pay hooks, or a string value to pass that to the pay hook instead. (optional)

Usage:

player.pay( 500 ) -- Gives player 500 credits

credits ([decimal])

Gets how many credits the player has on him.

Parameters:

decimal number Optional argument that makes it return human readable form with so many decimals. (optional)

Returns:

number The amount of credits in numerical form.
string The amount of credits in human-readable form.

Usage:

```
monies = player.credits()
```
```
monies, readable = player.credits( 2 )
```

wealth ([decimal])

Gets how many credits the player owns both directly, and in the form of assets (ships, outfits, ...).

Parameters:

decimal number Optional argument that makes it return human readable form with so many decimals. (optional)

Returns:

number The player's wealth in numerical form.
string The player's wealth in human-readable form.

Usage:

```
monies = player.wealth()
```
```
monies, readable = player.wealth( 2 )
```

msg (message[, display=false])

Sends the player an in-game message.

Parameters:

message string Message to send the player.
display boolean Display the message over the player's ship (like a broadcast message). (default false)

msgClear ()

Clears the player's message buffer.

msgToggle (boolean)

Clears the player's message buffer.

Parameters:

boolean ( enable Whether or not to enable the player receiving messages.

omsgAdd (msg[, duration=10[, fontsize=16[, col=white]]])

Adds an overlay message.

Parameters:

msg string Message to add.
duration number Duration to add message in seconds (if 0. the duration is infinite). (default 10)
fontsize number Size of the font to use. (default 16)
col Colour Colour to use for the text or white if not specified. (default white)

Returns:

number

Usage:

player.omsgAdd( "some_message", 5 )

omsgChange (id, msg, duration)

Changes an overlay message.

Parameters:

id number ID of the overlay message to change.
msg string Message to change to.
duration number New duration to set in seconds (0. for infinity).

Returns:

boolean

Usage:

player.omsgChange( omsg_id, "new message", 3 )

omsgRm (id)

Removes an overlay message.

Parameters:

id number ID of the overlay message to remove.

Usage:

player.omsgRm( msg_id )

allowSave ([b=true])

Sets player save ability.

Parameters:

b boolean true if the player is allowed to save, false otherwise. (default true)

Usage:

player.allowSave( b )

pos ()

Gets the player's position.

Returns:

Vec2

Usage:

v = player.pos()

pilot ()

Gets the player's associated pilot.

Returns:

Pilot

jumps ()

Gets a player's jump range based on their remaining fuel.

Returns:

number

Usage:

jumps = player.jumps()

fuel ()

Gets the amount of fuel a player has.

Returns:

number The player's fuel and
number The amount of fuel needed per jump.

Usage:

fuel, consumption = player.fuel()

refuel ([fuel])

Refuels the player.

Parameters:

fuel number Amount of fuel to add, will set to max if nil. (optional)

Usage:

```
player.refuel() -- Refuel fully
```

player.refuel( 200 ) -- Refuels partially

autonav ()

Checks to see if the player has autonav enabled.

Returns:

boolean true if the player has autonav enabled.
number Speed of the current autonav.

Usage:

autonav = player.autonav()

autonavSetTarget (sys, add)

Set the autonav target system to travel to.

Parameters:

sys StarSystem Star system to set as autonav target.
add boolean Whether or not this should be added to the current route.

autonavSetPos (pos)

Indicates the player where their autonav target position is.

Parameters:

pos Vec2 or nil Position to mark as autonav destination or nil to clear.

autonavDest ()

Gets the player's long term autonav destination.

Returns:

System or nil The destination system (or nil if none selected).
number or nil The number of jumps left.

Usage:

sys, jumps = player.autonavDest()

autonavRoute ()

Gets the player's autonav route.

Returns:

Table

Usage:

syslist = player.autonavRoute()

autonavAbort ([msg])

Stops the players autonav if active.

Parameters:

msg string Abort message. (optional)

Usage:

sys, jumps = player.autonavAbort()

<em>Note</em> Does not do anything if the player is not in autonav.

autonavReset ([timer=0.])

Resets the game speed without disabling autonav.

Note Does not do anything if the player is not in autonav.

Parameters:

timer number How many seconds to wait before starting autonav up again. (default 0.)

autonavEnd ()

Ends the autonav system. You probably want to use player.autonavAbort instead of this.

dt_defaults ()

Gets the current time modifier for the player.

Returns:

number

sped ()

Gets the current speed of the player.

Returns:

number

setSpeed (speed[, sound=speed[, noset=false]])

Sets the game speed directly.

Parameters:

speed number Speed to set the game to. If omitted it will reset the game speed.
sound number Sound speed to set to. (default speed)
noset boolean Avoid setting player.speed. Useful for autonav. (default false)

cinematics (enable, options)

Puts the game in cinematics mode or back to regular mode.

Possible options are:

abort : (string) autonav abort message
no2x : (boolean) whether to prevent the player from increasing the speed, default false
gui : (boolean) enables the player's gui, default disabled

Parameters:

enable boolean If true sets cinematics mode, if false disables. Defaults to disable.
options table Table of options.

Usage:

player.cinematics( true, { gui = true } ) -- Enables cinematics
without hiding gui.

damageSPFX (mod)

Applies the damage effects to the player.

Parameters:

mod number How strong the effect should be. It should be a value between 0 and 1, usually corresponding to how much armour damage the player has taken with respect to their total armour.

screenshot ()

Takes a screenshot (same as the keyboard action).

tryBoard (noisy)

Tries to make the player board their target.

Parameters:

noisy boolean Whether or not to do player messages.

Returns:

string

unboard ()

Unboards the player from its boarded target.

Use from inside a board hook.

Usage:

player.unboard()

isLanded ()

Checks to see if the player is landed or not.

Returns:

boolean

takeoff ()

Forces the player to take off if they are landed.

Assume the pilot is still landed until the current running function returns If you want to create pilots on take off please hook the takeoff/land hooks.

tryBoard (noisy)

Tries to make the player land.

Parameters:

noisy boolean Whether or not to do player messages.

Returns:

string

land (spb)

Automagically lands the player on a spob.

Note that this will teleport the player to the system in question as necessary.

Parameters:

spb Spob Spob to land the player on.

landAllow ([b=true[, msg]])

Allows or disallows the player to land.

This will allow or disallow landing on a system level and is reset when the player enters another system.

Parameters:

b boolean Whether or not to allow the player to land. (default true)
msg string Message displayed when player tries to land (only if disallowed to land). Can be omitted to use default. (optional)

Usage:

player.landAllow() -- Allows the player to land

player.landAllow( false ) -- Doesn't allow the player to land.

player.landAllow( false, "No landing." ) -- Doesn't allow the player
to land with the message "No landing."

landWindow (winname)

Sets the active land window.

Valid windows are:
- main
- bar
- missions
- outfits
- shipyard
- equipment
- commodity

Parameters:

winname string Name of the window.

Returns:

boolean

Usage:

player.landWindow( "outfits" )

commOpen (Target)

Opens communication with a pilot or spob.

Will do no checks with spobs.

Parameters:

Target Pilot or Spob to open communication channel with.

Returns:

boolean

commClose ()

Forces the player to close comm if they are chatting.

shipvarPeek (varname[, shipname])

Peeks at a ship variable.

Parameters:

varname string Name of the variable to check value of.
shipname string Name of the ship to check variable of. Defaults to player's current ship. (optional)

Usage:

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

shipvarPush (varname, val[, shipname])

Pushes a ship variable.

Parameters:

varname string Name of the variable to set value of.
val Value to push.
shipname string Name of the ship to push variable to. Defaults to player's current ship. (optional)

shipvarPop (varname[, shipname])

Pops a ship variable.

Parameters:

varname string Name of the variable to pop.
shipname string Name of the ship to pop variable from. Defaults to player's current ship. (optional)

ships ()

Gets the names of the player's ships.

Returns:

{String,...}

Usage:

names = player.ships() -- The player's ship names.

shipOutfits (name)

Gets the outfits for one of the player's ships.

Parameters:

name string Name of the ship to get the outfits of.

Returns:

{Outfit,...}

Usage:

outfits = player.shipOutfits("Llama") -- Gets the Llama's outfits

shipMetadata (name)

Gets meta-data about one of the player's ships.

Parameters:

name string Name of the ship to get the meta-data of.

Returns:

Table

shipDeploy (shipname[, deploy=false])

Sets the deployed status of a player's ship.

Parameters:

shipname string Name of the ship to set deployed status of.
deploy boolean Whether or not to set the deployed status of the ship. (default false)

outfits ([unequipped_only=false])

Gets all the outfits the player owns.

If you want the quantity, call player.outfitNum() on the individual outfit.

Parameters:

unequipped_only bool Whether or not to check only the unequipped outfits and not equipped outfits. Defaults to false. (default false)

Returns:

{Outfit,...}

Usage:

player.outfits() -- A table of all the player's outfits.

outfitNum (name[, unequipped_only=false])

Gets the number of outfits the player owns in their list (excludes equipped on ships).

Parameters:

name string Name of the outfit to remove.
unequipped_only bool Whether or not to check only the unequipped outfits and not equipped outfits. Defaults to false. (default false)

Returns:

number

Usage:

q = player.outfitNum( "Laser Cannon MK0", true ) -- Number of 'Laser
Cannon MK0' the player owns (unequipped)

outfitAdd (name[, q=1])

Adds an outfit to the player's outfit list.

Parameters:

name string Name of the outfit to give.
q number Quantity to give. (default 1)

Usage:

player.outfitAdd( "Laser Cannon" ) -- Gives the player a laser cannon

player.outfitAdd( "Plasma Blaster", 2 ) -- Gives the player two plasma
blasters

outfitRm (name[, q])

Removes an outfit from the player's outfit list.

"all" will remove all outfits.

Parameters:

name string Name of the outfit to give.
q number Quantity to remove (default 1). (optional)

Usage:

player.outfitRm( "Plasma Blaster", 2 ) -- Removes two plasma blasters
from the player

shipAdd (ship[, name=ship.get(ship):name()[, acquired[, noname=false]]])

Gives the player a new ship.

Note Should be given when landed, ideally on a spob with a shipyard. Furthermore, this invalidates all player.pilot() references.

Parameters:

ship string Name of the ship to add.
name string Name to give the ship if player refuses to name it (defaults to shipname if omitted). (default ship.get(ship):name())
acquired string A description of how the ship was acquired. (optional)
noname boolean If true does not let the player name the ship. (default false)

Returns:

string

Usage:

player.shipAdd( "Pirate Kestrel", _("Seiryuu"), _("") ) -- Gives the
player a Pirate Kestrel named Seiryuu if player cancels the naming.

shipSwap (ship[, ignore_cargo=false[, remove=false]])

Swaps the player's current ship with a ship they own by name.

Note You shouldn't use this directly unless you know what you are doing. If the player's cargo doesn't fit in the new ship, it won't be moved over and can lead to a whole slew of issues. Note This invalidates all player.pilot() references!

Parameters:

ship string Name of the ship to swap to. (this is name given by the player, not ship name)
ignore_cargo boolean Whether or not to ignore cargo and not move it, or try to move it over. (default false)
remove boolean If true removes the player's current ship (so it replaces and doesn't swap). (default false)

missions ()

Gets the list of the player's active missions.

Returns:

table

Usage:

n = \#player.missions() -- number of active missions

misnActive (name)

Checks to see if the player has a mission active.

Parameters:

name string Name of the mission to check.

Returns:

boolean or number

Usage:

if player.misnActive( "The Space Family" ) then -- Player is doing
space family mission

misnDone (name)

Checks to see if player has done a mission.

This only works with missions that have the unique flag.

Parameters:

name string Name of the mission to check.

Returns:

boolean

Usage:

if player.misnDone( "The Space Family" ) then -- Player finished
 mission

misnDoneList ()

Gets a list of all the missions the player has done.

Returns:

table

evtActive (name)

Checks to see if the player has an event active.

Parameters:

name string Name of the mission to check.

Returns:

boolean

Usage:

if player.evtActive( "Shipwreck" ) then -- The shipwreck event is
active

evtDone (name)

Checks to see if player has done an event.

This only works with events that have the unique flag.

Parameters:

name string Name of the event to check.

Returns:

boolean

Usage:

if player.evtDone( "Shipwreck" ) then -- Player finished event

table

Usage:

for k,v in ipairs( player.fleetCargoList() ) do print( v.c, v.q ) end

inventory ()

Gets the contents of the player's inventory.

name string The name of the item to check.

Returns:

integer

teleport (dest[, no_simulate=false[, silent=false]])

Teleports the player to a new spob or system (only if not landed).

If the destination is a system, the coordinates of the player will not change. If the destination is a spob, the player will be placed over that spob.

Parameters:

dest System, Spob or string System or name of a system or spob or name of a spob to teleport the player to.
no_simulate boolean Don't simulate the when teleporting if true. (default false)
silent boolean Doesn't display any entering system messages. (default false)

Usage:

player.teleport( system.get("Arcanis") ) -- Teleports the player to
 Arcanis.

player.teleport( "Arcanis" ) -- Teleports the player to Arcanis.

player.teleport( "Dvaer Prime" ) -- Teleports the player to Dvaer, and
 relocates him to Dvaer Prime.

player.teleport( "Sol", true ) -- Teleports the player to SOL, but
doesn't run any initial simulation

dt_mod ()

Gets the dt_mod of the player, which multiplies all time stuff.

Returns:

number

fleetCapacity ()

Gets the fleet capacity (and used) of the player.

Returns:

number Total fleet capacity of the player.
number Currently used fleet capacity of the player.
boolean Can take off.

fleetCapacitySet (capacity)

Sets the fleet capacity of the player.

Parameters:

capacity number Fleet capacity to set the player to.

chapter ()

Gets the player's current chapter.

Returns:

string

chapterSet (chapter)

Sets the player's current chapter.

Parameters:

chapter string The name of the chapter to set the player to.

infoButtonRegister (caption, func[, priority[, key]])

Registers a button in the info window.

Parameters:

caption string Caption of the button.
func function Function to run when clicked.
priority number Button priority, lower is more important. (optional)
key string Hotkey for using the button without it being focused. (optional)

Returns:

number

infoButtonUnregister (ID)

Unregisters a button in the info window.

Parameters:

ID number of the button to unregister.

canDiscover ([or=false])

Global toggle to whether or not the player can discover space objects and jumps. Meant to be used with cutscenes that use player.teleport().

Parameters:

or Whether not the player can discover objects. (default false)

save ([name="autosave"[, Spob=nil]])

Saves the game.

Parameters:

name string What to name the save. (default "autosave")
Spob Spob or string or name of spob to save the player at. (default nil)

saveBackup (name)

Backs up the player's last autosave with a custom name.

Parameters:

name string Name to give the copy of the autosave.

Returns:

boolean

gameover ()

Gives the player a game over message.

start ()

Gets information about the player's starting point.

Returns:

Returns

dat/start.xml

Naev Lua API

Modules

Module player

Functions

Functions

Returns:

Returns:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Returns:

Usage:

Returns:

Returns:

Usage:

Returns:

Usage:

Parameters:

Usage:

Returns:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Returns:

Parameters:

Parameters:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Usage:

Parameters:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Parameters:

Parameters:

Module `player`