Mod:Creation Kit/State Reference

A "state" is a mode that a script can be put in which will cause different versions of functions or events to be called.

State Definition
*            'EndState'

A state is defined by using the "State" keyword (optionally prefixed with "Auto"), followed by the identifier that represents the state. It then contains zero or more functions or events, and ends with the "EndState" keyword.

Auto States
By prefixing the state with "Auto" the script will start in that state (And no Mod:Creation Kit/OnBeginState will be sent). Only one state may be auto in a script. A child script's auto state takes precedence over a parent's, but if the child has no auto state, the parent's will be used.

The "Empty" State
Any function or event defined outside of a state block is said to be in the "empty state". This is the version of the function that is used when the script is not in any state, or when the current state does not implement an override for a function.

Every function implemented in a state must also be implemented (with an identical name, return type, and parameter list) in the empty state in either the current script or a parent.

Switching States
To switch a script's state, call GotoState, passing in the name of the state to switch to as a string. The state does not have to exist on the destination script. To switch to the empty state, pass in the empty string.

Getting Current State
To get the current state, call GetState. It will return the current state name as a string.

How States Affect Functions And Events
The function or event that is picked to run is determined by the following algorithm:
 * 1) Check current script's state for the function
 * 2) Check parent script's state for the function
 * 3) Check current script's empty state for the function
 * 4) Check parent script's state for the function

Examples
int Function MyFunction Return 1 EndFunction
 * Define a function and a state with an override

State MyState int Function MyFunction ; Name, parameters, and return type must match empty state version Return 2 EndFunction EndState

Function CallMyFunction int x = MyFunction ; Gets 1 when the script first starts up (not in a state) GotoState("MyState") x = MyFunction ; Gets 2 GotoState("WrongState") x = MyFunction ; Gets 1 (fallback because state doesn't exist in this script, but might in a child) GotoState("") x = MyFunction ; Gets 1 (empty state) EndFunction Auto State MyState int Function MyFunction ; Name, parameters, and return type must match empty state version Return 2 EndFunction EndState
 * Changing the state in the above example to have MyState be the auto state


 * Now x in CallMyFunction will get 2, 2, 1, 1 because the script starts in MyState