Orbit

Variables of type Orbit hold descriptive information about the elliptical shape of a predicted orbit. Whenever there are multiple patches of orbit ellipses strung together, for example, when an encounter with a body is expected to alter the path, or when a maneuver node is planned, then each individual patch of the path is represented by one Orbit object.

Each Orbitable item such as a Vessel or celestial Body has an :ORBIT suffix that can be used to obtain its current Orbit.

Whenever you get the Orbit of a Vessel, be aware that its just the current Orbit patch that doesn’t take into account any planetary encounters (slingshots) or maneuver nodes that may occur. For example, your vessel might never reach SHIP:ORBIT:APOAPSIS if you’re going to intersect the Mun and be flung by it into a new orbit.

Warning

Some of the parameters listed here come directly from KSP’s API and there is a bit of inconsistency with whether it uses radians or degrees for angles. As much as possible we have tried to present everything in kOS as degrees for consistency, but some of these may have slipped through. If you see any of these being reported in radians, please make a bug report.

Structure

structure Orbit

Members

Suffix	Type (units)	Description
NAME	String	name of this orbit
APOAPSIS	Scalar (m)	Maximum altitude
PERIAPSIS	Scalar (m)	Minimum altitude
BODY	Body	Focal body of orbit
PERIOD	Scalar (s)	orbital period
INCLINATION	Scalar (deg)	orbital inclination
ECCENTRICITY	Scalar	orbital eccentricity
SEMIMAJORAXIS	Scalar (m)	semi-major axis
SEMIMINORAXIS	Scalar (m)	semi-minor axis
LAN	Scalar (deg)	Same as LONGITUDEOFASCENDINGNODE
LONGITUDEOFASCENDINGNODE	Scalar (deg)	Longitude of the ascending node
ARGUMENTOFPERIAPSIS	Scalar	argument of periapsis
TRUEANOMALY	Scalar	true anomaly in degrees (not radians)
MEANANOMALYATEPOCH	Scalar	mean anomaly in degrees (not radians) at a specific fixed time called EPOCH
EPOCH	Scalar	The universal timestamp at which MEANANOMALYATEPOCH is measured.
TRANSITION	String	Transition from this orbit
POSITION	Vector	The current position
VELOCITY	OrbitableVelocity	The current velocity
NEXTPATCH	Orbit	Next Orbit
NEXTPATCHETA	Scalar	ETA to next Orbit
HASNEXTPATCH	Boolean	Has a next Orbit

Orbit:NAME

Type:String Access:Get only

a name for this orbit.

Orbit:APOAPSIS

Type:Scalar (m) Access:Get only

The max altitude expected to be reached.

Orbit:PERIAPSIS

Type:Scalar (m) Access:Get only

The min altitude expected to be reached.

Orbit:BODY

Type:Body Access:Get only

The celestial body this orbit is orbiting.

Orbit:PERIOD

Type:Scalar (seconds) Access:Get only

orbital period

Orbit:INCLINATION

Type:Scalar (degree) Access:Get only

orbital inclination

Orbit:ECCENTRICITY

Type:Scalar Access:Get only

orbital eccentricity

Orbit:SEMIMAJORAXIS

Type:Scalar (m) Access:Get only

semi-major axis

Orbit:SEMIMINORAXIS

Type:Scalar (m) Access:Get only

semi-minor axis

Orbit:LAN

Same as Orbit:LONGITUDEOFASCENDINGNODE.

Orbit:LONGITUDEOFASCENDINGNODE

Type:Scalar (deg) Access:Get only

The Longitude of the ascening node is the “celestial longitude” where the orbit crosses the body’s equator from its southern hemisphere to its northern hemisphere

Note that the “celestial longitude” in this case is NOT the planetary longitude of the orbit body. “Celestial longitudes” are expressed as the angle from the Solar Prime Vector, not from the body’s longitude. In order to find out where it is relative to the body’s longitude, you will have to take into account body:rotationangle, and take into account that the body will rotate by the time you get there.

Orbit:ARGUMENTOFPERIAPSIS

Type:Scalar Access:Get only

argument of periapsis

Orbit:TRUEANOMALY

Type:Scalar Access:Get only

true anomaly in degrees. Even though orbital parameters are traditionally done in radians, in keeping with the kOS standard of making everything into degrees, they are given as degrees by kOS.

Orbit:MEANANOMALYATEPOCH

Type:Scalar degrees Access:Get only

mean anomaly in degrees. Even though orbital parameters are traditionally done in radians, in keeping with the kOS standard of making everything into degrees, they are given as degrees by kOS.

Internally, KSP tracks orbit position using MEANANOMALYATEPOCH and EPOCH. “Epoch” is an arbitrary timestamp expressed in universal time (gameworld seconds from game start, same as TIME:SECONDS uses) at which the mean anomaly of the orbit would be MEANANOMALYATEPOCH.

Given the mean anomaly at epoch, and the epoch time, and the current time, and the orbital period, it’s possible to find out the current mean anomaly. Kerbal Space Program uses this internally to track orbit positions while under time warp without using the full physics system.

Orbit:EPOCH

Type:Scalar universal timestamp (seconds) Access:Get only

Internally, KSP tracks orbit position using MEANANOMALYATEPOCH and EPOCH. “Epoch” is an arbitrary timestamp expressed in universal time (gameworld seconds from game start, same as TIME:SECONDS uses) at which the mean anomaly of the orbit would be MEANANOMALYATEPOCH.

Beware, if you are an experienced programmer, you may be aware of the word “Epoch” being used to mean a fixed point in time that never ever changes throughout an entire system. For example, the Unix timestamp system refers to Jan 1, 1970 as the “epoch”. This is NOT how the word is used in KSP’s orbit system. In Kerbal Space Program, the “epoch” is not a true “epoch”, in that it often moves and you have to re-check what it is. It’s not a hardcoded constant.

(The epoch timestamp seems to change when you go on or off from time warp.)

Orbit:TRANSITION

Type:String Access:Get only

Describes the way in which this orbit will end and become a different orbit, with a value taken from this list.

Orbit:POSITION

Type:Vector Access:Get only

The current position of whatever the object is that is in this orbit.

Orbit:VELOCITY

Type:OrbitableVelocity Access:Get only

The current velocity of whatever the object is that is in this orbit. Be aware that this is not just a velocity vector, but a structure containing both the orbital and surface velocity vectors as a pair. (See OrbitableVelocity).

Orbit:NEXTPATCH

Type:Orbit Access:Get only

When this orbit has a transition to another orbit coming up, this suffix returns the next Orbit patch after this one. For example, when escaping from a Mun orbit into a Kerbin orbit from which you will escape and hit a Solar orbit, then the current orbit’s :NEXTPATCH will show the Kerbin orbit, and :NEXTPATCH:NEXTPATCH will show the solar orbit. The number of patches into the future that you can peek depends on your conic patches setting in your Kerbal Space Program Settings.cfg file.

Orbit:NEXTPATCHETA

Type:Scalar Access:Get only

When this orbit has a transition to another orbit coming up, this suffix returns the eta to that transition. This is different from the value provided by the ETA:TRANSITION suffix as it is not limited to the patch following the current orbit, but rather may be chained to multiple patch transitions. The number of patches depends on your conic patches setting in your Kerbal Space Program Settings.cfg file.

Orbit:HASNEXTPATCH

Type:Boolean Access:Get only

If :NEXTPATCH will return a valid patch, this is true. If :NEXTPATCH will not return a valid patch because there are no transitions occurring in the future, then HASNEXTPATCH <Orbit:HASNEXTPATCH will be false.

Both NEXTPATCH and HASNEXTPATCH both only operate on the current momentum of the object, and do not take into account any potential changes planned with maneuver nodes. To see the possible new path you would have if a maneuver node gets executed exactly as planned, you need to first get the orbit that follows the manuever node, by looking at the maneuver node’s :ORBIT suffix, and then look at its :NEXTPATCH and :HASNEXTPATCH.

Deprecated Suffix

Orbit:PATCHES

Type:List of Orbit Objects Access:Get only

Note

Deprecated since version 0.15: To get the same functionality, you must use Vessel:PATCHES which is a suffix of the Vessel itself.

Transition Names

INITIAL

Refers to the pure of a new orbit, which is a value you will never see from the Orbit:TRANSITION suffix (it refers to the start of the orbit patch, and Orbit:TRANSITION only refers to the end of the patch.

FINAL

Means that no transition to a new orbit is expected. It this orbit is the orbit that will remain forever.

ENCOUNTER

Means that this orbit will enter a new SOI of another orbital body that is smaller in scope and is “inside” the current one. (example: currently in Sun orbit, will enter Duna Orbit.)

ESCAPE

Means that this orbit will enter a new SOI of another orbital body that is larger in scope and is “outside” the current one. (example: currently in Kerbin orbit, will enter Sun Orbit.)

MANEUVER

Means that this orbit will end due to a manuever node that starts a new orbit?