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

<state> ::= ['Auto'] 'State' <identifier>
              <function or event>*
            '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 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

; Define a function and a state with an override
int Function MyFunction()
  Return 1
EndFunction

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

; Changing the state in the above example to have MyState be the auto state
Auto State MyState
  int Function MyFunction() ; Name, parameters, and return type must match empty state version
    Return 2
  EndFunction
EndState

; Now x in CallMyFunction() will get 2, 2, 1, 1 because the script starts in MyState