UnrealScript Control Structures

Overview

Many times you want the ability to have different code executed in different situations depending on certain factors or bits of code repeated. UnrealScript provides support for this through various control structures, such as loops, conditional statements, and switch statements.

In all of the flow control statements, you can either execute a single statement, without brackets, as follows:

// Example of simple "if".
if( LightBrightness < 20 )
	'log( "My light is dim" );

Or you can execute multiple statements, surrounded by curly braces, like this:

// Example of simple "if".
if( LightBrightness < 20 )
{
	'log( "My light is dim" );
	'log( "Brightness ="@LightBrightness );
}

It is generally recommended to use curly braces regardless of the number of statements. It makes your code easier to read and prevents logic errors from occurring by adding statements and forgetting to add curly braces.

Selection Structures

Selection structures allow you to determine which direction the flow of your code takes based on some condition, e.g. the value of a variable, value of an expression, etc.

If Statements

An if statement lets you execute code if certain conditions are met. The simplest form is an if statement and a single condition. To check multiple conditions, else if statements can be used after the initial if statement, each with their own condition. Finally, a catch-all else statement can be used to specify a block of code to execute if none of the preceding conditions are met.

// Example of simple "if".
if( LightBrightness < 20 )
   log( "My light is dim" );

// Example of "if-else".
if( LightBrightness < 20 )
   log( "My light is dim" );
else
   log( "My light is bright" );

// Example of "if-else if-else".
if( LightBrightness < 20 )
   log( "My light is dim" );
else if( LightBrightness < 40 )
   log( "My light is medium" );
else if( LightBrightness < 60 )
   log( "My light is kinda bright" );
else
   log( "My light is very bright" );

// Example of "if" with brackets.
if( LightType == LT_Steady )
{
   log( "Light is steady" );
}
else
{
   log( "Light is not steady" );
}

The examples above use conditions all checking the value of the same variable, but the conditions in the if/else if statements do not have to be related to each other in any way. They generally will be as it makes sense to group related items, but it is not a requirement.

Switch Statements

A switch statement can be used to execute different code depending on the value of an expression. This structure begins by using the switch keyword followed by the variable or expression in parentheses. The different possible values are designated using the case keyword followed by the value and a colon. Each case can have any number of statements associated with it wihch will be executed if the value of the switch expression matches the value of the case. The break command is used to halt execution and break out of the switch. If no break command is present, execution will "fall through" to any other cases that are below until continuing the end of the switch is reached. You can specify code to be executed if no case matches the switch expression by using the optional default keyword in the same manner the cases are specified.

// Example of switch-case.
function TestSwitch()
{
	// Executed one of the case statements below, based on
	// the value in LightType.
	switch( LightType )
	{
		case LT_None:
			log( "There is no lighting" );
			break;
		case LT_Steady:
			log( "There is steady lighting" );
			break;
		case LT_Backdrop:
			log( "There is backdrop lighting" );
			break;
		default:
			log( "There is dynamic" );
			break;
	}
}

An example of allowing execution to fall through is shown below. This is useful for having the same code executed for multiple values without repeating the code.

// Example of switch-case.
function TestSwitch2()
{
	switch( LightType )
	{
		case LT_None:
			log( "There is no lighting" );
			break;
		case LT_Steady:   // will "fall though" to the LT_Backdrop case
		case LT_Backdrop:
			log( "There is lighting" );
			break;
		default:
			log( "Something else" );
			break;
	}
}

Repetition Structures

Repetition structures, or loops, provide several different methods for repeating sections of code until some condition is met.

For Loops

A for loop lets you repeat a block of code as long as some condition is met. In a for loop, you must specify three expressions separated by semicolons. The first expression is for initializing a variable to its starting value. The second expression gives a condition which is checked before each iteration of the loop executes; if this expression is true, the loop executes. If it's false, the loop terminates. Generally, this condition performs a check on the value of the variable initialized in the first expression. The third expression is performed after each loop but before the condition expression is evaluated again. Generally, this modifies the variable initialized in the first expression in some manner

For example:

// Example of "for" loop.
function ForExample()
{
	local int i;
	log( "Demonstrating the for loop" );
	for( i=0; i<4; i++ )
	{
		log( "The value of i is " $ i );
	}
	log( "Completed with i=" $ i);
}

The output of this loop is:

Demonstrating the for loop
The value of i is 0
The value of i is 1
The value of i is 2
The value of i is 3
Completed with i=4

Though most for loop expressions just update a counter, you can also use for loops for more advanced things like traversing linked lists, by using the appropriate initialization, termination, and increment expressions.

Do Loops

A do loop lets you repeat a block of code while some ending expression is true. This means the block of code will always be executed at least once since the expression is not evaluated until afterward.

Note: Unreal uses do-until syntax, which differs from C/Java (which use do-while).

// Example of "do" loop.
function DoExample()
{
	local int i;
	log( "Demonstrating the do loop" );
	do
	{
		log( "The value of i is " $ i );
		i = i + 1;
	} until( i == 4 );
	log( "Completed with i=" $ i);
}

The output of this loop is:

Demonstrating the do loop
The value of i is 0
The value of i is 1
The value of i is 2
The value of i is 3
Completed with i=4

While Loops

A while loop lets you repeat a block of code while some starting expression is true. The expression is evaluated prior to executing the block of code each time, so it is possible that the loop will never execute if the starting condition is never met.

// Example of "while" loop.
function WhileExample()
{
	local int i;
	log( "Demonstrating the while loop" );
	while( i < 4 )
	{
		log( "The value of i is " $ i );
		i = i + 1;
	}
	log( "Completed with i=" $ i);
}

The output of this loop is:

Demonstrating the do loop
The value of i is 0
The value of i is 1
The value of i is 2
The value of i is 3
Completed with i=4

Continue

The continue command will jump back to the beginning of the loop, so everything after the continue command isn't executed. This can be used to skip the loop code in certain cases.

function ContinueExample()
{
   local int i;
   log( "Demonstrating continue" );
   for( i=0; i<4; i++ )
   {
      if( i == 2 )
         continue;
      log( "The value of i is " $ i );
   }
   log( "Completed with i=" $ i );
}

The output of this loop is:

Demonstrating continue
The value of i is 0
The value of i is 1
The value of i is 3
Completed with i=4

Break

The break command exits out of the nearest loop ("For", "Do", or "While").

function BreakExample()
{
   local int i;
   log( "Demonstrating break" );
   for( i=0; i<10; i++ )
   {
      if( i == 3 )
         break;
      log( "The value of i is " $ i );
   }
   log( "Completed with i=" $ i );
}

The output of this loop is:

Demonstrating break
The value of i is 0
The value of i is 1
The value of i is 2
Completed with i=3

Note that the "break" command can also be used to skip the remainder of a conditional statement("switch").

Goto

The Goto command makes it possible to arbitrarily control the flow of code execution by specifying a label somewhere in the current function or state to "goto" and continue execution from that location.

// Example of "goto".
function GotoExample()
{
	log( "Starting GotoExample" );
	goto Hither;
Yon:
	log( "At Yon" );
	goto Elsewhere;
Hither:
	log( "At Hither" );
	goto Yon;
Elsewhere:
	log( "At Elsewhere" );
}

The output is:

Starting GotoExample
At Hither
At Yon
At Elsewhere

This can be useful in certain circumstances, especially within states, but it can also present certain problems since the order of execution of your code is not immediately obvious. You will seldom, if ever, see this method of controlling code flow used anywhere other than in state code as most other situations lend themselves better to other control structures.