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)
TRANSITION string Transition from this orbit
POSITION Vector The current position
VELOCITY Vector The current velocity
NEXTPATCH Orbit 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
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.

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:Vector
Access:Get only

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

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

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 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 <node>, and then look at it’s :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?