Ship

Class representing a ship.  Inherits from ModelBody.

Summary
ShipClass representing a ship.
Methods
IsPlayerDetermines if the ship is the player ship
SetShipTypeReplaces the ship with a new ship of the specified type.
GetShipTypeReturns a string describing the ship type
GetShipClassReturns a string describing the ship class
SetHullPercentSets the hull mass of the ship to the given precentage of its maximum.
SetFuelPercentSets the thruster fuel tank of the ship to the given precentage of its maximum.
ExplodeDestroys the ship in an explosion
GetSkinGet the current skin object of the ship.
SetSkinSet the skin of the ship.
SetPatternChanges the pattern used for texturing the ship.
SetLabelChanges the ship’s label text.
SetShipNameChanges the ship’s name text.
SpawnCargoSpawns a container right next to the ship.
GetDockedWithGet the station that the ship is currently docked with
UndockUndock from the station currently docked with
BlastOffBlast off if landed on a surface.
SpawnMissileSpawn a missile near the ship.
UseECMActivates ECM of ship, destroying nearby missile with probability proportional to proximity.
InitiateHyperjumpToReady the ship to jump to the given system.
AbortHyperjumpAbort the upcoming hyperjump
GetInvulnerableFind out whether a ship can take damage or not.
SetInvulnerableMake a ship invulnerable to damage (or not).
GetWheelStateReturn the current state of the landing gear.
GetFlightStateReturn the current flight state of a ship as a string.
GetFlightControlStateReturn the current flight control state.
GetSetSpeedReturn the current SetSpeed speed in m/s.
GetSetSpeedTargetReturn the current SetSpeed target of the ship.
ToggleWheelStateIf the landing gear of the ship is up, start lowering it, and vice versa.
GetVelocityGet the ships velocity
GetStatsReturn some ship stats.
GetPositionGet the ship’s position
GetHullTemperature
GetGunTemperature
GetHullPercent
GetShieldPercent
IsDockedReturn true if the ship is docked.
IsLandedReturn true if the ship is landed.
GetHyperspaceCountdownReturn the current hyperspace countdown in seconds.
GetHyperspaceDestinationReturn the current hyperspace destination.
IsHyperspaceActiveReturn true if a hyperspace countdown is currently running.
GetThrusterStateReturn the state of the directional thrusters.
AI methodsThe AI methods are the script’s equivalent of the autopilot.
AIKillAttack a target ship and continue until it is destroyed
AIKamikazeCrash into the target ship.
AIFlyToFly to the vicinity of a given physics body
AIDockWithFly to and dock with a given station
AIEnterLowOrbitFly to and enter a low orbit around a given planet or star
AIEnterMediumOrbitFly to and enter a medium orbit around a given planet or star
AIEnterHighOrbitFly to and enter a high orbit around a given planet or star
CancelAICancel the current AI command
UpdateEquipStatsUpdate the ship’s statistics with regards to equipment changes
Attributes
alertStatusThe current alert status of the ship.
flightStateThe current flight state of the ship.
shipIdThe internal id of the ship type.
fuelThe current amount of fuel, as a percentage of full
fuelMassLeftRemaining thruster fuel mass in tonnes.
hullMassLeftRemaining hull integrity in tonnes.
shieldMassLeftRemaining shield strength in tonnes.
shieldMassMaximum shield strength for installed shields.
hyperspaceRangeFurthest possible hyperjump given current hyperspace fuel available.
maxHyperspaceRangeFurthest possible hyperjump assuming no limits to available hyperspace fuel.
staticMassMass of the ship including hull, equipment and cargo, but excluding thruster fuel mass.
usedCapacityHull capacity used by equipment and cargo.
usedCargoHull capacity used by cargo only (not equipment).
freeCapacityTotal space remaining.

Methods

IsPlayer

Determines if the ship is the player ship

isplayer = ship:IsPlayer()

Returns

isplayertrue if the ship is the player, false otherwise

Example

if Game.player:IsPlayer() then
    print("this is the player")
end

Availability

alpha 10

Status

stable

SetShipType

Replaces the ship with a new ship of the specified type.

ship:SetShipType(newtype)

Parameters

newtypethe name of the ship

Example

ship:SetShipType('sirius_interdictor')

Availability

alpha 15

Status

experimental

GetShipType

Returns a string describing the ship type

local shiptype = ship:GetShipType()

Availability

2017-04

Status

stable

GetShipClass

Returns a string describing the ship class

local shipclass = ship:GetShipClass()

Availability

2017-04

Status

stable

SetHullPercent

Sets the hull mass of the ship to the given precentage of its maximum.

ship:SetHullPercent(percent)

Setting the hull percentage to 0 will not destroy the ship until it takes damage.

Parameters

percentoptional.  A number from 0 to 100.  Less then 0 will use 0 and greater than 100 will use 100.  Defaults to 100.

Example

ship:SetHullPercent(3.14)

Availability

alpha 15

Status

experimental

SetFuelPercent

Sets the thruster fuel tank of the ship to the given precentage of its maximum.

ship:SetFuelPercent(percent)

Parameters

percentoptional.  A number from 0 to 100.  Less then 0 will use 0 and greater than 100 will use 100.  Defaults to 100.

Example

ship:SetFuelPercent(50)

Availability

alpha 20

Status

experimental

Explode

Destroys the ship in an explosion

ship:Explode()

Availability

alpha 20

Status

experimental

GetSkin

Get the current skin object of the ship.

ship:GetSkin()

Parameters

Example

ship:GetSkin()

Status

experimental

SetSkin

Set the skin of the ship.

ship:SetSkin(skin)

Parameters

skinthe skin object of the ship this can be created using SceneGraph.ModelSkin.New()

Example

ship:GetSkin(skin)

Status

experimental

SetPattern

Changes the pattern used for texturing the ship.

ship:SetPattern(num)

Parameters

numthe pattern number

Example

ship:SetPattern(5)

Status

experimental

SetLabel

Changes the ship’s label text.  This is the text that appears beside the ship in the HUD.

ship:SetLabel(newlabel)

Parameters

newlabelthe new label

Example

ship:SetLabel("AB-1234")

Availability

alpha 10

Status

stable

SetShipName

Changes the ship’s name text.  This is the name text that appears beside the ship in the HUD.

ship:SetShipName(newShipName)

Parameters

newShipNamethe new name of the ship

Example

ship:SetShipName("Boris")

Availability

September 2014

Status

stable

SpawnCargo

Spawns a container right next to the ship.

success = ship:SpawnCargo(item, lifeTime)

Parameters

itemthe item to put in the container.
lifeTimeoptional. time in seconds until self destruct.  Setting to 0 sec means no self destruct while player is in system.

Result

success: true if the container was spawned, false otherwise.

Example

Game.player:SpawnCargo(Equipment.cargo.hydrogen, 0)
Game.player:SpawnCargo(Equipment.cargo.hydrogen)

Availability

alpha 26

Status

experimental

GetDockedWith

Get the station that the ship is currently docked with

station = ship:GetDockedWith()

Return

stationa SpaceStation object for the station, or nil if the ship is not docked

Availability

alpha 10

Status

stable

Undock

Undock from the station currently docked with

success = ship:Undock()

Event.onShipUndocked will be triggered once undocking is complete

Return

successtrue if ship is undocking, false if the ship is unable to undock, probably because another ship is currently undocking

Availability

alpha 10

Status

stable

BlastOff

Blast off if landed on a surface.

SpawnMissile

Spawn a missile near the ship.

missile = ship:SpawnMissile(type, target, power)

Parameters

shiptypea string for the missile type. specifying an ship that is not a missile will result in a Lua error
targetthe Ship to fire the missile at
powerthe power of the missile.  If unspecified, the default power for the

Return

missileThe missile spawned, or nil if it was unsuccessful.

Availability

alpha 26

Status

experimental

UseECM

Activates ECM of ship, destroying nearby missile with probability proportional to proximity.

success, recharge_wait = Ship:UseECM()

Return

successis true or false depending on if the ECM was activated or not.  False indicating wither it is not fully recharged, or there is no ECM to activate.
recharge_waittime left to recharge.

Availability

2014 July

Status

experimental

InitiateHyperjumpTo

Ready the ship to jump to the given system.  This does not perform any check regarding hyperdrive class, range, fuel.  Nor does it respect minimum legal distance for hyperjump.  For those features use Ship.HyperjumpTo instead.

status = ship:InitiateHyperjumpTo(path, warmup, duration, checks)

Parameters

patha SystemPath for the destination system
warmupthe time, in seconds, needed for the engines to warm up.  Minimum time is one second, for saftey reasons.
durationtravel time, in seconds.
soundsa table of sounds, of the form: { warmup = “Hyperdrive_Charge”, abort = “Hyperdrive_Abort”, jump = “Hyperdrive_Jump”, } The values refer to sound-effects under the data/sounds/ directory.
checksoptional.  A function that doesn’t take any parameter and returns true as long as all the conditions for hyperspace are met.

Result

statusa Constants.ShipJumpStatus string that tells if the ship can hyperspace and if not, describes the reason

Availability

February 2014

Status

experimental

AbortHyperjump

Abort the upcoming hyperjump

ship:AbortHyperjump()

Availability

February 2014

Status

experimental

GetInvulnerable

Find out whether a ship can take damage or not.

is_invulnerable = ship:GetInvulnerable()

Return

is_invulnerableboolean; true if the ship is invulnerable to damage

Availability

November 2013

Status

experimental

SetInvulnerable

Make a ship invulnerable to damage (or not).  Note: Invulnerability is not currently stored in the save game.

ship:SetInvulnerable(true)

Availability

November 2013

Status

experimental

GetWheelState

Return the current state of the landing gear.

Returns

Return 0.0 if the landing gear is currently up, 1.0 if it is down, and a value in between if it is moving.

GetFlightState

Return the current flight state of a ship as a string.

Returns

One of

  • FLYING
  • DOCKING
  • UNDOCKING
  • DOCKED
  • LANDED
  • JUMPING
  • HYPERSPACE

GetFlightControlState

Return the current flight control state.

local state = ship:GetFlightControlState()

Returns

the current flight control state as a string, one of

  • CONTROL_MANUAL
  • CONTROL_FIXSPEED
  • CONTROL_FIXHEADING_FORWARD
  • CONTROL_FIXHEADING_BACKWARD
  • CONTROL_FIXHEADING_NORMAL
  • CONTROL_FIXHEADING_ANTINORMAL
  • CONTROL_FIXHEADING_RADIALLY_INWARD
  • CONTROL_FIXHEADING_RADIALLY_OUTWARD
  • CONTROL_FIXHEADING_KILLROT
  • CONTROL_AUTOPILOT

GetSetSpeed

Return the current SetSpeed speed in m/s.

local speed = ship:GetSetSpeed()

Returns

the current SetSpeed speed in m/s or nil if not in fix speed mode.

GetSetSpeedTarget

Return the current SetSpeed target of the ship.

Returns

The Body of the current SetSpeed target or nil.

ToggleWheelState

If the landing gear of the ship is up, start lowering it, and vice versa.

ship:ToggleWheelState()

GetVelocity

Get the ships velocity

ship:GetVelocity()

Availability

April 2016

Status

experimental

GetStats

Return some ship stats.

Returns

Return a table containing

  • usedCapacity
  • usedCargo
  • freeCapacity
  • staticMass
  • hullMassLeft
  • hyperspaceRange
  • hyperspaceRangeMax
  • shieldMass
  • shieldMassLeft
  • fuelTankMassLeft

GetPosition

Get the ship’s position

ship:GetPosition()

Availability

April 2016

Status

experimental

GetHullTemperature

Return the current hull temperature (0.01.0).

Returns

the hull temperature (0.01.0)

GetGunTemperature

Get a gun’s temperature (0.01.0).

Parameters

gun_indexthe index of the gun (0 for front, 1 for rear)

Returns

the gun’s current temperature (0.01.0)

GetHullPercent

Return the current percentage of hull left (0.01.0).

Returns

the current hull (0.01.0)

GetShieldPercent

Return the current percentage of shield left (0.01.0) or nil if no shield.

Returns

the current shield (0.01.0) or nil

IsDocked

Return true if the ship is docked.

Returns

true if the ship is docked

IsLanded

Return true if the ship is landed.

Returns

true if the ship is landed

GetHyperspaceCountdown

Return the current hyperspace countdown in seconds.

Returns

the current hyperspace countdown in seconds.

GetHyperspaceDestination

Return the current hyperspace destination.

Returns

paththe SystemPath of the destination
namea string of the name of the destination

IsHyperspaceActive

Return true if a hyperspace countdown is currently running.

Returns

true if a hyperspace countdown is currently running.

GetThrusterState

Return the state of the directional thrusters.

Returns

the state of the directional thrusters

AI methods

The AI methods are the script’s equivalent of the autopilot.  They are high-level commands to instruct the ship to fly somewhere and possibly take some action when it arrives (like dock or attack).

When an AI completes the Event.onAICompleted event is triggered, and the ship is left with engines off in whatever state the AI left it in.  For some AI methods (eg AIEnterLowOrbit) this is useful.  For others it will likely mean the ship will eventually succumb to gravity and crash somewhere.  You should invoke another AI method or take some other action to prevent this.

AIKill

Attack a target ship and continue until it is destroyed

ship:AIKill(target)

Note the combat AI currently will fly the ship and fire the lasers as necessary, but it will not activate any other equipment (missiles, ECM, etc).  It is the responsbility of the script to take those additional actions if desired.

Parameters

targetthe Ship to destroy

Returns

true if the command could be enacted, false otherwise

Availability

alpha 10

Status

experimental

AIKamikaze

Crash into the target ship.

ship:AIKamikaze(target)

Parameters

targetthe Ship to destroy

Returns

true if the command could be enacted, false otherwise

Availability

alpha 26

Status

experimental

AIFlyTo

Fly to the vicinity of a given physics body

ship:AIFlyTo(target)

Parameters

targetthe Body to fly to

Availability

alpha 10

Status

experimental

AIDockWith

Fly to and dock with a given station

ship:AIDockWith(target)

Parameters

targetthe SpaceStation to dock with

Availability

alpha 10

Status

experimental

AIEnterLowOrbit

Fly to and enter a low orbit around a given planet or star

ship:AIEnterLowOrbit(target)

Parameters

targetthe Star or Planet to orbit

Availability

alpha 10

Status

experimental

AIEnterMediumOrbit

Fly to and enter a medium orbit around a given planet or star

ship:AIEnterMediumOrbit(target)

Parameters

targetthe Star or Planet to orbit

Availability

alpha 10

Status

experimental

AIEnterHighOrbit

Fly to and enter a high orbit around a given planet or star

ship:AIEnterHighOrbit(target)

Parameters

targetthe Star or Planet to orbit

Availability

alpha 10

Status

experimental

CancelAI

Cancel the current AI command

ship:CancelAI()

This ship is left with the orientation and velocity it had when CancelAI was called.  The engines are switched off.

Note that Event.onAICompleted will not be triggered by calling CancelAI, as the AI did not actually complete.

You do not need to call this if you intend to immediately invoke another AI method.  Calling an AI method will replace the previous command if one exists.

Availability

alpha 10

Status

experimental

UpdateEquipStats

Update the ship’s statistics with regards to equipment changes

ship:UpdateEquipStats()

Availability

June 2014

Status

experimental

Attributes

alertStatus

The current alert status of the ship.  A Constants.ShipAlertStatus string.

Availability

alpha 10

Status

experimental

flightState

The current flight state of the ship.  A Constants.ShipFlightState string.

Availability

alpha 25

Status

experimental

shipId

The internal id of the ship type.  This value can be passed to <ShipType.GetShipType> to retrieve information about this ship type.

Availability

alpha 28

Status

stable

fuel

The current amount of fuel, as a percentage of full

Availability

alpha 20

Status

experimental

fuelMassLeft

Remaining thruster fuel mass in tonnes.

Availability

November 2013

Status

experimental

hullMassLeft

Remaining hull integrity in tonnes.  Ship damage reduces hull integrity.  When this reaches 0, the ship is destroyed.

Availability

November 2013

Status

experimental

shieldMassLeft

Remaining shield strength in tonnes.  As shields are depleted, the shield strength decreases.  When this reaches 0, the shields are fully depleted and the hull is exposed to damage.

Availability

November 2013

Status

experimental

shieldMass

Maximum shield strength for installed shields.  Measured in tonnes.

Availability

November 2013

Status

experimental

hyperspaceRange

Furthest possible hyperjump given current hyperspace fuel available.  Measured in light-years.

Availability

November 2013

Status

experimental

maxHyperspaceRange

Furthest possible hyperjump assuming no limits to available hyperspace fuel.  Measured in light-years.

Availability

November 2013

Status

experimental

staticMass

Mass of the ship including hull, equipment and cargo, but excluding thruster fuel mass.  Measured in tonnes.

Availability

November 2013

Status

experimental

usedCapacity

Hull capacity used by equipment and cargo.  Measured in tonnes.

Availability

November 2013

Status

experimental

usedCargo

Hull capacity used by cargo only (not equipment).  Measured in tonnes.

Availability

November 2013

Status

experimental

freeCapacity

Total space remaining.  Measured in tonnes.

Availability

November 2013

Status

experimental

class LuaModelBody
Class representing a body with an attached model.
Class representing a space station.
Triggered when a ship undocks with a space station.
Class representing a ship.
Hyperjump ship to system.
template <> void LuaObject<SystemPath>::PushToLua(const SystemPath &o)
Describes the location of a system within the galaxy and optionally, a body within that system.
Reasons that that a hyperspace jump might succeed or fail.
Class represents a physical body.
Triggered when a ship AI completes
Fly to and enter a low orbit around a given planet or star
template <> const char *LuaObject<Star>::s_type = "Star"
Class representing a star.
template <> const char *LuaObject<Planet>::s_type = "Planet"
Class representing a planet.
Cancel the current AI command
Current alert status.
Ship flight state
Close