.. default-domain:: c
.. highlight:: c


.. _cnano-api-stage:

Stage
=====


.. type:: krpc_SpaceCenter_Stage_t

   A single stage of a vessel. Obtain activation (burn) stages from
   ``Vessel.Stages`` / ``Vessel.StageAt``, and decouple stages from
   ``Vessel.DecoupleStages`` / ``Vessel.DecoupleStageAt``.

   .. note::

      Delta-v, thrust, TWR, specific impulse, burn time and mass members are only
      available on activation stages. On decouple stages those members throw
      InvalidOperationException because stock delta-v data does not
      apply. Thrust is reported in newtons and masses in kilograms (stock values
      are converted from kilonewtons and tonnes).

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_Number(krpc_connection_t connection, int32_t * returnValue, krpc_SpaceCenter_Stage_t instance)

      The stage number (activation stage for burn stages, decouple stage otherwise).

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_Parts(krpc_connection_t connection, krpc_list_object_t * returnValue, krpc_SpaceCenter_Stage_t instance)

      The parts that belong to this stage.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_Resources(krpc_connection_t connection, krpc_SpaceCenter_Resources_t * returnValue, krpc_SpaceCenter_Stage_t instance, bool cumulative)

      Returns a :func:`krpc_SpaceCenter_Stage_Resources` object for this stage.

      :Parameters:

       * **cumulative** -- When ``false``, only resources assigned to this stage. When ``true``, resources for this stage and all later activation or decouple stage numbers are included. On activation stages, unstaged resource containers (for example fuel tanks) are grouped with the first higher activation stage before they are detached.

   

      .. note:: This is an RPC method: call ``resources()`` (optional ``cumulative`` argument).
                For activation stages, unstaged resource containers (for example fuel tanks)
                are grouped with the first higher activation stage before they detach, matching
                the C# ``Resources()`` documentation.

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_DeltaV(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Delta-v for this stage in the current situation, in m/s.

   

      .. note:: Delta-v is only defined for **activation** stages (``decouple`` is ``false``).
                Calling this on a decouple stage raises an error.

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_VacuumDeltaV(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Vacuum delta-v for this stage, in m/s.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_SeaLevelDeltaV(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Sea-level delta-v for this stage, in m/s.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_Thrust(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Thrust in the current situation, in newtons.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_VacuumThrust(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Vacuum thrust, in newtons.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_SeaLevelThrust(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Sea-level thrust, in newtons.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_TWR(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Thrust-to-weight ratio in the current situation.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_VacuumTWR(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Vacuum thrust-to-weight ratio.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_SeaLevelTWR(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Sea-level thrust-to-weight ratio.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_SpecificImpulse(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Specific impulse in the current situation, in seconds.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_VacuumSpecificImpulse(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Vacuum specific impulse, in seconds.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_SeaLevelSpecificImpulse(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Sea-level specific impulse, in seconds.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_BurnTime(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      Burn time for this stage, in seconds.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_StartMass(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      The mass of the vessel after the stage activates, in kg.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_EndMass(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      The mass of the vessel when the stage burns out, in kg.

   

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_DryMass(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      The dry mass of the vessel after the stage activates, in kg.

   

      .. note::

         Includes the parts of all later stages.

   .. function:: krpc_error_t krpc_SpaceCenter_Stage_FuelMass(krpc_connection_t connection, float * returnValue, krpc_SpaceCenter_Stage_t instance)

      The fuel mass of the vessel when the stage activates, in kg.

   

      .. note::

         Includes the fuel of all later stages, and the fuel left in the parts the stage
         decouples. The stage burns :func:`krpc_SpaceCenter_Stage_StartMass` minus :func:`krpc_SpaceCenter_Stage_EndMass`.