AGI Specifications Resources : Logic resources

Au cœur de l'AGI (Adventure Game Interpreter) de Sierra se trouve le fichier “logique”.

Ces fichiers contiennent le code qui compose le jeu. Chaque pièce est accompagnée d'un script logique. Ce script logique régit ce qui peut se passer dans cette salle.

Voici un exemple de ce que le programmeur écrit lors de la création d'un jeu.

Exemple: KQ4. Room 7.

if (said( open, door))       // must be close enough
{
   if (posn( ego, 86, 120, 106, 133))
   {
      if (!night)
      {
         if ( door.open)
         {
            print("The door is already open");
         }
         else
         {
            set( game.control);
            set.priority( ego, 11);
            start.update( door);
            end.of.loop( door, door.done);
         }
      }
      else
      {
         print("You can't -- it's locked");
      }
   }
   else
   {
      set( notCloseEnough);
   }
}

Les tableaux suivants présentent une liste de toutes les commandes AGI et de leurs types d'arguments.

Les noms des commandes sont tirés des messages de débogage contenus dans certains jeux AGI.

L'entête (Header) de chaque script logique a une longueur de sept octets pour les jeux antérieurs à 1988.

Après cette date, une compression semble avoir été introduite et l'en-tête a été modifié par la suite.

Cette compression sera discutée ultérieurement.

Tout le texte qui peut être imprimé à l'écran à partir d'un script logique est stocké sous une forme cryptée à la fin du script logique.

Exemple: KQ1. Room 2.

 12 34    Signature
 01       vol.1
 5F 06    Length = 0x065F
 BA 02    Text start = 0x02BA

La section du code logique commence immédiatement après l'en-tête et se poursuit jusqu'au début de la section du message.

Trois séries de codes sont utilisées dans un script logique.

La plupart des codes ont entre un et sept arguments inclus. Nous y reviendrons plus loin.

La première série de codes correspond aux commandes AGI elles-mêmes énumérées dans les tableaux précédents et se situe dans la plage 0x00–0xB6.

La deuxième série de codes est la suivante :

À l'heure actuelle, ce sont les seuls codes de grande valeur que l'on rencontre. Les codes if et or sont comme des parenthèses, c'est-à-dire que le code sera au début et à la fin de la section de codes à laquelle il se réfère. L'exemple suivant l'illustre :

Exemple: KQ1, Room 2.

   FF      'if' conditions start.
   07      07 = isset
   05      05 = flag 5
   FF      'if' conditions close.

que l'on peut traduire comme ci-dessous:

if (isset(5))

ce code test si le “flag” numero 5 est actif. Le 0xFF fait passer l'interpréteur en mode de vérification des conditions, ce qui nous amène à la série de codes énumérés dans les tableaux suivants

 0x00 - 0x12    Condition codes.

Lorsque l'interprète rencontre un 0xFF, il interprète les valeurs de code suivantes comme étant dans la plage de codes de condition jusqu'à ce qu'il rencontre le 0xFF suivant, ce qui le ramène en mode de commande AGI normal. normal de l'AGI.

Les deux octets qui suivent immédiatement le deuxième 0xFF déterminent le nombre d'octets que dure cette instruction if avant que le if ne se termine.

Lorsque le deuxième 0xFF est rencontré, l'interprète, que ce soit nous ou la machine, fait trois choses. l'interprète, que ce soit nous ou la machine, fait trois choses :

1. Il lit les deux octets suivants.
2. Il ouvre une parenthèse.
3. Il passe en mode de commande AGI.

Exemple: KQ1, Room 2.

FF 07 05 FF    if (isset(5))
84 00          {			// For 0x0084 bytes.
18 00              load.pic(0);
19 00              draw.pic(0);
1B 00              discard.pic(0);
...		   ...
               }			// Closed. 0x0084 bytes counted.

L'instruction else continue toujours après un bloc de crochets if.

Cette caractéristique est importante et a causé un certain nombre de problèmes dans le passé.

Lorsqu'une instruction else suit une instruction if, la distance entre les crochets après l'instruction if sera plus longue de trois octets (ceci est une conséquence de la manière dont l'interpréteur gère les codes if et else, ce qui est discuté plus loin).

voici un exemple:

if (isset(231)) {                          FF 07 E7 FF 05 00
    printf("The door is already open.");   65 0F
}
else {                                     FE 11 00
    set(36);                               0C 24
    prevent.input();                       77
    start.update(5);                       3B 05
    assignn(152, 3);                       03 98 03
    cycle.time(5, 152);                    4C 05 98
    end.of.loop(5, 232);                   49 05 E8
    sound(70, 154);                        63 46 9A
}

En général, on s'attend à ce que la distance entre les crochets soit de 0x0002, mais dans le cas ci-dessus, elle est clairement de 0x0005, ce qui illustre la différence entre une instruction if directe et une structure if..else.

La situation est la même pour les structures if..else imbriquées.

Les instructions else elles-mêmes ressemblent beaucoup aux instructions if, sauf que leur condition de test est donnée après le code 0xFE, mais est l'inverse de la condition donnée par l'instruction if ci-dessus.

Seule la distance entre les crochets est donnée après le code 0xFE et ensuite l'horloge de commande AGI que l'instruction else englobe.

Les conditions peuvent être de l'un des types suivants:

 FF 07 05 FF                         Une condition testée, c'est-à-dire isset(5)
 FF FD 07 05 FF                      Une condition Inversée (NOT), c'est-à-dire !isset(5)
 FF 07 05 07 06 FF                   Plusieurs conditions, liée par un ET logique (AND).
 FF FC 07 05 07 06 FC FF             Plusieurs conditions, liée par un OU logique (OR).
 FF FC 07 06 07 06 FC FD 07 08 FF    Combination.

Ces conditions se traduisent comme ceci:

if (isset(5))
if (!isset(5))
if (isset(5) && isset(6))
if (isset(5) || isset(6))
if ((isset(5) || isset(6)) && !isset(7))

Si plusieurs expressions booléennes sont regroupées, leurs valeurs respectives sont combinées ensemble par un ET logique (AND).

Si plusieurs expressions booléennes sont regroupées et entourées d'une paire de codes 0xFC, leurs valeurs sont combinées. leurs valeurs sont combinées par un OU logique (OR).

Le code 0xFD ne s'applique qu'au code de condition suivant dont il inverse la valeur booléenne.

Vous vous demandez peut-être comment l'interpréteur sait combien d'arguments possède chaque code (ou fonction) et quel type d'argument est associé à chaque argument.

Cette information est stockée dans le fichier agidata.ovl de la version MS-DOS.

Dans ce fichier, il y a un tableau qui contient quatre octets pour chaque commande AGI et chaque code de condition.

Ces quatre octets sont interprétés comme suit :

Le type de valeur des arguments est interprété comme suit :

 Bit        7     6     5     4     3     2     1       0
 command( arg1, arg2, arg3, arg4, arg5, arg6, arg7); (unknown)

Si le bit est activé, l'argument est interprété comme une variable ; sinon, l'argument est interprété comme un nombre.

La fonction du bit 0 n'est pas connue, car aucune commande AGI ni aucun code de condition AGI n'a plus de sept arguments.

Examples:

• 0x80 Indique que le premier argument de la commande est une variable.
• 0x60 Indique que les deuxième et troisième arguments sont des nombres variables.

La section des messages d'un script logique contient toutes les chaînes qui peuvent être affichées par ce script logique.

Ces chaînes sont cryptées par XOR tous les onze octets avec la chaîne “Avis Durgan”.

Exemple: KQ1, Room 2.

if (said(look, alligators))
{
    print("The alligators are swimming in the moat.");
}

Dans l'exemple ci-dessus, l'instruction d'impression est représentée comme suit :

 65 08

Le 0x08 est le numéro attribué à la chaîne et correspond à sa position dans la liste des chaînes à la fin du script logique.

Le format de la section message est le suivant :

The implementation for each AGI statement is found in the agi/ file. This is the AGI interpreter itself. The data in the agidata.ovl file is used to find the start of the implementation for an AGI statement. Below are a couple of examples:

Example: MH2, equaln.

;equaln   (eg.   if (work = 3)   )
0D71 AC            LODSB                       ;get variable number
0D72 32FF          XOR     BH,BH
0D74 8AD8          MOV     BL,AL
0D76 AC            LODSB                       ;get test number
0D77 3A870900      CMP     AL,[BX+0009]        ;test if var = number
0D7B B000          MOV     AL,00               ;return 0 if not equal
0D7D 7502          JNZ     0D81
0D7F FEC0          INC     AL                  ;return 1 if equal
0D81 C3            RET

Example: MH2, equalv.

;equalv  (eg.   if (work = maxwork)   )
0D82 AC            LODSB                       ;get first var number
0D83 32FF          XOR     BH,BH               ;clear bh
0D85 8AD8          MOV     BL,AL               ;BX = variable number
0D87 8AA70900      MOV     AH,[BX+0009]        ;get first var value
0D8B AC            LODSB                       ;get second var number
0D8C 8AD8          MOV     BL,AL
0D8E 32C0          XOR     AL,AL               ;return 0 if not equal
0D90 3AA70900      CMP     AH,[BX+0009]        ;compare variables
0D94 7502          JNZ     0D98
0D96 FEC0          INC     AL                  ;return 1 if equal
0D98 C3            RET

These two examples show the difference between how numbers and variables are dealt with. In the case of a variable, the variables number is used as an index into the table of variable values to get the value which is being tested. It appears that the variable table is at offset 0x0009 in the data segment.

The following 8086 assembly language code is the actual code from the MS-DOS version of Manhunter: San Francisco. There are some calls to routines which aren't displayed. Take my word for it that they do what the comment says. For those of you who can't follow whats going on, I'll explain the interpretation in steps after the code block.

;Decoding a LOGIC file.
1E6C:2EF2 56            PUSH  SI
1E6C:2EF3 57            PUSH  DI
1E6C:2EF4 55            PUSH  BP
1E6C:2EF5 8BEC          MOV   BP,SP
1E6C:2EF7 83EC02        SUB   SP,+02
1E6C:2EFA 8B7608        MOV   SI,[BP+08]    ;SI -> start of LOGIC script.
1E6C:2EFD 8B7406        MOV   SI,[SI+06]    ;Skip first 6 bytes (header).
1E6C:2F00 AC            LODSB               ;Get next byte in LOGIC file.
1E6C:2F01 84C0          TEST  AL,AL         ;Is code a zero?
1E6C:2F03 7414          JZ    2F19          ;If so, jump to exit.
1E6C:2F05 3CFF          CMP   AL,FF         ;If an opening 'if' code is found
1E6C:2F07 7419          JZ    2F22          ;jump to 'if' handler.
1E6C:2F09 3CFE          CMP   AL,FE         ;If an 'else' has not been found
1E6C:2F0B 7505          JNZ   2F12          ;jump over else/branch.
1E6C:2F0D AD            LODSW               ;Get word (bracket distance)
1E6C:2F0E 03F0          ADD   SI,AX         ;Add to SI. Skip else code.
1E6C:2F10 EBEE          JMP   2F00          ;Go back to get next byte.
1E6C:2F12 E8A8D6        CALL  05BD          ;Execute AGI command.
1E6C:2F15 85F6          TEST  SI,SI         ;
1E6C:2F17 75E8          JNZ   2F01          ;Jump back to top.
1E6C:2F19 8BC6          MOV   AX,SI
1E6C:2F1B 83C402        ADD   SP,+02
1E6C:2F1E 5D            POP   BP
1E6C:2F1F 5F            POP   DI
1E6C:2F20 5E            POP   SI
1E6C:2F21 C3            RET
 
;Handler for 'if' statement.
;BH determines if its in an OR bracket (BH=1 means OR).
;BL determines the nature of the evalutation (BL=1 means NOT)
1E6C:2F22 33DB          XOR   BX,BX
1E6C:2F24 AC            LODSB               ;Get next byte
1E6C:2F25 3CFC          CMP   AL,FC         ;If less than 0xFC, then
1E6C:2F27 721C          JB    2F45          ;jump to normal processing.
1E6C:2F29 7508          JNZ   2F33          ;If greater, jump to 'if' close.
1E6C:2F2B 84FF          TEST  BH,BH         ;(Could BH be the evaluation reg?
1E6C:2F2D 7551          JNZ   2F80          ;or whether its the second FC?
1E6C:2F2F FEC7          INC   BH            ;
1E6C:2F31 EBF1          JMP   2F24          ;Go back to get next byte.
 
1E6C:2F33 3CFF          CMP   AL,FF         ;Is the code for an 'if' close?
1E6C:2F35 7505          JNZ   2F3C          ;If not, jump to 'not' test.
1E6C:2F37 83C602        ADD   SI,+02        ;
1E6C:2F3A EBC4          JMP   2F00          ;
1E6C:2F3C 3CFD          CMP   AL,FD         ;Is the code for a 'not'?
1E6C:2F3E 7505          JNZ   2F45          ;If not, jump to test command.
1E6C:2F40 80F301        XOR   BL,01         ;
1E6C:2F43 EBDF          JMP   2F24          ;Go back to get next byte.
1E6C:2F45 53            PUSH  BX            ;BX = test conditions??
1E6C:2F46 E8E8DD        CALL  0D31          ;Evaluate separate test command.
1E6C:2F49 5B            POP   BX            ;
1E6C:2F4A 32C3          XOR   AL,BL         ;Toggle the result for NOT.
1E6C:2F4C B300          MOV   BL,00         ;
1E6C:2F4E 7506          JNZ   2F56          ;If true jump to 2F56.
1E6C:2F50 84FF          TEST  BH,BH         ;If BH=0 then not in OR and
1E6C:2F52 742C          JZ    2F80          ;test is truely false.
1E6C:2F54 EBCE          JMP   2F24          ;Otherwise evaluate next OR.
1E6C:2F56 84FF          TEST  BH,BH         ;Are we in OR mode?
1E6C:2F58 7424          JZ    2F7E          ;If not, continue with testing.
1E6C:2F5A 32FF          XOR   BH,BH         ;If so, then we will skip the
1E6C:2F5C 32E4          XOR   AH,AH         ;rest of the tests in the OR
1E6C:2F5E AC            LODSB               ;bracket since the first is true.
1E6C:2F5F 3CFC          CMP   AL,FC         ;OR: Waiting for closing OR.
1E6C:2F61 741B          JZ    2F7E          ;If OR found, then continue testing.
1E6C:2F63 77F9          JA    2F5E          ;
1E6C:2F65 3C0E          CMP   AL,0E         ;If 'said' then goto said handler
1E6C:2F67 7507          JNZ   2F70          ;else goto normal handler
1E6C:2F69 AC            LODSB               ;Work out number of words in said
1E6C:2F6A D1E0          SHL   AX,1          ;and jump over them.
1E6C:2F6C 03F0          ADD   SI,AX         ;
1E6C:2F6E EBEE          JMP   2F5E          ;
1E6C:2F70 8BF8          MOV   DI,AX         ;Jumps over arguments.
1E6C:2F72 D1E7          SHL   DI,1          ;
1E6C:2F74 D1E7          SHL   DI,1          ;
1E6C:2F76 8A856407      MOV   AL,[DI+0764]  ;Load up the number of arguments
1E6C:2F7A 03F0          ADD   SI,AX         ;Add to the execution pointer
1E6C:2F7C EBE0          JMP   2F5E          ;
1E6C:2F7E EBA4          JMP   2F24
 
;Test is false.
;This routine basically skips over the rest of the codes until it finds the
;closing 0xFF at which point it will load the following two bytes and add
;them to the execution pointer SI.
1E6C:2F80 32FF          XOR   BH,BH
1E6C:2F82 32E4          XOR   AH,AH
1E6C:2F84 AC            LODSB               ;
1E6C:2F85 3CFF          CMP   AL,FF         ;If the closing 0XFF is found,
1E6C:2F87 741D          JZ    2FA6          ;jump 2FA6.
1E6C:2F89 3CFC          CMP   AL,FC         ;If greater than FC,
1E6C:2F8B 73F7          JNB   2F84          ;get next byte.
1E6C:2F8D 3C0E          CMP   AL,0E         ;If 'said' then goto said handler
1E6C:2F8F 7507          JNZ   2F98          ;else goto normal handler.
1E6C:2F91 AC            LODSB               ;Work out number of words in said
1E6C:2F92 D1E0          SHL   AX,1          ;and jump over them.
1E6C:2F94 03F0          ADD   SI,AX
1E6C:2F96 EBEC          JMP   2F84
1E6C:2F98 8AD8          MOV   BL,AL         ;Jump over arguments.
1E6C:2F9A D1E3          SHL   BX,1
1E6C:2F9C D1E3          SHL   BX,1
1E6C:2F9E 8A876407      MOV   AL,[BX+0764]  ;Load up the number of arguments.
1E6C:2FA2 03F0          ADD   SI,AX         ;Add to the execution pointer.
1E6C:2FA4 EBDE          JMP   2F84
1E6C:2FA6 AD            LODSW
1E6C:2FA7 03F0          ADD   SI,AX         ;Skip over if (includes 3 else bytes)
1E6C:2FA9 E954FF        JMP   2F00

Situation 1. Every logic script starts in normal AGI command execution mode. In this routine, if the code is below 0xFC, then it is presumed to be an AGI command. It will then call the main command execution routine which will jump to the relevant routine for the specific command using the jump table stored in agidata.ovl. The command is performed and it returns to the main execution routine where it loops back to the top and deals with the next code in the logic file.

Situation 2. If the code is an 0xFF code, then if jumps to the if statement handler. In this routine is basically assesses whether the whole test condition evaluates to true or to false. It does this by treating each test separately and calling the relevant test command routines using the jump table in the agidata.ovl file. Each test command routine will return a value in AL which says whether it is true or not. Depending on the NOTs and ORs, the whole expression is evaluated. If at any stage during the evaluation the routine decides that the expression will be false, it exits to another routine which skips the rest of the if statement and then adds the two byte word following the closing 0xFF code to the execution pointer. This usually has the affect of jumping over the if block of code. If the if handler gets to the ending 0xFF then it knows the expression is true simply because it hasn't exited out of the routine yet. At this stage it jumps over the two bytes following the closing 0xFF and then goes back to executing straight AGI commands.

Situation 3. If in the normal execution of AGI commands, the code 0xFE is encountered, a very simple action takes place. The two bytes which follow form a 16-bit twos complement value which is added to execution pointer. This is all it does. Previously we said that the 0xFE code stood for the else statement which is in actual fact correct for over 90% of the time, but the small number of other occurrences are best described as goto statements. If you're confused by this, the following example will probably explain things.

Example:

if (said( open, door)) {
    // first block of AGI statements
}
else {
    // second block of AGI statements
}

The above example is how the original coder would have written the AGI code. If we now look at the following example, it is not hard to see that it would achieve the same thing.

if (!said( open, door)) goto label1;
    // first block of AGI statements
    goto label2:
 
label1:
    // second block of AGI statements
 
label2:

This is exactly how all ifs and elses are implemented in the logic code. The if statement is a conditional branch where the branch is taken if the condition is not met, while the else statement is a nonconditional jump. If a 0xFE code appears in the middle of some AGI code and wasn't actually originally coded as an else, then it was most likely a goto statement.

The above assembly language code does raise a very important point. The said command can have a variable number of arguments. Its code is 0x0E, and the byte following this byte gives the number of two byte words that follow as parameters.

Examples:

if (said(marble))                          FF 0E 01 1E 01 FF
if (said( open, door))                     FF 0E 02 37 02 73 00 FF

In the above examples, the values 0x011E, 0x0237, and 0x0073 are just random word numbers that could stand for the words given.

At first I almost totally discarded the existence of loops in the AGI code because it seemed to me that execution of the logic script continually looped. Loop code like “while”, “do..while”, and “for” statements wouldn't be needed because you could just use a variable to increment with each pass and an if statement to test the value of the variable and take action if it was withing the desired range.

Example:

if (greatern(30, 45) && lessn(30, 55)) {
    print("You're in the hot zone!");
    increment(30);
}

I have found evidence of this sort of thing taking place which means that they must loop over continuously. I don't know whether this is something that the interpreter does itself or whether it is part of the AGI code, e.g. at the end of one logic script it calls another which then calls the first one again. With the existence of the conditional branching and unconditional branching nature of the if and else statement, it is easy to see that some of the structures such as “do..while” can infact be coded into logic scripts.

Example:

FF FD 0D FF 03 00 FE F7 FF
 
do {
} while (!havekey);

The above translation is a simple one which is taken from SQ2. The value 0xFFF7 is the twos complement notation for -9 which is the exact branching value to take the execution back to the start of the if statement. If the above example had AGI code between the 0x00 and the 0xFE, then there would be code within the brackets of the “do..while” structure. I don't know whether the original AGI coders used these statements or used goto statements to achieve the same result.