SCM language

Test link (please, submit changes with "Show preview"): http://www.gtamodding.com/index.php?title=SCM_language&action=edit (login required)

This section deals with the native script language syntax of GTA 3 series, nothing other than III, VC, SA, LCS and VCS.
It may incorporate nonstandard specifications due to the fact R* hasn't published enough documentation about yet.

On the occasion of the Grand Theft Auto III's 10th Anniversary, after a long period of darkness where we fell about the real scripting language syntax, R* finally treated us (or was it, as it seems, a War Drum Studios sloppy oversight?) by attaching part of its own original source code into the mobile release, 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 that were allegedly meaningful for a sort of script version checker uncut on debug builds. Nonetheless, many secrets are still unrevealed, thus some things cannot be fully documented and so they can be merely guessed. The .scm format abbreviation is one of countless proofs of this inconvenience, which may stand for Script Multifile; .scc, in turn, might be the short form of Script Compiled though we would better predilige the Combinedfile wording. No doubt come with source files, whose .sc extension is the contraction of Mission Script. Although we have enough information to suppose the currently unknown mysteries of the used language, we still have no safe clue about what was its original denomination. Furthermore, it is a matter of fact that R* developers have been left untouched the miss2 executable filename of the third generation compiler since the chapter 2. In this connection, we could imagine the newer scripting language is a variant or an evolution of the GTA2script (sometimes referred to as GBHscript), which label expressly popped up in the ancient documentation by DMA Design Ltd (at present Rockstar North). Therefore, we are almost sure to say the language name is most likely GTA3script (as-is casing). However, it is definitely based on BASIC.

Fundamentals

Comments

Codes are usually self-explanatory for the author but large sources can compromise everyone's management capability, that means some annotation can save much time on the long-term particularly when being stuck trying to understand old stuff which should never happen in the first place, not to mention team mates would certainly blame the original writer on each revision and slow down the completion of cooperative projects. Sometimes, it is also required to temporarily/permanently disable code lines for testing purposes. Fortunately, the language supports the following typologies of comments:

• Single-line comment, prefixed with // (two forward slashes), which extends till the end of the line. Everything is ignored inside: // Some comment.;
• Multi-line comment, enclosed with a pair of /* (a slash plus an asterisk) and */ (the other way around), which covers a cricumscribed text area. Several blocks can be nested together: /* Some /* comment */ . */.

Delimiters

Conventionally, lines can be splitted into various regions in order to enhance the code legibility through bracket-delimited and/or comma-separated elements. As being pure white-spaces, the opening parenthesis delimiter doesn't necessarily need to match the closing counterpart and viceversa. The only tangible use of separators carried out in public sources is related to inline declaration of multiple variables, text keys of print-commands and SETUP_ZONE_PED_INFO but codes can be organized to one's liking. Here are some demonstrations:

VAR_INT joeys_buggy, swank_taxi
PRINT_NOW (ASUKA) 2000 1
SETUP_ZONE_PED_INFO CHINA DAY (30) 350 600 0 (0 0 0 0) 0

Labels, Text labels and Strings

Thanks to the beneficial code fragmentation, the source is subject to external file inclusions and variegated in-file unconditional branches involving embedded code blocks diversification. Both kinds of partitioning are accomplished respectively through the specification of:

• Filenames, that is special labels which somehow resemble legit pathnames, starting with any valid pathname character but not containing whitespaces. They are relative to the root path deriving from the .sc extension removal of the main script full path where files are searched in by default: X:\folder\main. Subfolders are scanned as well:
  • Till the first tree level if inside one of the subdirectories: X:\parent\main\child;
  • Till the second tree level if inside one of the parent directories: X:\parent or X:\parent\main;
  • Indefinitely (unlimited recursion till the maximum path length allowed).

The .sc extension at the end of filenames is mandatory else an argument mismatch is warned, by contrast the main script can have any extension to which m (multifile) or c (combinedfile) is appended in the target pathname. Due to a Cd image system limitation, all sorts of filename must be shorter than 20 characters and conventionally they must be free of extra dots for streamed scripts.

• Label references, that is unique string identifiers suffixed by a colon which identify a precise location within the common (main script, main extensions and subscripts) or the actual (mission scripts and streamed scripts) script space. Basically, they represent the target position of either goto-like, script starter or function caller commands: my_label_ref: (on a new line). Weirdly enough, label references may begin with any character alike filenames despite they are susceptible to the same restrictions of string identifiers whenever passed as arguments but must not exceed 38 characters, colon excluded, either way. Whereas these are not commands, anything else can follow next to and being inlined so long as a splitting character is inserted.

That said, labels are essentially user-supplied string identifiers whose existence is verified. Text label identifiers are not fully bound to this rule (except script names) since they are massively employed as main/mission text keys or whatever referring to an internal resource, which the game handles according to a well-defined associative scheme. Notoriously, identifiers length is anything but expensive for readability reasons, in addition they do not even offer the ability to insert white-spaces or other inadmissible characters owing to the by-design absence of delimiting tokens. <incorrect>At this matter, variable-length strings and debugging texts sent as 128-byte string literals are enclosed by " " (double quotes):

CUSTOM_PLATE_FOR_NEXT_CAR CAR_TAMPA "_FELTCH_"</incorrect>
SAVE_STRING_TO_DEBUG_FILE "CURRENT_WANTED_LIST = "

Empty text labels are impracticable, though NIL compiles a NUL-string in the last Stories chapter^{[no source]} – as reported by some indiscreet sources, the rearrangement of crucial commands signals a syntax enhancement the language has undergone which sees delimited strings superseding text labels, lowly probable because string constants are still disallowed for multi-type parameters; as previously assumed, instead, DUMMY could have been the placeholder keyword but a text key exists actually, while a single _ (underscore) is more Python-oriented (used as a throwaway variable). It's worth noting string literals and text labels are not interchangeable because of their syntactic differences even if they present semantic similarities, moreover text labels do not ever interfere with command names and string constants. A final quirk to note concerning labels as a whole is they are automatically converted to upper case: this obvious evidence proves identifiers and whatnot are all case insensitive with the exception that 128-byte strings are left as-is for remastered game builds.

Data types

Forasmuch as the language obeys the strong typing paradigm, the syntactic elements that denote a value during execution do have fixed data types, most of which are appended as a suffix at variable declaration. Their conspicuous assortment is listed below:

Name	Format	Size	Range	Game support	Variable support	Is basic
Single-typed
LABEL	String identifier (translated to offset/index)	4	-231 to 231-1	Since	None
INT	Signed integer				Since	✓
FLOAT	Q11.4 fixed-point	2	-211 to 211-2-4	only		✓
	IEEE-754 floating-point	4	±3.4×10±38	Since
TEXT_LABEL	UTF-8 null-terminated string identifier	8	1 to 7	Since	and	✓
TEXT_LABEL16		16	1 to 15	only	only	✓
TEXT_LABEL32	UTF-8 null-terminated string identifier (4 contiguous blocks)	32×4	1 to 127		None
Multi-typed
PARAM	Same as INT and FLOAT			Since
	Same as TEXT_LABEL			Since
STRING	UTF-8 string (non null-terminated)	1..127	1 to N-1	only	None
	Same as TEXT_LABEL/16 (variable-only)				only

Some tiny caveats about immediate numeric fields:

• String constants are compatible with integer parameters;
• Literals must begin with a number or - (minus sign) or rather . (decimal point, for float values);
• Integers allow only the decimal notation;
• Floats disallow scientific notation and such;
• Integral and fractional parts are singularly omissible;
• F or f suffix can be appended next to (quite unused/useless).

Immediates and Variables

Data can take the appearance of a few expressions varying from numeric, text label and string literals each of which occupies a certain area of storage with unfixed size. Immediates can also be preserved for later use and therefore reserve space over the private script memory corresponding to a variable. The strongly-typed language property imposes to explicitly declare variables anywhere in the current scope, namely the context inside which they are visible for usage. Sensibly, declarations should figure beforehand but likewise it is allowed for accessing backward declarations. Variables accessible from any location are marked as globals (starting from offset 8, occupying lots of space in the script multifile, up to 64 kibibytes) and their declaration is achieved by prepending the VAR prefix followed by one of the basic data types (multiple declarations of the same type can be inlined), both separated by an in-between underscore:

VAR_INT player scplayer
VAR_FLOAT x_float, y_float, z_float
VAR_TEXT_LABEL interior_name
VAR_TEXT_LABEL16 shop_item

Globals are capable of being selectively marked as saveable using the SAVE_VAR prefix, in order to restore their value on savegame loading and free generic variables. In Trilogy chapters, if enabled properly in a hacky manner, these are solely common variable declarations with no additional purpose, a plan not gone through. On the other hand, globals declared within the mission context are not visible outside in Stories chapters since they overlap the same space, making a discernment among true and al-most globals. However, there's no exact rule for variable naming apart they must begin with a letter and never end with a colon, just like text labels. It's preferable definitions shall not contain operator tokens to prevent any parsing ambiguity plus, most importantly, they must not conflict with string constants and local timers. Nevertheless, text labels and variable names semantics may collide: in this case, the formers have priority over the latters unless a preceding dollar sign) is added:

PRINT_BIG TEXTKEY 5000 2  // Compiles a text label literal.
PRINT_BIG $textkey 5000 2 // Compiles a text label variable.

Despite variables are freed and zero-initialized at runtime on new/load game or script allocation in broad terms, statistical information are still gathered whenever they are read before being written, besides if they are never read or never written (passing a variable as reference has no effect onto the content). Furthermore, if a variable is set to hold an entity handle (alias unique index) returned by a specific create-command it cannot be assigned to any other entity-command of different kind or none, including the forseeable assignment operations. This restriction propagates on script and function callings as well: starting/streaming the same script or calling the same function multiple times with variables of dissimilar entity types is forbidden if triggers are encountered prior the script or function local scope is fetched, in which case entities are explicitly initialized in the form of unreachable code:

{
    LVAR_INT test_char sanity

    sanity = 0
    IF sanity = -1
        CREATE_CHAR PEDTYPE_CIVMALE male01 0.0 0.0 0.0 test_char
    ENDIF
}

Local scope

Once a script is started/streamed or a subscript/mission is launched, a local variable space of 72 (16+2 × 4, III/Vice City), 136 (32+2 × 4, San Andreas) or 424 (96+8+2 × 4, Stories) bytes is also reserved. As opposed to global variables, locals have visibility only inside a particular region of the source code and are preceded by the LVAR prefix at declaration within an unnestable block embraced by curly brackets:

{
    LVAR_INT pickup message_num
}

Local names do not override global definitions, they must not collide together otherwise a warn is issued. In the last Trilogy chapter, locals are mainly static variables whose space (having a size of 4096 bytes, 1024×4) is shared among each mission thus they are reasonably more abundant in this context. Beyond user-defined locals, predefined TIMERA and TIMERB variables are provided: these timers measures the playing time milliseconds passed since the script beginning but they can be reset just fine. As deducible, any script file inclusion within a local scope does inherit no local variable even for the unassuming foreign gosub.

Arrays

Since the last Trilogy chapter, instead of declaring multiple scalar variables of same type, an unidimensional, numeric (unassociative) array can be defined. Each element is accessed through either a positive, zero-based^{[no source]}, 8-bit unsigned number or a variable index embraced by a pair of square brackets on assignment or argument passing. On declaration, the said brackets enclose the array size which mustn't be bigger than 255 units:

VAR_INT prop_assets[32]
CREATE_FORSALE_PROPERTY_PICKUP -1969.27 282.47 34.6 50000 PROP_3 prop_assets[0]

In sooth, one-based arrays were already supported in the second Trilogy chapter but they missed the intrinsic data type, giving no reference point on how to interpret the compiled operands, producing corrupted intermediate code because of fall-through reading. There is no precedent to safely assert that arrays became zero-based later on the language evolution but what is certain is this sort of indexing lines up immediate with variable indices. Oddly, as a result of the unidimensionality constraint implementation, a complementary yet nonfactual identifier can follow the closing bracket immediately afterwards with no redundancy notice (i.e. prop_assets[0]anything). Moreover, scalar variables have an implicit array size of one element which is needlessly accessible and plus the index part of the first element of an array is in turn omissible, everything notwithstanding the misleading declaration. Granted that brackets do not encompass any separator character, array indices reject string constants but admit local timers.

String constants

Very often, numeric literals express arbitrary values which are far from being self-documenting without descriptive labels belonging to a list of predefined names. These strings or enumerations are guaranteed to store an immutable constant and must forcibly pertain to the required namespace if passed as arguments unless, if and only if no namespace is set, the default constants TRUE/FALSE, ON/OFF, DAY/NIGHT or KILLFRENZY statuses are supplied:

CHANGE_BLIP_DISPLAY blip1_jm1 BLIP_ONLY
flag_car_blip_displayed_jm1 = TRUE

Assignments and comparisons do not suffer such a restriction and, what's more, in case of too long lines (wider than 255 characters) immediates can safely replace string constants to shorten the exceeding length and fall within the limits. During the development stage, the game's map experiences lots of continuous changes that make the management of objects, as a result of having a fixed indexing, pretty awkward without taking into account their bulk amount. In this respect, parameters expecting level objects are able to define the used objects (no more longer than 23 characters) under the hood, bringing them together in a sorted array whose criteria depends on the order of their appearance, something other than the default models which are hardcoded (for peds, cars, weapons, wheels, cutscene objects and the like). A blank, unavailable object is always reserved, shifting ahead each next negated position becoming one-based. Negative indices assure models fit in the used objects array, according to which the runtime matches the right index through a lookup table:

REQUEST_MODEL bridgefuka // First use ever. It compiles -1 from now on.
REQUEST_MODEL bridgefukb // First use again. This time it compiles -2.
LOAD_ALL_MODELS_NOW
CREATE_OBJECT_NO_OFFSET bridgefuka 715.746 -937.908 40.194 damagea
CREATE_OBJECT_NO_OFFSET bridgefukb 787.835 -939.24 38.971 damageb

The lack of error-checking requires a meticulous handwriting to avoid script deadlocks at runtime, the reason why both default models and level objects are loaded straight from IDE files for Vice City's remastered build. Nonetheless, iterating among several objects can be very expensive for a poorly optimised, rough compiler even on fast machines, not to mention namespaced constants are likely to collide without specializing prefixes (i.e. SNIPER camera mode and weapon name, formerly WEAPON_SNIPER), enough to revert back thereafter. Assignments and comparisons have no clue about used objects and are therefore not designed to accommodate or implicitly define one on their own, because they are supposed to be strict with the identifier existence as being more prone to work out with variables. This concept somehow extends to those parameters not featuring used objects as a general rule. If an unusual application needs to take place, making use of non-inlined CONSTANT_INT declarations would hint the compiler to treat unequivocally the specified string constants as used objects, truly defining a new one on the first practical usage wherever it occurs and not yielding an undefined variable error:

CONSTANT_INT cj_pizza_1
CONSTANT_INT cj_pizza_2
VAR_INT test_model1 test_model2

REQUEST_MODEL pizzahigh  // -1
test_model1 = cj_pizza_1 // -2
test_model2 = cj_pizza_2 // -3
REQUEST_MODEL test_model1
REQUEST_MODEL test_model2

Any string constant passed in place of an object model compiles a used object indiscriminately assuming no CONSTANT_INT declaration, preventing redefinitions (whether default or namespaced), does exist. Messing around with frequent compiler tool recompilations can be tedious solely to establish broad, same-indexed or math-related string constants but fortunately, in the last Trilogy chapter, the language offers the opportunity to settle user-supplied default constants for numeric literals using CONST-prefixed declarations which, alike for variables and CONSTANT_INTs, are backward accessible:

CONST_INT gf_date_active 1
CONST_FLOAT math_pi 3.1415927

SET_BIT gf_date_flags gf_date_active
rad_angle = deg_angle * math_pi
rad_angle /= 180.0

Given that default models are also default constants in Stories chapters^{[no source]}, default constants and used objects count as pseudoconstants: contrary to what namespaced constants entail, generic alternatives are favoured on assignment or comparison command pairing. It should be pointed out that, due to a critical compiler bug, the high 16 bits of the value held by a namespaced constant are unexpectedly discarded on assignment or comparison and that, if set, the 16th bit yields a nonexistent variable error (i.e. THREAT_GANG9 flag) prior Stories chapters, where a default constant is compiled only if the low 16 bits represent a value lesser than -1^{[no source]}:

Mission script		Script multifile
SET_CHAR_THREAT_SEARCH test_char THREAT_GANG_GOLFER SET_CHAR_THREAT_SEARCH test_char THREAT_GANG9 SET_CHAR_THREAT_SEARCH test_char THREAT_EMERGENCY threat_flag = THREAT_GANG_GOLFER threat_flag = THREAT_GANG9 // Ill-formed in Trilogy. threat_flag = THREAT_EMERGENCY		SET_CHAR_THREAT_SEARCH test_char 16384 SET_CHAR_THREAT_SEARCH test_char 32768 SET_CHAR_THREAT_SEARCH test_char 65536 SET_VAR_INT_TO_CONSTANT threat_flag 16384 SET_VAR_INT threat_flag 32768 SET_VAR_INT_TO_CONSTANT threat_flag 0

This inconvenient unwittingly affects real code in Liberty City Stories in one circumstance. On a final note, string constants are incompatible with optional arguments and thus taking advantage of a temporary variable would overcome this syntactic limitation.

Operators

As soon as a numeric or text label variable is declared, it can be subjected to algebric operations and/or logical comparisons by virtue of several operators. Their support is sadly very primitive, in fact the ability to establish complex expressions with parentheses and such is not featured albeit one and only binary operation is enabled to follow the basic assignment. In this regard, the variable being assigned to the lvalue cannot be the same as the outer rvalue for non-commutative operations: VAR1 = THING - VAR1, VAR1 = THING / VAR1, VAR1 = THING +@ VAR1 and VAR1 = THING -@ VAR1 are all ill-formed. This issue arises because the explicit usage of a temporary variable is needed which would be harmful for the compiler to waste by itself under the hood, thus here expressions are necessarily made up of distinct two-operand instructions, that is the lvalue content is initialized prior encoding any supplementary rvalue arithmetic:

//VAR1 = 1 - VAR1 // Invalid, cause VAR1 = 1; VAR1 -= VAR1 doesn't make sense. It would perform 1 - 1 = 0.
VAR1 = 1 - VAR2   // Valid, cause VAR1 = 1; VAR1 -= VAR2 doesn't null itself like above.
VAR1 = 1 + VAR1   // Valid, addition (as well as multiplication) is commutative so this is compiled to VAR1 += 1.

The subtraction of positive or negative rvalues necessitates a splitting character in order to discern the infix operator unambiguously, which would be treated as part of the literal or a variable decrement otherwise (i.e. VAR1 = VAR1 -1 or VAR1 = VAR1 --1). Typically, string constants are not suitable for math calculations because of the lack of pairable command alternatives but even so they are semantically contemplated as long as a namespaced constant is provided as the inner rvalue of a compound assignment or a default constant is passed to any rvalue. Another clear limitation is prefix and postfix operators do not apply onto arguments, hence there's no concrete differentiation. However, the language introduces the timed addition/subtraction to looply update a variable in a frame-rate independent way, the cast assignment to do a mutual conversion between integers and floats but it doesn't give support for the modulo operation as its predecessor. The inequality comparison was planned but quickly gone obsolete^{[no source]} – availing of the negated form of the equality operator would have sounded more intuitive but one should be aware the not-flag is not bundled with the command index when pairing command alternatives. Due to a programmers' negligence, the local-global in/equality comparison between integer or float variables is not feasible except in the last chapter of Trilogy and Stories series.

Arithmetic operators

Name		Syntax	INT	FLOAT	TEXT_LABEL/16
Basic assignment		VAR = THING	✓	✓	✓
Addition		THING + THING	✓	✓
Subtraction		THING - THING	✓	✓
Multiplication		THING * THING	✓	✓
Division		THING / THING	✓	✓
Timed addition		THING +@ THING		✓
Timed subtraction		THING -@ THING		✓
Increment	Prefix	++ VAR	✓
	Postfix	VAR ++
Decrement	Prefix	-- VAR	✓
	Postfix	VAR --

Compound assignment operators

Name	Syntax	Meaning	INT	FLOAT
Addition assignment	VAR += THING	VAR1 = VAR1 + THING	✓	✓
Subtraction assignment	VAR -= THING	VAR1 = VAR1 - THING	✓	✓
Multiplication assignment	VAR *= THING	VAR1 = VAR1 * THING	✓	✓
Division assignment	VAR /= THING	VAR1 = VAR1 / THING	✓	✓
Timed addition assignment	VAR +=@ THING	VAR1 = VAR1 +@ THING		✓
Timed subtraction assignment	VAR -=@ THING	VAR1 = VAR1 -@ THING		✓
Cast assignment	VAR =# THING	AS IS	✓	✓

Comparison operators/relational operators

Name	Syntax	INT	FLOAT	TEXT_LABEL/16
Equal to	VAR = THING	✓	✓	✓
Not equal to	VAR <> THING	✓	✓
Greater than	THING > THING	✓	✓
Less than	THING < THING	✓	✓
Greater than or equal to	THING >= THING	✓	✓
Less than or equal to	THING <= THING	✓	✓

Logical operators

Name	Syntax
Logical negation	NOT
Logical conjunction	AND
Logical disjunction	OR

Commands

The imperative programming paradigm provides for a conglomerate of commands the script is filled up of and structured in, which are seen as orders to instruct the execution of the relative built-in portion of game code at runtime. Their invocation is faithful to procedure calls: they may feature zero or more parameters of any type or indefinite, depending on whether or not qualified as optional, and receive as much as arguments either by-value or by-reference affecting the read/written access accordingly (do note a pure reference does not initialize anything). Alike procedures, no assignable result is returned but a boolean state is catched anyway on conditional evaluation. One major peculiarity is command names are usually identified by a verb in its imperative form:

GIVE_WEAPON_TO_CHAR mafia_1X WEAPONTYPE_UZI 999

Historically, complex commands stand out over the simple counterpart in the way they are implemented compiler-wise:

• Variable and local scope declarators are true, non-compilable commands;
• File includers assemble multiple files in a single source and require the rightmost argument to be a filename if inside the main script or main extension, otherwise START_NEW_SCRIPT is expected (this behaviour is originally buggy);
• Script starters/streamers and function callers involve a type-checking of the optional parameters passed basing on the variables declared in the local scope, whose opening brace must precede the script label reference even few lines earlier since the second Trilogy chapter (the first one needs it right after instead but it's likely it is merely due to good style programming);
• SCRIPT_NAME defines an univocal script name immune to redefinitions but not among mission scripts because they can only run one at a time;
• SKIP_CUTSCENE_START and SKIP_CUTSCENE_END mark a specific region of code (mostly inside mission scripts). Several blocks cannot be nested together;
• Dynamic counters expect one argument to be a zero-value which gets updated automatically/internally on compilation, keeping track of the times few commands are used (unless, if applicable, the only acceptable argument is a variable, then the command is not taken into account) or the total sum of the first argument values (of course, non-immediates are discarded):

Initializer	Dependency/ies	Check arg.	Is addend
SET_COLLECTABLE1_TOTAL	CREATE_COLLECTABLE1
SET_PROGRESS_TOTAL	PLAYER_MADE_PROGRESS	✓	✓
SET_TOTAL_NUMBER_OF_MISSIONS	REGISTER_MISSION_PASSED	✓
	REGISTER_ODDJOB_MISSION_PASSED
SET_MISSION_RESPECT_TOTAL	AWARD_PLAYER_MISSION_RESPECT	✓	✓

A third category consisting of special commands or command pairs, is able to look for the matching signature into a list of akin commands on the basis of the data type of the passed arguments and choose, accordingly, the equivalent alternative in a direct and effortless way. Although the alternative commands are also accessible by and can share the same definition, the selection process is not entirely conform to function overloading because these still maintain their own unique name, they are just smartly resolved through common aliases. The complete lists are reported below:

Trilogy and first Stories chapters

Second Stories chapter

Command Game support Alternative SET (=) Since SET_VAR_INT SET_VAR_FLOAT SET_LVAR_INT SET_LVAR_FLOAT SET_VAR_INT_TO_VAR_INT SET_LVAR_INT_TO_LVAR_INT SET_VAR_FLOAT_TO_VAR_FLOAT SET_LVAR_FLOAT_TO_LVAR_FLOAT SET_VAR_FLOAT_TO_LVAR_FLOAT SET_LVAR_FLOAT_TO_VAR_FLOAT SET_VAR_INT_TO_LVAR_INT SET_LVAR_INT_TO_VAR_INT SET_VAR_INT_TO_CONSTANT Since SET_LVAR_INT_TO_CONSTANT SET_VAR_TEXT_LABEL only SET_LVAR_TEXT_LABEL SET_VAR_TEXT_LABEL16 SET_LVAR_TEXT_LABEL16 CSET (=#) Since CSET_VAR_INT_TO_VAR_FLOAT CSET_VAR_FLOAT_TO_VAR_INT CSET_LVAR_INT_TO_VAR_FLOAT CSET_LVAR_FLOAT_TO_VAR_INT CSET_VAR_INT_TO_LVAR_FLOAT CSET_VAR_FLOAT_TO_LVAR_INT CSET_LVAR_INT_TO_LVAR_FLOAT CSET_LVAR_FLOAT_TO_LVAR_INT ADD_THING_TO_THING (+=) Since ADD_VAL_TO_INT_VAR ADD_VAL_TO_FLOAT_VAR ADD_VAL_TO_INT_LVAR ADD_VAL_TO_FLOAT_LVAR ADD_INT_VAR_TO_INT_VAR ADD_FLOAT_VAR_TO_FLOAT_VAR ADD_INT_LVAR_TO_INT_LVAR ADD_FLOAT_LVAR_TO_FLOAT_LVAR ADD_INT_VAR_TO_INT_LVAR ADD_FLOAT_VAR_TO_FLOAT_LVAR ADD_INT_LVAR_TO_INT_VAR ADD_FLOAT_LVAR_TO_FLOAT_VAR SUB_THING_FROM_THING (-=) Since SUB_VAL_FROM_INT_VAR SUB_VAL_FROM_FLOAT_VAR SUB_VAL_FROM_INT_LVAR SUB_VAL_FROM_FLOAT_LVAR SUB_INT_VAR_FROM_INT_VAR SUB_FLOAT_VAR_FROM_FLOAT_VAR SUB_INT_LVAR_FROM_INT_LVAR SUB_FLOAT_LVAR_FROM_FLOAT_LVAR SUB_INT_VAR_FROM_INT_LVAR SUB_FLOAT_VAR_FROM_FLOAT_LVAR SUB_INT_LVAR_FROM_INT_VAR SUB_FLOAT_LVAR_FROM_FLOAT_VAR MULT_THING_BY_THING (*=) Since MULT_INT_VAR_BY_VAL MULT_FLOAT_VAR_BY_VAL MULT_INT_LVAR_BY_VAL MULT_FLOAT_LVAR_BY_VAL MULT_INT_VAR_BY_INT_VAR MULT_FLOAT_VAR_BY_FLOAT_VAR MULT_INT_LVAR_BY_INT_LVAR MULT_FLOAT_LVAR_BY_FLOAT_LVAR MULT_INT_VAR_BY_INT_LVAR MULT_FLOAT_VAR_BY_FLOAT_LVAR MULT_INT_LVAR_BY_INT_VAR MULT_FLOAT_LVAR_BY_FLOAT_VAR DIV_THING_BY_THING (/=) Since DIV_INT_VAR_BY_VAL DIV_FLOAT_VAR_BY_VAL DIV_INT_LVAR_BY_VAL DIV_FLOAT_LVAR_BY_VAL DIV_INT_VAR_BY_INT_VAR DIV_FLOAT_VAR_BY_FLOAT_VAR DIV_INT_LVAR_BY_INT_LVAR DIV_FLOAT_LVAR_BY_FLOAT_LVAR DIV_INT_VAR_BY_INT_LVAR DIV_FLOAT_VAR_BY_FLOAT_LVAR DIV_INT_LVAR_BY_INT_VAR DIV_FLOAT_LVAR_BY_FLOAT_VAR IS_THING_EQUAL_TO_THING (=) Since IS_INT_VAR_EQUAL_TO_NUMBER IS_INT_LVAR_EQUAL_TO_NUMBER IS_INT_VAR_EQUAL_TO_INT_VAR IS_INT_LVAR_EQUAL_TO_INT_LVAR IS_INT_VAR_EQUAL_TO_INT_LVAR IS_INT_LVAR_EQUAL_TO_INT_VAR only IS_FLOAT_VAR_EQUAL_TO_NUMBER IS_FLOAT_LVAR_EQUAL_TO_NUMBER IS_FLOAT_VAR_EQUAL_TO_FLOAT_VAR IS_FLOAT_LVAR_EQUAL_TO_FLOAT_LVAR IS_FLOAT_VAR_EQUAL_TO_FLOAT_LVAR IS_FLOAT_LVAR_EQUAL_TO_FLOAT_VAR only IS_INT_VAR_EQUAL_TO_CONSTANT Since IS_INT_LVAR_EQUAL_TO_CONSTANT IS_VAR_TEXT_LABEL_EQUAL_TO_TEXT_LABEL only IS_LVAR_TEXT_LABEL_EQUAL_TO_TEXT_LABEL IS_VAR_TEXT_LABEL16_EQUAL_TO_TEXT_LABEL IS_LVAR_TEXT_LABEL16_EQUAL_TO_TEXT_LABEL IS_THING_NOT_EQUAL_TO_THING (<>) Since IS_INT_VAR_NOT_EQUAL_TO_NUMBER IS_INT_LVAR_NOT_EQUAL_TO_NUMBER IS_INT_VAR_NOT_EQUAL_TO_INT_VAR IS_INT_LVAR_NOT_EQUAL_TO_INT_LVAR IS_INT_VAR_NOT_EQUAL_TO_INT_LVAR IS_INT_LVAR_NOT_EQUAL_TO_INT_VAR only IS_FLOAT_VAR_NOT_EQUAL_TO_NUMBER IS_FLOAT_LVAR_NOT_EQUAL_TO_NUMBER IS_FLOAT_VAR_NOT_EQUAL_TO_FLOAT_VAR IS_FLOAT_LVAR_NOT_EQUAL_TO_FLOAT_LVAR IS_FLOAT_VAR_NOT_EQUAL_TO_FLOAT_LVAR IS_FLOAT_LVAR_NOT_EQUAL_TO_FLOAT_VAR only IS_THING_GREATER_THAN_THING (>, <=) Since IS_INT_VAR_GREATER_THAN_NUMBER IS_INT_LVAR_GREATER_THAN_NUMBER IS_NUMBER_GREATER_THAN_INT_VAR IS_NUMBER_GREATER_THAN_INT_LVAR IS_INT_VAR_GREATER_THAN_INT_VAR IS_INT_LVAR_GREATER_THAN_INT_LVAR IS_INT_VAR_GREATER_THAN_INT_LVAR IS_INT_LVAR_GREATER_THAN_INT_VAR IS_FLOAT_VAR_GREATER_THAN_NUMBER IS_FLOAT_LVAR_GREATER_THAN_NUMBER IS_NUMBER_GREATER_THAN_FLOAT_VAR IS_NUMBER_GREATER_THAN_FLOAT_LVAR IS_FLOAT_VAR_GREATER_THAN_FLOAT_VAR IS_FLOAT_LVAR_GREATER_THAN_FLOAT_LVAR IS_FLOAT_VAR_GREATER_THAN_FLOAT_LVAR IS_FLOAT_LVAR_GREATER_THAN_FLOAT_VAR IS_INT_VAR_GREATER_THAN_CONSTANT Since IS_INT_LVAR_GREATER_THAN_CONSTANT IS_CONSTANT_GREATER_THAN_INT_VAR IS_CONSTANT_GREATER_THAN_INT_LVAR IS_THING_GREATER_OR_EQUAL_TO_THING (>=, <) Since IS_INT_VAR_GREATER_OR_EQUAL_TO_NUMBER IS_INT_LVAR_GREATER_OR_EQUAL_TO_NUMBER IS_NUMBER_GREATER_OR_EQUAL_TO_INT_VAR IS_NUMBER_GREATER_OR_EQUAL_TO_INT_LVAR IS_INT_VAR_GREATER_OR_EQUAL_TO_INT_VAR IS_INT_LVAR_GREATER_OR_EQUAL_TO_INT_LVAR IS_INT_VAR_GREATER_OR_EQUAL_TO_INT_LVAR IS_INT_LVAR_GREATER_OR_EQUAL_TO_INT_VAR IS_FLOAT_VAR_GREATER_OR_EQUAL_TO_NUMBER IS_FLOAT_LVAR_GREATER_OR_EQUAL_TO_NUMBER IS_NUMBER_GREATER_OR_EQUAL_TO_FLOAT_VAR IS_NUMBER_GREATER_OR_EQUAL_TO_FLOAT_LVAR IS_FLOAT_VAR_GREATER_OR_EQUAL_TO_FLOAT_VAR IS_FLOAT_LVAR_GREATER_OR_EQUAL_TO_FLOAT_LVAR IS_FLOAT_VAR_GREATER_OR_EQUAL_TO_FLOAT_LVAR IS_FLOAT_LVAR_GREATER_OR_EQUAL_TO_FLOAT_VAR IS_INT_VAR_GREATER_OR_EQUAL_TO_CONSTANT Since IS_INT_LVAR_GREATER_OR_EQUAL_TO_CONSTANT IS_CONSTANT_GREATER_OR_EQUAL_TO_INT_VAR IS_CONSTANT_GREATER_OR_EQUAL_TO_INT_LVAR ADD_THING_TO_THING_TIMED (+=@) Since ADD_TIMED_VAL_TO_FLOAT_VAR ADD_TIMED_VAL_TO_FLOAT_LVAR ADD_TIMED_FLOAT_VAR_TO_FLOAT_VAR ADD_TIMED_FLOAT_LVAR_TO_FLOAT_LVAR ADD_TIMED_FLOAT_LVAR_TO_FLOAT_VAR ADD_TIMED_FLOAT_VAR_TO_FLOAT_LVAR SUB_THING_FROM_THING_TIMED (-=@) Since SUB_TIMED_VAL_FROM_FLOAT_VAR SUB_TIMED_VAL_FROM_FLOAT_LVAR SUB_TIMED_FLOAT_VAR_FROM_FLOAT_VAR SUB_TIMED_FLOAT_LVAR_FROM_FLOAT_LVAR SUB_TIMED_FLOAT_LVAR_FROM_FLOAT_VAR SUB_TIMED_FLOAT_VAR_FROM_FLOAT_LVAR ABS Since ABS_VAR_INT ABS_LVAR_INT ABS_VAR_FLOAT ABS_LVAR_FLOAT IS_EMPTY only IS_VAR_TEXT_LABEL_EMPTY IS_LVAR_TEXT_LABEL_EMPTY IS_VAR_TEXT_LABEL16_EMPTY IS_LVAR_TEXT_LABEL16_EMPTY IS_BIT_SET only IS_GLOBAL_VAR_BIT_SET_CONST IS_GLOBAL_VAR_BIT_SET_VAR IS_GLOBAL_VAR_BIT_SET_LVAR IS_LOCAL_VAR_BIT_SET_CONST IS_LOCAL_VAR_BIT_SET_VAR IS_LOCAL_VAR_BIT_SET_LVAR SET_BIT only SET_GLOBAL_VAR_BIT_CONST SET_GLOBAL_VAR_BIT_VAR SET_GLOBAL_VAR_BIT_LVAR SET_LOCAL_VAR_BIT_CONST SET_LOCAL_VAR_BIT_VAR SET_LOCAL_VAR_BIT_LVAR CLEAR_BIT only CLEAR_GLOBAL_VAR_BIT_CONST CLEAR_GLOBAL_VAR_BIT_VAR CLEAR_GLOBAL_VAR_BIT_LVAR CLEAR_LOCAL_VAR_BIT_CONST CLEAR_LOCAL_VAR_BIT_VAR CLEAR_LOCAL_VAR_BIT_LVAR

Command Alternative SET (=) SET_VAR_INT SET_VAR_FLOAT SET_VAR_TEXT_LABEL SET_VAR_INT_TO_VAR_INT SET_VAR_FLOAT_TO_VAR_FLOAT SET_VAR_TEXT_LABEL_TO_VAR_TEXT_LABEL SET_VAR_INT_TO_CONSTANT CSET (=#) CSET_VAR_INT_TO_VAR_FLOAT CSET_VAR_FLOAT_TO_VAR_INT ADD_THING_TO_THING (+=) ADD_VAL_TO_INT_VAR ADD_VAL_TO_FLOAT_VAR ADD_INT_VAR_TO_INT_VAR ADD_FLOAT_VAR_TO_FLOAT_VAR SUB_THING_FROM_THING (-=) SUB_VAL_FROM_INT_VAR SUB_VAL_FROM_FLOAT_VAR SUB_INT_VAR_FROM_INT_VAR SUB_FLOAT_VAR_FROM_FLOAT_VAR MULT_THING_BY_THING (*=) MULT_INT_VAR_BY_VAL MULT_FLOAT_VAR_BY_VAL MULT_INT_VAR_BY_INT_VAR MULT_FLOAT_VAR_BY_FLOAT_VAR DIV_THING_BY_THING (/=) DIV_INT_VAR_BY_VAL DIV_FLOAT_VAR_BY_VAL DIV_INT_VAR_BY_INT_VAR DIV_FLOAT_VAR_BY_FLOAT_VAR IS_THING_EQUAL_TO_THING (=) IS_INT_VAR_EQUAL_TO_NUMBER IS_INT_VAR_EQUAL_TO_INT_VAR IS_FLOAT_VAR_EQUAL_TO_NUMBER IS_FLOAT_VAR_EQUAL_TO_FLOAT_VAR IS_TEXT_LABEL_VAR_EQUAL_TO_TEXT_LABEL IS_TEXT_LABEL_VAR_EQUAL_TO_TEXT_LABEL_VAR IS_INT_VAR_EQUAL_TO_CONSTANT IS_THING_GREATER_THAN_THING (>, <=) IS_INT_VAR_GREATER_THAN_NUMBER IS_NUMBER_GREATER_THAN_INT_VAR IS_INT_VAR_GREATER_THAN_INT_VAR IS_FLOAT_VAR_GREATER_THAN_NUMBER IS_NUMBER_GREATER_THAN_FLOAT_VAR IS_FLOAT_VAR_GREATER_THAN_FLOAT_VAR IS_INT_VAR_GREATER_THAN_CONSTANT IS_CONSTANT_GREATER_THAN_INT_VAR IS_THING_GREATER_OR_EQUAL_TO_THING (>=, <) IS_INT_VAR_GREATER_OR_EQUAL_TO_NUMBER IS_NUMBER_GREATER_OR_EQUAL_TO_INT_VAR IS_INT_VAR_GREATER_OR_EQUAL_TO_INT_VAR IS_FLOAT_VAR_GREATER_OR_EQUAL_TO_NUMBER IS_NUMBER_GREATER_OR_EQUAL_TO_FLOAT_VAR IS_FLOAT_VAR_GREATER_OR_EQUAL_TO_FLOAT_VAR IS_INT_VAR_GREATER_OR_EQUAL_TO_CONSTANT IS_CONSTANT_GREATER_OR_EQUAL_TO_INT_VAR ADD_THING_TO_THING_TIMED (+=@) ADD_TIMED_VAL_TO_FLOAT_VAR ADD_TIMED_FLOAT_VAR_TO_FLOAT_VAR SUB_THING_FROM_THING_TIMED (-=@) SUB_TIMED_VAL_FROM_FLOAT_VAR SUB_TIMED_FLOAT_VAR_FROM_FLOAT_VAR ABS ABS_VAR_INT ABS_VAR_FLOAT

Control flows

Insofar as subprograms, scripts are organized in a systematic arrangement through which goto branches, subroutine branches, function calls and returns are executed to form control flow statements and structures. These alter the program counter most of the time affecting the top-down order all commands are fetched by. Facing off code duplication is quite recurring especially when the tasks to perform vary only in the input data, the case where a piece of code or subroutine, built once in the source, is invoked many times from various different places and returns back, as if the GOSUB statement is substituted in-place by the subroutine's body without RETURN during the control transferring, shrinking long codes and reducing the script overall size. The flow of execution can also be broken up conditionally by means of:

• Decision-making structures (IF, IFNOT, SWITCH), which evaluate the result of one or more conditions and choose what path to follow based off the trueness or falseness of the check being tested. Been deemed the most basic tool of structured programming, IF is a bidirectional statement that proceeds with the execution of the underneath code only if the test carried out evaluates to true otherwise it transfers the control next to ENDIF, unless a preceding and optional ELSE clause, establishing an alternative path, is specified. In the first Trilogy and both Stories chapters where GOTO_IF_TRUE is handled by game code, the barely used IFNOT can be deployed as a placeholder to easily invert the compare-flag, a boolean state which is set or cleared as a result of the bitwise conjunction or disjunction with the true/false state caught by a condition, applying the inversion according to the presence of the not-flag before updating. Logical operators make possible the connection among multiple conditions via the AND conjunction and OR disjunction giving the chance to verify if conditions are all true or if just one of them is satisfied bearing in mind that the NOT negation, inverting the boolean state of a single condition, may be supplied. Connectivity information are held by ANDOR, whose argument depicts a value in the range [1,8) or [21,28) for logical conjunction and disjunction respectively, limiting the amount of total conditions to provide to a maximum of 8 per check (the prominent intervals discrepancy also suggests NAND and NOR operators might have been a plan). A value of 0 does nothing relevant functional-wise at runtime, what led programmers to not compile said command in such a situation for Stories chapters. The inability to create subexpressions enforces to not combine AND with OR in a check, plus evaluations are eager and therefore not short-circuited meaning all conditions are executed prior potentially branching through GOTO_IF_FALSE in the common case after the compare-flag gets processed. Nesting lots of IF-ELSE-ENDIF structures of one-condition checks testing the equality of the same variable against a few integer literals or string constants can add a ridiculous code redundancy and performance overhead, sorted out in the last Trilogy chapter thanks to the introduction of the SWITCH statement, a multiway statement either branching to the switch section labelled by fall-through CASE statements of which one passses a value that shall match the variable content to compare or optionally branching to DEFAULT in the worst-case scenario, each ending with a nonmandatory BREAK statement goto-ing past ENDSWITCH. On compilation, the implementation somehow mimics the pattern of a jump table sorting case label references by value to fulfil the runtime's binary search among at least 1 of 75 entries (default case aside);
• Looping structures (REPEAT, WHILE, WHILENOT), which repeatedly execute a block of code certain number of times (count-controlled) or by constantly and successfully evaluating a check (condition-controlled).

IF/IFNOT-ELSE-ENDIF SWITCH-CASE/DEFAULT-BREAK-ENDSWITCH

WHILE/WHILENOT-ENDWHILE REPEAT-ENDREPEAT

Code layout

Subscripts and Mission scripts

[...] The so-called official compiler is custom by War Drum Studios.

[...] LOAD_SPRITE expects a variable-length text label of 14 characters but then the game code enforces an useless uppercase conversion of a fixed-length 15 character identifier, incorrectly including the null-terminator at 15th position during the process. [...] Variable and text label identifiers are limited to 40 characters, the reason why 4 TEXT_LABEL32 parameters are needed to store 128-byte strings. They can be passed individually as 32-byte aligned blocks but the first character is trimmed out. [...] In the last Trilogy and Stories chapter, text labels must begin with an alphanumeric character or an underscore, provided that they aren't valid integer or floating-point literals. [...] It is prohibited to fetch or handle a long text label using a variable of shorter length but this one is rather passable to those text label parameters also permitting long-lengthed literals. [...] Variable-length text labels are kind of Pascal strings. Reference: https://en.wikipedia.org/wiki/String_(computer_science)#Length-prefixed.

[...] In the last Trilogy chapter, local variables start at index 34 in mission scripts so local timers are also ignored.

[...] Some commands have non-typified arguments which are referred to as parameters.

[*] No more than 8 conditions are allowed per check [*] Checks are not short-circuited at runtime meaning all conditions are executed before branching [*] NAND and NOR might have been planned considering ANDOR values (0, 1 to 7, 21 to 27). Hint: mention the compare flag. [*] ANDOR is not compiled in Stories games for one condition checks [*] IFNOT and WHILENOT are not supported in VC and SA because GOTO_IF_TRUE is not handled by game code there. [*] REPEAT is supported since VC [*] REPEAT cycles at least one-time [*] REPEAT wrongly accepts a value lesser than 1 for the times argument [*] SWITCH is supported only in SA [*] SWITCH allows fall-through CASEs so BREAK is not mandatory [*] SWITCH handles up to 75 CASEs chosen as a result of a binary search which requires CASEs to be sorted on compilation [*] In contrast to scope-free subroutines which feature no argument... [*] Boolean-valued gosub and function [*] Recursion is allegedly not supported albeit gosubs and functions have 8 global levels of nesting in Trilogy chapters and 16 in Stories'. [*] Decision-making statement (IF, IFNOT, SWITCH) [*] Count-controlled loop (REPEAT) [*] Condition-controlled loop (WHILE, WHILENOT) [*] An unconditional branch, despite considered harmful in the programming literature, is the only way to go for breaking loops prematurely and enhance the simplistic code logic. [*] Infinite loops are achieved by means of a backward GOTO

[...] Although it is able to infer nothing regarding the aim exclusive mission scripts were planned for which swings among testing, mission pack and multiplayer purposes, there are bunch of irrefutable evidences implementation-wise. The functionality is analoguous to usual mission scripts but, on the other hand, the opposing kind of them is totally superseded and completely overlooked during the compilation phase. Their coexistence is perfectly legal, though leftover launchers are bad style and dangerous in so far as noncompilable unless an exclusive variation is also provided. Additionally, they are a lot limited in quantity: the first Trilogy chapter expects in theory only an intro mission (INTRO, shame not at runtime), the second chapter an auxiliary initialization mission (INITIAL), the third one an extra initialization mission (INITIL2) and whereas Stories chapters have game provision for such feature along the lines of Vice City, their compilers have allegedly no support because of deprecation (the trigger command is still there, however the too many initialization missions seen in the script binary might speak from themselves). Hints: one's complement

[...] Early in development, STREAM_SCRIPT was compiled to STREAM_SCRIPT_INTERNAL.

Despite streamed scripts may receive an entity handle as input parameter, they are not necessarily callable and so an on-top, unreachable, explicit entity's creation is due:

{
    VAR_INT test_char sanity

    sanity = 0
    IF sanity = -1
        CREATE_CHAR PEDTYPE_CIVMALE male01 0.0 0.0 0.0 test_char
    ENDIF
}

This scenario also extends to any embedded script or script file

Originally, explicit entity creations are conventionally put on top of any sort of script by mean of unreachable code to confer specific entity types to declared variables for better error-checking: