Vessel¶
All vessels share a structure. To get a variable referring to any vessel you can do this:
// Get a vessel by it's name.
// The name is Case Sensitive.
SET MY_VESS TO VESSEL("Some Ship Name").
// Save the current vessel in a variable,
// in case the current vessel changes.
SET MY_VESS TO SHIP.
// Save the target vessel in a variable,
// in case the target vessel changes.
SET MY_VESS TO TARGET.
Vessels are also Orbitable, and as such have all the associated suffixes as well as some additional suffixes.
- structure Vessel¶
Suffix
Type
Description
Every suffix of
Orbitable
Raw flight controls
Scalar
(deg)relative heading to this vessel
Scalar
(deg)Absolute heading to this vessel
Sum of active thrusts
Sum of active maximum thrusts
Sum of active maximum thrusts at the given atmospheric pressure
Sum of active limited maximum thrusts
Sum of active limited maximum thrusts at the given atmospheric pressure
The way the vessel is pointed
Construct bounding box information about the vessel
Scalar
(metric tons)Mass of the ship
Scalar
(metric tons)Mass of the ship fully fuelled
Scalar
(metric tons)Mass of the ship with no resources
Scalar
(ATM’s)Air Pressure surrounding the vessel
Scalar
(ATM’s)Alias name for DYNAMICPRESSURE
Scalar
(m/s)How fast the ship is moving “up”
Scalar
(m/s)How fast the ship is moving “horizontally”
Scalar
(m/s)How fast the ship is moving relative to the air
TERMVELOCITY
(DEPRECATED)Scalar
(m/s)terminal velocity of the vessel
The name of the vessel
Synonym for SHIPNAME
Current ship status
Summed Delta-V info about the ship
One stage’s Delta-V info
Which stage number is current
Ship type
None
Start tracking the asteroid “vessel” via the tracking station
None
Stop tracking the asteroid “vessel” via the tracking station
Return the size class for an asteroid-like object
In SHIP_RAW
In SHIP_RAW
Sensor data
loaded into KSP physics engine or “on rails”
The ship has individual parts unpacked
the
LoadDistance
object for this vesselTrue if the vessel refers to a ship that has gone away.
Orbit
patchesRoot
Part
of this vesselControl reference
Part
of this vesselall
Parts
all
Engines
all
RCS
all
DockingPorts
all
Elements
PartModules
byNAME
Parts
by action groupPartModules
by action groupParts
that have non-blank nametagsCrew capacity of this vessel
all
CrewMembers
Returns your connection to this vessel
This vessel’s message queue
Scalar
(m/s)The total delta-v of this vessel in its current situation
Scalar
(m/s)The total delta-v of this vessel if it were at sea level
Scalar
(m/s)The total delta-v of this vessel if it were in a vacuum
Scalar
(s)The total burn time of this vessel (or 5 if the vessel has 0 delta/v).
Note
This type is serializable.
- Vessel:CONTROL¶
- Type
- Access
Get only
The structure representing the raw flight controls for the vessel.
WARNING: This suffix is only gettable for CPU Vessel
- Vessel:BEARING¶
- Type
- Access
Get only
relative compass heading (degrees) to this vessel from the CPU Vessel, taking into account the CPU Vessel’s own heading.
- Vessel:HEADING¶
- Type
- Access
Get only
absolute compass heading (degrees) to this vessel from the CPU Vessel
- Vessel:THRUST¶
- Type
- Access
Get only
Sum of all the engines’ THRUSTs of all the currently active engines In Kilonewtons.
- Vessel:MAXTHRUST¶
- Type
- Access
Get only
Sum of all the engines’ MAXTHRUSTs of all the currently active engines In Kilonewtons.
- Vessel:MAXTHRUSTAT(pressure)¶
- Parameters
pressure – atmospheric pressure (in standard Kerbin atmospheres)
- Return type
Scalar
(kN)
Sum of all the engines’ MAXTHRUSTATs of all the currently active engines In Kilonewtons at the given atmospheric pressure. Use a pressure of 0 for vacuum, and 1 for sea level (on Kerbin). (Pressure must be greater than or equal to zero. If you pass in a negative value, it will be treated as if you had given a zero instead.)
- Vessel:AVAILABLETHRUST¶
- Type
- Access
Get only
Sum of all the engines’ AVAILABLETHRUSTs of all the currently active engines taking into account their throttlelimits. Result is in Kilonewtons.
- Vessel:AVAILABLETHRUSTAT(pressure)¶
- Parameters
pressure – atmospheric pressure (in standard Kerbin atmospheres)
- Return type
Scalar
(kN)
Sum of all the engines’ AVAILABLETHRUSTATs of all the currently active engines taking into account their throttlelimits at the given atmospheric pressure. Result is in Kilonewtons. Use a pressure of 0 for vacuum, and 1 for sea level (on Kerbin). (Pressure must be greater than or equal to zero. If you pass in a negative value, it will be treated as if you had given a zero instead.)
- Vessel:FACING¶
- Type
- Access
Get only
The way the vessel is pointed, which is also the rotation that would transform a vector from a coordinate space where the axes were oriented to match the vessel’s orientation, to one where they’re oriented to match the world’s ship-raw coordinates.
i.e.
SHIP:FACING * V(0,0,1)
gives the direction the ship is pointed (it’s Z-axis) in absolute ship-raw coordinates
- Vessel:BOUNDS¶
- Type
- Access
Get only
Constructs a “bounding box” structure that can be used to give your script some idea of the extents of the vessel’s shape - how wide, long, and tall it is.
It is rather expensive in terms of CPU time to call this suffix. (Calling
Part:BOUNDS
on ONE part on the ship is itself a little expensive, and this has to perform that same work on every part on the ship, finding the bounding box that would surround all the parts.) Because of that expense, kOS forces your script to give up its remaining instructions this update when you call this (It forces the equivalent of doing aWAIT 0.
right after you call it). This is to discourage you from calling this suffix again and again in a fast loop. The proper way to use this suffix is to call it once, storing the result in a variable, and then use that variable repeatedly, rather than using the suffix itself repeatedly. Only call the suffix again when you have reason to expect the bounding box to change or become invalid, such as docking, staging, changing facing to a new control-from part, and so on.More detailed information about how to read the bounds box, and what circumstances call for getting a re-generated copy of the bounds box, is found on the documentation page for
Bounds
.
- Vessel:WETMASS¶
- Type
Scalar
(metric tons)- Access
Get only
The mass of the ship if all resources were full
- Vessel:DRYMASS¶
- Type
Scalar
(metric tons)- Access
Get only
The mass of the ship if all resources were empty
- Vessel:DYNAMICPRESSURE¶
- Type
Scalar
(ATM’s)- Access
Get only
Returns what the air pressure is in the atmosphere surrounding the vessel. The value is returned in units of sea-level Kerbin atmospheres. Many formulae expect you to plug in a value expressed in kiloPascals, or kPA. You can convert this value into kPa by multiplying it by constant:ATMtokPa.
- Vessel:VERTICALSPEED¶
- Type
Scalar
(m/s)- Access
Get only
How fast the ship is moving. in the “up” direction relative to the SOI Body’s sea level surface.
- Vessel:GROUNDSPEED¶
- Type
Scalar
(m/s)- Access
Get only
How fast the ship is moving in the two dimensional plane horizontal to the SOI body’s sea level surface. The vertical component of the ship’s velocity is ignored when calculating this.
Note
New in version 0.18: The old name for this value was SURFACESPEED. The name was changed because it was confusing before. “surface speed” implied it’s the
Scalar
magnitude of “surface velocity”, but it wasn’t, because of how it ignores the vertical component.
- Vessel:AIRSPEED¶
- Type
Scalar
(m/s)- Access
Get only
How fast the ship is moving relative to the air. KSP models atmosphere as simply a solid block of air “glued” to the planet surface (the weather on Kerbin is boring and there’s no wind). Therefore airspeed is generally the same thing as as the magnitude of the surface velocity.
- Vessel:SHIPNAME¶
- Type
- Access
Get/Set
The name of the vessel as it appears in the tracking station. When you set this, it cannot be empty.
- Vessel:NAME¶
Same as
Vessel:SHIPNAME
.
- Vessel:STATUS¶
- Type
- Access
get only
The current status of the vessel possible results are: LANDED, SPLASHED, PRELAUNCH, FLYING, SUB_ORBITAL, ORBITING, ESCAPING and DOCKED.
- Vessel:STAGEDELTAV(num)¶
-
One stage’s Delta-V info. Pass in the stage number for which stage. The curent stage can be found with
:STAGENUM
, and they count down from there to stage 0 at the “top” of the staging list.If you pass in a number that is less than zero, it will return the info about stage 0. If you pass in a number that is greater than the current stage, it will return the info about the current stage. In other words, if there are currently stages 5, 4, 3, 2, 1, and 0, then passing in -99 gives you stage 0, and passing in stage 9999 gets you stage 5.
- Vessel:STAGENUM¶
- Type
- Access
get only
Tells you which stage number is current. Stage numbers always count down, which is backward from how you might usually refer to stages in most space lingo, but in KSP, it’s how it’s done. (Stage 5 on bottom, Stage 0 on top, for example).
e.g. if STAGENUM is 4, that tells you the vessel has 5 total stages remaining, numbered 4, 3, 2, 1, and 0.
- Vessel:TYPE¶
- Type
- Access
Get/Set
The ship’s type as described on the KSP wiki.
- Vessel:STARTTRACKING()¶
- Returns
None
Call this method to start tracking the object. This is functionally the same as clicking on the “Start Tracking” button in the Tracking Station interface. The primary purpose is to change asteroids from being displayed in the tracking station or on the map as
"Unknown"
to being displayed as"SpaceObject"
. By doing so, the asteroid will not be de-spawned by KSP’s asteroid management system.Note
This does not change the value returned by
Vessel:TYPE
. KSP internally manages the “discovery information” for vessels, including assteroids, in a different system. As a result, the value kOS reads forTYPE
may be different from that displayed on the map.
- Vessel:STOPTRACKING()¶
- Returns
None
Call this method to stop tracking an asteroid or asteroid-like object. This is functionally the same as using the Tracking Station interface to tell KSP to forget the asteroid. Doing so also tells the Tracking Station that it’s okay to de-spawn the object if it feels the need to clean it up to avoid clutter.
- Vessel:SIZECLASS¶
- Type
- Access
Get only
Returns the size class for an asteroid or asteroid-like object (which is modeled in the game as a vessel). (i.e. class A, B, C, D, or E for varying size ranges of asteroid.) For objects that the tracking station is tracking but you have not yet rendezvous’ed with, sometimes all the game lets you know is the general class and not the specific dimensions or mass.
If you are not tracking the object yet, the returned string can come back as “UNKNOWN” rather than one of the known class sizes.
- Vessel:ANGULARMOMENTUM¶
- Type
- Access
Get only
Given in SHIP_RAW reference frame. The vector represents the axis of the rotation (in left-handed convention, not right handed as most physics textbooks show it), and its magnitude is the angular momentum of the rotation, which varies not only with the speed of the rotation, but also with the angular inertia of the vessel.
Units are expressed in: (Megagrams * meters^2) / (seconds * radians)
(Normal SI units would use kilograms, but in KSP all masses use a 1000x scaling factor.)
Justification for radians here: Unlike the trigonometry functions in kOS, this value uses radians rather than degrees. The convention of always expressing angular momentum using a formula that assumes you’re using radians is a very strongly adhered to universal convention, for… reasons. It’s so common that it’s often not even explicitly mentioned in information you may find when doing a web search on helpful formulae about angular momentum. This is why kOS doesn’t use degrees here. (That an backward compatibility for old scripts. It’s been like this for quite a while.).
- Vessel:ANGULARVEL¶
Angular velocity of the body’s rotation about its axis (its day) expressed as a vector.
The direction the angular velocity points is in Ship-Raw orientation, and represents the axis of rotation. Remember that everything in Kerbal Space Program uses a left-handed coordinate system, which affects which way the angular velocity vector will point. If you curl the fingers of your left hand in the direction of the rotation, and stick out your thumb, the thumb’s direction is the way the angular velocity vector will point.
The magnitude of the vector is the speed of the rotation.
Note, unlike many of the other parts of kOS, the rotation speed is expressed in radians rather than degrees. This is to make it congruent with how VESSEL:ANGULARMOMENTUM is expressed, and for backward compatibility with older kOS scripts.
- Vessel:SENSORS¶
- Type
- Access
Get only
Structure holding summary information of sensor data for the vessel
- Vessel:LOADED¶
- Type
- Access
Get only
True if the vessel is fully loaded into the complete KSP physics engine (false if it’s “on rails”). See
LoadDistance
for details.
- Vessel:UNPACKED¶
- Type
- Access
Get only
True if the vessel is fully unpacked. That is to say that all of the individual parts are loaded and can be interacted with. This allows docking ports to be targeted, and controls if some actions/events on parts will actually trigger. See
LoadDistance
for details.
- Vessel:LOADDISTANCE¶
- Type
- Access
Get only
Returns the load distance object for this vessel. The suffixes of this object may be adjusted to change the loading behavior of this vessel. Note: these settings are not persistent across flight instances, and will reset the next time you launch a craft from an editor or the tracking station.
- Vessel:ISDEAD¶
- Type
- Access
Get only
It is possible to have a variable that refers to a vessel that doesn’t exist in the Kerbal Space Program universe anymore, but did back when you first got it. For example: you could do: SET VES TO VESSEL(“OTHER”). WAIT 10. And in that intervening waiting time, the vessel might have crashed into the ground. Checking :ISDEAD lets you see if the vessel that was previously valid isn’t valid anymore.
- Vessel:PATCHES¶
- Type
- Access
Get only
The list of orbit patches that describe this vessel’s current travel path based on momentum alone with no thrusting changes. If the current path has no transitions to other bodies, then this will be a list of only one orbit. If the current path intersects other bodies, then this will be a list describing the transitions into and out of the intersecting body’s sphere of influence. SHIP:PATCHES[0] is always exactly the same as SHIP:OBT, SHIP:PATCHES[1] is the same as SHIP:OBT:NEXTPATCH, SHIP:PATCHES[2] is the same as SHIP:OBT:NEXTPATCH:NEXTPATCH, and so on. Note that you will only see as far into the future as your KSP settings allow. (See the setting CONIC_PATCH_LIMIT in your settings.cfg file)
- Vessel:ROOTPART¶
- Type
- Access
Get only
The ROOTPART is usually the first
Part
that was used to begin the ship design - the command core. Vessels in KSP are built in a tree-structure, and the first part that was placed is the root of that tree. It is possible to change the root part in VAB/SPH by using Root tool, so ROOTPART does not always point to command core or command pod. Vessel:ROOTPART may change in flight as a result of docking/undocking or decoupling of some part of a Vessel.
- Vessel:CONTROLPART¶
- Type
- Access
Get only
Returns the
Part
serving as the control reference, relative to which the directions (as displayed on the navball and returned inFACING
) are determined. A part may be set as the control reference part by “Control From Here” action orPART:CONTROLFROM
command (available for parts of specific types). NOTE: It is possible for this to return unexpected values if the root part of the vessel cannot serve as a control reference, and the control has not been directly selected.
- Vessel:PARTS¶
-
A List of all the parts on the vessel.
SET FOO TO SHIP:PARTS.
has exactly the same effect asLIST PARTS IN FOO.
. For more information, see ship parts and modules.
- Vessel:RCS¶
-
A List of all the RCS thrusters on the Vessel.
- Vessel:DOCKINGPORTS¶
- Type
List
ofDockingPort
objects- Access
Get only
A List of all the docking ports on the Vessel.
- Vessel:RESOURCES¶
- Type
List
ofAggregateResource
objects- Access
Get only
A List of all the AggregateResources on the vessel.
SET FOO TO SHIP:RESOURCES.
has exactly the same effect asLIST RESOURCES IN FOO.
.
- Vessel:PARTSNAMED(name)¶
-
Returns a list of all the parts that have this as their
Part:NAME
. The matching is done case-insensitively. For more information, see ship parts and modules.
- Vessel:PARTSNAMEDPATTERN(namePattern)¶
-
Returns a list of all the parts that have this Regex pattern in their
Part:NAME
. The matching is done identically as inString:MATCHESPATTERN
. For more information, see ship parts and modules.
- Vessel:PARTSTITLED(title)¶
-
Returns a list of all the parts that have this as their
Part:TITLE
. The matching is done case-insensitively. For more information, see ship parts and modules.
- Vessel:PARTSTITLEDPATTERN(titlePattern)¶
-
Returns a list of all the parts that have this Regex pattern in their
Part:TITLE
. The matching is done identically as inString:MATCHESPATTERN
. For more information, see ship parts and modules.
- Vessel:PARTSTAGGED(tag)¶
-
Returns a list of all the parts that have this name as their
Part:TAG
value. The matching is done case-insensitively. For more information, see ship parts and modules.
- Vessel:PARTSTAGGEDPATTERN(tagPattern)¶
-
Returns a list of all the parts that match this Regex pattern in their
part:TAG
value. The matching is done identically as inString:MATCHESPATTERN
. For more information, see ship parts and modules.
- Vessel:PARTSDUBBED(name)¶
-
Return a list of all the parts that match this name regardless of whether that name is the Part:Name, the Part:Tag, or the Part:Title. It is effectively the distinct union of :PARTSNAMED(val), :PARTSTITLED(val), :PARTSTAGGED(val). The matching is done case-insensitively. For more information, see ship parts and modules.
- Vessel:PARTSDUBBEDPATTERN(namePattern)¶
- Parameters
namePattern – (
String
) Pattern of the name, title or tag of the parts
- Returns
Return a list of parts that match this Regex pattern regardless of whether that name is the Part:Name, the Part:Tag, or the Part:Title. It is effectively the distinct union of :PARTSNAMEDPATTERN(val), :PARTSTITLEDPATTERN(val), :PARTSTAGGEDPATTERN(val). The matching is done identically as in
String:MATCHESPATTERN
. For more information, see ship parts and modules.
- Vessel:MODULESNAMED(name)¶
- Parameters
name – (
String
) Name of the part modules
- Returns
List
ofPartModule
objects
Return a list of all the
PartModule
objects that match the given name. The matching is done case-insensitively. For more information, see ship parts and modules.
- Vessel:PARTSINGROUP(group)¶
-
one action triggered by the given action group. For more information, see ship parts and modules.
- Vessel:MODULESINGROUP(group)¶
- Parameters
group – (integer) the action group number
- Returns
List
ofPartModule
objects
have at least one action triggered by the given action group. For more information, see ship parts and modules.
- Vessel:ALLTAGGEDPARTS()¶
-
Return all parts who’s nametag isn’t blank. For more information, see ship parts and modules.
- Vessel:CREW()¶
- Returns
List
ofCrewMember
objects
list of all
kerbonauts
aboard this vessel
- Vessel:CONNECTION¶
- Return
Returns your connection to this vessel.
- Vessel:MESSAGES¶
- Return
Returns this vessel’s message queue. You can only access this attribute for your current vessel (using for example SHIP:MESSAGES).
- Vessel:DELTAV
- Return
The total delta-v of this vessel in its current situation, using the stock calulations the KSP game shows in the staging list. Note that this is only as accurate as the stock KSP game’s numbers are.
- Vessel:DELTAVASL¶
- Return
The total delta-v of this vessel if it were at sea level, using the stock calulations the KSP game shows in the staging list. Note that this is only as accurate as the stock KSP game’s numbers are.
- Vessel:DELTAVVACUUM¶
- Return
The total delta-v of this vessel if it were at sea vacuum, using the stock calulations the KSP game shows in the staging list. Note that this is only as accurate as the stock KSP game’s numbers are.
- Vessel:BURNTIME¶
- Return
The total burn time, in seconds, of this vessel (or 5 if the vessel has 0 delta/v). Burn time is not affected by atmosphere. This is using the stock calulations the KSP game shows in the staging list. Note that this is only as accurate as the stock KSP game’s numbers are.
Deprecated Suffix¶
- Vessel:TERMVELOCITY¶
- Type
Scalar
(m/s)- Access
Get only
(Deprecated with KSP 1.0 atmospheric model)
Terminal velocity of the vessel in freefall through atmosphere, based on the vessel’s current altitude above sea level, and its drag properties. Warning, can cause values of Infinity if used in a vacuum, and kOS sometimes does not let you store Infinity in a variable.
Note
Deprecated since version 0.17.2: Removed to account for significant changes to planetary atmosphere mechanics introduced in KSP 1.0