Note
 This is a draft. It may be wrong, incomplete and subject to change.

Introduction

Grand Theft Auto III was released in 2001 to great critical acclaim, becoming one of the most important titles of all time and changing the gaming landscape forever with its immersive open world sandbox.

To support this open world, a scripting language was created in order to fasten development, reducing the complexities of programming languages for less-skilled personnel.

This is an attempt to produce a formal language specification for this language. More specifically, this document is an extension to [GTA3script Specification], providing details specific to the implementation of the language in GTA III.

1. Scope

This document is an extension to the GTA3script language. It provides the necessary changes to the translation (and part of the execution) environment to accomodate the details of the implementation used in 2001’s GTA III.

[GTA3script Specification] provides important context and specification for this extension. The sections of this document should be read as if merged to the original sections of [GTA3script Specification].

2. Terms and Definitions

For the purposes of this document, the terms and definitions given in [GTA3script Specification] and the following apply.

mission

TODO

collectable

TODO

progress points

TODO

timer

TODO

model

TODO

level model

TODO

text key

TODO

3. General Principles

3.1. Implementation Conformance

Other extensions may expand and alter this document for the purpose of specifying other implementations, provided they still conform to [GTA3script Specification].

3.2. Structure of this Document

Section 4 through 9 provides changes to the sections of same name in [GTA3script Specification].

Section 10 and 11 describes the set of string constants and entity types necessary to support this implementation.

Section 12 provides the limits of this implementation.

4. Elements

4.1. Commands

4.1.1. Identifiers

As text label variables are not supported, the first character of an identifier shall not be a dollar.

4.1.2. String Literals

String literals are not supported.

4.1.3. Variable References

As text label variables are not supported, the first character of a variable name shall not be a dollar.

As array variables are not supported, subscripts are ill-formed.

5. Parameters

5.1. String Constants

There exists an enumeration called the default models enumeration.[1]

5.2. Used Objects

An object string constant is a string constant matching any string constant in the default models enumeration or any level model name (in this order).[2]

A parameter definition can be associated with object string constants. Further semantics for this association are defined along this specification.

Any object string constant used in the multi-file is called an used object.

5.3. Parameter Types

5.3.1. INPUT_INT

If the parameter is associated with object string constants, it should behave as if the parameter was associated with an enumeration containing the object string constants.

5.3.2. VAR_TEXT_LABEL

As text label variables are not supported, this parameter type is not supported.

5.3.3. LVAR_TEXT_LABEL

As text label variables are not supported, this parameter type is not supported.

5.3.4. STRING

As string literals are not supported, this parameter type is not supported.

5.3.5. Optional Parameters

As text label variables are not supported, the VAR_TEXT_LABEL_OPT and LVAR_TEXT_LABEL_OPT parameter types are not supported.

6. Expressions

6.1. Assignment Expressions

The ternary assignments a = b - c, a = b / c, a = b +@ c and a = b -@ c where a is the same name as c are ill-formed.

7. Statements

7.1. Scope Statements

Semantics

The activation of a lexical scope causes the declaration of two local variables of integer type named TIMERA and TIMERB which are timers counting up.

7.2. Variable Declaration Statements

Text label variables are not supported.

Array variables are not supported.

Constraints

The name of a variable shall not be TIMERA nor TIMERB.

8. Supporting Commands

The GTA III implementation of the language provides an extensive list of commands to interact with the game engine. It is not of the intent of this specification to document these commands. This is left as a task for other projects in the modding community. Please see [GTAMods Wiki], [GTAG Opcode Database] and [GTA3script Configuration] for some of these efforts.

Nevertheless, there are commands that require additional support from the translation environment. These commands are specified below.

8.1. START_NEW_SCRIPT

The definition present in [GTA3script Specification] remains with the following rectification in the constraints of the command.

Constraints

The specified label location must be within a scope. Such scope can begin at the next non-empty embedded statement relative to the label location.

8.2. PLAYER_MADE_PROGRESS

Parameters

PLAYER_MADE_PROGRESS INT

Side effects

Adds the given amount of progress points to the game.

8.3. SET_PROGRESS_TOTAL

Parameters

SET_PROGRESS_TOTAL INT

Side effects

Sets the total amount of progress points that can be archieved in the game.

Constraints

The translation environment must enforce the following constraints.

There shall be only a single occurrence of this command in the multi-file.

The given integer value shall be equal zero. The argument must be rewritten to correspond to the sum of the arguments to all instances of PLAYER_MADE_PROGRESS in the multi-file.

8.4. REGISTER_MISSION_PASSED

Parameters

REGISTER_MISSION_PASSED TEXT_LABEL

Side effects

Registers that the mission associated with the given text key has been passed.

8.5. SET_TOTAL_NUMBER_OF_MISSIONS

Parameters

SET_TOTAL_NUMBER_OF_MISSIONS INPUT_INT

Side effects

Sets the total number of missions present in the game.

Constraints

The translation environment must enforce the following constraints.

There shall be only a single occurrence of this command in the multi-file.

The argument must not be a variable and shall evaluate to an interger value equal zero. The argument must be rewritten to correspond to the number of times the command REGISTER_MISSION_PASSED occurs in the multi-file.

8.6. CREATE_COLLECTABLE1

Parameters

CREATE_COLLECTABLE1 INPUT_FLOAT INPUT_FLOAT INPUT_FLOAT

Side effects

Creates a collectable at the specified X, Y and Z coordinates respectively.

If the given Z coordinate is equal -100.0, the collectable is created at the ground of the given X, Y coordinates.

8.7. SET_COLLECTABLE1_TOTAL

Parameters

SET_COLLECTABLE1_TOTAL INPUT_INT

Side effects

Sets the total number of collectables in the game.

Constraints

The translation environment must enforce the following constraints.

There shall be only a single occurrence of this command in the multi-file.

The argument must not be a variable and shall evaluate to an interger value equal zero. The argument must be rewritten to correspond to the number of times the command CREATE_COLLECTABLE1 occurs in the multi-file.

9. Supporting Command Selectors

The following rectifies a few command selectors specified in [GTA3script Specification] to eliminate unsupported alternatives from the selection set.

9.1. SET

The following alternatives are not supported and thus removed:

SET_VAR_INT_TO_CONSTANT VAR_INT INPUT_INT
SET_LVAR_INT_TO_CONSTANT VAR_INT INPUT_INT
SET_VAR_TEXT_LABEL VAR_TEXT_LABEL TEXT_LABEL
SET_LVAR_TEXT_LABEL LVAR_TEXT_LABEL TEXT_LABEL

9.2. IS_THING_EQUAL_TO_THING

The following alternatives are not supported and thus removed[3]:

IS_INT_VAR_EQUAL_TO_CONSTANT VAR_INT INPUT_INT
IS_INT_LVAR_EQUAL_TO_CONSTANT LVAR_INT INPUT_INT
IS_VAR_TEXT_LABEL_EQUAL_TO_TEXT_LABEL VAR_TEXT_LABEL TEXT_LABEL
IS_LVAR_TEXT_LABEL_EQUAL_TO_TEXT_LABEL LVAR_TEXT_LABEL TEXT_LABEL
IS_INT_LVAR_EQUAL_TO_INT_VAR LVAR_INT VAR_INT
IS_FLOAT_LVAR_EQUAL_TO_FLOAT_VAR LVAR_FLOAT VAR_FLOAT

9.3. IS_THING_GREATER_THAN_THING

The following alternatives are not supported and thus removed:

IS_INT_VAR_GREATER_THAN_CONSTANT VAR_INT INPUT_INT
IS_INT_LVAR_GREATER_THAN_CONSTANT LVAR_INT INPUT_INT
IS_CONSTANT_GREATER_THAN_INT_VAR INPUT_INT VAR_INT
IS_CONSTANT_GREATER_THAN_INT_LVAR INPUT_INT LVAR_INT

9.4. IS_THING_GREATER_OR_EQUAL_TO_THING

The following alternatives are not supported and thus removed:

IS_INT_VAR_GREATER_OR_EQUAL_TO_CONSTANT VAR_INT INPUT_INT
IS_INT_LVAR_GREATER_OR_EQUAL_TO_CONSTANT LVAR_INT INPUT_INT
IS_CONSTANT_GREATER_OR_EQUAL_TO_INT_VAR INPUT_INT VAR_INT
IS_CONSTANT_GREATER_OR_EQUAL_TO_INT_LVAR INPUT_INT LVAR_INT

10. Supporting String Constants

TODO

11. Supporting Entity Types

TODO

12. Implementation Limits

TODO

References

1. This enumeration behaves like any other enumeration. It is defined here such that section 5.2 can refer to it.
2. Although it may seem like object string constants form an enumeration, they don’t. Semantics are sighly different. Two examples come to mind: Variables can have the same name as level models and alternators do not take object string constants into account. All of this is unlike the in-house compiler we have, but is in accordance to what is seen in the GTA III 10th Anniversary scripts (e.g. variable and used object named playersdoor) as well as what is seen in GTA San Andreas to support assignment of level models to variables (i.e. not through SET_VAR_INT_TO_CONSTANT but SET_VAR_INT — but this is an history for the GTA3script extensions for GTA San Andreas).
3. This list is not wrong. Commands to compare local variables (left-hand side) to global variables (right-hand side) are not available in GTA III nor Vice City.