.. _orbitablevelocity:

OrbitableVelocity
=================

When any :struct:`Orbitable` object returns its :attr:`VELOCITY <Orbitable:VELOCITY>` suffix, it returns it as a structure containing a pair of both its orbit-frame velocity and its surface-frame velocity at the same instant of time. To obtain its velocity as a vector you must pick whether you want the oribtal or surface velocities by giving a further suffix:

.. structure:: OrbitableVelocity::

    .. list-table:: Members
        :header-rows: 1
        :widths: 1 1

        * - Suffix
          - Type
        * - :attr:`ORBIT`
          - :struct:`Vector`
        * - :attr:`SURFACE`
          - :struct:`Vector`

.. attribute:: OrbitableVelocity:ORBIT

    :type: :struct:`Vector`
    :access: Get only

    Returns the orbital velocity.
     
.. attribute:: OrbitableVelocity:SURFACE

    :type: :struct:`Vector`
    :access: Get only

    Returns the surface-frame velocity. Note that this is the surface velocity relative to the surface of the SOI body, not the orbiting object itself. (i.e. Mun:VELOCITY:SURFACE returns the Mun's velocity relative to the surface of its SOI body, Kerbin).

Examples::

    SET VORB TO SHIP:VELOCITY:ORBIT
    SET VSRF TO SHIP:VELOCITY:SURFACE
    SET MUNORB TO MUN:VELOCITY:ORBIT
    SET MUNSRF TO MUN:VELOCITY:SURFACE

.. note::

    At first glance it may seem that ``Mun:VELOCITY:SURFACE`` is wrong because it creates a vector in the opposite direction from ``Mun:VELOCITY:ORBIT``, but this is actually correct. Kerbin's surface rotates once every 6 hours, and the Mun takes a lot longer than 6 hours to orbit Kerbin. Therefore, relative to Kerbin's surface, the Mun is going backward.