Difference between revisions of "AGIWiki/Logic syntax"

From ScummVM :: Wiki
Jump to navigation Jump to search
m
m (Text replacement - "<source lang=" to "<syntaxhighlight lang=")
Line 9: Line 9:
 
Normal action commands are specified by the command name followed by parentheses which contain the arguments, separated by commas. A semicolon is placed after the parentheses. The parentheses 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 [[AGIWiki/Variable|variable]], for example, when they think they are using a [[AGIWiki/Flag|flag]]).
 
Normal action commands are specified by the command name followed by parentheses which contain the arguments, separated by commas. A semicolon is placed after the parentheses. The parentheses 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 [[AGIWiki/Variable|variable]], for example, when they think they are using a [[AGIWiki/Flag|flag]]).
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
assign.v(v50,0);
 
assign.v(v50,0);
  
Line 17: Line 17:
 
Multiple commands may be placed on the one line:
 
Multiple commands may be placed on the one line:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
reset(f6); reset(f7);
 
reset(f6); reset(f7);
 
</source>
 
</source>
Line 23: Line 23:
 
Substitutions for the following action commands are available:
 
Substitutions for the following action commands are available:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
increment(v30);      v30++;
 
increment(v30);      v30++;
 
decrement(v30);      v30--;
 
decrement(v30);      v30--;
Line 46: Line 46:
 
An if structure looks like this:
 
An if structure looks like this:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (test commands) {
 
if (test commands) {
 
   action commands
 
   action commands
Line 54: Line 54:
 
or like this
 
or like this
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (test commands) {
 
if (test commands) {
 
   action commands
 
   action commands
Line 65: Line 65:
 
Carriage returns are not necessary:
 
Carriage returns are not necessary:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (test commands) { action Commands } else { more action commands }
 
if (test commands) { action Commands } else { more action commands }
 
</source>
 
</source>
Line 72: Line 72:
 
Test commands are coded like action commands except there is no semicolon. They are separated by <code>&&</code> or <code>||</code> for AND and OR, respectively:
 
Test commands are coded like action commands except there is no semicolon. They are separated by <code>&&</code> or <code>||</code> for AND and OR, respectively:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (isset(f5) &&
 
if (isset(f5) &&
 
     greatern(v5,6)) { ......
 
     greatern(v5,6)) { ......
Line 79: Line 79:
 
Again, carriage returns are not necessary within the if statement:
 
Again, carriage returns are not necessary within the if statement:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (lessn(v5,6) && (greatern(v5,2)) { .......
 
if (lessn(v5,6) && (greatern(v5,2)) { .......
  
Line 88: Line 88:
 
A&nbsp;! placed in front of a command signifies a NOT.
 
A&nbsp;! placed in front of a command signifies a NOT.
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (!isset(f7)) {
 
if (!isset(f7)) {
 
   ......
 
   ......
Line 95: Line 95:
 
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.
 
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.
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if ((isset(f1) || isset(f2)) {
 
if ((isset(f1) || isset(f2)) {
 
   ......
 
   ......
Line 109: Line 109:
 
Substitutions for the following test commands are available:
 
Substitutions for the following test commands are available:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
equaln(v30,4)      v30 == 4
 
equaln(v30,4)      v30 == 4
 
equalv(v30,v32)    v30 == v32
 
equalv(v30,v32)    v30 == v32
Line 126: Line 126:
 
Also, flags can be tested for by just using the name of the flag:
 
Also, flags can be tested for by just using the name of the flag:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (f6) { .....
 
if (f6) { .....
  
Line 134: Line 134:
 
which is equivalent to:
 
which is equivalent to:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (isset(f6)) { .....
 
if (isset(f6)) { .....
  
Line 192: Line 192:
 
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.
 
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.
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
move.obj(o4, 80, 120, 2, f66);
 
move.obj(o4, 80, 120, 2, f66);
  
Line 202: Line 202:
 
Messages and inventory items may be given in either numerical or text format:
 
Messages and inventory items may be given in either numerical or text format:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
print("He's not here.");
 
print("He's not here.");
  
Line 214: Line 214:
 
Messages can also be split over multiple lines:
 
Messages can also be split over multiple lines:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
print("This message is split "
 
print("This message is split "
 
       "over multiple lines.");
 
       "over multiple lines.");
Line 221: Line 221:
 
Quote marks must be used around messages and inventory item names. This is important because some messages or inventory item names may contain parentheses or commas, which could confuse the compiler. This is also the case for the said command which will be described shortly.
 
Quote marks must be used around messages and inventory item names. This is important because some messages or inventory item names may contain parentheses or commas, which could confuse the compiler. This is also the case for the said command which will be described shortly.
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (has("Buckazoid(s)")) { .....  // no ambiguity here about where
 
if (has("Buckazoid(s)")) { .....  // no ambiguity here about where
 
                                   // the argument ends
 
                                   // the argument ends
Line 230: Line 230:
 
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.
 
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.
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (said(4, 80)) { .....
 
if (said(4, 80)) { .....
 
</source>
 
</source>
Line 236: Line 236:
 
Words can also be given in place of the numbers:
 
Words can also be given in place of the numbers:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
if (said("look")) { .....
 
if (said("look")) { .....
  
Line 248: Line 248:
 
Labels are given like this:
 
Labels are given like this:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
Label1:
 
Label1:
 
</source>
 
</source>
Line 256: Line 256:
 
The [[AGIWiki/Goto|Goto]] command takes on parameter, the name of a label:
 
The [[AGIWiki/Goto|Goto]] command takes on parameter, the name of a label:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
goto(Label1);
 
goto(Label1);
 
</source>
 
</source>
Line 264: Line 264:
 
There are three ways that comments can be used.
 
There are three ways that comments can be used.
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
// - rest of line is ignored
 
// - rest of line is ignored
  
Line 274: Line 274:
 
The /*...*/ can be nested:
 
The /*...*/ can be nested:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
/* comment start
 
/* comment start
  
Line 304: Line 304:
 
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:
 
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:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
#message 4 "You can't do that now."
 
#message 4 "You can't do that now."
 
</source>
 
</source>
Line 310: Line 310:
 
Then you can give the message number as the parameter in commands:
 
Then you can give the message number as the parameter in commands:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
print(m4);
 
print(m4);
 
</source>
 
</source>
Line 316: Line 316:
 
Or embed the message in commands as normal and the number you assigned to it before will be used:
 
Or embed the message in commands as normal and the number you assigned to it before will be used:
  
<source lang="cpp">
+
<syntaxhighlight lang="cpp">
 
print("You can't do that now.");
 
print("You can't do that now.");
 
</source>
 
</source>

Revision as of 15:12, 25 October 2018

AGIWiki


This article describes the logic syntax for the C-like "official" AGI syntax described in the AGI Specs and supported by AGI Studio and WinAGI.

Note: The WinAGI development environment supports an alternate syntax, that is based on Microsoft's Visual Basic language, rather than the C language. At this time, the C-based syntax described in this article is the most widely-supported AGI logic syntax.

Action Commands

Normal action commands are specified by the command name followed by parentheses which contain the arguments, separated by commas. A semicolon is placed after the parentheses. The parentheses 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 variable, for example, when they think they are using a flag).

<syntaxhighlight lang="cpp"> assign.v(v50,0);

program.control(); </source>

Multiple commands may be placed on the one line:

<syntaxhighlight lang="cpp"> reset(f6); reset(f7); </source>

Substitutions for the following action commands are available:

<syntaxhighlight lang="cpp"> 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; </source>

If structures and test commands

An if structure looks like this:

<syntaxhighlight lang="cpp"> if (test commands) {

 action commands

} </source>

or like this

<syntaxhighlight lang="cpp"> if (test commands) {

 action commands

} else {

 more action commands

} </source>

Carriage returns are not necessary:

<syntaxhighlight lang="cpp"> if (test commands) { action Commands } else { more action commands } </source>


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

<syntaxhighlight lang="cpp"> if (isset(f5) &&

   greatern(v5,6)) { ......

</source>

Again, carriage returns are not necessary within the if statement:

<syntaxhighlight lang="cpp"> if (lessn(v5,6) && (greatern(v5,2)) { .......

if (isset(f90) && equalv(v32,v34) &&

   greatern(v34,20)) { .......

</source>

A ! placed in front of a command signifies a NOT.

<syntaxhighlight lang="cpp"> if (!isset(f7)) {

 ......

</source>

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.

<syntaxhighlight lang="cpp"> if ((isset(f1) || isset(f2)) {

 ......

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

 ......

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

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).

Substitutions for the following test commands are available:

<syntaxhighlight lang="cpp"> 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 </source>

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

<syntaxhighlight lang="cpp"> if (f6) { .....

if (v7 > 0 && !f6) { ..... </source>

which is equivalent to:

<syntaxhighlight lang="cpp"> if (isset(f6)) { .....

if (v7 > 0 && !isset(f6)) { ..... </source>

Argument types

There are 9 different types of arguments that commands use:

Type Prefix
Number (no prefix)

Variable

v

Flag

f

Message

m

Object

o

Inventory item

i

String

s

Word

w

Controller

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 represents words that the player has typed in (as opposed to 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.

<syntaxhighlight lang="cpp"> move.obj(o4, 80, 120, 2, f66);

if (obj.in.box(o2, 30, 60, 120, 40)) { ..... </source>

For a complete list of the commands and their argument types, see Logic commands by name.

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

<syntaxhighlight lang="cpp"> print("He's not here.");

print(m12);

if (has("Jetpack")) { .....

if (has(i9)) { .....

</source> Messages can also be split over multiple lines:

<syntaxhighlight lang="cpp"> print("This message is split "

     "over multiple lines.");

</source>

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

<syntaxhighlight lang="cpp"> if (has("Buckazoid(s)")) { ..... // no ambiguity here about where

                                  // the argument ends

</source>

If quote marks are part of the message or inventory object, a \ should be placed in front of these. To use a \, \\ should be used. \n can also be used for a new line.

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.

<syntaxhighlight lang="cpp"> if (said(4, 80)) { ..... </source>

Words can also be given in place of the numbers:

<syntaxhighlight lang="cpp"> if (said("look")) { .....

if (said("open","door")) { ..... </source>

Quote marks must also be used around the words.

Labels and the goto command

Labels are given like this:

<syntaxhighlight lang="cpp"> Label1: </source>

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

The Goto command takes on parameter, the name of a label:

<syntaxhighlight lang="cpp"> goto(Label1); </source>

Comments

There are three ways that comments can be used.

<syntaxhighlight lang="cpp"> // - rest of line is ignored

[ - rest of line is ignored

/* Text between these are ignored */ </source>

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

<syntaxhighlight lang="cpp"> /* 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

</source>

Note: the fact that these comments can be nested is very different from almost every other language that uses these types of comments, including C, C , and Java.

Defines

See Defines.

Including files

See Includes.

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:

<syntaxhighlight lang="cpp">

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

</source>

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

<syntaxhighlight lang="cpp"> print(m4); </source>

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

<syntaxhighlight lang="cpp"> print("You can't do that now."); </source>

#message can be used anywhere in the file, so you do not have to set the message before you use it.

For more details, see Message.

The return command

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

See also

Sources