State Reference

From the Fallout4 CreationKit Wiki
Jump to navigation Jump to search

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[edit | edit source]

<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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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[edit | edit source]

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

How States Affect Functions And Events[edit | edit source]

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[edit | edit source]

; 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