Knowledge Base - Variables

Variables

---

Action Code Scripting (ACS) only has one data type, a four byte integer. In order for a variable to be used it must be declared.

int line;
str message;

The above statements tell the engine is to allocate a space in memory for two variables, one a number the other a string. The variables at this point, do not have any meaningful values since they haven't been initialized. The declaration simply sets aside some memory to hold the future value.

Assignment

To use a variable you must set it to a meaningful value by using one of the assignment operators. ACS recognizes the following assignment operators: =, +=, -=, *=, /=, %=, ++, --. These will be familiar to C programmers, and for the rest of us, the following definitions will clarify their use.

=

Assign the value into the variable.
A = 1;

+=

Add to the value already in the variable.
A += 1; This is the same as A = A + 1.

-=

Subtract from the value already in the variable.
A -= 1; This is the same as A = A - 1.

*=

Multiply to the value already in the variable.
A *= 2; This is the same as A = A * 2.

/=

Divide by the value already in the variable.
A /= 2; This is the same as A = A / 2.

%=

Assign the remainder (modulus) to the variable.
A %= 3; This is the same as A = A % 3.

++

Add 1 to the value already in the variable.
A++; This is the same A = A + 1.

--

Subtract 1 from the value already in the variable.
A--; This is the same as A = A - 1.

Scope

In addition to a value, a variable has a property called scope. Scope is the visibility of the variable. There are three levels of scope in ACS. World, Map and Script.

World scope means that the variable is visible to all scripts in all maps. This type of variable would be used for information that pertains to the wad file as a whole. A world variable could be used in any script in any map in the wad file.

Map scope means that the variable is visible only in a particular map. That is, if you declare a variable in map01, it is not accessible to map02. All the scripts in map01 though, will have access to the variable.

Script scope means that the variable is visible only in a particular script. If you define a variable within script 1, it will not be accessible in script 2.

The scope of a variable depends on where the variable is declared. World scope variables can be defined outside of any script and must be identified by the keyword world, followed by an index number and the variable name:

world int 1:wadbadguycount;

The variable wadbadguycount will be accessible to any script in any map.

Map scope variables are declared outside of any scripts, within a particular map.

int mapbadguycount;

The variable mapbadguycount will be accessible by any script within the current map.

Script scope variables are declared within a script.

script 1 (void)
{
    str message;
 
    message = "Hello";

    ...commands...;
}

The variable message can only be used within script 1 and cannot be used in any other script.

The purpose of the variable determines where the variable needs to be declared. If the map designer needs to know if the player has visited map06 yet, then a world variable would be declared. If the map designer needs to execute a command when all the keys have been picked up by the player on a particular map, then a map level variable would be defined to keep track of the number of keys in the current map. If the variable needs to store a temporary value, then it would be defined within a particular script.

Data types

As previously mentioned, ACS has only one data type, a four byte integer. By declaring the variable as an int, it will be treated like a number. If the variable is declared as a str, then it will be treated as a string. How can an integer represent a string? Remember that the declaration only allocates space for the variable. When a variable is declared as a str, then the variable "points" to the location in memory where the string is stored.

Summary

Variables are a necessary part of scripting and when used properly will ease both the creation and execution of scripts. The key is to remember the scope of a variable and to use the lowest level of scope whenever possible to reduce any errors creeping into the scripts.

Back