Control the flow of HSL scripts

You can control the flow of script execution by using the following types of statements to manage the order in which operations are executed:

Use conditional statements (if, else, else if, switch)

Conditional statements execute a command (or grouping of commands) when a specific test condition is true. This flow control mechanism is useful if you have created a series of commands that will be executed only if a certain condition exists.

You write a test condition by enclosed it in parentheses (). The resulting value must be an int, float, or vector data type. The test condition value is then converted to an int data type to represent either true or false.

// if (test condition) execute statement;
if (0 < 1) print "zebra";

If the test condition has a value of type int or float, the test condition is true only if the value, converted to type int is not 0:

if (<<0,0,0>> == <<0,0,0>>) print "referee"; //true

You can use the following types of conditional statements in Shogun Post:

• IF statements
• ELSE statements
• ELSE IF statements
• SWITCH statements

IF statements

The IF statement works as follows: if the test condition is true, the statement is executed.

You write an IF statement expression in this format:

If you are using multiple statements, use grouping to control scope execution by enclosing the statements within braces {}.

For example:

if ( 2 < 3 )
 {
 string $blah = "This worked";
 print ($blah);
 }

ELSE statements

The ELSE statement always follows the IF statement. The ELSE statement is executed when the preceding IF statement is false.

You write an ELSE statement expression in this format:

For example:

if (5 % 2 >1)
 {
 print "bah";
 }
 else
 {
 print "humbug";
 }

ELSE IF statements

The ELSE IF statement is always paired with the IF conditional statement. Unlike the else command which executes a statement when the IF statement is false, the ELSE IF statement requires another test condition to be true, or it will not execute either statement.

You write an ELSE IF statement expression in this format:

For example:

if (-1 >= 1)
 {
 print "Statement 1";
 }
 else if (-1 <= 1)
 {
 print "Statement 2";
 }

SWITCH statements

The switch statement is a conditional statement that executes a code block depending on which one of a number of given cases is matched to the switch expression.

The switch statement takes either a float, int, Boolean, or string as an argument. Each case must be the same data type as the switch expression, that is, if the switch expression takes an int, all cases within the switch statement must also be int, as shown in the following example.

The optional keyword break is often used in switch statements to break out of the statement when one of the cases is found to match the expression, as shown below.

You write a switch statement in this format:

For example:

int $test = 2;
switch($test)
{
 case 1:
   print "1";
   break;
 case 2: 
   print "2";
   break;
 case 3: 
   print "3";
   break;
}

Use looping statements (while, do while, for)

Looping statements repeatedly execute statements while a specific test condition is true. This flow control mechanism is useful when you have a set of statements you want to run until a certain condition is met.

You can nest looping statements.

You can use the following types of looping statements in Shogun Post:

• WHILE statements
• DO WHILE statements
• FOR statements

WHILE statements

A WHILE looping statement continuously executes designated statements as long as a specific condition remains true.

You write a WHILE looping statement in this format:

For example:

int $PJ = 5;
  while ($PJ > 0)
    {
     print
     ("There are " + string($PJ) + " P.J. sandwiches left.");
     $PJ = $PJ - 1;
    }
  print ("Houston, we have a problem!");

DO WHILE statements

A DO WHILE looping statement executes a specific statement then checks whether or not to repeat the loop. This ensures that the statement is executed at least once.

You write a DO WHILE looping statement in this format:

For example:

int $peanuts = 1;
 do {
 print ("Elephants work for peanuts");
 $peanuts += 1;
 print ($peanuts);
 }
 while ( $peanuts < 10);

FOR statements

A FOR looping statement provides loop control that has initialization, test, and an increment statement.

You write a FOR looping statement in this format:

For example:

string $blah;
 int $i;
 for( $i = 1; $i < 6; $i += 1 )
 {
 $blah = "This is what happens when things coincide";
 print( $blah );
 }

Looping examples

These examples show you how to use looping statements.

Single and nested loops

You can use the script below as a template for creating single and nested loops. Refer to the comments to learn what each set of statements does. You may want to save this script to a file called loop-example.hsl for future reference.

//Define the statement you are going to print each iteration
 string $statement;
//Define variables to use as counters
 int $i, $ j;
//Start the $i loop and specify start, end, and amount to increment
 for( $i = 1; $i < 6; $i += 1 ) {
//Start the $ j loop and specify start, end, and amount to increment 
   for( $j = 1; $j < 15; $j += 2 ) {
//Tell Shogun Post to print something if $i < $J
     if( $i < $j )
       $statement = string( $i ) + " is less than " + string( $j );
//Tell Shogun Post to print something else if $i > $j
     else if( $i > $j )
       $statement = string( $i ) + " is greater than " + string( $j );
//Tell Shogun Post what to print if the two counters are equal
     else
       $statement = "This is what happens when things coincide";
//Tell Shogun Post to actually print the statement you've assembled
   print( $statement );
//Close the second loop
   }
//Close the first loop
 }

Loop through objects in a scene

Sometimes you may need to cycle through all the objects in a scene in order to find an object you cannot identify, initially, by name. On other occasions you may wish to create a list of all the objects in a scene, or a list of all the new objects added to a scene.

The following example shows you how to list all the objects in a scene by name. You can modify this set of steps to perform the tasks listed above, and to handle any activity which requires you to execute one or more operations on through a given set of objects in a scene.

// Courtesy of Jake Wilson of SCEA
// Initialize Variables
print " ";  
// Create array of children under 'Actor' Mary's character node
string $childarray[] = `getChildren Mary`;    
// Determine # of children
int $childcount = `getCount $childarray`;  
// Create a $childarrayloop to hold a number 
int $childarrayloop = 0;  
// Print an empty string
   string $ proptest;
// Start a loop which run once for each of Mary's children
for ( $childarrayloop=0 ;
 $childarrayloop < $childcount ;
 $childarrayloop +=1 ){
    // print name of current child marker in array   
    print ( string ($ childarray[$childarrayloop] ) );
    // return the name of the marker and compare the name 
    // of the marker to the name"LFWT"
    $ proptest = ` getStringProperty $ childarray[$childarrayloop] Name`; 
    if ($ proptest==LKNE){
        // if that LFWT marker is found, this tells the loop to quit
        $ childarrayloop=$childcount; 
        print ( "EXITING LOOP" );
        }
    }

Use interruption statements (break)

You can use break statements to affect the flow control in Looping statements.

The break statement is a loop interruption that exits the loop immediately. It works inside all loops.

You write a break statement in this format:

For example:

int $parole = 3;
 while ($parole <8)
 {
 print (string($parole) + " days until $parole");
 $parole -= 1;
 if ($parole <= 0)
 break;
 }
 print "monopoly";