Call of Duty 5: Scripting Syntax And Grammar

What Is GSC?

GSC is the IWEngine's custom scripting language. It is very quickly compiled at runtime by the game executable during the level load stage. Conveniently, it is also reloaded and recompiled during a "map_restart", which only takes a second or two, allowing for very quick iteration. It also supports an in-game script debugger which functions relatively similarly to debugging in DevStudio, including such features as step by step debugging, watch window, and breakpoints.

Where Do GSC Files Reside?

GSC files are found in the \raw\maps folder and subfolders. In broad terms there are two types of gsc files, which are separates primarily by filenaming and organizational conventions.

The first are the utility modules, whose filenames are prefixed by an '_'. Some, like the _ambientpackage.gsc, are designed to be a nearly autonomous module which can run on its own following one or more lines of initialization. Others, such as the aptly named _utility.gsc, are more of a convenience, housing lots of commonly used functions that are implemented in script.

The second is the level module, which may be made up of one or more files prefixed by the name of the level they are associated with. levelname.gsc is expected by the game to exist and to contain a function called main(). Depending how the level script has been organized, there may be other level files referenced by levelname.gsc. For example, levelname_amb.gsc is the convention which denotes the ambient sound scripting for a given level. This allows the sound department to setup their ambient scripts without interfering with the level scripter, and vice versa. For example, the main function for a map named amb_pkg_test which tests the _ambientpackage might look like this:

#include maps\_utility;
main()
{
	maps\scriptgen\amb_pkg_test_scriptgen::main();
	level thread maps\amb_pkg_test_amb::main();
}

Notice the second line. The first token, "level", declares the thing which will be acted upon, the second, "thread", declares that a new thread is desired (threads will be discussed in more detail later on), and the third token acts as input, telling the script the name of the function to be used as the basis of the new thread. This third token is in fact made up of two pieces separated by the pair of colons. The first, "maps\amb_pkg_test_amb", tells which file to look in relative to the raw directory, and the second, "main()", identifies the name of the function to be found within that file. If we wished to reference a function in the same file, we would not need the pathing declaration, or the double colons.

Comments

A comment is one or more lines of a script file that are not compiled into the script at run time. They allow us to put notes or explanations about the script into the script file without affecting the script:

// this is a single line comment
/* this
   is a multi line
   comment
*/
x = 10; // this is a single line comment placed after a statement which will execute

The "//" declares that script should ignore any text (including it) on the remainder of the line it is found on. As we can see above, that means that such a comment can even be placed following a statement that is meant to be executed at runtime. The other comment type is the multi line comment, which is opened with "/*" and is closed with "*/". Anything in between those special characters will be ignored.

Variables, Arrays and Structs

Variables are not formally declared, instead, you simply name a new variable and assign a value to it:

var_int = 7; // declare an integer variable
var_float = 4.2; // declare a float variable
var_string = "test_string"; // declare a string variable

GSC is loosely typed, i.e. a variable receives a type (int, float, bool, string, etc.) when it is created based on the value or variable assigned to it. Functions, particularly builtin functions (functions defined in code instead of other script files), will sometimes perform validation on input parameters to ensure that the expected data type is being passed in.

There are some types which can be silently interchanged, for example:

// set the variable to var_int concatenated as a string onto the end of var_string
var_compound_string = var_string + var_int;

// the == operator signifies the value of var_compound_string must be the same as "test_string7"
if ( var_compound_string == "test_string7" )
    return true;

In the above example var_int is automatically treated as a string for the scope of the expression, simplifying the creation of compound strings.

Finally, there is a special "undefined" data type, which is returned by variables that do not yet exist or haven't been initialized. This case can be tested for through the "isDefined" function:

// the ! operator inverts the value of a boolean statement, ie. true becomes false, and false becomes true
if ( !isDefined( var_does_not_exist ) )
{
    var_does_not_exist = false;
}

// see whether var_does_not_exist is a variable that exists
if ( isDefined( var_does_not_exist ) )
{
    return var_does_not_exist;
}

The above example returns the value that varDoesNotExist has been set to, false, because it doesn't previously exist, causing it to be initialized, at which point it is found to be defined, allowing the return statement to be executed.

Arrays

Arrays are initialized by assigning "[]". Arrays are zero-indexed and automatically have a "size" member which can be accessed through the dot operator:

level._ambient_packages[package].elements = []; // declare this variable to be an array
index = level._ambient_packages[package].elements.size; //store the count of elements in the index variable
level._ambient_packages[package].elements[index] = spawnStruct(); // add a struct to the end of the array
level._ambient_packages[package].elements[index].alias = alias; // a new variable w/ the value alias

Here we have created an array in the variable "level._ambient_packages[package].elements", retrieved its size, 0, to determine which index to append our new data to, and finally used the bracket operator on it to assign our new data. If we were to repeat the last three lines, size would have automatically been updated to 1, reflecting the previously added element, and we would be adding elements at the 1th index.

Arrays can also be indexed by strings:

level._ambient_packages["outdoors"] = "outdoor_package"; //index into the array by string instead of number
level._ambient_packages["indoors"] = "indoor_package";
level._ambient_packages["both"] = "all";
packageArray = getArrayKeys( level._ambient_packages ); // get an array of the strings used to index
for ( i = 0; i < packageArray.size; i++ )
{
    if ( level._ambient_packages[packageArray[i]] == "indoor_package" )
    {
        return i;
    }
}

The above will return 1 as the value of i.

Structs

There is one other variable type of note, the struct, which allows for combing multiple pieces of related data together into one variable:

timer = spawnStruct(); // declare a struct
timer.start = 10; // add the variable start to it, with the value 10
timer.current = timer.start; // add the variable current to it and set its value to that of start
timer.end = 150; // add the variable end to it, with the value 150

In the example we have declared a timer struct using the spawnStruct() function. Once we have a struct, we can declare new variables as members of it using the dot operator, including variables that contain arrays, or even other structs. Not only is it convenient to group related data together like this, but it also simplifies passing this data around to other functions, or as well see later, using it as input to a thread. For example:

// declare a new function named "is_timer_finished"
// which takes 1 variable as input, which will be referred in the function as timer
is_timer_finished( timer )
{
    if ( timer.current < timer.end ) // if current time is less than end time
    {
        return false;
    }
    else // otherwise end time must be greater than or equal to current time
    {
        return true;
    }
}

Functions

Functions allow you to write script once, and then reference multiple times, possibly changing its results by using different input. The syntax for a function is very simple:

foo_bar( param_1, param_2, optional_param ) // decalre the function foo_bar, with 3 inputs
{
    opt_var = 0; // intialize opt_var to 0
    if ( isDefined( optional_param ) )
    {
        opt_var = optional_param; // only set opt_var to optional_param if optional_param was passed in
    }

    return param_1 * param_2 + opt_var; // multiply param_1 by param_2, then add opt_var to the result
}

foo_bar( 2, 6, 5 ) // results equal 17
foo_bar( 2, 6 )    // results equal 12
maps\this_file_name::foo_bar( 2, 6, 3 ) // results equal 15

Here we have created a new function, which tests to see if a value was passed into optional_param, and then performs arithmetic on those values which were passed in. We can also see that by simply defining the function once here, we have a number of different ways to reference it. If it were defined in a different file, we could reference it through the double colon syntax, as seen in the last line. Otherwise, we can simply call the function and supply the parameters as needed. Note that calling a function with not enough parameters will generally result in a script error about using an undefined variable.

Execution Flow

There are numerous methods for directing the flow of execution in script, which will be covered briefly here. Threads are complicated enough to warrant their own section, and thus will be discussed later on.

wait

GSC runs once every server frame, and there are 20 server frames per second. Script can not run indefinitely each server frame and still maintain a solid 60FPS, so the wait command is offered to force execution of a given thread to cease for 1 or more frames. The wait command takes a float value as a parameter representing the number of seconds to wait:

wait 0.05; // waits 1/20th of a second, or 1 server frame
wait 0.5;  // waits half a second, or 10 server frames
wait 1;    // waits 1 second, or 20 server frames

Of special note is the script error "script runtime warning: potential infinite loop in script", which occurs when the game determines that a thread has run for too long during a single thread. This occurs either when script tries to do too many operations all at once, which can be fixed by inserting wait statements to break up the tasks across multiple frames, or when an infinite for or while loop (discussed later) run without hitting a wait statement, and again the solution is to add a wait statement.

if

If statements are used to execute statements based on one or more conditions:

if ( a < b ) // if the value of a is less than the value of b
{
    c = b - a;
}
else if ( a > b ) // otherwise, if the value of a is greater than the value of b
{
    c = a - b;
}
else // otherwise, the value of a must be equal to the value of b
{
    c = 0;
}

Here we see the setting of c to the absolute value of the difference of a and b. The first expression within the parentheses that evaluates to true will cause the statements in the braces below to be executed, and no further checking of other "else if" statements in the chain will occur. Any number of "else if" statements are optional, as well as the optional trailing else statement. Furthermore the expression in the parentheses can be compounded to test multiple things:

if ( !isDefined( a ) || !isDefined( b ) ) // if either a or b has yet to be declared
{
    c = 0;
}

The "||" operator represents the concept of or. So in the above example if either a is not defined or b is not defined, then the statment becomes true. An interesting note is that if a is not defined, then whter b is defined will not be checked, as the expression is already known to be true. The expression could be equivalently written using the and operator "&&":

// again, if either a or b has yet to be declared, this time using a slightly different logic
if ( !( isDefined( a ) && isDefined( b ) ) )
{
    c = 0;
}

All expressions in an and operation must be true for the entire expression to be true, thus similarly to the or operator, if a is determined to not be defined, whether b is defined will not be checked as the expression is already known to be false.

switch

The switch statement allows for a more compact script when you want to have multiple execution paths based on numerous possible values for a single variable:

switch ( level.gametype ) // check the value of level.gametype
{
    case "sab": // if the value of level.gametype is "sab"
        setDvar( "ui_gametype_text", "@MP_SABOTAGE" );
        break;

    case "sd": // if the value of level.gametype is "sd"
        setDvar( "ui_gametype_text", "@MP_SEARCH_AND_DESTROY" );
        break;

    case "dom": // if the value of level.gametype is "dom"
        setDvar( "ui_gametype_text", "@MP_DOMINATION" );
        break;

    case "war": // if the value of level.gametype is "war"
    default: // if the value of level.gametype is none of the values listed above
        setDvar( "ui_gametype_text", "@MP_WAR" );
        break;
}

Rather than use a long series of if-else-if statements, the switch statement will skip to the case statement whose value matches the value of the variable in parentheses (numerals may also be used as the parameter to the case statements), and if no matching case statement is found, execution skips to "default:". Multiple case statements can be stacked together, as seen above where default and case"war" are together, allowing multiple values to result in the same code execution. It's important to add the break statement after your list of desired statments, otherwise execution would continue on past the next case statement and execute the code there as well.

for

The for loop is typically used to perform the same set of statements on a series of items. it takes three expressions as input separated by semicolons (all 3 of which are optional, though the semicolons are not), the initialization (to intialize variables as needed), the continuation check (an expression which if true will cause the script within the for loop's braces to execute again, otherwise the for loop will be left, and execution will continue on past it), and the post execution step (the opportunity to perform variable incrementing or other such loop maintenance just after the loop has been executed, but just before the continuation check occurs):

// starting off with idx equal to 0, and iterating as long as it is less than the number of elements
// in the weaponslist array, increasing idx by 1 on each iteration
for( idx = 0; idx < weaponsList.size; idx++ )
{
    weapon = weaponsList[idx];
    if ( weapon == "none" )
        continue; // skip the remainder of this for loop, but continue iterating
    if ( weapon == "claymore" )
        continue; // skip the remainder of this for loop, but continue iterating
    if ( weapon == "claymore_detonator" )
        continue; // skip the remainder of this for loop, but continue iterating
					
    self switchToWeapon( weapon ); 
    break; // leave the for loop
}

This for loop will start by setting idx to 0, check if that value is less than the size of the weaponsList and if so run the code in the braces, then increase the value of idx by 1 and check against the size again, repeating this entire process (with the exception of the initializing of idx to 0, which only occurs once) until the continuation check is false.

We also see two additional keywords that may be used in a for loop. The break statement immediately leaves the for loop and execution goes on past it. The continue statement skips the remainder of execution within the loop, moving directly to the post execution step.

while

A while loop is functionally very similar to a for loop, in fact a for loop can be made functionally equivalent to a while loop by omitting the initialization and post execution step. A while loop simply tests a single expression and as long as that expression is true, the body of the while loop will execute, and this will repeat until that expression is false:

index = 3;
while ( index ) // as long as index is true, which is as long as it is not zero
{
    iprintlnbold( "index is currently " + index ); // prints the given string to the screen
    index--; // decrease the value of index by 1
}

iprintlnbold( "done" ); // prints the given string to the screen

// results:
// index is currently 3
// index is currently 2
// index is currently 1
// done

Also note that the continue and break statements are valid for the while loop and function the same way as in a for loop.

Threads

Threads allow mutiple paths of execution to run in the same server frame, and they can wait until a certain event occurs, do some processing, and then either end themselves, or wait again for the next event they care about. They are very simple to create, you simply define a function as you normally would, and then launch the thread using the name of that function:

// declare the function foo that is intended for use as a thread
foo()
{
    for ( ; ; ) // this for loop continues forever
    {
        do_stuff();
        wait 5;
    }
}

thread foo(); // start up a thread, using the function foo as the basis of the thread

In this example the thread foo will call the do_stuff() function every 5 seconds for the remainder of the level.

self

When a thread is run on a particular variable, say the player, a trigger, or perhaps a struct, that variable can be referenced from within the thread using the self variable:

// declare the function foo_self that is intended for use as a thread that runs on a specific object
foo_self()
{
    for ( ; ; ) // this for loop continues forever
    {
        self moveto(self.origin + (0, 0, 5), .05); // self is the object the thread is run on
        wait 0.05;
    }
}

// start up a thread, using the function foo_self as the basis of the thread, and run it on elevator
elevator thread foo_self();

Here, we have run the foo_self() thread on an entity named elevator, and the thread causes it to smoothly rise 5 units every server frame by referencing it through the self variable

notifies, waittills And endOns

While a thread can be made to execute until completion and then end, the most typical use of a thread is for processing that you want to occur repeatedly throughout the level or until some event occurs. In the examples we've seen so far, the threads use an infinite for loop and run until the level is complete. Now we'll see how we can use Waittills and EndOns to control when threads execute and stop. Each of these statements take a string as their parameter, are run on some variable (be it level, player, an entity, or a struct), and are triggered by a corresponding call to notify run on that same variable with the same string as its parameter. Let's see how we could use these statements to cause an elevator to rise 100 units at the player's command:

rise()
{
    // declare that this thread should end if the notify "death" is sent on self
    self endOn( "death" );

    for ( ; ; )
    {
        self waittill( "rise" ); // wait until the notify "rise is sent on self
        for ( count = 20; count; count-- )
        {
            self moveto(self.origin + (0, 0, 5), .05);
            wait 0.05;
        }
        self notify( "rise done" ); // send the notify "rise done" on self
    }
}

elevator thread rise();

// later on the player presses the up button:
elevator notify( "rise" );
elevator waittill( "rise done" );

This rise() thread waits until something notifies the elevator it was attached to, causing it to wake up and start executing. Once it has completed moving the elevator, it sends a notify back through the elevator that it is done. The thread begins with an endOn("death") statement, which will cause the thread to cease if the elevator is ever destroyed.

Source: Treyarch's Wiki