GoTo statement

From Unreal Wiki, The Unreal Engine Documentation Site
Jump to navigation Jump to search

The GoTo statement makes code execution jump to the specified label. The exact behavior is slightly different depending on whether it is used in state code, in function code or within a ForEach loop.

Syntax in functions and ForEach loops

The following syntax applies in functions (including operators and delegates) and also in ForEach loops within state code:

goto labelname ;

The label name must be an identifier matching a label name in the immediately surrounding function or ForEach block. The label can also be outside the current code block, but it is not allowed to jump out of or into a ForEach block. Other loop types and If, Else or Switch blocks are unproblematic in that respect.

Usage considerations

The GoTo statement should generally be avoided. Instead, other flow control statements, such as break, continue or one of the various available loop constructs should be used.

The label name must be an identifier, not a name literal. It is not possible to specify a name-type variable or other kind of expression here.

Syntax in state code

The syntax in states (outside any ForEach loops) is similar to that in functions, but there is a small difference:

goto expression ;

Instead of a simple identifier to specify a label, an expression is expected that evaluates to a name value. The simplest case would be a name literal, but you can also access variables or call functions here.

As with any other expression, the compiler can only check the syntax. In particular, the expression's result is not validated at compile-time, so it is possible to specify invalid label names. Such an invalid name will generate a runtime warning and stop state code execution as if the Stop statement was used.

Using GotoState() instead

As mentioned above, the GoTo statement for jumping to state labels can only be used in state code outside any ForEach loop. If you want to jump to a different state label from within a function, you can use the GotoState() function as described below.

Warning: Functions called from within a ForEach loop in state code, as part of a function parameter expression or in similar nested context (such as the condition of a loop or an If statement) must not change the actor's state or jump to a different state label as side effect. Doing so will crash the engine with a general protection fault!

The GotoState() function is a non-static native function defined in the Object class of all engine generations:

native(113) final function GotoState (optional name NewState, optional name Label)

Within state code, the result of a GoTo statement is the same as calling the GotoState() function and only passing the label expression as the second parameter:

GotoState(, expression);

Due to the introduction of state stacking, Unreal Engine 3 added some parameters:

native(113) final function GotoState (optional name NewState, optional name Label, optional bool bForceEvents, optional bool bKeepStack)

Thus the corresponding GotoState() call would be:

GotoState(, expression, False, True);

The last two parameters can also be omitted if the current state was not pushed onto the state stack with the PushState() function.