ForceState

(Engine-Level Function)

Description:	Sets the next state to start when the action script completes.
Returns:	Nothing
Usage:	Script Only.
Function Groups:	Compilation and On-Line Modifications, Logic Control, State
Related to:	FirstState
Format:	ForceState(State)
Parameters:

State

Required. Any text expression giving the name of the state to start upon completion of the script.

Comments:

A script may contain more than one ForceState statement, but it is only the last one executed that sets the state to which the module will switch.

This statement does not act as an immediate exit point from the script - the script will still run in its entirety. That said, the first ForceState will cause the current state to end and any reference to objects in that state will fail.
If the script trigger statement did not specify a destination state to transfer to, this function will stop the current state as if one had been specified.

IF statements are the standard tool for specifying the next state. Use ForceState rarely and only when significant effort would be required otherwise to control the flow from one state to another.

Example:

  If TimeOut(1, 1) Main;
  [
    IfThen(Level < 10, ForceState("Exit")); 
  ]

After one second this statement will cause a state transfer to Main. However, if level is less than 10 at that time, the next state will become Exit rather than Main.