Variable commands
 
These are the commands which give SinScript its true power (gameX86 source code reference: scriptvariable.cpp). There are 2 kinds of variable commands: operators and conditional test. Operators set or modify the value of a variable. Conditional tests compare the value of a variable with either an explicit value or another variable. If the condition test returns "true", the command following the conditional test is executed. For more info on variables in SinScript, refer to the basic variables primer.

Variable commands are colored in medium green in my custom SinScript syntax coloring wordfile for UltraEdit32.


=  
 
Function
 
Number variable operator. This sets a number variable to the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> = <integer>|<floating_point>|<number_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value specified in the command argument.

Note:
Do not use a text string or a string variable as the argument for this command.



+=  
 
Function
 
Number variable operator: add. This increments a number variable by the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> += <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a number variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet, this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command.



-=  
 
Function
 
Number variable operator: subtract. This decrements a number variable by the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> += <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a number variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet (the sign will be inverted however), this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command.



*=  
 
Function
 
Number variable operator: multiply. This multiplies a number variable by the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> *= <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a number variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will invariably be 0 but this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command.



/=  
 
Function
 
Number variable operator: divide. This divides a number variable by the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> /= <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a number variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will invariably be 0 but this is not the proper way to use this command.

Note:
Never divide a number variable by 0. Doing this will give the variable an invalid value (-1.#LND00 if variable = 0, 1.#LNF00 if variable > 0, -1.#LNF00 if variable < 0). Do not use a text string or a string variable as the argument for this command.



append  
 
Function
 
Operator. This appends a text string at the end of a number or string variable. A text string or an existing string variable must be used as the argument.

Syntax
 
<variable_name> append "<text_string>"|<string_variable>

Notes & examples
 
This command is meant to be used with a string or number variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet, this is not the proper way to use this command.

Note:
Do not use a number or a number variable as the argument for this command.



appendfloat  
 
Function
 
Operator. This appends a floating point number at the end of a string variable. A floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> appendfloat <floating_point_number>|<number_variable>

Notes & examples
 
This command is meant to be used with a string variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet, this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command.



appendint  
 
Function
 
Operator. This appends an integer at the end of a string variable. An integer or an existing number variable must be used as the argument.

Syntax
 
<variable_name> appendint <integer>|<number_variable>

Notes & examples
 
This command is meant to be used with a string variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet, this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command.



coninput
 
Function
 
Operator. Passes the last menu or command prompt data stored in the <console_variable> to a user defined variable. The <console_variable> is a user defined variable to which is assigned the "consolename" of the console entity (without the % symbol).

Syntax
 
<variable_name> coninput <console_variable>

Notes & examples
 
This command is used right after a waitForConsole command which stands by for and detects when new data was entered at the console by the player.


div  
 
Function
 
Number variable operator: integer divide. This divides a number variable by the value specified after the operator but only the integer part of the result is kept. An integer or an existing number variable must be used as the argument.

Syntax
 
<variable_name> div <integer>|<number_variable>

Notes & examples
 
Here's an example of the result obtained with the div operator:

local.bob = 7
local.bob div 2
print local.bob


The result of the operation is 3 since the floating point part of the result (0.5) was dropped.

If a floating point number is used as the command argument, the operator will ignore the part after the decimal period and perform the operation of the integer part of the value only. So for example:

local.bob = 7
local.bob div 2.5
print local.bob


The result of the operation is still 3 since the floating point part of the number argument is ignored and the operation was in fact performed on the value 2.

This command is meant to be used with a number variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will invariably be 0 but this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command.



getcvar
 
Function
 
Operator. This fetches the current value of any valid game console variable and stores it in a user defined script variable.

Syntax
 
<variable_name> getcvar <cvar_name>

Notes & examples
 
For a complete list of all game cvar's, drop the console while in the game with the tilde (~) key and type the command "cvarlist". To get a permanent record of all cvar's, you can dump the output of the console into a log file by setting the "logfile" cvar to 1 before executing the "cvarlist" command as follows:

logfile 1
cvarlist
logfile 0


Then leave the game (this is necessary in order for the logfile to close). Browse the game's base folder. You will find a text file named qconsole.log which should be about 20K in size. This file now contains the complete list of all cvar's. It is recommended that you rename the file to a relevant name and keep it in a convenient folder on your HD for future reference.


ifequal  
 
Function
 
Number variable conditional test. This will execute the command following the conditional test if the value of the argument is equal to the value of the variable. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> ifequal <integer>|<floating_point>|<number_variable> <command>

Notes & examples
 
This command must be used with a number variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a text string or a string variable as the argument for this command.


ifgreater  
 
Function
 
Number variable conditional test. This will execute the command following the conditional test if the value of the argument is greater than the value of the variable. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> ifgreater <integer>|<floating_point>|<number_variable> <command>

Notes & examples
 
This command must be used with a number variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a text string or a string variable as the argument for this command.


ifgreaterequal  
 
Function
 
Number variable conditional test. This will execute the command following the conditional test if the value of the argument is greater or equal to the value of the variable. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> ifgreaterequal <integer>|<floating_point>|<number_variable> <command>

Notes & examples
 
This command must be used with a number variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a text string or a string variable as the argument for this command.


ifless  
 
Function
 
Number variable conditional test. This will execute the command following the conditional test if the value of the argument is less than the value of the variable. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> ifless <integer>|<floating_point>|<number_variable> <command>

Notes & examples
 
This command must be used with a number variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a text string or a string variable as the argument for this command.


iflessequal  
 
Function
 
Number variable conditional test. This will execute the command following the conditional test if the value of the argument is less or equal to the value of the variable. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> iflessequal <integer>|<floating_point>|<number_variable> <command>

Notes & examples
 
This command must be used with a number variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a text string or a string variable as the argument for this command.


ifnotequal  
 
Function
 
Number variable conditional test. This will execute the command following the conditional test if the value of the argument is not equal to the value of the variable. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> ifnotequal <integer>|<floating_point>|<number_variable> <command>

Notes & examples
 
This command must be used with a number variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a text string or a string variable as the argument for this command.


ifstrequal  
 
Function
 
String variable conditional test. This will execute the command following the conditional test if the text string in the argument is identical to the text string contained in the variable. A text string or an existing string variable must be used as the argument.

Syntax
 
<variable_name> ifstrequal "<text_string>"|<string_variable> <command>

Notes & examples
 
This command must be used with a string variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use an existing number variable as the argument for this command.


ifstrnotequal  
 
Function
 
String variable conditional test. This will execute the command following the conditional test if the text string in the argument is not identical to the text string contained in the variable. A text string or an existing string variable must be used as the argument.

Syntax
 
<variable_name> ifstrnotequal "<text_string>"|<string_variable> <command>

Notes & examples
 
This command must be used with a string variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use an existing number variable as the argument for this command.


ifthreadactive
 
Function
 
Conditional test. This will execute the command following the conditional test if the previously called thread is active (still running). It is always used after a thread call command and requires the use of the reserved variable parm.previousthread either by using it directly or by passing its value to a user defined local variable first and using that local variable for the conditional test.

Syntax
 
parm.previousthread ifthreadactive <command>

Notes & examples
 
The variable parm.previousthread contains a value which is the status of the previously called thread. When the called thread ends, the value of parm.previousthread changes to indicate this. In principle, parm.previousthread can be used directly by the ifthreadactive conditional test.

Please note that the value of parm.previousthread will be available as long as the called thread is running BUT if it is halted with a pause or wait command, the value of parm.previousthread will be LOST so be warned that parm.previousthread is temporary by nature.

This is why it is often passed to a local variable and that the local variable is refered to instead in the ifthreadactive command. This is a way to ensure that the variable will always be available no matter what happens in the called thread. So it is good practice to always use the following syntax:

thread <thread_name>
local.<variable_name> = parm.previousthread
local.<variable_name> ifthreadactive <command>

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command.


ifthreadnotactive
 
Function
 
Conditional test. This will execute the command following the conditional test if the previously called thread is inactive (terminated). It is always used after a thread call command and requires the use of the reserved variable parm.previousthread either by using it directly or by passing its value to a user defined local variable first and using that local variable for the conditional test.

Syntax
 
parm.previousthread ifthreadnotactive <command>

Notes & examples
 
The variable parm.previousthread contains a value which is the status of the previously called thread. When the called thread ends, the value of parm.previousthread changes to indicate this. In principle, parm.previousthread can be used directly by the ifthreadnotactive conditional test.

Please note that the value of parm.previousthread will be available as long as the called thread is running BUT if it is halted with a pause or wait command, the value of parm.previousthread will be LOST so be warned that parm.previousthread is temporary by nature.

This is why it is often passed to a local variable and that the local variable is refered to instead in the ifthreadnotactive command. This is a way to ensure that the variable will always be available no matter what happens in the called thread. So it is good practice to always use the following syntax:

thread <thread_name>
local.<variable_name> = parm.previousthread
local.<variable_name> ifthreadnotactive <command>

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command.


mod  
 
Function
 
Number variable operator: modulo. This divides a number variable by the value specified after the operator but only the remainder part of the result is kept. An integer or an existing number variable must be used as the argument.

Syntax
 
<variable_name> mod <integer>|<number_variable>

Notes & examples
 
Here's an example of the result obtained with the mod operator:

local.bob = 7
local.bob mod 2
print local.bob


The result of the operation is 1 since 7 divided by 2 equals 3 with a remainder of 1 (3 x 2 = 6, 7 - 6 = 1).

If a floating point number is used as the command argument, the operator will ignore the part after the decimal period and perform the operation of the integer part of the value only. So for example:

local.bob = 7
local.bob mod 2.5
print local.bob


The result of the operation is still 1 since the floating point part of the number argument is ignored and the operation was in fact performed on the value 2.

This command is meant to be used with a number variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will invariably be 0 but this is not the proper way to use this command.

Note:
Do not use a text string or a string variable as the argument for this command. Most of all, do not use 0 as the argument for the command because this will make the game crash!



randomfloat  
 
Function
 
Number variable operator: random floating point number generator. This sets a number variable to a random floating point value between 0 and the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> randomfloat <integer>|<floating_point>|<number_variable>

Notes & examples
 
The floating point number assigned to the variable will have a precision of 2 digits after the decimal period. So for example, if you use the command:

local.bob randomfloat 1

The value of local.bob could be anything from 0.00 to 1.00. If you use a negative value as the command argument, the principle remains the same. So by using the following command:

local.bob randomfloat -1

The value of local.bob could be anything from -1.00 to 0.00

If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change it's current value to the new value specified in the command argument.

Note:
Do not use a text string or a string variable as the argument for this command.



randomint  
 
Function
 
Number variable operator: random integer generator. This sets a number variable to an integer value between 0 and the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> randomint <integer>|<floating_point>|<number_variable>

Notes & examples
 
The integer number that will be assigned to the variable can be any value from 0 to the value specified in the command argument minus 1. So for example, if you use the command:

local.bob randomint 5

The value of local.bob could be anything from 0 to 4. The same goes for negative values. If you use the command:

local.bob randomint -5

The value of local.bob could be anything from -4 to 0. If the value of the command argument is a floating point number, the figures after the decimal period are ignored and the operation is performed only on the integer part of the number. Thus the command:

local.bob randomint 5.75    Does the same thing as:    local.bob randomint 5

If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change it's current value to the new value specified in the command argument.

Note:
Do not use a text string or a string variable as the argument for this command.



string  
 
Function
 
String variable operator. This sets a string variable to the value specified after the operator. A text string or an existing string variable must be used as the argument.

Syntax
 
<variable_name> string "<text_string>"|<string_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value specified in the command argument.

Note:
Do not use a number variable as the argument for this command.



vector  
 
Function
 
Vector variable operator. This sets a vector variable to the value specified after the operator. A vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value specified in the command argument.

Note:
Do not use a number, text string, number variable or string variable as the argument for this command.



vector_add  
 
Function
 
Vector variable operator. This increments a vector variable by the value specified after the operator. A vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_add "(<X Y Z>)"|<vector_variable>

Notes & examples
 
This command is meant to be used with a vector variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet, this is not the proper way to use this command.

Note:
Do not use a number, text string, number variable or string variable as the argument for this command.



vector_cross  
 
Function
 
Vector variable operator. This performs a cross product between the 2 vectors or vector variables specified after the operator and stores the resulting vector in <variable_name>. Vectors or existing vector variables must be used as the arguments.

Syntax
 
<variable_name> vector_cross "(<X Y Z>)"|<vector_variable> "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value calculated by the operation.

Note:
Do not use numbers, text strings, number variables or string variables as the argument for this command.



vector_dot  
 
Function
 
Vector variable operator. This performs a dot product between the 2 vectors or vector variables specified after the operator and stores the resulting number in <variable_name>. Vectors or existing vector variables must be used as the arguments.

Syntax
 
<variable_name> vector_dot "(<X Y Z>)"|<vector_variable> "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value calculated by the operation. Note that here, <variable_name> will be a number variable because of the nature of the operation.

Note:
Do not use numbers, text strings, number variables or string variables as the argument for this command.



vector_ifequal  
 
Function
 
Vector variable conditional test. This will execute the command following the conditional test if the value of the argument is equal to the value of the variable. An vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_ifequal "(<X Y Z>)"|<vector_variable> <command>

Notes & examples
 
This command must be used with a vector variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a number, text string, number variable or a string variable as the argument for this command.


vector_ifnotequal  
 
Function
 
Vector variable conditional test. This will execute the command following the conditional test if the value of the argument is not equal to the value of the variable. An vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_ifnotequal "(<X Y Z>)"|<vector_variable> <command>

Notes & examples
 
This command must be used with a vector variable that already exists.

Note: As with all variable conditional test commands, <command> can be be any valid SinScript command. Do not use a number, text string, number variable or a string variable as the argument for this command.


vector_length  
 
Function
 
Vector variable operator. This calculates the length of the vector or vector variable specified after the operator and stores the resulting number in <variable_name>. Vectors or existing vector variables must be used as the arguments.

Syntax
 
<variable_name> vector_length "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value calculated by the operation. Note that here, <variable_name> will be a number variable because of the nature of the operation.

Note:
Do not use numbers, text strings, number variables or string variables as the argument for this command.



vector_normalize  
 
Function
 
Vector variable operator. This automatically scales the size of the vector <variable_name> so it will have a length of 1.

Syntax
 
<variable_name> vector_normalize

Notes & examples
 
This command must be used with a vector variable that already exists.


vector_scale  
 
Function
 
Vector variable operator. This scales a vector variable by the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> vector_scale <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a vector variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will invariably be "(0 0 0)" but this is not the proper way to use this command.

Note:
Do not use a text string, vector, string variable or a vector variable as the argument for this command.



vector_setx  
 
Function
 
Vector variable operator. This sets the X component of a vector variable to the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> vector_setx <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a vector variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will be "(X_value 0 0)" but this is not the proper way to use this command.

Note:
Do not use a text string, vector, string variable or a vector variable as the argument for this command.



vector_sety  
 
Function
 
Vector variable operator. This sets the Y component of a vector variable to the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> vector_sety <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a vector variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will be "(0 Y_value 0)" but this is not the proper way to use this command.

Note:
Do not use a text string, vector, string variable or a vector variable as the argument for this command.



vector_setz  
 
Function
 
Vector variable operator. This sets the Z component of a vector variable to the value specified after the operator. An integer, floating point number or an existing number variable must be used as the argument.

Syntax
 
<variable_name> vector_setz <integer>|<floating_point>|<number_variable>

Notes & examples
 
This command is meant to be used with a vector variable that already exists. If you use this command with a <variable_name> that doesn't exist yet, the result will be "(0 0 Z_value)" but this is not the proper way to use this command.

Note:
Do not use a text string, vector, string variable or a vector variable as the argument for this command.



vector_subtract  
 
Function
 
Vector variable operator. This decrements a vector variable by the value specified after the operator. A vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_subtract "(<X Y Z>)"|<vector_variable>

Notes & examples
 
This command is meant to be used with a vector variable that already exists. Although the command will create and set <variable_name> to the value specified in the command argument if it doesn't exist yet (the sign will be inverted however), this is not the proper way to use this command.

Note:
Do not use a number, text string, number variable or string variable as the argument for this command.



vector_x  
 
Function
 
Vector variable operator. This reads the X component of the vector or vector variable specified after the operator and stores the number in <variable_name>. A vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_x "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value fetched by the operation. Note that here, <variable_name> will be a number variable because of the nature of the operation.

Note:
Do not use numbers, text strings, number variables or string variables as the argument for this command.



vector_y  
 
Function
 
Vector variable operator. This reads the Y component of the vector or vector variable specified after the operator and stores the number in <variable_name>. A vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_y "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value fetched by the operation. Note that here, <variable_name> will be a number variable because of the nature of the operation.

Note:
Do not use numbers, text strings, number variables or string variables as the argument for this command.



vector_z  
 
Function
 
Vector variable operator. This reads the Z component of the vector or vector variable specified after the operator and stores the number in <variable_name>. A vector or an existing vector variable must be used as the argument.

Syntax
 
<variable_name> vector_z "(<X Y Z>)"|<vector_variable>

Notes & examples
 
If the <variable_name> doesn't exist, this command will automatically create it and assign a value to it. If the <variable_name> already exists, the operator will simply change its current value to the new value fetched by the operation. Note that here, <variable_name> will be a number variable because of the nature of the operation.

Note:
Do not use numbers, text strings, number variables or string variables as the argument for this command.