A variable (var) is a named storage location that contains a value and can be read/rewrite many times. Variables can be either global or local.
A global variable starts with
$followed by any combination of letters, digits and
Their values are available from any place of the code.
A saved variable is a special global variable available only in
VCSmodes. Its name is prefixed with
$_var. The value of this variable persists across saved games. Global variables denoted by
$var) are not saved and they get blank values when the LCS or VCS game loads.
When global variables are compiled, each one of them gets a new index in the global variable space. This index will be used by the game to locate the variable value. This index is unique across all scripts (hence global).
A local variable name may only be a number followed by
Their values are available only within the current script or the mission.
Each script or a mission have 2 special local variables called
TIMERB. The value of a timer variable is increased automatically when the game clock advances, so they are commonly used to measure time elapsed since the timer reset:
0006: TIMERA = 0 // reset the timer
0001: wait 0 ms
0019: TIMERA > 2000 // if the timer value is > 2000, i.e. 2 seconds has passed
004D: jump_if_false @WAIT_2S
0662: printstring "2 seconds has passed" // display the message
TIMERBnames are only available starting with Sanny Builder v3.3.0. In older scripts the timers are known as
17@(GTA3, VC) or
Variables are commonly used in the expressions. If the right operand is a number constant, the opcode can be omitted:
$var = 0
$myarray($index, 10i) >= 150
If both operands in the expression are variables, the compiler cannot determine the correct opcode, because the types of the variables are unknown.
For example, there are two opcodes to increment a variable value:
0058for integer values and
0059for floating-point values.
0058: $Var1 += $Var2 // (int)
0059: $Var1 += $Var2 // (float)
Assuming there is no opcode, which one to use?
$Var1 += $Var2 // ??
To tell the compiler the type of the variable, use the
var <variable>: <type>
variableis a valid global or local variable name as described above.
typecould be one of these:
Int- integer values
Float- floating-points values
ShortString- a variable containing a string literal with the fixed length (only for the arrays, use
LongString- a variable containing a string literal with the variable length (only for the arrays, use
var $size: integer
You can define types for multiple variables by separating each declaration with a comma like this:
var $x: float, $y: float, $z: float
If you prefer to have each declaration on its own line, conclude them in a
When variable types are known, the compiler is able to process the expression without opcode:
$Var1 : Integer
$Var2 : Integer
$Var1 += $Var2 // opcode 0058
Once the type of the variable is declared it is used for all the code following the declaration. You can re-declare variables to set the new type:
10@ : Float
$Var : Float
$var = 1
10@ = $Var
10@ : Int
$Var : Int
$var = 1
10@ = $Var
10@is the floating-point variable. In the
10@is the integer variable.
You can re-declare variables as many times as you need.
Since v3.2.0 it's possible to declare a variable of a built-in type (
LongString) using only the type name.
<type> <variable name>
int 0@ // 0@ declared as an integer variable.
Starting from v3.4.0 it is possible to declare variables with custom names:
a = 1
distance = 15.5
name = 'CJ'
An initial value can follow the variable name to reduce the number of the lines of code:
int a = 1
float distance = 15.5
string name = 'CJ'
The compiler binds a new local variable to each name. In the example above one may expect a resulting code to look like:
0006: 0@ = 1
0007: 1@ = 15.5
05AA: 2@ = 'CJ'
You can specify an initial value for the variable when declaring it. Write
=and then the value:
var $fVar: float = 1.0
float $fVar = 1.0
$fVaris now declared as
Floatand the compiler adds the opcode
0005in the script:
0005: $fVar = 1.0
Initialization is allowed for variables, but not for arrays.