2.2 How the interpreter works (from AGDS docs) Last updated: 27 January 1998 How AGI worls The AGI interpreter contains: - 256 (0 - 255) one-byte variables (Var); - 256 (0 - 255) flags (Flag); - a number of objects controlled by the interpreter, one of which (the object 0) may be controlled by the player using the keyboard; - a number of inventory items; - 12 40-character string variables (string). Some variables (0 - 26) and flags (0 - 15) are reserved by the interpreter, all others are free to be used by the programmer. The interpreter provides a common variable and flag space for all programs simultaneously loaded in the memory. The number of objects and things is determined by the OBJECT resource. Interpreter's actions are described using the commands of the interpreter's language. For example, there are commands to manage objects, load and unload resources, etc. Further we shall consider the commands in detail. Note! Any variable, flag, object, string, word, message, etc. has a unique ID number, and numbering of different data types is independent (for example, there can be a variable number 5, a string number 5, and a flag number 5).   Resources - the fundamental AGI data type When we develop a game, we invent the plot, create objects of the game, animate them, develop scenery and a dictionary of words for the dialogue with the player. To describe all of these, resources are used. To create some of the resources, we use utilities included with AGDS, in this case the input of the utilities are resources. [Sounds weird, but that's literally what it says. --VB] Here is a list of all the existing resources. Resources are used to represent: colour background drawings (PICTURE resource); colour animated images (VIEW resource); sound effects (music, noise) (SOUND resource); inventory items and other objects (OBJECT resource); system dictionary for communicating with the user (WORD resource); programs in internal AGI programming language (LOGIC resource). General principles of the interpreter operation Let us now consider the interpreter algorithm and the purpose of reserved variables and flags. When interpreter starts, LOGIC resource number 0 is loaded in memory. It stays there during the whole play time and determines all the interpreter's actions related to the overall control of the game. The interpreter works in a loop, i.e. all its actions are described by the INTERPRETER WORK CYCLE shown in the block diagram below. In each cycle the interpreter performs the following basic actions: time delay; clears the keyboard buffer; polls the keyboard and the joystick; analyses some of the reserved variables and flags (see block diagram); for all controllable objects for which animate_obj, start_update and draw commands were issued, directions of motion are recalculated; LOGIC resource 0 is executed, as well as any logics it calls--which, in turn, can call other logics. Depending on the state of variables and flags analyzed at step 4 the number of commands interpreted at stage 4 commands varies from one iteration of the cycle to another depending, for example, on a number of LOGIC resources to be called in the current situation; tests if the new_room command has been issued; Then the cycle is repeated. All logics (programs and subroutines) simultaneously loaded in memory operate on a common set of variables, flags, and strings, each identified by a unique for each data type ID number. The fact that the interpreter runs in a loop influences the general programming principles and style when programming for AGDS. This makes programming a little unusual and takes a certain time to get used to. For example, many cyclic activities requiring explicit loops in "conventional" programming languages, are executed in the interpreter programs by default, provided the program has a proper structure. General hints on how to reduce the time to adapt to the interpreter's language are given below, using an educational program "Thunderstorm" as an example. However, this does not reduce the usefulness of analyzing the game programs of Sierra Online, Inc.   Interpreter work cycle +---------------------------+ | 1. delay time | +---------------------------+ | V +----------------------------+ |2. clear the keyboard buffer| +----------------------------+ | V +---------------------------+ | Flag (2) - > 0 | | Flag (4) - > 0 | +---------------------------+ | V +-------------------------------------+ | 3. poll keyboard and joystick | +-------------------------------------+ | V +-------------------------------------+ | If the current mode is | | - program_control, the direction of | | EGO motion <-- var(6). | | - player_control, var (6) --> dir. | | of EGO motion. | +-------------------------------------+ | V +---------------------------------------------------------------+ | For all objects for which command animate_obj, start_update | | and draw were carried out, the recalculation of the direction | | of movement is performed. | +---------------------------------------------------------------+ | V +---------------------------------------------------------------+ | If the score has changed (var (3)) or the sound has been | | turned on or off (Flag (9)), the status line is updated. | +---------------------------------------------------------------+ | +---------+ V +--------------------------+ +---------------->| 4 Logic 0 is executed | | +--------------------------+ | | | V | +--------------------------------------+ | | - Dir. of motion of EGO <-- var (6) | | | - If score (var (3)) or Flag (9) | | | have changed their values - update | | | the status and score (on Var (3)); | | | - Var (5) - > 0; | | | - Var (4) - > 0; | | | - Flag (5) - > 0!!!! | | | - Flag (6) - > 0; | | | - Flag (12) - > 0. | | +--------------------------------------+ +----------------------------+ | | Execute: | V | ~~~~~~~~~~~~~~~~~~~~~~~~ | +------------------------+ | - stop_update; | | Update all controlled | | - unanimate_all; | | objects on the screen. | | - destroy all logic | +------------------------+ | resources except | | | for logic 0; | V | - player_control; | +--------------+ | - unblock; | | new_room n | | - set_horizon 36; | | or | | - var (1) = var (0); | | new_room_v n | | - var (0) = n | (var (n)); | | was issued? | | - var (4) = 0; | | | | - var (5) = 0; | +-------+------+ | - var (9) = 0; |<-----------+ Yes | No | | - var (16) = number of | +-------+--+---+ | view assoc. w/EGO; | | | - EGO coords from var (2); | | | - var (2) = 0; | | | - flag (2) - > 0; | V | - flag (5) - > 1!!!! | +--------------+ | - score < - var (3); | | Go to step 1 | +----------------------------+ +--------------+ Variables used by the interpreter On interpreter startup all variables are set to 0. Var n 0 - Current room number (parameter new_room cmd), initially 0. 1 - Previous room number. 2 - Code of the border touched by EGO: 0 - Touched nothing; 1 - Top edge of the screen or the horizon; 2 - Right edge of the screen; 3 - Bottom edge of the screen; 4 - Left edge of the screen. 3 - Current score. 4 - Number of object, other than EGO, that touched the border. 5 - The code of border touched by the object in Var (4). 6 - Direction of EGO's motion. 1 8 | 2 \ | / \ | / 7 ------------- 3 0 - the object / | \ is motionless / | \ 6 | 4 5 7 - Maximum score. 8 - Number of free 256-byte pages of the interpreter's memory. 9 - If = 0, it is the number of the word in the user message that was not found in the dictionary. [I would assume they mean "if != 0", but that's what they say. --VB] 10 - Time delay between interpreter cycles in 1/20 second intervals. 11 - Seconds (interpreter's internal clock) 12 - Minutes (interpreter's internal clock) 13 - Hours (interpreter's internal clock) 14 - Days (interpreter's internal clock) 15 - Joystick sensitivity (if Flag (8) = 1). 16 - ID number of the view-resource associated with EGO. 17 - Interpreter error code (if = 0) [again I would expect this to say "if != 0". --VB] 18 - Additional information that goes with the error code. 19 - Key pressed on the keyboard. 20 - Computer type. For IBM PC it always 0. 21 - If Flag (15) = 0 (command reset 15 was issued) and Var (21) is not equal to 0, the window is automatically closed after 1/2 * Var (21) seconds. 22 - Sound generator type: 1 = PC; 3 = Tandy. 23 - 0:F - sound volume (for TANDY). 24 - 29h. 25 - ID number of the item selected using status command or FF if ESC was pressed. 26 - monitor type 0 - CGA; 2 - Hercules; 3 - EGA. Flags used by the interpreter On the interpreter startup all flags are set to 0. Flag n 0 - EGO base line is completely on pixels with priority = 3 (water surface). 1 - EGO is invisible of the screen (completely obscured by another object). 2 - the player has issued a command line. 3 - EGO base line has touched a pixel with priority 2 (signal). 4 - `said' command has accepted the user input. 5 - The new room is executed for the first time. 6 - `restart_game' command has been executed. 7 - if this flag is 1, writing to the script buffer is blocked. 8 - if 1, Var(15) determines the joystick sensitivity. 9 - sound on/off. 10 - 1 turns on the built-in debugger. 11 - Logic 0 is executed for the first time. 12 - `restore_game' command has been executed. 13 - 1 allows the `status' command to select items. 14 - 1 allows the menu to work. 15 - Determines the output mode of `print' and `print_at' commands: 1 - message window is left on the screen 0 - message window is closed when Enter or Esc key are pressed. If Var(21) is not 0, the window is closed automatically after 1/2 * Var(21) seconds