SCM language

This section deals with the native SCM syntax of GTA 3 series, nothing other than III, VC, SA, LCS and VCS.
It may contain non-standard SCM definitions as R* hasn't published enough documentation about it yet.

On the occasion of the GTAIII's tenth anniversary, after a long period of darkness where we fell about the real SCM syntax, R* finally treated us by attaching part of its own original source code into the GTAIII Anniversary game, available for iOS and Android devices. As far back as 2001, a snip of some debugging scripts has been already provided with main.sc and debug.sc files. However, many secrets are unrevealed yet, thus some things cannot be documented fully and so they can be only guessed. The SCM format abbreviation is one of countless proofs of this inconvenience, which may stand for Script Control Merged. Other doubts come with source files, whose SC extension appears to be very close to Script Control. At first, someone could have asked oneself how R* named its own programming language: R#? R-Sharp? Rockstar Sharp? Who knows. We simply call it SCM language due to the lack of information. Nevertheless, the SCR language name is cropping up gradually.

Preliminary remarks

---

This article makes use of formatted codes to improve the reading comprehension. Note that:

• Square brackets mean everything inside may be omitted.
• Curly brackets denote the presence of useful codes but not necessarily needed.
• Vertical bars divide what can be chosen alternatively.
  
  

Fundamentals

Comments

A comment is an additional text that may be helpful for the code writer or other users, in short for the reader. It is the only part of the source code which gets always ignored when compiling.

Inline

An inline comment, denoted by // (two slashes), makes everything that follows some plain text:

[...] // Some inline comment

Multiline

A multiline comment embraces a particular area of the source code, starting by the opening tag /* (slash and asterisk) and ending with */ (asterisk and slash):

[...]
/*
 * Some multiline comment
 * ...
 */
[...]

Currently, more than one multiline comment is allowed per line:

[...] /* Some inline comment */ [...] /* Some inline comment */ [...]

Limit

Multiline comments cannot be nested.

Brackets

Brackets play an important role, especially when organizing multiple scripts in a single file becomes necessary.

Curly brackets

Curly brackets (or multiline brackets) act like a local variable scope. Essentially, they enclose the code where local variables are used, including timers. They can be opened and closed many times in a script:

{
    [...]
}

Round brackets

Actually, the round brakets (or multi inline brackets) behaviour sounds trivial, that's to say they simply highlight one or more arguments per command, individually or together. In , they appear to be used only for SETUP_ZONE_PED_INFO (in a various order) and GXT keys:

SETUP_ZONE_PED_INFO FISHFAC DAY (0) 0 0 0 (0 0 0 0) 0
PRINT_BIG (T4X4_1) 5000 2

They might lock up null values.

Labels

A label is a sequence of characters which identifiy a location of the source code useful for jumps. It can be accessed by any part of the source code. To define a label just append : (colon) to its name:

[...]

{lblname}:

[...]

At the compiling time, they are automatically converted into an offset.

Variables

A variable is a storage location assigned to a symbolic name which contains a value of any type.

Scope

---

The usage of a variable depends on the scope, that is the context where a specific variable is declared. At this point, we can distinguish the global and local scope.

Global

The global scope grasps the whole source code. Variables defined as globals are visible in any script. They are declared by appending the VAR prefix.

Local

---

The local scope wraps a localized part of the source code. Variables defined as locals are visible only in the code enclosed by curly brackets. They are declared by appending the LVAR prefix.

Timers

A timer is a singular local variable whose value rises automatically. It starts incrementing since the beginning of the script where it has been placed and grows endlessly. There are 2 usable timers which are already defined as TIMERA and TIMERB, therefore they do not need to be declared.

Types

---

Among the available types, some are equivalent to the most known programming types. Their length is up to 4, 8 and 16 bytes. Each type is appended as a suffix in the variable declaration.

INT

The INT type handles 32-bit signed integer values. It is also used to store values with less bytes, such as a bool, a char and a short int.

FLOAT

The FLOAT type handles 32-bit floating-point values. As it normally does, decimal precision is usually stuck to 6 digits beyond which it may get lost.

CONST

CONST is a special type that handles 32-bit signed integer values. It is used only to compare constants of model identifiers, task statuses, ped events and such. It mightn't be used directly but divided into other subordinal types. At the moment, it is merely a suggestion because constants are processed in bulk apparently instead of file by file.

Limit

CONST variables are supported since .

STRING

The STRING type handles 8-byte strings. Generally, a string is an array of 1-byte characters. It often requires 7 characters plus the null-terminator (a blank byte meaning the end of the string). It is used to hold GXT keys (those of town zones, interiors, help textes or dialogue subtitles) or script names.

Limit

STRING variables are supported in and .

NAME

The NAME type handles 16-byte strings. Like the previous type, it often holds 15 characters plus the null-terminator. It is used to store model and texture names of player clothes or animation names. It may be a ghost type as R*'s compiler might choose between the two string types automatically according to the length of the string itself.

Limit

It is supported in .

Declaration

---

Defining a variable means assigning a token string to a memory cell at the compiling time. Variables must be declared in the following manner:

{varscope}_{vartype} {varname0}[,] [... {varnameN}]

As mentioned in the sections above, local variables have to be put within curly brackets:

{
    {varscope}_{vartype} {varname0}[,] [... {varnameN}]

    [...]
}

Inline variable declaration is allowed, you just have to separate them by spaces or tabulations. Adding a preceding comma before these characters is optional.

Limit

Whereas the variable buffer is limited, you can declare a certain amount of globals and locals. Numerical (INT, FLOAT) and special (CONST) types take 1 variable, while string types (STRING, NAME) occupy respectively 2 and 4 variables to store some data (have a look here for further details).

Arrays

A array is a collection of variables having the same type which can be accessed by an index, an integer value enclosed by square brackets:

{varscope}_{vartype} {varname0}{[arrsize0]}[,] [... {varnameN}{[arrsizeN]}]

Limit

It is supported since .

Operators

In general, an operator is a token string that represents a math calculation or an operation of any other kind, in order to make the code understanding clearer at a glance.

Arithmetic

Arithmetic operators compute some of the most common algebric calculations between either a variable and a value or two variables. As well as in some programming language happens, string (STRING, NAME) and special (CONST) types are free from these operators, except for the basic assigment (see also Operators composition):

Operator	Name		Syntax	Description
=	Assignment		expr0 = expr1	Store expr1 to expr0
+	Addition		expr0 + expr1	Add expr1 to expr0
-	Subtraction		expr0 - expr1	Subtract expr1 to expr0
*	Multiplication		expr0 * expr1	Multiply expr0 by expr1
/	Division		expr0 / expr1	Divide expr0 by expr1
++	Increment	Pre[*]	++ expr0	Increment expr0 by 1 and store the result to expr0
		Post	expr0 ++
--	Decrement	Pre[*]	-- expr0	Decrement expr0 by 1 and store the result to expr0
		Post	expr0 --

Note

^ Pre and post increments have no difference unlike what you would expect.

Yet, you can put the assignment and algebric operators together inline as follows:

Operators	Name	Syntax	Description
= +	Addition and assignment	expr0 = expr1[*] + expr2	Add expr2 to expr1 and store the result to expr0
= -	Subtraction and assignment	expr0 = expr1[*] - expr2	Subtract expr2 to expr1 and store the result to expr0
= *	Multiplication and assignment	expr0 = expr1[*] * expr2	Multiply expr1 by expr2 and store the result to expr0
= /	Division and assignment	expr0 = expr1[*] / expr2	Divide expr1 by expr2 and store the result to expr0

Note

^ expr1 can represent expr0 too.

Limit

Multiple algebric operators per line are not allowed.

Compound assignment

Compound assignment operators store values or variable's content to other variables having a particular type afterwards the computation of an arithmetic operation, to squeeze the code and clear it up from granted repetitions:

Operator	Name	Syntax	Description
+=	Addition assignment	expr0 += expr1	Add expr1 to expr0 and store the result to expr0
-=	Subtraction assignment	expr0 -= expr1	Subtract expr1 to expr0 and store the result to expr0
*=	Multiplication assignment	expr0 *= expr1	Multiply expr0 by expr1 and store the result to expr0
/=	Division assignment	expr0 /= expr1	Divide expr0 by expr1 and store the result to expr0

Uncompounded assignment

Uncompounded assignment operators are those on their own, or rather they are neither derivable nor decomposable similarly as those compounds:

Operator	Name	Syntax	Description
=+	Time step addition assignment	expr0 =+ expr1	Multiply expr1 by time step, add the result to expr0 and store everything to expr0
=-	Time step subtraction assignment	expr0 =- expr1	Multiply expr1 by time step, subtract the result to expr0 and store everything to expr0
=#	Conversion assignment	expr0 =# expr1	Convert expr1 to any other type and store the result to expr0

Limit

Supported conversions are FLOAT to INT and INT to FLOAT.

Logical

Logical operators influence the way conditions are evalueted and enable to test more of them at a time. More than anything, they are built-in statements:

Operators	Name	Syntax	Description
NOT	Logical negation	IF NOT condition0	Test if condition0 is false
AND	Logical conjunction	IF condition0 AND condition8	Test if both condition0 and conditionN are true
OR	Logical disjunction	IF condition0 OR condition8	Test if either condition0 or conditionN is true

Comparison

Comparison operators test the truth or falsity of the relation between either a variable and a value, a value and a variable or two variables:

Operator	Name	Syntax	Description
=	Equal to	IF expr0 = expr1	Test if expr0 and expr1 are equal
>	Greater than	IF expr0 > expr1	Test if expr0 is greater than expr1
<	Lesser than	IF expr0 < expr1	Test if expr0 is lesser than expr1
>=	Greater than or equal to	IF expr0 >= expr1	Test if expr0 is greater than or equal to expr1
<=	Lesser than or equal to	IF expr0 <= expr1	Test if expr0 is lesser than or equal to expr1

Theorically, string types (STRING, NAME) should be compared with the first operator only, but the presence of COMPARE_STRING increase the doubts concerning the existence of such operator for strings.

Commands

A command is a symbolic name associated to an opcode which executes a portion of code that specifies the operation to be performed by passing zero or more arguments. Opcodes do not return values that can be assigned to a variable, even though the boolean flag is kept whenever they are used as conditions. It follows the common programming syntax adopted for procedure or function calls:

{commandname} [{anyvalue0|varname0} ... {anyvalueN|varnameN}]

Built-in

Built-in commands are those which are associated to more opcodes that differ each other by argument types or actions:

• :
  • OPERATORS
  • ABSI
  • ABSF
• :
  • COMPARE_STRING
  • SAVE_STRING_TO_DEBUG_FILE
  • IS_BIT_SET
  • SET_BIT
  • CLEAR_BIT
  • IS_STRING_NULL
  • STRING_STRING
• :
  • CALL_FUNCTION

This section is incomplete. You can help by fixing and expanding it.

WAIT

A WAIT skips the execution of a script according to some milliseconds after which it will resume again. Indeed, it is absolutely necessary into infinite loops or those that break after more than one frame, such as the WHILE statement. In this case, a value equal to 0 is passed.

GOTO

A GOTO is the jump to the label of any location of the source code. It is also used internally to build other statements or singularly but then it mustn't point off the current context:

jump0:
GOTO jumpN

[...]

jumpN:
GOTO jump0

Constants

A constant is a symbolic name associated to a specific value. When compiling, their caption is converted in the assigned value. They are listed into TXT files, whose name follows the Pascal Notation which implyies that all first letters of the words are in uppercase and other characters are lowercase (eg. AudioEvents.txt). These files respect the syntax below:

{constname0} {constvalue0}

{constnameN} {constvalueN}

Constant names and values are divided by as many spaces or tabulations as you want. Constant lines are distinguished by two \n (new line) characters. The model names which aren't assigned to a constant are still valid (see also Identifiers).

Others

The arguments of some commands accept only constant values of a single namespace. Instead, the CONST type can hold every constant of any namespace.

This section is incomplete. You can help by fixing and expanding it.

Formatting

Everything is case-insensitive, that means the uppercase and lowercase letters are computed as the same character. Usually, the source code is formatted as shown in this table:

Entity	Uppercase	Lowercase
Label		X
Declaration	X
Variable		X
Command	X
Constant	X
Statement	X

Compiling

Structure

The source code is split up into several SC files which comprehend main, gosubs, scripts, missions, streams and functions.

Main

---

Main is the most significant part of the whole source. It consists of a single file that can include many script files through LAUNCH_* and START_* commands. It is characterized by the absence of the local scope.

Gosubs

---

A gosub is the jump to the label of a subroutine, which executes some code and returns back to the place where it was called with RETURN.

Embedded

---

Embedded gosubs are those enclosed into a script file. They allow the use of the local scope for timers but they cannot declare local variables. Actually, they can inherit the local scope of the parent script but then they cannot be called by any other script.

Trigger

GOSUB gosub

Code

gosub:
{
    [...]
}
RETURN

File

---

File gosubs are those included into a script file singularly. LAUNCH_GOSUB jumps to the desired gosub defined into the input file that can call other embedded gosubs or scripts.

Trigger

LAUNCH_GOSUB gosub0 gosub.sc

Code

// File: gosub.sc

:gosub0
{
    [LVAR_{vartype} {varname0}[,] [... {varnameN}]]

    GOSUB gosubN

    [...]
}
RETURN

gosubN:
{
    [...]
}
RETURN

Limit

File gosubs were introduced since . They were unused in and got removed in , but then they were reimplemented in and .

Scripts

---

A script is a code block which takes part of a queue of other scripts. As long as it isn't terminated with TERMINATE_THIS_SCRIPT or TERMINATE_ALL_SCRIPTS_WITH_THIS_NAME (elsewhere in another script), its execution never expires till the end of the game process. Each one works independently, even though they are able to share global variables.

Embedded

---

Embedded scripts are those started by SC files where their body is included into. Note START_NEW_SCRIPT has an undefined amount of arguments which match with each local variable of the starting script.

Trigger

START_NEW_SCRIPT script [{anyvalue0|varname0} ... {anyvalueN|varnameN}]

Code

script:
SCRIPT_NAME script

script_loop:
{
    [LVAR_{vartype} {varname0}[,] [... {varnameN}]]

    [...]
}
//GOTO script_loop
TERMINATE_THIS_SCRIPT

File

---

File scripts are those which enclose none or more embedded scripts other than their main script. The MISSION opening and closing commands let us supposing scripts that own a SC file are computed as missions. MISSION_START is a special directive which doesn't get compiled, whereas MISSION_END is an alias of TERMINATE_THIS_SCRIPT. Yet, you can also start the scripts embedded in other files.

Trigger

START_TEST_SCRIPT script.sc

Code

// File: script.sc

MISSION_START

[VAR_{vartype} {varname0}[,] [... {varnameN}]]

SCRIPT_NAME main

main_loop:
{
    [LVAR_{vartype} {varname0}[,] [... {varnameN}]]

    START_NEW_SCRIPT script [{anyvalue0|varname0} ... {anyvalueN|varnameN}]

    [...]
}
//GOTO main_loop
MISSION_END

script:
SCRIPT_NAME script

script_loop:
{
    [LVAR_{vartype} {varname0}[,] [... {varnameN}]]

    [...]
}
//GOTO script_loop
TERMINATE_THIS_SCRIPT

Missions

---

A mission is a script which takes part of the mission block. When it is launched, the pointer is moved to the corresponding mission offset located somewhere in the mission block. Do not forget to begin a mission with MISSION_START (ghost command) and stop its execution with MISSION_END. Although missions are script files, you are able to start embedded scripts, whether they are put in the current file or not.

Trigger

LAUNCH_MISSION mission.sc

Code

// File: mission.sc

MISSION_START

GOSUB mission_start

IF HAS_DEATHARREST_BEEN_EXECUTED
    GOSUB mission_failed
ENDIF

GOSUB mission_cleanup

MISSION_END

[VAR_{vartype} {varname0}[,] [... {varnameN}]]

mission_start:

REGISTER_MISSION_GIVEN
SCRIPT_NAME mission

// Variables initialization

{
    [LVAR_{vartype} {varname0}[,] [... {varnameN}]]

    [...]
}
GOTO mission_passed

mission_failed:
[...]
RETURN

mission_passed:
REGISTER_MISSION_PASSED mission
//PLAYER_MADE_PROGRESS 1
[...]
RETURN

mission_cleanup:
// Mark everything as no longer needed
[...]
RETURN

Streams

---

This section is incomplete. You can help by fixing and expanding it.

Functions

---

This section is incomplete. You can help by fixing and expanding it.

Statements

As usual, the evolution of something implies its development over the years. Alongside, the statements implementation has been distributed equally into every chapter. Their definitions are similar to those used in pseudocodes resulting in a raw source code.

IF

IF is one of the most widespread conditional statements which executes some codes by evaluating a boolean flag, also known as a condition. According to the returning value, either the consequence or the alternative will be performed. The condition result can be inverted by appending the NOT logical operator before. More conditions require the use of the remaining logical operators, they are AND, when verifying if all checks are true, and OR, while testing if one of all checks is true. The syntax below summarize the whole explanation:

IF [NOT] {condition0}
[AND|OR [NOT] {condition8}]
    {consequence}
[ELSE
    {alternative}]
ENDIF

Limit

More than 9 conditions per statement are't supported.

WHILE

Alike the IF construct, WHILE is a conditional statement. The only difference consists in how it performs the consequence, that is it loops every line of code built into if the boolean flag is true:

WHILE [NOT] {condition0}
[AND|OR [NOT] {condition8}]
    {consequence}
ENDWHILE

DO-WHILE

DO-WHILE is a variation of the WHILE statement as already stated. It performs the consequence until the boolean flag becomes false. As opposed to its closest relative, the evaluation of the boolean flag happens after the execution of the consequence. Do not mix it with the DO-LOOP construct (not implemented by R*):

DO
    {consequence}
WHILE [NOT] {condition0}
[AND|OR [NOT] {condition8}]

Limits

It is supported since .

FOR

Similar to the WHILE construct, FOR iterates some code depending on an incremental variable which goes through the given range, whose ending value must be subsequent to its beginning:

FOR {varname} FROM {value0} TO {valueN}
    {consequence}
ENDFOR

Limits

It is supported since .

The range accepts only integer values.

Values must be subsequent.

The code will be read at least once in any case.

CASE

Basically, CASE is a group of concatenated IF statements. When a condition is false the next case gets performed, otherwise the consequence is executed and the code jumps to the end of the construct. If none of the cases is true, an ELSE clause may be carried out:

CASE {varname}
    WHEN {value0}
        {consequence}
    [WHEN {valueN}
        {consequence}]
    [ELSE
        {alternative}]
ENDCASE

Limits

It is supported since .

The WHEN clause allows the use of integer values only.

In , values must be sorted.

Multiple cases per consequence aren't allowed.

Decompiling

Structure

For further information about the SCM file format, read this article. Take into account the compiling order of each SC file is main-gosubs-scripts-missions apart from the reading order of the commands used to include them. streams are compiled individually into the script.img file. On the other hand, functions are compiled like embedded gosubs.

Identifiers

Undefined constants of model identifiers, whose name refers to a DFF which is presumably archived into any of the IMGs, loaded by the game, are overwritten by a decrementing value in the order they get compiled. These model names are then put into the second segment of the SCM header. Those of missions and streams respect the same rule except the fact they are turned into a 0-based growing identifier.

Offsets

An offset is a 32-bit signed integer value which points to a location of the source code. Those within main, gosub and script files are absolute offsets that start from the beginning of the main script, while the ones inside mission and stream files are relative offsets starting from their beginning. The offset is related to global variables aswell, whose interval goes from 8 and ends to FFFC, each one is aligned to the nearest 4 bytes.

Variables

The following table shows the variables range of the local scope for each game version:

Scope
Gosub	0-15	0-15	n/a	0-95	0-95
Script	0-15	0-15	0-31	0-95	0-95
Mission[*]	0-15	0-15	0-1023	0-95	0-95
Stream	n/a	n/a	0-31	n/a	n/a
Function	n/a	n/a	n/a	0-95	0-95
Timer	16-17	16-17	32-33	10-11?	254-255

Note

^ Although the mission block is allocated as an unique script, locals point to the same storage location, therefore they are some kind of globals for missions uniquely.

Operators composition

As far as you wouldn't know, SCM's operators always take two operands to compute an operation. Their composition is listed below:

Operator/s	Name		Syntax	Composition
++	Increment	Pre	++ expr0	expr0 += 1
		Post	expr0 ++
--	Decrement	Pre	-- expr0	expr0 -= 1
		Post	expr0 --
= +	Addition and assignment		expr0 = expr1 + expr2	expr0 = expr1 expr0 += expr2
= -	Subtraction and assignment		expr0 = expr1 - expr2	expr0 = expr1 expr0 -= expr2
= *	Multiplication and assignment		expr0 = expr1 * expr2	expr0 = expr1 expr0 *= expr2
= /	Division and assignment		expr0 = expr1 / expr2	expr0 = expr1 expr0 /= expr2

Opcodes

An opcode is a 16-bit unsigned integer value referring to a portion of code the game executes when it is called by passing an undefined or absent amount of arguments. The maximum number of available opcodes is 0x7FFF, since the last bit (0x8000) is set whenever they are used as negative conditions (those with the NOT logical operator).

Arguments

An argument is some data given as input to an opcode. Normally, opcodes have a defined amount of arguments up to 32. Those not, such as START_NEW_SCRIPT, can pass as many arguments as the available local variables are, except timers. This limitation is game specific.

Internal

Here is the list of all commands handled arbitrarily by a hypothetical compiler:

Acronym	Description	Acronym	Description	Acronym	Description	Acronym	Description	Acronym	Description
IV	INT value	FV	FLOAT value	CV	CONST value	SV	STRING value	NV	NAME value
GI	Global INT	GF	Global FLOAT	GC	Global CONST	GS	Global STRING	GN	Global NAME
LI	Local INT	LF	Local FLOAT	LC	Local CONST	LS	Local STRING	LN	Local NAME

Command or Operator		Opcode	Args count	Arguments
				1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19	20	21	22	23	24	25	26	27	28	29	30	31	32
MISSION_START[*]			0
GOTO[*]		0002	1	IV
MOVI[*]	VN	0004	2	GI	IV
		0006		LI	IV
	VV	0084		GI	GI
		0085		LI	LI
		008A		GI	LI
		008B		LI	GI
MOVF[*]	VN	0005	2	GF	FV
		0007		LF	FV
	VV	0086		GF	GF
		0087		LF	LF
		0088		GF	LF
		0089		LF	GF
ADDI[*]	VN	0008	2	GI	IV
		000A		LI	IV
	VV	0058		GI	GI
		005A		LI	LI
		005C		LI	GI
		005E		GI	LI
ADDF[*]	VN	0009	2	GF	FV
		000B		LF	FV
	VV	0059		GF	GF
		005B		LF	LF
		005D		LF	GF
		005F		GF	LF
SUBI[*]	VN	000C	2	GI	IV
		000E		LI	IV
	VV	0060		GI	GI
		0062		LI	LI
		0064		LI	GI
		0066		GI	LI
SUBF[*]	VN	000D	2	GF	FV
		000F		LF	FV
	VV	0061		GF	GF
		0063		LF	LF
		0065		LF	GF
		0067		GF	LF
MULI[*]	VN	0010	2	GI	IV
		0012		LI	IV
	VV	0068		GI	GI
		006A		LI	LI
		006C		GI	LI
		006E		LI	GI
MULF[*]	VN	0011	2	GF	FV
		0013		LF	FV
	VV	0069		GF	GF
		006B		LF	LF
		006D		GF	LF
		006F		LF	GF
DIVI[*]	VN	0014	2	GI	IV
		0016		LI	IV
	VV	0070		GI	GI
		0072		LI	LI
		0074		GI	LI
		0076		LI	GI
DIVF[*]	VN	0015	2	GF	FV
		0017		LF	FV
	VV	0071		GF	GF
		0073		LF	LF
		0075		GF	LF
		0077		LF	GF
CMPGI[*]	VN	0018	2	GI	IV
		0019		LI	IV
	NV	001A		IV	GI
		001B		IV	LI
	VV	001C		GI	GI
		001D		LI	LI
		001E		GI	LI
		001F		LI	GI
CMPGF[*]	VN	0020	2	GF	FV
		0021		LF	FV
	NV	0022		FV	GF
		0023		FV	LF
	VV	0024		GF	GF
		0025		LF	LF
		0026		GF	LF
		0027		LF	GF
CMPGEI[*]	VN	0028	2	GI	IV
		0029		LI	IV
	NV	002A		IV	GI
		002B		IV	LI
	VV	002C		GI	GI
		002D		LI	LI
		002E		GI	LI
		002F		LI	GI
CMPGEF[*]	VN	0030	2	GF	FV
		0031		LF	FV
	NV	0032		FV	GF
		0033		FV	LF
	VV	0034		GF	GF
		0035		LF	LF
		0036		GF	LF
		0037		LF	GF
CMPEI[*]	VN	0038	2	GI	IV
		0039		LI	IV
	VV	003A		GI	GI
		003B		LI	LI
		003C		GI	LI
CMPEF[*]	VN	0042	2	GF	FV
		0043		LF	FV
	VV	0044		GF	GF
		0045		LF	LF
		0046		GF	LF
ADDTSF[*]	VN	0078	2	GF	FV
		0079		LF	FV
	VV	007A		GF	GF
		007B		LF	LF
		007C		LF	GF
		007D		GF	LF
SUBTSF[*]	VN	007E	2	GF	FV
		007F		LF	FV
	VV	0080		GF	GF
		0081		LF	LF
		0082		LF	GF
		0083		GF	LF
CVFI[*]	VV	008C	2	GI	GF
		008E		LI	GF
		0090		GI	LF
		0092		LI	LF
CVIF[*]	VV	008D	2	GF	GI
		008F		LF	GI
		0091		GF	LI
		0093		LF	LI
ABSI		0094	1	GI
		0095		LI
ABSF		0096	1	GF
		0097		LF
GOTO_IF_FALSE[*]		004D	1	IV
TERMINATE_THIS_SCRIPT		004E	0
MISSION_END
START_NEW_SCRIPT[*]		004F	1	IV	_ _ _
GOSUB		0050	1	IV
RETURN		0051	0
COMPARING_RULE[*]		00D6	1	IV
START_TEST_SCRIPT[*]		00D7	1	IV
LAUNCH_MISSION		0417	1	IV
GOTO_IF_TRUE[*]		004C	1	IV
RETURN_TRUE[*]		00C5	0
RETURN_FALSE[*]		00C6	0
LAUNCH_GOSUB[*]		02CD	2	IV	IV
MOVC[*]	VN	04AE	2	GC	CV
		04AF		LC	CV
CMPGC[*]	VN	04B0	2	GC	CV
		04B1		LC	CV
	NV	04B2		CV	GC
		04B3		CV	LC
CMPGEC[*]	VN	04B4	2	GC	CV
		04B5		LC	CV
	NV	04B6		CV	GV
		04B7		CV	LC
CMPEC[*]	VN	04A3	2	GC	CV
		04A4		LC	CV
MOVS[*]	VN	05A9	2	GS	SV
		05AA		LS	SV
	VV	05A9		GS	GS
		05AA		LS	LS
		05A9		GS	LS
		05AA		LS	GS
MOVN[*]	VN	06D1	2	GN	NV
		06D2		LN	NV
	VV	06D1		GN	GN
		06D2		LN	LN
		06D1		GN	LN
		06D2		LN	GN
CMPES[*] COMPARE_STRING	VN	05AD	2	GS	SV
		05AE		LS	SV
	VV	05AD		GS	GS
		05AE		LS	LS
		05AD		GS	LS
		05AE		LS	GS
CMPEN[*] COMPARE_STRING	VN	08F9	2	GN	NV
		08FA		LN	NV
	VV	08F9		GN	GN
		08FA		LN	LN
		08F9		GN	LN
		08FA		LN	GN
CMPEI[*]	VV	07D6	2	LI	GI
CMPEF[*]	VV	07D7	2	LF	GF
SAVE_STRING_TO_DEBUG_FILE[*][*]		05B6	0
IS_STRING_NULL		0844	1	GS
		0845		LS
		0846		GN
		0847		LN
INIT_TABLE_OF_GOTO[*]		0871	18	GI	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV
				LI	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV
APPEND_GOTO_TO_TABLE[*]		0872	18	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV	IV
IS_BIT_SET	VN	08B4	2	GI	IV
		08B7		LI	IV
	VV	08B5		GI	GI
		08B6		GI	LI
		08B8		LI	GI
		08B9		LI	LI
SET_BIT	VN	08BA	2	GI	IV
		08BD		LI	IV
	VV	08BB		GI	GI
		08BC		GI	LI
		08BE		LI	GI
		08BF		LI	LI
CLEAR_BIT	VN	08C0	2	GI	IV
		08C3		LI	IV
	VV	08C1		GI	GI
		08C2		GI	LI
		08C4		LI	GI
		08C5		LI	LI
STRING_STRING		098B	3	GS	GS	GS
		098C		GN	GN	GN
MOVC[*]	VN	04B3	2	GC	CV
		04B4		LC	CV
CMPGC[*]	VN	04B5	2	GC	CV
		04B6		LC	CV
	NV	04B7	2	CV	GC
		04B8		CV	LC
CMPGEC[*]	VN	04B9	2	GC	CV
		04BA		LC	CV
	NV	04BB	2	CV	GV
		04BC		CV	LC
CMPEC[*]	VN	04A8	2	GC	CV
		04A9		LC	CV
COMPARING_RULE[*]		00DB	1	IV
START_TEST_SCRIPT[*]		00DC	1	IV
LAUNCH_GOSUB[*]		02D2	2	IV	IV
LAUNCH_MISSION		041C	1	IV
CALL_FUNCTION[*][*]		05AE	4	IV	IV	IV	IV	_ _ _
		05AF
MOVI[*]	VN	0004	2	GI	IV
				LI	IV
	VV	0035		GI	GI
				LI	LI
				GI	LI
				LI	GI
MOVF[*]	VN	0005	2	GF	FV
				LF	FV
	VV	0036		GF	GF
				LF	LF
				GF	LF
				LF	GF
MOVS[*]	VN	0006	2	GS	SV
				LS	SV
	VV	0037		GS	GS
				LS	LS
				GS	LS
				LS	GS
ADDI[*]	VN	0007	2	GI	IV
				LI	IV
	VV	0029		GI	GI
				LI	LI
				GI	LI
				LI	GI
ADDF[*]	VN	0008	2	GF	FV
				LF	FV
	VV	002A		GF	GF
				LF	LF
				GF	LF
				LF	GF
SUBI[*]	VN	0009	2	GI	IV
				LI	IV
	VV	002B		GI	GI
				LI	LI
				GI	LI
				LI	GI
SUBF[*]	VN	000A	2	GF	FV
				LF	FV
	VV	002C		GF	GF
				LF	LF
				GF	LF
				LF	GF
MULI[*]	VN	000B	2	GI	IV
				LI	IV
	VV	002D		GI	GI
				LI	LI
				GI	LI
				LI	GI
MULF[*]	VN	000C	2	GF	FV
				LF	FV
	VV	002E		GF	GF
				LF	LF
				GF	LF
				LF	GF
DIVI[*]	VN	000D	2	GI	IV
				LI	IV
	VV	002F		GI	GI
				LI	LI
				GI	LI
				LI	GI
DIVF[*]	VN	000E	2	GF	FV
				LF	FV
	VV	0030		GF	GF
				LF	LF
				GF	LF
				LF	GF
CVFI[*]	VV	0038	2	GI	GI
				LI	LI
				GI	LI
				LI	GI
CVIF[*]	VV	0039	2	GF	GF
				LF	LF
				GF	LF
				LF	GF
CMPGI[*]	VN	000F	2	GI	IV
				LI	IV
	NV	0010		IV	GI
				IV	LI
	VV	0011		GI	GI
				LI	LI
				GI	LI
				LI	GI
CMPGF[*]	VN	0012	2	GF	FV
				LF	FV
	NV	0013		FV	GF
				FV	LF
	VV	0014		GF	GF
				LF	LF
				GF	LF
				LF	GF
CMPGEI[*]	VN	0015	2	GI	IV
				LI	IV
	NV	0016		IV	GI
				IV	LI
	VV	0017		GI	GI
				LI	LI
				GI	LI
				LI	GI
CMPGEF[*]	VN	0018	2	GF	FV
				LF	FV
	NV	0019		FV	GF
				FV	LF
	NV	001A		GF	GF
				LF	LF
				GF	LF
				LF	GF
CMPEI[*]	VN	001B	2	GI	IV
				LI	IV
	VV	001C		GI	GI
				LI	LI
				GI	LI
				LI	GI
CMPEF[*]	VN	001D	2	GF	FV
				LF	FV
	VV	001E		GF	GF
				LF	LF
				GF	LF
				LF	GF
CMPES[*] COMPARE_STRING	VN	001F	2	GS	SV
				LS	SV
	VV	0020		GS	GS
				LS	LS
				GS	LS
				LS	GS
ADDTSF[*]	VN	0031	2	GF	FV
				LF	FV
	VV	0032		GF	GF
				LF	LF
				GF	LF
				LF	GF
SUBTSF[*]	VN	0033	2	GF	FV
				LF	FV
	VV	0034		GF	GF
				LF	LF
				GF	LF
				LF	GF
ABSI		003A	1	GI
				LI
ABSF		003B	1	GF
				LF
MOVC[*]	VN	02E2	2	GC	CV
				LC	CV
CMPGC[*]	VN	02E3	2	GC	CV
				LC	CV
	NV	02E4		CV	GC
				CV	LC
CMPGEC[*]	VN	02E5	2	GC	CV
				LC	CV
	NV	02E6		CV	GV
				CV	LC
CMPEC[*]	VN	02DB	2	GC	CV
				LC	CV
GOTO_IF_TRUE[*]		0021	1	IV
GOTO_IF_FALSE[*]		0022	1	IV
TERMINATE_THIS_SCRIPT		0023	0
MISSION_END
START_NEW_SCRIPT[*]		0024	1	IV	_ _ _
GOSUB		0025	1	IV
RETURN		0026	0
RETURN_TRUE[*]		005E	0
RETURN_FALSE[*]		005F	0
COMPARING_RULE[*]		0078	1	IV
START_TEST_SCRIPT[*]		0079	1	IV
LAUNCH_GOSUB[*]		01BA	2	IV	IV
LAUNCH_MISSION		0289	1	IV
CALL_FUNCTION[*][*]		037A	4	IV	IV	IV	IV	_ _ _
		037B

Notes

^ A special mission directive which is never compiled.

^ It is hidden when used to build statements.

^ It is never used cause it is explicitly transformed in an operator.

^ It is used only to build statements.

^ It has an undefined amount of arguments.

^ It is a likely definition of the standard command.

^ The command still accepts an argument which can admit up to 127 characters plus the null-terminator. In the compiling process, the argument is skipped but its string is copied to a predefined 128-bytes buffer, compiled afterwards. These are the predetermined bytes that seem to do nothing:

00 00 41 00 09 2E 00 00 00 00 00 00 00 00 00 00 
09 2E 00 00 00 00 00 00 1C FB 12 00 D8 A8 41 00
00 00 41 00 09 2E 00 00 00 00 00 00 01 00 00 00 
09 2E 00 00 00 00 00 00 1C FB 12 00 D8 A8 41 00
00 00 41 00 09 2E 00 00 00 00 00 00 02 00 00 00 
09 2E 00 00 00 00 00 00 1C FB 12 00 D8 A8 41 00
00 00 41 00 09 2E 00 00 00 00 00 00 03 00 00 00 
09 2E 00 00 00 00 00 00 1C FB 12 00 D8 A8 41 00

Dynamic values within a block are marked in grey, while those which differs among each block are coloured in blue.

^ Arguments vary when compiling.

This section is incomplete. You can help by fixing and expanding it.

Uncommon

Arguments of some commands keep uncommon values which look familiar after encoding:

Command	Arg ID	Syntax	Encoded
			Value	Type
GOTO	1	Any label	Offset	INT
GOTO_IF_FALSE	1	Any label	Offset	INT
GOSUB	1	Gosub label	Offset	INT
LAUNCH_GOSUB	1	Gosub label	0-based offset	INT
	2	Gosub file
START_NEW_SCRIPT	1	Script label	0-based offset	INT
START_TEST_SCRIPT	1	Script file	0-based offset	INT
LAUNCH_MISSION	1	Mission file	Mission ID	INT
GOTO_IF_TRUE	1	Any label	Offset	INT
CALL_FUNCTION	1	Function label	Function arguments	INT
	2		Returning arguments
	3		Parent script locals
	4		Offset
SAVE_STRING_TO_DEBUG_FILE	1	Literal string	128-byte immediate string	STRING

This section is incomplete. You can help by fixing and expanding it.

Comparing rule

The comparing rule can handle up to 9 checks per construct. 006D (, , ), 00DB () and 0078 ( indicate you are verifying a single check (0) or multiple checks with either AND (1 to 8) or OR (21 to 28) logical operators.

Analysis

As an overview of the compiled source, statements are literally nested meaning that the code is unoptimized. Furthermore, the jump of an embedded construct doesn't get merged with that of the construct itself, which consists of a benefit for the code parsing.

IF

As regards the IF statement, if the whole check is true the consequence is performed and the code jumps to the end of the construct, otherwise it skips to the alternative (see also Comparing rule):

Decompiled				Compiled
IF [NOT] {condition0} [AND|OR [NOT] {condition8}] {consequence} [ELSE {alternative}] ENDIF	{006D} {....} {....} {004D} {....} {0002} ---- {....} ----	{00DB} {....} {....} {004D} {....} {0002} ---- {....} ----	{0078} {....} {....} {0022} {....} {0002} ---- {....} ----	COMPARING_RULE {value} [NOT] {condition0} [[NOT] {condition8}] GOTO_IF_FALSE ELSE {consequence} [GOTO ENDIF ELSE: {alternative}] ENDIF:

WHILE

The WHILE statement is pretty much similar to the previous, even though when the consequence is read the code is moved to the beginning of the construct:

Decompiled				Compiled
WHILE [NOT] {condition0} [AND|OR [NOT] {condition8}] {consequence} ENDWHILE	---- {006D} {....} {....} {004D} {....} {0002} ----	---- {00DB} {....} {....} {004D} {....} {0002} ----	---- {0078} {....} {....} {0022} {....} {0002} ----	WHILE: COMPARING_RULE {value} [NOT] {condition0} [[NOT] {condition8}] GOTO_IF_FALSE ENDWHILE {consequence} GOTO WHILE ENDWHILE:

DO-WHILE

Not that much to say more than the preceding construct, the DO-WHILE statement is built nearly in the same way. In fact, the ELSE clause points to the end of the construct, the GOTO jumps to the its beginning, while the consequence is put before all conditions. Judging by its compiled code, it is the most certain definition that R* has originally used like the indisputable one of IF and WHILE constructs. However, a colliding issue with the WHILE statement can happen:

Decompiled				Compiled
DO {consequence} WHILE [NOT] {condition0} [AND|OR [NOT] {condition8}]	---- {....} {006D} {....} {....} {004D} {0002} ----	---- {....} {00DB} {....} {....} {004D} {0002} ----	---- {....} {0078} {....} {....} {0022} {0002} ----	DO: {consequence} COMPARING_RULE {value} [NOT] {condition0} [[NOT] {condition8}] GOTO_IF_FALSE WHILE GOTO DO WHILE:

FOR

Seemingly, the FOR statement is the first construct ever optimized as a result of a possible R*'s compiler fault. Moreover, it sounds ambiguous as it loops at least once. This was probably the intention of R*'s programmers, that is iterating at least once else the construct is useless. However, there are some chance they decide to use such structure to avoid some conflict with the WHILE or DO-WHILE construct:

Decompiled	G/L		G/L	Compiled
FOR {varname} FROM {value0} TO {valueN} {consequence} ENDFOR	{0004} ---- {....} {0008} {0028} {004D}	{0005} ---- {....} {0009} {0029} {004D}	{0004} ---- {....} {0007} {0015} {0022}	{varname} = {value0} LOOP: {consequence} ++ {varname} {varname} >= {valueN} GOTO_IF_FALSE LOOP

CASE

In , the CASE statement is more complex and efficient because the game uses internally a binary search algorithm to jump at the label that matches with the value of a particular case. This method requires a known amount of cases which is up to 75. When a case is true, a consequence is executed and the code jumps to the end of the construct, otherwise the alternative may be performed. As the code is unoptimized, the GOTO of the last case is still compiled even though its label points to the end of the jump itself:

Decompiled		Compiled
CASE {varname} WHEN {value0} {consequence} [WHEN {valueN} {consequence}] [ELSE {alternative}] ENDCASE	{0871} {0872} ---- {....} {0002} ---- {....} {0002} ---- {....} {0002} ----	{varname} {cases} {iselse} ELSE {value0} WHEN0 {valueN} WHENN -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE [-1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE -1 ENDCASE] WHEN0: {consequence} GOTO ENDCASE [WHENN: {consequence} GOTO ENDCASE] [ELSE: {alternative} GOTO ENDCASE] ENDCASE:

In and , such statement is a set of nested IF constructs which causes a very slight loss of performance by considering that 00DB () and 0078 ( aren't compiled:

Decompiled	G/L		G/L	Compiled
CASE {varname} WHEN {value0} {consequence} [WHEN {valueN} {consequence}] [ELSE {alternative}] ENDCASE	---- {0038} {004D} {....} {0002} ---- {0038} {004D} {....} {0002} ---- {....} ---- ----	---- {0039} {004D} {....} {0002} ---- {0039} {004D} {....} {0002} ---- {....} ---- ----	---- {001B} {0022} {....} {0002} ---- {001B} {0022} {....} {0002} ---- {....} ---- ----	WHEN0: {varname} = {value0} GOTO_IF_FALSE WHENN {consequence} [GOTO ENDCASE0 WHENN: {varname} = {valueN} GOTO_IF_FALSE ELSE {consequence} [GOTO ENDCASEN ELSE: {alternative}] ENDCASEN:] ENDCASE0:

Optimization

In and , whenever a single condition is checked 00DB () and 0078 () don't get compiled cause no logical operator (AND, OR) is used and so they become really useless. Its lack increase the script efficiency a lot. However, the jump of the ELSE clause of an IF statement which points to the end of the construct is still compiled after a GOTO. Furthermore, Stories Games come with an improved data type managing which causes a considerable decrease of the compiled file size.

External links

• SC source files (no main.sc)