Stage

Contents

Staging Example

A very simple auto-stager using :READY

LIST ENGINES IN elist.

UNTIL false {
    PRINT "Stage: " + STAGE:NUMBER AT (0,0).
    FOR e IN elist {
        IF e:FLAMEOUT {
            STAGE.
            PRINT "STAGING!" AT (0,0).

            UNTIL STAGE:READY {
                WAIT 0.
            }

            LIST ENGINES IN elist.
            CLEARSCREEN.
            BREAK.
        }
    }
}

Stage Function

Stage
Return

None

Activates the next stage if the cpu vessel is the active vessel. This will trigger engines, decouplers, and any other parts that would normally be triggered by manually staging. The default equivalent key binding is the space bar. As with other parameter-less functions, both STAGE. and STAGE(). are acceptable ways to call the function.

Note

Changed in version 1.0.1: The stage function will automatically pause execution until the next tick. This is because some of the results of the staging event take effect immediately, while others do not update until the next time that physics are calculated. Calling STAGE. is essentially equivalent to:

STAGE.
WAIT 0.

Warning

Calling the Stage function on a vessel other than the active vessel will throw an exception.

Stage Structure

The “Stage” structure gives you some information about the current stage of the vessel.

structure Stage
Members

Suffix

Type (units)

Access

Description

READY

Boolean

Get only

Is the craft ready to activate the next stage.

NUMBER

Scalar

Get only

The current stage number for the craft

RESOURCES

List

Get only

the List of AggregateResource in the current stage

RESOURCESLEX

Lexicon

Get only

the Lexicon of name String keyed AggregateResource values in the current stage

NEXTDECOUPLER

Decoupler or String

Get only

one of the nearest Decoupler parts that is going to be activated by staging (not necessarily in next stage). None if there is no decoupler.

NEXTSEPARATOR

Decoupler or String

Get only

Alias name for NEXTDECOUPLER

DELTAV

DeltaV

Get only

Gets delta-V information about the current stage.

Stage:READY
Access

Get only

Type

Boolean

Kerbal Space Program enforces a small delay between staging commands, this is to allow the last staging command to complete. This bool value will let you know if kOS can activate the next stage.

Stage:NUMBER
Access

Get only

Type

Scalar

Every craft has a current stage, and that stage is represented by a number, this is it!

Stage:Resources
Access

Get

Type

List

This is a collection of the available AggregateResource for the current stage.

Stage:Resourceslex
Access

Get

Type

Lexicon

This is a dictionary style collection of the available Resource for the current stage. The String key in the lexicon will match the name suffix on the AggregateResource. This suffix walks the parts list entirely on every call, so it is recommended that you cache the value if it will be reference repeatedly.

Stage:NextDecoupler
Access

Get

Type

Decoupler

One of the nearest Decoupler parts that is going to be activated by staging (not necessarily in next stage, if that stage does not contain any decoupler, separator, launch clamp or docking port with staging enabled). None if there is no decoupler.

This is particularly helpful for advanced staging logic, e.g.:

STAGE.
IF stage:nextDecoupler:isType("LaunchClamp")
    STAGE.
IF stage:nextDecoupler <> "None" {
    WHEN availableThrust = 0 or (
        stage:resourcesLex["LiquidFuel"]:amount = 0 and
        stage:resourcesLex["SolidFuel"]:amount = 0)
    THEN {
        STAGE.
        return stage:nextDecoupler <> "None".
    }
}
Stage:NextSeparator
Access

Get

Type

Decoupler

Alias for NEXTDECOUPLER

Stage:DELTAV
Type

DeltaV

Access

Get only

Returns delta-V information (see DeltaV) about the current stage.:

// These two lines would do the same thing:
SET DV TO STAGE:DELTAV.
SET DV TO SHIP:STAGEDELTAV(SHIP:STAGRENUM).