AGI Commands References - saintfrater/LSL1FR GitHub Wiki
Thanks to the Sarien team and to Nick Sonneveld for some info on the unknown commands.
I ARITHMETIC COMMANDS
Commands that operate on variables
increment(n);
The value of the variable Var(n) is incremented by one.
Var(n) = Var(n)+1.
If the value is already 255, it is left unchanged.
decrement(n);
The value of the variable Var(n) is decremented by one.
Var(n) = Var(n)-1.
If the value is 0, it is left unchanged.
assign(n, m);
Variable Var(n) is assigned the value m.
Var(n) = m
assignv(n, m);
Variable Var(n) is assigned the value of Var(m).
Var(n) = Var(m)
addn(n, m); The value of variable Var(n) is incremented by m.
Var(n) = Var(n) + m
addv(n, m);
The value of variable Var(n) is incremented by the value of Var(m).
Var(n) = Var(n) + m
- Now what happens in the above two commands on 8-bit overflow: does the result wrap over 0 or stays 255? I.e. is 250 + 10 == 4 or 250 + 10 == 255?*
subn(n, m); The value of Var(n) is decremented by m.
Var(n) = Var(n) - m
subv(n, m); The value of Var(n) is decremented by Var(m).
Var(n) = Var(n) - Var(m)
Again, what happens when the result must be negative: is 1 - 2 == 255 or 1 - 2 == 0?
lindirectn(n, m); Variable Var(i) where i is the value of Var(n) is assigned a value m,
Var(Var(n)) = m
lindirectv(n, m);
Variable Var(i) where i is the value of Var(n) is assigned the value of Var(m).
Var(Var(n)) = Var(m)
rindirect(n, m);
Variable Var(n) is assigned the value of Var(i) where i is the value of Var(m).
Var(n) = Var(Var(m))
muln(n, m);
Variable Var(n) is multiplied by m.
Var(n) = Var(n) * m
mulv(n, m);
Variable Var(n) is multiplied by the value of Var(m).
Var(n) = Var(n) * Var(m)
What happens on overflow?
divn(n, m);
Variable Var(n) is divided by m.
Var(n) = Var(n) / m
divv(n, m);
Variable Var(n) is divided by the value of Var(m).
Var(n) = Var(n) / Var(m)
What happens on division by 0?
random(n, m, k);
Variable Var(k) is assigned a random value in the range between n and m.
Now let us consider the commands changing flag values.
Remember that a flag can only have a value 0 or 1.
set(n);
flag(n) is set to 1.
set.v(n);
flag(i), where i is the value of var (n), is set to 1.
flag(var(n)) = 1
reset(n);
flag(n) is set to 0.
reset.v(n);
flag(i), where i is the value of var (n), is set to 0.
flag(var(n)) = 0
toggle(n); flag(n) toggles its value.
toggle.v(n);
flag(i), where i is the value of var (n).
toggles is value:
flag(var(n));
II COMMANDS TO LOAD AND UNLOAD RESOURCES
Commands in this chapter load (into the interpreter's memory) and unload (discard, thus freeing interpreter's memory) LOGIC, PICTURE, VIEW, and SOUND resources.
Always remember that the internal memory of the interpreter is 64K. This restriction is rarely a problem, but do not forget about it.
When the internal memory is full, the program has to be broken into parts which are loaded and unloaded as the story unfolds in the given room, or PICTURE, VIEW, and SOUND resources have to be manipulated using the commands below. Remember that when a resource is unloaded, all resources loaded after it ARE ALSO AUTOMATICALLY UNLOADED!
load.logic(n);
Load into memory the LOGIC resource number n.
Logic(n);
load.logic.v(n);
Load into memory the LOGIC resource number i, where i is the value of Var(n).
Logic(Var(n));
load.pic(n);
Loads into memory the PICTURE resource number i, where i is the value of Var(n).
Picture(Var(n));
This may be a mistake in the original: I would expect this command to be load_pic_v
, while load_pic n
would load resource number n.
load_pic_v
may be a more appropriate name for it, but the name above is what they gave it. There is no equivalent command that takes a number rather than a variable.
load.view(n);
Loads into memory the VIEW resource number n.
View(n);
load.view.v(n); Loads into memory the VIEW resource number i, where i is the value of Var(n).
View(Var(n));
load.sound(n);
Loads into memory the SOUND resource number n.
Sound(n);
Note that there is no load_sound_v
listed. I wonder if this is a mistake or there really is no way to load a sound with indirection (unlikely, I think)
There really is no way of loading a sound with indirection. The command doesn't exist.
discard.pic(n);
Unloads PICTURE resource number i where i is the value of Var(n).
discard.view(n);
Unload VIEW resource number n. View(n)
discard.view.v(n);
Unloads VIEW resource number i where i the value of Var(n). View(Var(n)).
And what about discard_logic
, discard_logic_v
, discard_sound
, and discard_sound_v
?
There must be some other way that those commands are removed from memory, because the commands you mention above don't exist.
III PROGRAM CONTROL COMMANDS
new.room
command is one of the most powerful commands of the interpreter.
It is used to change algorithms of the object behaviour, props, etc. Automatic change of EGO coordinates imitates moving into a room adjacent to the edge of the initial one.
Sounds awkward but that's what it says.
The format of the command:
new.room(n); new.room.v(n);
These commands do the following:
- Commands
stop_update
and unanimate are issued to all objects; - All resources except Logic(0) are discarded;
- Command
player_control
is issued; unblock
command is issued;set_horizon
36 command is issued;- Var(1) is assigned the value of Var(0);
- Var(0) is assigned n (or the value of Var(n) when the command is
new_room_v
); - Var(4) is assigned 0;
- Var(5) is assigned 0;
- Var(16) is assigned the ID number of the VIEW resource that was associated with EGO (the player character).
- Logic(i) resource is loaded where i is the value of Var(0)!
- Set EGO coordinates according to Var(2):
- if EGO touched the bottom edge, put it on the horizon;
- if EGO touched the top edge, put it on the bottom edge of the screen;
- if EGO touched the right edge, put it at the left and vice versa.
- Var(2) is assigned 0 (meaning EGO has not touched any edges).
- Flag(5) is set to 1 (meaning in the first interpreter cycle after the
new_room
command all initialization parts of all logics loaded and called from the initialization part of the new room's logic will be called. In the subsequent cycle Flag(5) is reset to 0. - Clear keyboard input buffer and return to the main AGI loop.
call(n); call.v(n);
Subroutine call commands
LOGIC resource number n (or number i where i the value of Var(n)) is executed as a subroutine.
If the logic with the given ID is not loaded in memory, it is temporarily loaded and discarded after returning from the call (this takes extra time). call command does not change any variables or flags.
return();
This command returns control to the interpreter if it is executed in Logic(0), or to the command following the call command which called the current logic.
jump [label];
This command unconditionally transfers control to a command starting with a symbol combination within the same logic.
set.scan.start reset.scan.start
Normally, when a logic is called using call command, execution begins at the first instruction.
set_scan_start
command sets the entry point at the command following it, while reset_scan_start
returns entry point to the beginning.
IV OBJECT CONTROL COMMANDS
Interpreter controls movement of objects around the screen automatically checking the following conditions:
- If an object priority is 0 it cannot cross an unconditional barrier (pixels with priority 0).
- If an object priority is 15 and a command
ignore_block();
has not been given to it, it cannot cross a conditional barrier (pixels with priority 1) and leave the block set using theblock
command. - If an object has not been given
ignore.horizon(oi);
Object(i) command, it cannot move above the horizon set using theset_horizon
command. - An object should follow the conditions set using
object.on.water(oi);
andobject.on.land(oi);
Object(i)
commands (see object description commands).
Object number 0 is called EGO. It is different from others in that the player may move it around using the keyboard.
V OBJECT DESCRIPTION COMMANDS
animate.obj(n);
Object number n is included in the list of object controlled by the interpreter.
OBJECTS NOT INCLUDED IN THAT LIST ARE CONSIDERED INEXISTENT!
unanimate.all();
All objects are removed from the control list and are considered inexistent.
set.view(n, m); set.view.v(n, m);
Object n is associated with a VIEW resource number m (or pointed to by Var(m)), which may be an image of the object.
set.loop(n, m); set.loop.v(n, m);
Chooses a loop m (or Var(m)) in the VIEW resource associated with the object n.
fix.loop(n);
Turns off automatic choice of loop number for the object number n.
release.loop(n);
Turns on automatic choice of loop number depending on the direction of motion of the object n.
1
8 | 2
\ | /
\ | /
7 -------------- 3 0 - object stands still
/ | \
/ | \
6 | 4
5
Automatic choice of the loop is done according to the table:
- for objects with fewer than 4 but more than 1 loops:
Direction still(0) 1 2 3 4
Loop * * 0 0 0 * 1
* - means the current loop number is retained
- for objects with more than 4 loops:
Direction still(0) 1 2 3 4
Loop * 3 0 0 0 2 1
set.cel(n, m); set.cel.v(n,m);
Selects a cel m in the current loop of the object m.
last.cel(n, m);
The number of the last cel of the current loop of the object n is stored in Var(m).
current.cel(n, m);
The number of the current cel of the object n is stored in Var(m).
current.loop(n, m); The number of the current loop of the object n is stored in Var(m).
current.view(n, m);
The number of the current VIEW resource associated with the object n is stored in Var(m).
set.priority(n, m); set.priority.v(n,m);
Set priority of the view of the object n to m (or Var(m)).
release.priority(n);
Turns on the automatic priority choice for the object n.
The priority is set depending on the vertical coordinate of the object.
< | y | < | priority |
---|---|---|---|
0 | 48 | 4 | |
48 | 60 | 5 | |
60 | 72 | 6 | |
72 | 84 | 7 | |
84 | 96 | 8 | |
96 | 108 | 9 | |
108 | 120 | 10 | |
120 | 132 | 11 | |
132 | 144 | 12 | |
144 | 156 | 13 | |
156 | 168 | 14 |
This way, as an object moves down it approaches the viewer.
get.priority(n, m);
The value of the current priority of the object n is stored in Var(m).
position(n, x, y); position.v(n, x, y);
Coordinates of the object n, not yet displayed on the screen, are set to x and y (or Var(x) and Var(y)).
draw(n);
Object n is shown on the screen.
The image uses the values of the loop and the cel in the VIEW resource associated with the object n (see set_view
), as well as the priority and coordinates of the object.
If a command start_cycling
is also issued, an infinite "movie" for the object n is shown until stopped (for example, with stop_cycling
).
erase(n);
Object n is erased from the screen.
get.posn(n, x, y);
Coordinates of the object n are stored in Var(x) and Var(y).
Coordinates of the object are coordinates of the base point (bottom left corner) of cels of the VIEW resource associated with the object.
Interpreter automatically shows a "movie" (a loop in the VIEW resource) associated with the object, starting at the specified cel.
The following commands control this process.
start.cycling(n);
Enables automatic change of cels in a chosen (using set_loop
) loop of a VIEW resource associated with the object n (using set_view
).
stop.cycling(n);
Disables automatic change of cels in a chosen (using set_loop
) loop of a VIEW resource associated with the object n (using set_view
).
normal.cycle(n);
Cels of the loop associated with the object n follow in a normal order: 0, 1, 2, .., k-1, 0, 1, 2..
reverse.cycle(n);
Cels of the loop associated with the object n follow in a reverse order: k-1, k-2, ..., 1, 0, k-1, k-2, ..1, 0, ..
end.of.loop(n, m);
Plays the loop associated with the object n once, from the current cel to the last. When finished, Flag(m) is set to 1.
reverse.loop(n, m);
Plays the loop associated with the object n once in a reverse order, from the current cel to the first. When finished, Flag(m) is set to 1.
cycle.time(n, m);
Var(m) sets the time in interpreter cycles between cel changes for the object n. When Var(m) = 1 cels are changed every cycle.
VI OBJECT MOTION CONTROL COMMANDS
The following commands can be given to the object included in the interpreter control list with animate_obj:
set.horizon(n);
Set the horizon to y = n.
ignore.horizon(n);
Object n moves regardless of the horizon position.
observe.horizon(n);
Object n cannot move above the horizon.
block(x1, y1, x2, y2);
Sets a rectangular area (block).
(x1, y1)
------------------
| |
| |
| |
------------------
(x2, y2)
unblock();
Cancels previously set block.
ignore.blocks(n);
Object n moves ignoring conditional barriers (pixels with priority 1) and a block set with a block command.
observe.blocks(n);
Object n may not cross conditional barriers or leave the block.
ignore.objs(n);
Object n moves regardless of positions of other objects.
observe.objs(n);
Object n treats other objects as obstacles.
player.control();
The player is allowed to control EGO (object number 0) using the keyboard or the joystick.
program.control();
The player is not allowed to control object 0 (EGO).
stop.motion(n);
Motion of object n is stopped. If n = 0, program_control is automatically executed.
start.motion(n);
Motion of object n is started. If n = 0 (EGO), player_control automatically executed.
step.size(n, m);
Var(n) determines the number of pixels the object n moves each step.
step.time(n, m);
Var(n) determines the speed of object n motion: delay in the interpreter cycles between consecutive steps. If Var(m) = 1, step occurs on every cycle.
move.obj(n, x, y, s, m); move.obj.v(n, x, y, s, m);
Object n is told to move to the point x,y (or Var(x), Var(y)) by s pixels every step.
When the destination is reached, Flag(m) is set to 1. If n = 0 (EGO), program_control
is executed automatically.
follow.ego(n, s, m);
Object n is told to chase object 0 (EGO) by s pixels every step. When EGO's and the object's coordinates become equal, Flag(m) is set to 1.
wander(n);
Object n randomly changes the direction of its motion (wanders). If n = 0 (EGO), program_control is issued automatically.
normal.motion(n);
Special object motion mode is canceled. The object continues to move in the direction it was moving in at the time the command was issued.
set.dir(n, m);
Object n is told to move in the direction Var(m)
1
8 | 2
\ | /
\ | /
7 ------------- 3 0 - stop
/ | \
/ | \
6 | 4
5
get.dir(n, m);
Direction of object n motion is stored in Var(m).
object.on.water(n);
Object n is allowed to be only in the area where its base line is completely on pixels with priority 3 (water surface).
object.on.land(n);
Object n is not allowed to touch pixels of water surface (priority 3).
object.on.anything(n);
Motion restrictions previously set on the object n with commands object_on_water
or object_on_land
are cancelled.
reposition(n, dx, dy);
Object n jumps from its current location into the location with coordinates x + Var(dx), y + Var(dy).
Shouldn't there be reposition and reposition.v?
There should be, but they don't exist.
reposition.to(n, x, y); reposition.to.v(n, x, y);
Similar to the preceding command, but the object is moved to the point x, y (Var(x),Var(y)).
stop.update(n);
Object n is removed from the list of objects updated by the interpreter on each step. The object stays on the screen unchanged.
start.update(n);
Object n is redrawn on each interpreter step.
force.update(n);
Object n is redrawn immediately, without waiting for the end of the interpreter cycle.
distance(n, m, d);
If both objects n and m are on the screen, then
Var(d) = ABS(x(n) - x(m)) + ABS(y(n) - y(m)), otherwise
Var(d) = 255.
VII INVENTORY ITEM MANAGEMENT COMMANDS
OBJECT resources, stored in a separate file OBJECT, are most often used to represent inventory items.
An item is a structure which consists of a one-byte field called room and a string of text, the item name.
If the room field of an item is 255, the item belongs to the player. Otherwise the item is considered to be in the room with the corresponding ID number.
Let us consider item management commands.
get(n); get.v(n);
Stores 255 in room field of an object n, which means the player owns it.
drop(n);
Stores 0 in the room field of object n.
put(n, m); put.v(n, m);
Stores the value m (or Var(m)) in the room field of the object n.
get.room.v(n, m);
Stores the value of the room field of object Var(n) in Var(m).
status();;
The screen is switched to text mode; the top line displays "You are carrying:", then the names of the object with room field equal to 255 are listed.
If there are no such objects, the word "nothing" is displayed.
If Flag(13) = 1 (allow item selection), a highlight appears which allows the player to select an item name.
When Enter is pressed, the selected object number is stored in Var(25).
When Esc is pressed, 255 is stored in Var(25).
VIII PICTURE RESOURCE MANAGEMENT COMMANDS
The following commands operate on PICTURE resources (3D props), prepared using PM editor and loaded in the interpreter memory using load_pic:
draw.pic(n);
A PICTURE resource number i, where i is the value of Var(n) is executed.
As the result, the background picture is created in the internal buffer of the interpreter.
Before execution, the buffer is cleared, i.e. all pixels are set to colour 15 and priority 4.
overlay.pic(n);
Just like the above, only the internal buffer is not cleared before drawing. Picture(Var(n)) is drawn over the existing picture.
add.to.pic(a, b, c, d, e, f, g); add.to.pic.v(a, b, c, d, e, f, g);
A picture of a VIEW resource is added to the background as its component.
Typically, this is used to add small complicated details which would require too many PICTURE resource commands to draw.
Parameters are:
a ( Var(a) ) - number of the VIEW resource;
b ( Var(b) ) - loop number;
c ( Var(c) ) - cel number;
d ( Var(d) ) - x coordinate;
e ( Var(e) ) - y coordinate;
f ( Var(f) ) - priority;
g ( Var(g) ) - margin.
If margin is 0, 1, 2, or 3, the base of the cel is surrounded with a rectangle of the corresponding priority. If margin > 4, this extra margin is not shown.
show.pic();
Shows internal buffer on the screen.
ATTENTION!
Please use the following sequence of commands when loading PICTURE resources in the interpreter memory:
load.pic(n);
draw.pic(n);
discard.pic(n);
.............
show.pic;
Any other order may crash the interpreter without any diagnostic messages.
IX SOUND RESOURCE MANAGEMENT COMMANDS
sound(n, m);
Starts playback of the SOUND resource number n. When finished, Flag(m) is set to 1.
stop.sound();
Stops the playback.
X TEXT MANAGEMENT COMMANDS
prevent.input();
Prevents the user from entering anything using the keyboard.
accept.input();
Allows the user to enter text using the keyboard.
print(n); print.v(n);
Opens a text window in the centre of the screen, where a message number n (or Var(n)) from the messages field of the current LOGIC resource is displayed.
Output mode is determined by Flag(15).
The message is a NULL-terminated string of text. In addition to letters, digits, and other symbols, the string may contain:
- Newline character (0Ah);
- Format element:
- %v - at this place the output will include a decimal value of variable with the given number.
- %m - the text of the message with the given number is inserted at this place.
- %0 - the name of the item with the given number is inserted at this place.
- %w - a vocabulary word with the given number is inserted at this place.
- %s - a string variable with the given number is inserted at this place.
- %g - a message with this number from message field of Logic(0) is inserted at this place.
For v format, you can add a vertical line and a number of characters the output should take. In this case leading zeros are not suppressed in the output.
Example:
%v34 | 2
When you write your messages, remember that the interpreter wraps the text between the lines as needed when the message is displayed.
display(R, C, N); display.v(R, C, N);
Prints a message number N (Var(N)) in the row R (Var(R)), starting with the column C (Var(C)).
No window is created, so it is up to the programmer to erase the output when it is no longer needed.
print.at(n, x, y, l); print.at.v(n, x, y, l);
Analogous to print but the programmer can specify the window location. x, y, and l are constants specifying coordinates of the top left corner of the window and its width in character cells of a 40x25 screen.
version();
Prints interpreter version in the centre of the screen.
text.screen();
The screen switches to the text mode 40x25.
graphics();
The screen returns to the graphics mode.
The picture on the screen is restored.
set.cursor.char(n);
First byte of the message n is user as a text mode cursor.
set.text.attribute(F, B);
Sets foreground and background colours for display, get_num, and get_string commands.
clear.lines(n, m, C);
Clears text lines from n to m using colour C.
clear.text.rect(x1, y1, x2, y2, C);
Clears a rectangular area with top left corner coordinates (x1,y1) and bottom right coordinates (x2,y2) using colour C.
status.line.on();
Shows the status line containing the current score and sound status (on/off).
status.line.off();
Removes the status line.
XI STRING MANAGEMENT COMMANDS
set.string(n, m);
Stores message number m in the string variable n.
word.to.string(n, m);
Word number m of the user input is stored in String(n).
get.string(n, m, x, y, l);
User input is stored in String(n). m is the number of the message used as the prompt, x, y, l are input position and maximum string length.
parse(n);
Parses String(n) as if it were entered by the player.
get.num(n, m);
Enters a number from the keyboard into Var(m). Message n is used as the prompt.
XII INITIALIZATION COMMANDS
set.key(s, c);
Set interpreter's special key.
c - code (decimal number from 0 to 255);
s - if the key is a regular, or Ctrl+key pair, the ASCII code (for example, 0009h - TAB);
- if the key is functional or Alt+key pair, the corresponding scan-code in the high byte of s.
For example, the scan code of F1 is 3b00h, Alt+Z - 2c00h, etc.
set.game.id(n);
Message n is scanned by the interpreter and compared with its internal identifier. On mismatch, the program exits.
script.size(n);
Sets the size of script table in bytes. Script table stores codes of some interpreter commands. It is needed to the interpreter can correctly reload resources when restore_game is executed.
trace.info(n, m, l);
Sets the built-in debugger parameters n - number of LOGIC resource with command names. m, l - first line and height of the debugger window.
trace.on();
Turns on the debugger. In general, the debugger is turned on with Scroll Lock key when the command name table is loaded even if this command does not occur in the program.
log(n);
This is a debugging command. It writes a log message in a file: Room [current room] Input line [current input line] followed by the message number n.
XIII MENU MANAGEMENT COMMANDS
Creating your program, you can offer the player a choice using a system of menus.
These may be short one-line questions (menu header) with several answers (menu elements), or a prompt to change some of the system parameters, for example, object movement speed. Let us consider these commands.
set.menu(n);
Message n is used as the header of the menu elements which follow.
set.menu.item(n, c);
Message n is used as a menu element, where c is this element's code (a number between 0 and 255).
submit.menu();
Ends menu creation.
enable.item(c); disable.item(c);
Enables or disables a menu item with the code c.
|-------- heading
v
-------------------------------
| File |
-------------------------------
Menu --->| Save |
Element |------------|
| Restore |
|------------|
|XXXXXXXXXXXX|<- menu element disabled
|------------| using disable.item
| Quit |
--------------
menu.input();
If Flag(14) = 1, a menu system is shown on the screen, allowing the user to choose an item. Whether an item with the code c has been chosen can be tested using a command controller(c)
, where c is the code assigned to the menu item.
XIV TEST COMMANDS
The result of test command can be either TRUE or FALSE.
equaln(n,m);
True if Var(n) = m.
equalv(n, m);
true if Var(n) = Var(m).
lessn(n,m);
True if Var(n) < m.
lessv(n, m);
True if Var(n) < Var(m).
greatern(n, m);
True if Var(n) > m.
greaterv(n, m);
True if Var(n) > Var(m).
isset(n);
True if Flag(n) = 1 (set).
isset.v(n);
True if Flag(Var(n)) = 1 (set).
has(n); True if the room field of item n is 255, i.e. the item belongs to the player.
obj.in.room(n, m);
True if room field of the object n is Var(m).
posn(n, x1, y1, x2, y2);
True if the coordinates of the base point of the cel which is the current image of object n satisfies the equation x1 <= x <= x2, y1 <= y <= y2.
obj.in.box(n, x1, y1, x2, y2); True if the base of the object n is completely within the rectangle specified using its top left (x1,y1) and bottom right (x2,y2) corners.
(x1, y1)
------------------
| |
| |
| |
------------------
(x2, y2)
center.position(n, x1, y1, x2, y2);
True of the center of the base line of the object n is inside the rectangle specified as its top left and bottom right corners.
right.position(n, x1, y1, x2, y2);
True of the right side of the base line of the object n is inside the rectangle specified as its top left and bottom right corners.
have.key();
True if the user has pressed any key on the keyboard. Used to create cycles to wait until any key is pressed.
compare.strings(s1, s2);
True if string(s1) = string(s2).
said(n, W(i));
where i = 1, ..., n True if the player has entered a phrase that completely matches W(1),...W(n), where n is the number of W(i) which are codes of the vocabulary words.
Here is how the input is matched. After the player types a message and presses Enter, the input line is processed by the interpreter.
Interpreter removes all punctuation marks.
All characters are converted to lowercase.
All sequences of more than one space are replaced with a single space.
Starting with the first word of the input, the interpreter looks up the vocabulary, trying to find the longest character sequence matching the entered.
If the search is unsuccessful, Var(9) is assigned the number of the word in the message that failed to match and the processing ends.
If all the words have been assigned some codes:
- The Interpreter removes from the sequence of codes all zeros (that means all vocabulary words with zero codes are ignored).
- Flag(2) (the user has entered an input line) is set to 1
- Flag(4) (
said
command accepted the user input) is set to 0.
If the sequence of code produced by the interpreter is V(1), V(2),...V(m).
The test is performed as follows:
If Flag(2) = 0 or Flag(4) = 1, return FALSE. Compare parameters W(i) and codes V(i) as follows: - if W(i) = 1, it matches any V(i);
- if W(i) = 9999, it matches the whole remaining input i.e. the codes V(i), V(i+1),...V(m).
Otherwise W(i) should be equal to V(i).
If all elements match, Flag(4) (said
accepted the user input) is set to 1 and the command returns TRUE. Otherwise, FALSE is returned.
controller(n)
True if the event with code n has occurred:
- a key with the code n was pressed (set using
set_key
); menu item with code n was selected in commandmenu_input
.
XV OTHER COMMANDS
configure.screen(a, b, c);
Sets position of lines on the screen:
a = 1 (minimum line number for print);
b - user input line;
c - status line.
obj.status.v(n);
Prints a message for the object Var (n):
Obj [number] x: [coordinate] y: [coordinate] pri: [priority] stepsize: .
show.mem();
Displays a report of the interpreter memory status.
show.pri.screen();
Shows priorities of the screen pixels. Priority n is shown as color number n (see color setting commands in I.1.2.1.1).
show.obj(n);
In the centre at the bottom of the screen a cel 0 of loop 0 of the VIEW resource n is shown. In the centre of the screen, a message associated with the VIEW resource is printed.
That's what they say but I suspect they mean OBJECT n, not VIEW resource.
Actually, in this case the argument does refer to the VIEW resource. This is because the VIEW in question isn't meant to be a controlled object but instead is simply the picture and textual description of the an inventory item.
shake.screen(n);
The screen shakes n times.
echo.line();
The last line entered by the user is displayed in the input line.
cancel.line();
Input line is cleared.
close.window();
If there is a text window on the screen, it is removed.
open.dialogue(); close.dialogue();
Enables and disables get_string and get_num commands if prevent_input has been issued.
restart.game();
Restarts the game from the very beginning.
save.game(); restore.game();
These command save and restore the current state of the game into disk files.
pause();
Stops the interpreter until any key is pressed.
quit(n);
Exits the interpreter.
If n = 1, quits immediately
If n = 0, asks "Press ENTER to quit.", "Press ESC to continue."
init.joy();
Initialize joystick.
toggle.monitor();
Switch RGB monitor into the graphics mode.
upper.left();
Usually the crossing by an object of various areas and lines is tracked by the base point (bottom right corner) of its cel. After this command, top left corner is used as such a point.
XVI UNKNOWN COMMANDS
only works with pc v3 games.
All of the mouse commands in this tutorial do not work with Brian's AGI mouse hack.
unknown170(n); [set.simple(n);]*
n is a string number using this makes a saved game's name the same as the string n you used.
unknown171(); [push.script();]*
This command is used if you want to temporarily load up something then unload it so that you do not use the interpreters script. This can stop the problem out of script.
unknown172(); [pop.script();]*
This command is used if you want to temporarily load up something then unload it so that you do not use the interpreters script. This can stop the problem out of script.
unknown173(); [hold.key();]*
This command makes it so you have to hold the arrow key to move a good example of this is in Mixed Up Mother Goose.
unknown174(n); [set.pri.base(n);]*
This affects the priority base of the AGI interpreter Kings Quest 4 uses this function to affect the table so the "base" (priorities <= 4) is bigger or larger at the top.
unknown175(n); [discard.sound(n);]
This command discards sound n.
unknown176(); [hide.mouse(n);]
This command hides the mouse pointer.
unknown177(n); [allow.menu(n);]*
This command determines wheather the menu is activated or not.
If n = 0 the menu is turned off.
If n = 1 the menu is turned on.
unknown178(n); [show.mouse(n);]
This command makes the mouse appear.
unknown179(n1,n2,n3,n4); [fence.mouse(n1,n2,n3,n4);]
This command sets up a fence which the mouse can not go out of.
unknown180(x,y); [mouse.posn(x,y);]
This command gets the position of the mouse pointer.
unknown181(n); [release.key(n);]*
This command does the opposite of unknown173(); it allows you to walk until you press a key to stop.
unknown182(x,y); [adj.ego.move.to.x.y(x,y);]
This moves the ego to the position set in x y.
AGI Command Reference
Thanks to the Sarien team and to Nick Sonneveld for some info on the unknown commands.
Table of Contents
I ARITHMETIC COMMANDS
Commands that operate on variables
increment(n);
The value of the variable Var(n) is incremented by one.
Var(n) = Var(n)+1.
If the value is already 255, it is left unchanged.
decrement(n);
The value of the variable Var(n) is decremented by one.
Var(n) = Var(n)-1.
If the value is 0, it is left unchanged.
assign(n, m);
Variable Var(n) is assigned the value m.
Var(n) = m
assignv(n, m);
Variable Var(n) is assigned the value of Var(m).
Var(n) = Var(m)
addn(n, m); The value of variable Var(n) is incremented by m.
Var(n) = Var(n) + m
addv(n, m);
The value of variable Var(n) is incremented by the value of Var(m).
Var(n) = Var(n) + m
- Now what happens in the above two commands on 8-bit overflow: does the result wrap over 0 or stays 255? I.e. is 250 + 10 == 4 or 250 + 10 == 255?*
subn(n, m); The value of Var(n) is decremented by m.
Var(n) = Var(n) - m
subv(n, m); The value of Var(n) is decremented by Var(m).
Var(n) = Var(n) - Var(m)
Again, what happens when the result must be negative: is 1 - 2 == 255 or 1 - 2 == 0?
lindirectn(n, m); Variable Var(i) where i is the value of Var(n) is assigned a value m,
Var(Var(n)) = m
lindirectv(n, m);
Variable Var(i) where i is the value of Var(n) is assigned the value of Var(m).
Var(Var(n)) = Var(m)
rindirect(n, m);
Variable Var(n) is assigned the value of Var(i) where i is the value of Var(m).
Var(n) = Var(Var(m))
muln(n, m);
Variable Var(n) is multiplied by m.
Var(n) = Var(n) * m
mulv(n, m);
Variable Var(n) is multiplied by the value of Var(m).
Var(n) = Var(n) * Var(m)
What happens on overflow?
divn(n, m);
Variable Var(n) is divided by m.
Var(n) = Var(n) / m
divv(n, m);
Variable Var(n) is divided by the value of Var(m).
Var(n) = Var(n) / Var(m)
What happens on division by 0?
random(n, m, k);
Variable Var(k) is assigned a random value in the range between n and m.
Now let us consider the commands changing flag values.
Remember that a flag can only have a value 0 or 1.
set(n);
flag(n) is set to 1.
set.v(n);
flag(i), where i is the value of var (n), is set to 1.
flag(var(n)) = 1
reset(n);
flag(n) is set to 0.
reset.v(n);
flag(i), where i is the value of var (n), is set to 0.
flag(var(n)) = 0
toggle(n); flag(n) toggles its value.
toggle.v(n);
flag(i), where i is the value of var (n).
toggles is value:
flag(var(n));
II COMMANDS TO LOAD AND UNLOAD RESOURCES
Commands in this chapter load (into the interpreter's memory) and unload (discard, thus freeing interpreter's memory) LOGIC, PICTURE, VIEW, and SOUND resources.
Always remember that the internal memory of the interpreter is 64K. This restriction is rarely a problem, but do not forget about it.
When the internal memory is full, the program has to be broken into parts which are loaded and unloaded as the story unfolds in the given room, or PICTURE, VIEW, and SOUND resources have to be manipulated using the commands below. Remember that when a resource is unloaded, all resources loaded after it ARE ALSO AUTOMATICALLY UNLOADED!
load.logic(n);
Load into memory the LOGIC resource number n.
Logic(n);
load.logic.v(n);
Load into memory the LOGIC resource number i, where i is the value of Var(n).
Logic(Var(n));
load.pic(n);
Loads into memory the PICTURE resource number i, where i is the value of Var(n).
Picture(Var(n));
This may be a mistake in the original: I would expect this command to be load_pic_v
, while load_pic n
would load resource number n.
load_pic_v
may be a more appropriate name for it, but the name above is what they gave it. There is no equivalent command that takes a number rather than a variable.
load.view(n);
Loads into memory the VIEW resource number n.
View(n);
load.view.v(n); Loads into memory the VIEW resource number i, where i is the value of Var(n).
View(Var(n));
load.sound(n);
Loads into memory the SOUND resource number n.
Sound(n);
Note that there is no load_sound_v
listed. I wonder if this is a mistake or there really is no way to load a sound with indirection (unlikely, I think)
There really is no way of loading a sound with indirection. The command doesn't exist.
discard.pic(n);
Unloads PICTURE resource number i where i is the value of Var(n).
discard.view(n);
Unload VIEW resource number n. View(n)
discard.view.v(n);
Unloads VIEW resource number i where i the value of Var(n). View(Var(n)).
And what about discard_logic
, discard_logic_v
, discard_sound
, and discard_sound_v
?
There must be some other way that those commands are removed from memory, because the commands you mention above don't exist.
III PROGRAM CONTROL COMMANDS
new.room
command is one of the most powerful commands of the interpreter.
It is used to change algorithms of the object behaviour, props, etc. Automatic change of EGO coordinates imitates moving into a room adjacent to the edge of the initial one.
Sounds awkward but that's what it says.
The format of the command:
new.room(n); new.room.v(n);
These commands do the following:
- Commands
stop_update
and unanimate are issued to all objects; - All resources except Logic(0) are discarded;
- Command
player_control
is issued; unblock
command is issued;set_horizon
36 command is issued;- Var(1) is assigned the value of Var(0);
- Var(0) is assigned n (or the value of Var(n) when the command is
new_room_v
); - Var(4) is assigned 0;
- Var(5) is assigned 0;
- Var(16) is assigned the ID number of the VIEW resource that was associated with EGO (the player character).
- Logic(i) resource is loaded where i is the value of Var(0)!
- Set EGO coordinates according to Var(2):
- if EGO touched the bottom edge, put it on the horizon;
- if EGO touched the top edge, put it on the bottom edge of the screen;
- if EGO touched the right edge, put it at the left and vice versa.
- Var(2) is assigned 0 (meaning EGO has not touched any edges).
- Flag(5) is set to 1 (meaning in the first interpreter cycle after the
new_room
command all initialization parts of all logics loaded and called from the initialization part of the new room's logic will be called. In the subsequent cycle Flag(5) is reset to 0. - Clear keyboard input buffer and return to the main AGI loop.
call(n); call.v(n);
Subroutine call commands
LOGIC resource number n (or number i where i the value of Var(n)) is executed as a subroutine.
If the logic with the given ID is not loaded in memory, it is temporarily loaded and discarded after returning from the call (this takes extra time). call command does not change any variables or flags.
return();
This command returns control to the interpreter if it is executed in Logic(0), or to the command following the call command which called the current logic.
jump [label];
This command unconditionally transfers control to a command starting with a symbol combination within the same logic.
set.scan.start reset.scan.start
Normally, when a logic is called using call command, execution begins at the first instruction.
set_scan_start
command sets the entry point at the command following it, while reset_scan_start
returns entry point to the beginning.
IV OBJECT CONTROL COMMANDS
Interpreter controls movement of objects around the screen automatically checking the following conditions:
- If an object priority is 0 it cannot cross an unconditional barrier (pixels with priority 0).
- If an object priority is 15 and a command
ignore_block();
has not been given to it, it cannot cross a conditional barrier (pixels with priority 1) and leave the block set using theblock
command. - If an object has not been given
ignore.horizon(oi);
Object(i) command, it cannot move above the horizon set using theset_horizon
command. - An object should follow the conditions set using
object.on.water(oi);
andobject.on.land(oi);
Object(i)
commands (see object description commands).
Object number 0 is called EGO. It is different from others in that the player may move it around using the keyboard.
V OBJECT DESCRIPTION COMMANDS
animate.obj(n);
Object number n is included in the list of object controlled by the interpreter.
OBJECTS NOT INCLUDED IN THAT LIST ARE CONSIDERED INEXISTENT!
unanimate.all();
All objects are removed from the control list and are considered inexistent.
set.view(n, m); set.view.v(n, m);
Object n is associated with a VIEW resource number m (or pointed to by Var(m)), which may be an image of the object.
set.loop(n, m); set.loop.v(n, m);
Chooses a loop m (or Var(m)) in the VIEW resource associated with the object n.
fix.loop(n);
Turns off automatic choice of loop number for the object number n.
release.loop(n);
Turns on automatic choice of loop number depending on the direction of motion of the object n.
1
8 | 2
\ | /
\ | /
7 -------------- 3 0 - object stands still
/ | \
/ | \
6 | 4
5
Automatic choice of the loop is done according to the table:
- for objects with fewer than 4 but more than 1 loops:
Direction still(0) 1 2 3 4
Loop * * 0 0 0 * 1
* - means the current loop number is retained
- for objects with more than 4 loops:
Direction still(0) 1 2 3 4
Loop * 3 0 0 0 2 1
set.cel(n, m); set.cel.v(n,m);
Selects a cel m in the current loop of the object m.
last.cel(n, m);
The number of the last cel of the current loop of the object n is stored in Var(m).
current.cel(n, m);
The number of the current cel of the object n is stored in Var(m).
current.loop(n, m); The number of the current loop of the object n is stored in Var(m).
current.view(n, m);
The number of the current VIEW resource associated with the object n is stored in Var(m).
set.priority(n, m); set.priority.v(n,m);
Set priority of the view of the object n to m (or Var(m)).
release.priority(n);
Turns on the automatic priority choice for the object n.
The priority is set depending on the vertical coordinate of the object.
< | y | < | priority |
---|---|---|---|
0 | 48 | 4 | |
48 | 60 | 5 | |
60 | 72 | 6 | |
72 | 84 | 7 | |
84 | 96 | 8 | |
96 | 108 | 9 | |
108 | 120 | 10 | |
120 | 132 | 11 | |
132 | 144 | 12 | |
144 | 156 | 13 | |
156 | 168 | 14 |
This way, as an object moves down it approaches the viewer.
get.priority(n, m);
The value of the current priority of the object n is stored in Var(m).
position(n, x, y); position.v(n, x, y);
Coordinates of the object n, not yet displayed on the screen, are set to x and y (or Var(x) and Var(y)).
draw(n);
Object n is shown on the screen.
The image uses the values of the loop and the cel in the VIEW resource associated with the object n (see set_view
), as well as the priority and coordinates of the object.
If a command start_cycling
is also issued, an infinite "movie" for the object n is shown until stopped (for example, with stop_cycling
).
erase(n);
Object n is erased from the screen.
get.posn(n, x, y);
Coordinates of the object n are stored in Var(x) and Var(y).
Coordinates of the object are coordinates of the base point (bottom left corner) of cels of the VIEW resource associated with the object.
Interpreter automatically shows a "movie" (a loop in the VIEW resource) associated with the object, starting at the specified cel.
The following commands control this process.
start.cycling(n);
Enables automatic change of cels in a chosen (using set_loop
) loop of a VIEW resource associated with the object n (using set_view
).
stop.cycling(n);
Disables automatic change of cels in a chosen (using set_loop
) loop of a VIEW resource associated with the object n (using set_view
).
normal.cycle(n);
Cels of the loop associated with the object n follow in a normal order: 0, 1, 2, .., k-1, 0, 1, 2..
reverse.cycle(n);
Cels of the loop associated with the object n follow in a reverse order: k-1, k-2, ..., 1, 0, k-1, k-2, ..1, 0, ..
end.of.loop(n, m);
Plays the loop associated with the object n once, from the current cel to the last. When finished, Flag(m) is set to 1.
reverse.loop(n, m);
Plays the loop associated with the object n once in a reverse order, from the current cel to the first. When finished, Flag(m) is set to 1.
cycle.time(n, m);
Var(m) sets the time in interpreter cycles between cel changes for the object n. When Var(m) = 1 cels are changed every cycle.
VI OBJECT MOTION CONTROL COMMANDS
The following commands can be given to the object included in the interpreter control list with animate_obj:
set.horizon(n);
Set the horizon to y = n.
ignore.horizon(n);
Object n moves regardless of the horizon position.
observe.horizon(n);
Object n cannot move above the horizon.
block(x1, y1, x2, y2);
Sets a rectangular area (block).
(x1, y1)
------------------
| |
| |
| |
------------------
(x2, y2)
unblock();
Cancels previously set block.
ignore.blocks(n);
Object n moves ignoring conditional barriers (pixels with priority 1) and a block set with a block command.
observe.blocks(n);
Object n may not cross conditional barriers or leave the block.
ignore.objs(n);
Object n moves regardless of positions of other objects.
observe.objs(n);
Object n treats other objects as obstacles.
player.control();
The player is allowed to control EGO (object number 0) using the keyboard or the joystick.
program.control();
The player is not allowed to control object 0 (EGO).
stop.motion(n);
Motion of object n is stopped. If n = 0, program_control is automatically executed.
start.motion(n);
Motion of object n is started. If n = 0 (EGO), player_control automatically executed.
step.size(n, m);
Var(n) determines the number of pixels the object n moves each step.
step.time(n, m);
Var(n) determines the speed of object n motion: delay in the interpreter cycles between consecutive steps. If Var(m) = 1, step occurs on every cycle.
move.obj(n, x, y, s, m); move.obj.v(n, x, y, s, m);
Object n is told to move to the point x,y (or Var(x), Var(y)) by s pixels every step.
When the destination is reached, Flag(m) is set to 1. If n = 0 (EGO), program_control
is executed automatically.
follow.ego(n, s, m);
Object n is told to chase object 0 (EGO) by s pixels every step. When EGO's and the object's coordinates become equal, Flag(m) is set to 1.
wander(n);
Object n randomly changes the direction of its motion (wanders). If n = 0 (EGO), program_control is issued automatically.
normal.motion(n);
Special object motion mode is canceled. The object continues to move in the direction it was moving in at the time the command was issued.
set.dir(n, m);
Object n is told to move in the direction Var(m)
1
8 | 2
\ | /
\ | /
7 ------------- 3 0 - stop
/ | \
/ | \
6 | 4
5
get.dir(n, m);
Direction of object n motion is stored in Var(m).
object.on.water(n);
Object n is allowed to be only in the area where its base line is completely on pixels with priority 3 (water surface).
object.on.land(n);
Object n is not allowed to touch pixels of water surface (priority 3).
object.on.anything(n);
Motion restrictions previously set on the object n with commands object_on_water
or object_on_land
are cancelled.
reposition(n, dx, dy);
Object n jumps from its current location into the location with coordinates x + Var(dx), y + Var(dy).
Shouldn't there be reposition and reposition.v?
There should be, but they don't exist.
reposition.to(n, x, y); reposition.to.v(n, x, y);
Similar to the preceding command, but the object is moved to the point x, y (Var(x),Var(y)).
stop.update(n);
Object n is removed from the list of objects updated by the interpreter on each step. The object stays on the screen unchanged.
start.update(n);
Object n is redrawn on each interpreter step.
force.update(n);
Object n is redrawn immediately, without waiting for the end of the interpreter cycle.
distance(n, m, d);
If both objects n and m are on the screen, then
Var(d) = ABS(x(n) - x(m)) + ABS(y(n) - y(m)), otherwise
Var(d) = 255.
VII INVENTORY ITEM MANAGEMENT COMMANDS
OBJECT resources, stored in a separate file OBJECT, are most often used to represent inventory items.
An item is a structure which consists of a one-byte field called room and a string of text, the item name.
If the room field of an item is 255, the item belongs to the player. Otherwise the item is considered to be in the room with the corresponding ID number.
Let us consider item management commands.
get(n); get.v(n);
Stores 255 in room field of an object n, which means the player owns it.
drop(n);
Stores 0 in the room field of object n.
put(n, m); put.v(n, m);
Stores the value m (or Var(m)) in the room field of the object n.
get.room.v(n, m);
Stores the value of the room field of object Var(n) in Var(m).
status();;
The screen is switched to text mode; the top line displays "You are carrying:", then the names of the object with room field equal to 255 are listed.
If there are no such objects, the word "nothing" is displayed.
If Flag(13) = 1 (allow item selection), a highlight appears which allows the player to select an item name.
When Enter is pressed, the selected object number is stored in Var(25).
When Esc is pressed, 255 is stored in Var(25).
VIII PICTURE RESOURCE MANAGEMENT COMMANDS
The following commands operate on PICTURE resources (3D props), prepared using PM editor and loaded in the interpreter memory using load_pic:
draw.pic(n);
A PICTURE resource number i, where i is the value of Var(n) is executed.
As the result, the background picture is created in the internal buffer of the interpreter.
Before execution, the buffer is cleared, i.e. all pixels are set to colour 15 and priority 4.
overlay.pic(n);
Just like the above, only the internal buffer is not cleared before drawing. Picture(Var(n)) is drawn over the existing picture.
add.to.pic(a, b, c, d, e, f, g); add.to.pic.v(a, b, c, d, e, f, g);
A picture of a VIEW resource is added to the background as its component.
Typically, this is used to add small complicated details which would require too many PICTURE resource commands to draw.
Parameters are:
a ( Var(a) ) - number of the VIEW resource;
b ( Var(b) ) - loop number;
c ( Var(c) ) - cel number;
d ( Var(d) ) - x coordinate;
e ( Var(e) ) - y coordinate;
f ( Var(f) ) - priority;
g ( Var(g) ) - margin.
If margin is 0, 1, 2, or 3, the base of the cel is surrounded with a rectangle of the corresponding priority. If margin > 4, this extra margin is not shown.
show.pic();
Shows internal buffer on the screen.
ATTENTION!
Please use the following sequence of commands when loading PICTURE resources in the interpreter memory:
load.pic(n);
draw.pic(n);
discard.pic(n);
.............
show.pic;
Any other order may crash the interpreter without any diagnostic messages.
IX SOUND RESOURCE MANAGEMENT COMMANDS
sound(n, m);
Starts playback of the SOUND resource number n. When finished, Flag(m) is set to 1.
stop.sound();
Stops the playback.
X TEXT MANAGEMENT COMMANDS
prevent.input();
Prevents the user from entering anything using the keyboard.
accept.input();
Allows the user to enter text using the keyboard.
print(n); print.v(n);
Opens a text window in the centre of the screen, where a message number n (or Var(n)) from the messages field of the current LOGIC resource is displayed.
Output mode is determined by Flag(15).
The message is a NULL-terminated string of text. In addition to letters, digits, and other symbols, the string may contain:
- Newline character (0Ah);
- Format element:
- %v - at this place the output will include a decimal value of variable with the given number.
- %m - the text of the message with the given number is inserted at this place.
- %0 - the name of the item with the given number is inserted at this place.
- %w - a vocabulary word with the given number is inserted at this place.
- %s - a string variable with the given number is inserted at this place.
- %g - a message with this number from message field of Logic(0) is inserted at this place.
For v format, you can add a vertical line and a number of characters the output should take. In this case leading zeros are not suppressed in the output.
Example:
%v34 | 2
When you write your messages, remember that the interpreter wraps the text between the lines as needed when the message is displayed.
display(R, C, N); display.v(R, C, N);
Prints a message number N (Var(N)) in the row R (Var(R)), starting with the column C (Var(C)).
No window is created, so it is up to the programmer to erase the output when it is no longer needed.
print.at(n, x, y, l); print.at.v(n, x, y, l);
Analogous to print but the programmer can specify the window location. x, y, and l are constants specifying coordinates of the top left corner of the window and its width in character cells of a 40x25 screen.
version();
Prints interpreter version in the centre of the screen.
text.screen();
The screen switches to the text mode 40x25.
graphics();
The screen returns to the graphics mode.
The picture on the screen is restored.
set.cursor.char(n);
First byte of the message n is user as a text mode cursor.
set.text.attribute(F, B);
Sets foreground and background colours for display, get_num, and get_string commands.
clear.lines(n, m, C);
Clears text lines from n to m using colour C.
clear.text.rect(x1, y1, x2, y2, C);
Clears a rectangular area with top left corner coordinates (x1,y1) and bottom right coordinates (x2,y2) using colour C.
status.line.on();
Shows the status line containing the current score and sound status (on/off).
status.line.off();
Removes the status line.
XI STRING MANAGEMENT COMMANDS
set.string(n, m);
Stores message number m in the string variable n.
word.to.string(n, m);
Word number m of the user input is stored in String(n).
get.string(n, m, x, y, l);
User input is stored in String(n). m is the number of the message used as the prompt, x, y, l are input position and maximum string length.
parse(n);
Parses String(n) as if it were entered by the player.
get.num(n, m);
Enters a number from the keyboard into Var(m). Message n is used as the prompt.
XII INITIALIZATION COMMANDS
set.key(s, c);
Set interpreter's special key.
c - code (decimal number from 0 to 255);
s - if the key is a regular, or Ctrl+key pair, the ASCII code (for example, 0009h - TAB);
- if the key is functional or Alt+key pair, the corresponding scan-code in the high byte of s.
For example, the scan code of F1 is 3b00h, Alt+Z - 2c00h, etc.
set.game.id(n);
Message n is scanned by the interpreter and compared with its internal identifier. On mismatch, the program exits.
script.size(n);
Sets the size of script table in bytes. Script table stores codes of some interpreter commands. It is needed to the interpreter can correctly reload resources when restore_game is executed.
trace.info(n, m, l);
Sets the built-in debugger parameters n - number of LOGIC resource with command names. m, l - first line and height of the debugger window.
trace.on();
Turns on the debugger. In general, the debugger is turned on with Scroll Lock key when the command name table is loaded even if this command does not occur in the program.
log(n);
This is a debugging command. It writes a log message in a file: Room [current room] Input line [current input line] followed by the message number n.
XIII MENU MANAGEMENT COMMANDS
Creating your program, you can offer the player a choice using a system of menus.
These may be short one-line questions (menu header) with several answers (menu elements), or a prompt to change some of the system parameters, for example, object movement speed. Let us consider these commands.
set.menu(n);
Message n is used as the header of the menu elements which follow.
set.menu.item(n, c);
Message n is used as a menu element, where c is this element's code (a number between 0 and 255).
submit.menu();
Ends menu creation.
enable.item(c); disable.item(c);
Enables or disables a menu item with the code c.
|-------- heading
v
-------------------------------
| File |
-------------------------------
Menu --->| Save |
Element |------------|
| Restore |
|------------|
|XXXXXXXXXXXX|<- menu element disabled
|------------| using disable.item
| Quit |
--------------
menu.input();
If Flag(14) = 1, a menu system is shown on the screen, allowing the user to choose an item. Whether an item with the code c has been chosen can be tested using a command controller(c)
, where c is the code assigned to the menu item.
XIV TEST COMMANDS
The result of test command can be either TRUE or FALSE.
equaln(n,m);
True if Var(n) = m.
equalv(n, m);
true if Var(n) = Var(m).
lessn(n,m);
True if Var(n) < m.
lessv(n, m);
True if Var(n) < Var(m).
greatern(n, m);
True if Var(n) > m.
greaterv(n, m);
True if Var(n) > Var(m).
isset(n);
True if Flag(n) = 1 (set).
isset.v(n);
True if Flag(Var(n)) = 1 (set).
has(n); True if the room field of item n is 255, i.e. the item belongs to the player.
obj.in.room(n, m);
True if room field of the object n is Var(m).
posn(n, x1, y1, x2, y2);
True if the coordinates of the base point of the cel which is the current image of object n satisfies the equation x1 <= x <= x2, y1 <= y <= y2.
obj.in.box(n, x1, y1, x2, y2); True if the base of the object n is completely within the rectangle specified using its top left (x1,y1) and bottom right (x2,y2) corners.
(x1, y1)
------------------
| |
| |
| |
------------------
(x2, y2)
center.position(n, x1, y1, x2, y2);
True of the center of the base line of the object n is inside the rectangle specified as its top left and bottom right corners.
right.position(n, x1, y1, x2, y2);
True of the right side of the base line of the object n is inside the rectangle specified as its top left and bottom right corners.
have.key();
True if the user has pressed any key on the keyboard. Used to create cycles to wait until any key is pressed.
compare.strings(s1, s2);
True if string(s1) = string(s2).
said(n, W(i));
where i = 1, ..., n True if the player has entered a phrase that completely matches W(1),...W(n), where n is the number of W(i) which are codes of the vocabulary words.
Here is how the input is matched. After the player types a message and presses Enter, the input line is processed by the interpreter.
Interpreter removes all punctuation marks.
All characters are converted to lowercase.
All sequences of more than one space are replaced with a single space.
Starting with the first word of the input, the interpreter looks up the vocabulary, trying to find the longest character sequence matching the entered.
If the search is unsuccessful, Var(9) is assigned the number of the word in the message that failed to match and the processing ends.
If all the words have been assigned some codes:
- The Interpreter removes from the sequence of codes all zeros (that means all vocabulary words with zero codes are ignored).
- Flag(2) (the user has entered an input line) is set to 1
- Flag(4) (
said
command accepted the user input) is set to 0.
If the sequence of code produced by the interpreter is V(1), V(2),...V(m).
The test is performed as follows:
If Flag(2) = 0 or Flag(4) = 1, return FALSE. Compare parameters W(i) and codes V(i) as follows: - if W(i) = 1, it matches any V(i);
- if W(i) = 9999, it matches the whole remaining input i.e. the codes V(i), V(i+1),...V(m).
Otherwise W(i) should be equal to V(i).
If all elements match, Flag(4) (said
accepted the user input) is set to 1 and the command returns TRUE. Otherwise, FALSE is returned.
controller(n)
True if the event with code n has occurred:
- a key with the code n was pressed (set using
set_key
); menu item with code n was selected in commandmenu_input
.
XV OTHER COMMANDS
configure.screen(a, b, c);
Sets position of lines on the screen:
a = 1 (minimum line number for print);
b - user input line;
c - status line.
obj.status.v(n);
Prints a message for the object Var (n):
Obj [number] x: [coordinate] y: [coordinate] pri: [priority] stepsize: .
show.mem();
Displays a report of the interpreter memory status.
show.pri.screen();
Shows priorities of the screen pixels. Priority n is shown as color number n (see color setting commands in I.1.2.1.1).
show.obj(n);
In the centre at the bottom of the screen a cel 0 of loop 0 of the VIEW resource n is shown. In the centre of the screen, a message associated with the VIEW resource is printed.
That's what they say but I suspect they mean OBJECT n, not VIEW resource.
Actually, in this case the argument does refer to the VIEW resource. This is because the VIEW in question isn't meant to be a controlled object but instead is simply the picture and textual description of the an inventory item.
shake.screen(n);
The screen shakes n times.
echo.line();
The last line entered by the user is displayed in the input line.
cancel.line();
Input line is cleared.
close.window();
If there is a text window on the screen, it is removed.
open.dialogue(); close.dialogue();
Enables and disables get_string and get_num commands if prevent_input has been issued.
restart.game();
Restarts the game from the very beginning.
save.game(); restore.game();
These command save and restore the current state of the game into disk files.
pause();
Stops the interpreter until any key is pressed.
quit(n);
Exits the interpreter.
If n = 1, quits immediately
If n = 0, asks "Press ENTER to quit.", "Press ESC to continue."
init.joy();
Initialize joystick.
toggle.monitor();
Switch RGB monitor into the graphics mode.
upper.left();
Usually the crossing by an object of various areas and lines is tracked by the base point (bottom right corner) of its cel. After this command, top left corner is used as such a point.
XVI UNKNOWN COMMANDS
only works with pc v3 games.
All of the mouse commands in this tutorial do not work with Brian's AGI mouse hack.
unknown170(n); [set.simple(n);]*
n is a string number using this makes a saved game's name the same as the string n you used.
unknown171(); [push.script();]*
This command is used if you want to temporarily load up something then unload it so that you do not use the interpreters script. This can stop the problem out of script.
unknown172(); [pop.script();]*
This command is used if you want to temporarily load up something then unload it so that you do not use the interpreters script. This can stop the problem out of script.
unknown173(); [hold.key();]*
This command makes it so you have to hold the arrow key to move a good example of this is in Mixed Up Mother Goose.
unknown174(n); [set.pri.base(n);]*
This affects the priority base of the AGI interpreter Kings Quest 4 uses this function to affect the table so the "base" (priorities <= 4) is bigger or larger at the top.
unknown175(n); [discard.sound(n);]
This command discards sound n.
unknown176(); [hide.mouse(n);]
This command hides the mouse pointer.
unknown177(n); [allow.menu(n);]*
This command determines wheather the menu is activated or not.
If n = 0 the menu is turned off.
If n = 1 the menu is turned on.
unknown178(n); [show.mouse(n);]
This command makes the mouse appear.
unknown179(n1,n2,n3,n4); [fence.mouse(n1,n2,n3,n4);]
This command sets up a fence which the mouse can not go out of.
unknown180(x,y); [mouse.posn(x,y);]
This command gets the position of the mouse pointer.
unknown181(n); [release.key(n);]*
This command does the opposite of unknown173(); it allows you to walk until you press a key to stop.
unknown182(x,y); [adj.ego.move.to.x.y(x,y);]
This moves the ego to the position set in x y.