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

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