Open main menu
ScummVM :: Wiki

Difference between revisions of "AGI/Specifications/Internals"

AGI/Specifications/Internals (view source)

Revision as of 19:59, 4 January 2009

2,165 bytes added ,  19:59, 4 January 2009
Wikifying. Adding missing bits from SGML. Work in Progress
(Added more info on v20, v22 and v26 (Amiga & Apple IIGS related values. Tested with XGS/32 and WinUAE).)
(Wikifying. Adding missing bits from SGML. Work in Progress)
Line 8: Line 8:
* 256 8 bit variables, numbered 0--255 (Var);
* 256 8 bit variables, numbered 0--255 (Var);
* 256 flags, numbered 0--255 (Flag);
* 256 flags, numbered 0--255 (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 objects controlled by the interpreter, one of which (the object 0, ego) may be controlled by the player;
* a number of inventory items;
* a number of inventory items;
* 12 40-character string variables (string).
* 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.
Variables 0 to 26 and flags 0 to 16 are reserved for internal use.
 
All others are available to be used by the programmer. The variables
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.
and flags are global to all scripts. Each variable, flag, object,
 
string, word, message, etc. has a unique ID number, and numbering of
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.
different data types is independent (for example, there can be a
 
variable number 5, a string number 5, and a flag number 5).
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==
==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)
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:
Here is a list of all the existing resources. Resources are used to represent:
Line 37: Line 36:
Let us now consider the interpreter algorithm and the purpose of reserved variables and flags.
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.
When the interpreter is started it loads script 0, not unloading it
until the end of the game execution. This script is then executed
over and over, and is responsible for sequencing all other scripts
according to the current room. Since script 0 is executed in all rooms,
it's common to handle actions that can happen in different places
directly on script 0, or in a script called from script 0 but not
associated to a specific room number.


In each cycle the interpreter performs the following basic actions:
In each cycle the interpreter performs the following basic actions:


* time delay;
# time delay;
* clears the keyboard buffer;
# clear the keyboard buffer;
* polls the keyboard and the joystick;
# poll the keyboard and the joystick;
* analyses some of the reserved variables and flags (see block diagram);
# 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;
# 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;
# 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;
# test if the '''new.room''' command has been issued;


then the cycle is repeated.
then the cycle is repeated.
Line 147: Line 152:


<span id="VariableTypes"></span>
<span id="VariableTypes"></span>
=Variable types=
=AGI data types=


Written by Lance Ewing, with additions/modifications by Claudio Matsuoka (Last updated: 22 May 1999).
Written by Lance Ewing, with additions/modifications by Claudio Matsuoka (Last updated: 22 May 1999).
Line 154: Line 159:
==Variable==
==Variable==


This is an unsigned eight-bit variable type equivalent of a byte, or unsigned char. Its values range from 0 to 255. There are 256 variables and in the LOGIC code (listed in section Variables used by the interpreter); they are numbered from 0 to 255 and are indentified by their number. (The original LOGIC source code that Sierra's programmers wrote would have had textual identifiers for these variables, but when the LOGIC source was compiled into the LOGIC codes, the original variable names were lost. To the interpreter, the variables are known by their index into the variable table.)
This is an unsigned eight-bit data type equivalent of a byte, or
unsigned char. Its values range from 0 to 255. There are 256 variables,
being the first 27 (listed in [[AGI/Specifications/Internals#tab-reserved-variables | Table 3-1]])
reserved for internal use by the interprter. On interpreter startup, all
variables are set to 0.
 
<span id="tab-reserved-variables"></span>
 
{| border="1"
|+ '''Table 3-1. Reserved variables'''
|-
! Variable
! Description
|-
| 0
| Current room number, initially 0
|-
| 1
| Previous room number
|-
| 2
| Code of the border touched by ego, according to [[AGI/Specifications/Internals#tab-border-code | Table 3-2]]
|-
| 3
| Current score
|-
| 4
| Number of the object, if not ego, that touched the border
|-
| 5
| Code of border touched by the object in '''v4'''
|-
| 6
| Direction of ego's motion
|-
| 7
| Maximum score
|-
| 8
| Number of free 256-byte pages of memory
|-
| 9
| Number of the word in the user message that was not found in the dictionary
|-
| 10
| Interpreter cycle time in 20ths of second
|-
| 11
| Seconds (in the internal clock)
|-
| 12
| Minutes (in the internal clock)
|-
| 13
| Hours (in the internal clock)
|-
| 14
| Days (in the internal clock)
|-
| 15
| Joystick sensitivity (if f8 == 1)
|-
| 16
| View resource associated with ego
|-
| 17
| Interpreter error code
|-
| 18
| Error code parameter
|-
| 19
| Key pressed on the keyboard
|-
| 20
| Computer type (see table XX)
|-
| 21
| Message window timer (if f15 == 0, the window is automatically closed after 0.5 * v21 seconds)
|-
| 22
| Sound type (see table XX)
|-
| 23
| Sound volume (0 to 15)
|-
| 24
| Input buffer size (default 41)
|-
| 25
| Number of inventory item selected using the '''status''' command or 255 if none
|-
| 26
| Monitor type (see table XX)
|}
 
<span id="tab-border-code"></span>
 
{| border="1"
|+ '''Table 3-2. Border codes'''
|-
! Code
! Description
|-
| 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
|}


Variables are the most commonly used type. They feature in arithmetic commands such as addition and multiplication, and a lot of AGI commands have a version that has variable paramaters as an alternative to the normal constant parameter versions.
==Flag==
==Flag==


Flags are the boolean type of the AGI system. Their value can be either 1 or 0 (true or false). There are 256 flags that are numbered 0 to 255. (In the original LOGIC source code, they would have had textual identifiers, but in the compiled LOGIC code they are known only by their index into the interpreters flag table.)
Flags are 1-bit boolean data types whose value can be either 1 or 0
(true or false). There are 256 flags numbered from 0 to 255. The
first 16 flags (listed in [[AGI/Specifications/Internals#tab-reserved-flags | Table 3-3]] are
reserved by the interpreter for internal use. On the interpreter startup,
all flags are set to 0.
 
<span id="reserved-flags"></span>
 
 
{|  class="CALSTABLE" border="1"<col><col>
|+ Table 3-3. Reserved flags
|-
! Flag
! Description
|-
| 0
| Ego's base line is completely on water
|-
| 1
| Ego is completely obscured by another object
|-
| 2
| The player has entered a command
|-
| 3
| Ego touched a trigger line
|-
| 4
| '''said''' accepted user input
|-
| 5
| Room script executed for the first time
|-
| 6
| '''restart.game''' has been executed
|-
| 7
| Writing to the script buffer is blocked
|-
| 8
| If set, '''v15''' determines joystick sensitivity
|-
| 9
| Sound is enabled
|-
| 10
| Built-in debugger is enabled
|-
| 11
| Logic 0 is executed for the first time
|-
| 12
| '''restore.game''' has been executed
|-
| 13
| '''status''' to select items
|-
| 14
| Enable menu
|-
| 15
| Enable non-blocking windows. If set, the message window is left on the screen, otherwise the message window is closed when '''ENTER''' or '''ESC''' are pressed. If '''v21''' is not zero, the window is closed automatically after '''v21''' * 500 milliseconds.
|-
| 16
| (Related to game restart)
|}


Flags are used to indicate when certain things have taken place.
==String==
==String==


According to another source, there are only 12 strings available. I don't know if this is true, but it agrees with the minimum amout of space set aside for strings that I have seen in examining memory usage during a game. However, the majority of AGI games have enough room for exactly 24 strings: AGI interpreter versions 2.089, 2.411, 3.002.107 and 3.002.149 have room for 12 strings, the remaining versions have room for 24 strings.
Strings are 40 characters long, including the zero terminator.
String number zero is the input prompt (e.g. <tt>">"</tt> or <tt>"]"</tt>).
The majority of AGI interpreters have enough room for exactly 24 strings:
AGI interpreter versions 2.089, 2.411, 3.002.107 and 3.002.149 have room
for 12 strings, the remaining versions have room for 24 strings.


Whether the versions that have enough space for 24 strings do infact support 24 strings is not known. Strings are 40 characters long which includes the zero terminator. String number zero is usually the input prompt (e.g. ">" or "]").
Whether the versions that have enough space for 24 strings do infact
support 24 strings is not known.


==Word==
==Word==


Words are the words that the user types in. An input sentence is composed of a number of words. The important words (e.g. for the sentence "look at the tree", "look" and "tree" are important) are assigned to the words variables corresponding to their place in the sentence once unimportant words and punctuation has been taken out. For example, in the earlier example word(1) would be "look" and word(2) would be "tree". Words can be converted to strings.
Words are the words that the user types in. An input sentence is composed of a number of words. The important words (e.g. for the sentence "look at the tree", "look" and "tree" are important) are assigned to the words variables corresponding to their place in the sentence once unimportant words and punctuation has been taken out. For example, in the earlier example word(1) would be "look" and word(2) would be "tree". Words can be converted to strings.
==Inventory Item==
==Inventory Item==


There are a number of AGI commands that refer to inventory items (e.g. get(), drop()). One of the arguments to these commands will represent an inventory item number. In the original LOGIC source text, the programmer would have written things like get(dagger) but the interpreter knows them only as an index into the OBJECT table.
There are a number of AGI commands that refer to inventory items (e.g. '''get()''', '''drop()'''). One of the arguments to these commands will represent an inventory item number. In the original LOGIC source text, the programmer would have written things like '''get(dagger)''' but the interpreter knows them only as an index into the OBJECT table.
 
==Object==
==Object==


There can be a bit of confusion between this type and the inventory item because of the name of the object file. The object file has almost nothing to do with what the interpreter generally calls objects. There are a large number of AGI commands that deal with objects. For example,
Objects are instances of View resources in use in a given room,
and essentially an entry in the view table. Many objects can use
the same view resource for its appearance (e.g. in KQ1 with the
crocodile filled moat). View table entries have positional and
sequential attributes that only make sense for a on-screen


<pre>
There can be a bit of confusion between this type and the inventory item because of the name of the '''object''' file. The '''object''' file has almost nothing to do with what the interpreter generally calls objects, such as '''move.obj''',
    move.obj
'''animate.obj''', '''set.view''', '''set.cel''', '''set.loop''' and '''draw'''.
    animate.obj
    set.view
    set.cel
    set.loop
    draw
</pre>


In fact the interpreter calls its usage of the VIEW resource "objects". An object is one usage of a VIEW resource. It is essentially an entry in the object table (or VIEW table/VIEW list). Many objects can use the same VIEW resource for its appearance which can be seen in KQ1 and BC with the crocodile filled moats.
In fact the interpreter calls its usage of the VIEW resource "objects". An object is one usage of a VIEW resource. It is essentially an entry in the object table (or VIEW table/VIEW list). Many objects can use the same VIEW resource for its appearance which can be seen in KQ1 and BC with the crocodile filled moats.


So when an AGI command has an object as a parameter to it, the value of the parameter is an index number into a table of objects that the interpreter is currently controlling.
So when an AGI command has an object as a parameter to it, the value of the parameter is an index number into a table of objects that the interpreter is currently controlling.
==Message==
==Message==


Line 195: Line 387:


Example:
Example:
<pre>
 
<syntax type="C++">
print ("Message 34 in logic.0 is %g34.");
print ("Message 34 in logic.0 is %g34.");
</pre>
</syntax>


Therefore messages in logic.0 can be displayed by any LOGIC in this way.
Therefore messages in logic.0 can be displayed by any LOGIC in this way.
<!-- XXXXXXX -->


<span id="Variables"></span>
<span id="Variables"></span>
Retrieved from "https://wiki.scummvm.org/index.php?title=Special:MobileDiff/9717"