Difference between revisions of "AGI Logic Language Reference"

From AGI Wiki
Jump to navigationJump to search
(Much of the information on the commands is either incomplete or incorrect here; up to date and detailed infomration on commands are available as separate wiki pages.)
 
Line 299: Line 299:
  
 
The return command is just a normal action command (number 0), with no arguments. This must be the last command in every script.
 
The return command is just a normal action command (number 0), with no arguments. This must be the last command in every script.
 
<<span id="Sample"></span>
 
  
 
==Discussion of sample LOGIC code from KQ4==
 
==Discussion of sample LOGIC code from KQ4==

Latest revision as of 16:12, 27 March 2019

The script language

Source code conventions

This section lists conventions that will be adopted in the AGI script language description in this document. They may differ from Sierra's original syntax, but the resulting bytecode is strictly the same.

Commands and operators

Normal commands are specified by the command name followed by brackets which contain the arguments, separated by commas. A semicolon is placed after the brackets. The brackets are required even if there are no arguments. The arguments given must have the correct prefix for that type of argument as explained later in this document (this is to make sure the programmer does not use a var, for example, when they think they are using a flag).

    assign.v(v50,0);
    program.control();

Multiple commands may be placed on the one line:

   reset(f6); reset(f7);

Substitutions for the following action commands are available:

    increment(v30);       v30++;
    decrement(v30);       v30--;
    assignn(v30,4);       v30 = 4;
    assignv(v30,v32);     v30 = v32;
    addn(v30,4);          v30 = v30 + 4; or v30 += 4;
    addv(v30,v32);        v30 = v30 + v32; or v30 += v32;
    subn(v30,4);          v30 = v30 - 4; or v30 -= 4;
    subv(v30,v32);        v30 = v30 - v32; or v30 -= v32;
    mul.n(v30,4);         v30 = v30 * 4; or v30 *= 4;
    mul.v(v30,v32);       v30 = v30 * v32; or v30 *= v32;
    div.n(v30,4);         v30 = v30 / 4; or v30 /= 4;
    div.v(v30,v32);       v30 = v30 / v32; or v30 /= v32;
    lindirectn(v30,4);    *v30 = 4;
    lindirectv(v30,v32);  *v30 = v32;
    rindirect(v30,v32);   v30 = *v32;

Conditionals and tests

An if structure looks like this:

    if (<test commands>) {
        <action commands>
    }

or like this :

    if (<test commands>) {
        <action commands>
    }
    else {
      <more action commands>
    }

Multiple commands can be placed in a single line:

    if (<test commands>) { <action Commands> } else { <more action commands> }

Test commands are coded like action commands except there is no semicolon. They are separated by && or || for AND or OR.

    if (isset(f5) &&
        greatern(v5,6)) { ......
Multiple tests can be placed in a single line within the if statement:
    if (lessn(v5,6) && (greatern(v5,2)) { .......

    if (isset(f90) && equalv(v32,v34)
        && greatern(v34,20)) { .......

A ! placed in front of a command negates its result:

    if (!isset(f7)) {
      ......

Boolean expressions are not necessarily simplified so they must follow the rules set down by the file format. If test commands are to be ORred together, they must be placed in brackets.

    if ((isset(f1) || isset(f2)) {
      ......

    if (isset(f1) && (isset(f2) || isset(f3))) {
      ......

    if (isset(1) || (isset(2) && isset(3))) {    // is NOT legal

Depending on the compiler, simplification of boolean expressions may be supported, so the above may not apply in all cases (although if these are rules are followed then the logic will work with all compilers).

The following test commands and operations are equivalent:

    equaln(v30,4)         v30 == 4
    equalv(v30,v32)       v30 == v32
    greatern(v30,4)       v30 > 4
    greaterv(v30,v32)     v30 > v32
    lessn(v30,4)          v30 < 4
    lessv(v30,v32)        v30 < v32
    !equaln(v30,4)        v30 != 4
    !equalv(v30,v32)      v30 != v32
    !greatern(v30,4)      v30 <= 4
    !greaterv(v30,v32)    v30 <= v32
    !lessn(v30,4)         v30 >= 4
    !lessv(v30,v32)       v30 >= v32

Also, flags can be tested for by just using the name of the flag:

    if (f6) { .....

    if (v7 > 0 && !f6) { .....

Argument types

There are 9 different types of arguments that commands use:

  • Number (no prefix)
  • Var (prefix "v")
  • Flag (prefix "f")
  • Message (prefix "m")
  • Object (prefix "o")
  • Inventory Item (prefix "i")
  • String (prefix "s")
  • Word (prefix "w")
  • Controller (prefix "c")

The said test command uses its own special arguments which will be described later.

Each of these types of arguments is given by the prefix and then a number from 0--255, e.g. v5, f6, m27, o2.

The "word" type is words that the player has typed in, not words that are stored in the words.tok file. Strings are the temporary string variables stored in memory, not to be confused with messages (that are stored in the LOGIC resources). Controllers are menu items and keys.

Compilers can enforce type checking, so that the programmer must use the correct prefix for an argument so that they know they are using the right type. Decoders should display arguments with the right type.

    move.obj(so4,80,120,2,f66);
    if (obj.in.box(so2,30,60,120,40)) { .....

A complete list of the commands and their argument types is available in Command list and argument types table.

Messages and inventory items may be given in either numerical text format:

    print("He's not here.");
    print(m12);
    if (has("Jetpack")) { .....
    if (has(io9)) { .....

Messages can also be split over multiple lines:

    print("This message is split "
          "over multiple lines.");

Quote marks must be used around messages and object names. This is important because some messages or object names may contain brackets or commas, which could confuse the compiler. This is also the case for the said command which will be described shortly.

    if (has("Buckazoid(s)")) { .....        // no ambiguity here about where
                                            // the argument ends

The said test command uses different parameters to all the other commands. Where as the others use 8 bit arguments (0--255), said takes 16 bit arguments (0--65535). Also, the number of arguments in a said command can vary. The numbers given in the arguments are the word group numbers from the words.tok file.

    if (said(4,80)) { .....

Words can also be given in place of the numbers:

    if (said("look")) { .....
    if (said("open","door")) { .....

Quote marks must also be used around the words.

Labels and the goto command

Labels are given like this:

    Label1:

The label name can contain letters, numbers, and the characters "_" and ".". No spaces are allowed. The goto command takes one parameter, the name of a label.

    goto(Label1);

Comments

There are three ways that comments can be used.

    // Rest of line is ignored
    [  Rest of line is ignored
    /* Text between these are ignored */

The /*...*/ can be nested:

    /* comment start
      print("Hello");    // won't be run
      /*                 // a new comment start (will be ignored!)
        v32 = 15;        // won't be run
      */                 // uncomments the most inner comment
      print("Hey!");     // won't be run, still inside comments
    */                   // uncomments

Defines

To give vars, flags etc. proper names the #define command is used. The name of the define is given followed by the define value:

    #define ego o0
    #define room_descr "This is a large hall with tall pillars down each side."

Then the define name can be used in place of the define value:

    draw(ego);
    print(room_descr);

Define names can only be used in arguments of commands (including gotos and the v0 == 3 type syntax), although some compilers may allow you to use them anywhere.

Defines must be defined in the file before they are used.

The define name can contain letters, numbers, and the characters '_' and .. No spaces are allowed.

Including files

You can include another file in your logic source code by using the #include command:

    #include "file.txt"

When the compiler encounters the above line, it will replace it with the contents of file.txt.

It is a good idea to have all the defines that you need for multiple logics in an #include file, so if you need to change the define value you only have to do it once (although you will need to recompile all logics that use that define). More on messages

In some cases you may want to assign a specific number to a message so you can refer to it in other places. This is done by using the #message command, followed by the number of the message then the message itself:

    #message 4 "You can't do that now."

Then you can give the message number as the parameter in commands:

    print(m4);

Or embed the message in commands as normal and the number you assigned to it before will be used:

    print("You can't do that now.");
  1. message can be used anywhere in the file, so you do not have to set the message before you use it.

The return command

The return command is just a normal action command (number 0), with no arguments. This must be the last command in every script.

Discussion of sample LOGIC code from KQ4

(Last updated: 31 August 1997).

Some of you may know that "The Official Book of King's Quest" included three small fragments of AGI code for room 7 in the AGI version of KQ4. These fragments are given below along with the same fragments taken from the game itself. There are a few differences which is to be expected but generally the code is very similar. These examples show how the coder wrote the code and what it now looks like in the final product. I've included a few comments where some interesting observations can be seen. Animating the smoke

From the book:

animate.obj(smoke);
ignore.horizon(smoke);
set.view(smoke, v.fish.cabin);
set.loop(smoke, 1);
ignore.blocks(smoke);
position(smoke, 95, 16);
work = 3;
step.time(smoke, work);
cycle.time(smoke, work);
draw(smoke);

From the game:

animate.obj(7);
ignore.horizon(7);
set.view(7, 114);
set.loop(7, 1);
ignore.objs(7);                // These two lines have been added.
set.priority(7, 5);            //
ignore.blocks(7);
position(7, 95, 16);
assignn(152, 3);               // Equivalent to 'work = 3;'
step.time(7, 152);
cycle.time(7, 152);
draw(7);

Opening the door

From the book:

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);
  }
}

From the game:

if (said(OPEN, DOOR||DOORS||DOORWAY||DOORWAYS)) {
  if (posn(0, 86, 120, 106, 133)) {
    if (!isset(38)) {
      if (isset(231)) {
        print("The door is already open.");
      }
      else {
        set(36);
        prevent.input();
        start.update(5);
        assignn(152, 3);
        cycle.time(5, 152);
        end.of.loop(5, 232);
        sound(70, 154);
      }
    }
    else {
      print("You can't.  It's locked and you
             don't have the key.");
    }
  }
  else {
    set(113);
  }
}

Unlocking the door

From the book:

if (said( unlock, door)) {     // must be close enough
  if (posn( ego, 86, 120, 106, 133)) {
    if (!night) {
      print("The door is already unlocked. . .");
    }
    else {
      printf("You can't, it's locked. . .");
    }
  }
  else {
    set( notCloseEnough);
  }
}

From the game:

if (said(UNLATCH||UNLOCK, DOOR||DOORS||DOORWAY||DOORWAYS)) {
  if (posn(0, 86, 120, 106, 133)) {
    if (!isset(38)) {
      print("The door is already unlocked.");
    }
    else {
      print("You can't.  It's locked and you
             don't have the key.");
    }
  }
  else {
    set(113);
  }
}

Knocking on the door

From the book:

if ((said( knock, at, door) || said( knock) ||
     said( knock, on, door) || said( knock, door)) {
  if (posn( ego, 86, 120, 106, 133)) {
    if (!night) {
      print("You knock on the door. . .
             a woman says. . .");
    }
    else {
      printf("You knock on the. . .
              a man calls out. . .");
    }
  }
  else {
    set( notCloseEnough);
  }
}

From the game:

if (said(BANG||KNOCK||RAP||TAP) ||
    said(BANG||KNOCK||RAP||TAP, DOOR||DOORS||DOORWAY||DOORWAYS)) {
  if (posn(0, 86, 120, 106, 133)) {
    if (!isset(38)) {
      print("You assertively knock on the shanty
             door.  A woman's voice answers, "Jest come on in!"");
    }
    else {
      print("You assertively knock on the shanty
             door.  From inside, a man's voice calls out, "D'ya know
             what TIME it is?!  GO AWAY!!"");
    }
  }
  else {
    set(113);
  }
}

Fall rocks

File:Agispec-kq4 fall rocks.png
King's Quest IV fall rocks

From the book:

if (hit.special) {
  if ((rf2 || rf3 || rf4)) {
    reset(hit.special);
    get.posn(ego, priorx, priory);
    position.f(dude, priorx, priory);
    ignore.blocks(dude);
    set( game.control);
    set.view( dude, v.ego.land);
    if ((ego.dir == 3 || ego.dir == 4)) {
      set.loop( dude, 2);
    }
    else {
      set.loop( dude, 3);
    }
    fix.loop(dude);
    work = 3;
    step.size( dude, work);
    work = 3;
    cycle.time( dude, work);
    start.cycling(dude);
    erase(ego);
    draw(dude);
    if (rf3) {
      work6 = 0;
      move.obj.f( dude, tempx, tempy, work6, fall.done);
    }
    if (rf4) {
      work6 = 0;
      move.obj.f( dude, tempx, tempy, work6, fall.done);
    }
    if (rf2) {
      if (priory < 125) {
        set.priority( dude, 9);
        tempy=132;
        work6=0;
        move.obj.f( dude, ego,x, tempy, work6, fall.done);
      }
      else {
        set.priority(dude, 15);
        tempy = 156;
        work6 = 0;
        move.obj.f( dude, ego.x, tempy, work6, fall.done);
      }
    }
  }
}

From the game:

if (isset(3)) {     [ hit.special
  if (isset(222) || isset(223) || isset(224)) {     // rf2, rf3, rf4
    reset(3);
    sound(51, 154);
    get.posn(0, 134, 135);
    position.v(12, 134, 135);
    ignore.blocks(12);
    set(36);
    prevent.input();
    set.view(12, 11);
    if (equaln(6, 3) || equaln(6, 4)) {
      set.loop(12, 2);
    }
    else {
      set.loop(12, 3);
    }
    fix.loop(12);
    assignn(152, 3);
    step.size(12, 152);
    assignn(152, 3);
    cycle.time(12, 152);
    start.cycling(12);
    erase(0);
    draw(12);
    if (isset(223)) {
      assignn(158, 0);
      move.obj.v(12, 107, 108, 158, 226);
    }
    if (isset(224)) {
      assignn(158, 0);
      move.obj.v(12, 107, 108, 158, 226);
      set.priority(12, 14);
    }
    if (isset(222)) {
      if (lessn(135, 125)) {
        set.priority(12, 9);
        assignn(108, 132);
        assignn(158, 0);
        move.obj.v(12, 33, 108, 158, 226);
      }
      else {
        set.priority(12, 14);
        assignn(108, 158);
        assignn(158, 0);
        move.obj.v(12, 33, 108, 158, 226);
      }
    }
  }
}