View source for AGDS - Adventure Game Development System Documentation

[[Official AGDS/AGI Documentation]]<br />

<div align="center" style="font-size: 22pt">AGDS - Adventure Game Development System</div>


==<br /> OVERVIEW ==

'''AGDS''' was developed as a fast means to implement adventure games using a machine portable language. It outwardly resembles the programming language "C".

'''AGDS''' is a specialized set of commands which help manipulate objects on a 3-D plane. Before looking at the commands, it is important to understand some basic terminology.

'''[[Room|ROOM]]''' -- we divide our games into "rooms"--locations based upon a map. For instance, if a game is inside a house, room 1 might be the living room, room#2 the kitchen, etc. When the adventure moves outdoors, room #11 might be the left side of a lake and room #12, the right side. The amount of landscape in a room is controlled by the graphics of the room's picture.

'''[[AGI Picture Resource|PICTURE]]''' -- Usually, each ROOM has an associated picture. In some cases a room has multiple pictures. In King's Quest 2, Dracula's castle had numerous rooms with two pictures; one with the room lit, and another mainly black picture (indicating the lights were out). Donald uses three pictures within the banner page room, a logo picture, a title picture and the credits screen.

'''[[Object|OBJECT]]''' -- OBJECTs may be either ANIMATED OBJECTS or INVENTORY OBJECTS, the difference being whether thye appear graphically on screen or exist only to be
carried. Example:  in Quest2 there were two objects, the mallet and the bracelet. King Graham sees a tree in the woods that contains a mallet. He can say "GET MALLET" and the mallet goes into his inventory. With the mallet in inventory, he can say "SHOW MALLET" and a window opens, displaying the mallet. The bracelet is seen lying on the beach. When he says "GET BRACELET" it disappears off the screen. Once in inventory, it can be "look"ed at just like the mallet. Because the bracelet appears on screen during the game, it is an "animated object."  Since the mallet exists only to be taken into inventory, it is called an "inventory object."  "Animated" objects can be "DRAWN" on the screen and animated. "Inventory" OBJECTs can only be held in inventory. Both may be "SHOWn" in a pop-up screen window, once they are in inventory.

'''[[Cel|CELLS]]''' -- AGDS works like traditional cartoon animation. If Little Red Riding Hood is seen stooping to pick flowers, she must be drawn as a series of CELLS showing her going from standing up to bending over. At
NORMAL speed, AGDS cells are cycled at the rate of 9 per second. If Riding Hood is 20 pixels by 20 pixels, each CELL uses about 200 bytes of memory. Obviously, all CELLS to be displayed must be in memory when the animation begins. A collection of CELLS that form an animation sequence is called a LOOP. Each cell contains the specific bit-maps AGDS displays on-screen.

'''[[Loop|LOOPS]]''' -- Each loop contains from 1 to 10 CELLS. Little Red Riding Hood picking a flower is a LOOP, Red skipping is another LOOP, Red walking without skipping is yet another. VIEWS -- Views consist of from 1 to 4 LOOPS. An animated object may have a view consisting of 4 LOOPS:  right, left, front, and back. You can only load VIEWS, not just a LOOP. Often, memory constraints will force a character to have only 2 loops, a right and a left. AGDS determines which LOOP is displayed, based on the direction of an object. Only the four directions [r, l, f, b] are supported. LOGICS -- Each room has LOGIC associated with it. This LOGIC is the procedural set of instructions that gets executed describing game play. AGDS always automatically loads, and executes ROOM 0. From there, the logic programmer must handle everything.

'''[[ROOM 0|ROOM #0]]''' contains the LOGICS that are common to the entire game, low level functions like "SAVE GAME," "HELP," etc. Instead of coding instructions to handle saving the game into every room, put it in room 0. DYNAMIC LOGICS are used for the same reason. They are rooms that have no picture, but process commands that occur in multiple ROOMs. Every ROOM that needs swimming can load a LGC.SWIM which deals with commands like SWIM, and standing ego up when he is no longer in water. It would be a nuisance and a waste of disk space to code this redundantly for each ROOM with water in it. If it were in ROOM #0 it would occupy ram even in ROOMs without water. Memory is valuable; anything that cuts down memory requirements is good!

'''[[LAST LOGICS]]''' are simply the last LOGICS executed. Here you handle things like the player giving a command that the other logics don't recognize. For instance, if the player asks the game to swim when there is no water in a ROOM, no dynamic logic is loaded to deal with water. Somehow the player needs to be told we don't understand what he said. LAST LOGICs handles all code trying to provide intelligent responses to input not dealt with by one of the earlier-processed logics.

'''[[Sound Resource|SOUNDS]]''' -- sound effects and music work just like PICTURES and OBJECTS, load
them, then call them.

==<br /> Priorities ==

AGDS pictures are composed of a picture screen, and a priority screen. The picture is arranged as 160 by 168 pixels, numbered from 0-159, and 0-167. Each pixel is one of 16 colors. Associated with each pixel is a "priority", from 0 to 15. Priorities 4 to 15 determine the 3-D plane, 0 to 3 are "control" priorities, with special meaning.

=== Three-D Priorities ===

Priority 4 is the lowest 3-D priority; any pixel on this priority will always be in the background, and ego and all other objects appear "in front" of it. All objects appear behind priority 15 pixels, unless the object is also a priority 15.

Objects can only be one priority at a time. An object's priority is usually determined by the Y coordinate of its baseline, according to the following table:

{| <!-- class="wikitable" --> width="150" align="center" border="1" cellspacing="0" cellpadding="0" bgcolor="#F9F9F9"
|- bgcolor="#F2F2F2"
! align="center" colspan="2"|Priority Table
|- align="Center"
|&nbsp;'''Y-coord'''&nbsp;||'''Priority'''
|-
|0-47||align="center"|4
|-
|48-59||align="center"|5
|-
|60-71||align="center"|6
|-
|72-83||align="center"|7
|-
|84-95||align="center"|8
|-
|96-107||align="center"|9
|-
|108-119||align="center"|10
|-
|120-131||align="center"|11
|-
|132-143||align="center"|12
|-
|144-155||align="center"|13
|-
|156-167||align="center"|14
|}

'''Example:''' if EGO is at 50/75, he is at priority 7. He will show behind pixels at priority 8 to 15 and in front of priorities 4 to 7.

If an object with priority 8 is drawn on a picture that also has priority 8, the object appears in front. If it appears in front of another object with the same priority, the object with the lower Y coordinate appears in front.

=== Control Priorities ===

These priorities apply only to pictures. Object may not be set to priorities 0 thru 3.

==== Priority 0 ====

Called "Priority Zero."  No pixel of an object's baseline may land on a picture pixel of priority 0. It is used at the base of trees, rocks, etc, to stop objects from passing thru them. However, objects set to priority 15 appear to "float" over the entire picture, and thus do ignore Priority 0.

==== Priority 1 ====

Called "block."  Nearly the same as priority 0, except objects can pass over it, or not. The action "ignore.blocks()" allows objects to cross priority 1. There is also an action "block(x,y,x,y)" that can be established through the logics; it works exactly the same way, but can be defined, redefined, and discarded on the fly.

==== Priority 2 ====

Called "special."  When any pixel of EGO's baseline coincides with a pixel of priority 2, the "hit.special" global flag is set. This priority is used when you need to know if EGO has touched a location, and a position block won't work. Used to know if ego has walked into a chasm.

==== Priority 3 ====

Called "water."  When all pixels of EGO's baseline are on priority 3, the "on.water" global flag is set. This priority is often used for water, so EGO can swim, or to keep a character within a boundary.

==== COMMENTS ON PRIORITIES ====

Control pixels still have a visual priority from 4 to 15. To accomplish this, AGDS scans directly down the control priority until it finds some "non-control" priority.

Some objects step by more than 1. This means that their baseline when moving along the Y coordinate can step over priority 0. To get around this, in Quest 2 we put vertical bars of priority 0 inside trees and rocks etc.

Priority 15 objects ignore all control priorities in the picture. For instance, they pass over priority 0 as if it weren't there.


See the file [[AGI.DOC]] for a complete discussion on each individual function.

==<br /> WORKING WITH LOGIC FILES ==

=== [[CG]] ===
the game compiler<br />
This is the most used. Assuming you use [[BRIEF]] to edit the source code files, call the compile macro (often assigned to the F9 key). It saves your file, calls the CG game compiler, routes CG's output to your [[LGC Subdirectory|LGC]] subdirectory, and if errors are found, displays them in the current window.

In addition, 'cg' can now be run properly from BRIEF.

* It generates output in the filename format which the interpreter and utilities want. Thus:<br /><code>cg rm0</code><br />puts its output in 'rm.0'.<br />&nbsp;

* You can reroute output with the '-o' switch:<br /><code>cg rm0 -o..\lgc</code><br />puts its output in ..\lgc\rm.0.<br />&nbsp;

* It takes wildcards in filenames. You can compile the world with:<br /><code>cg *.cg</code><br />&nbsp;

* You can pass 'cg' its parameters from a file:<br /><code>cg @file</code><br />gets its command line from the file '[[FILE File|file]]'. This is used in the '[[MAKE.BAT|make]]' and '[[MAKEUSE.BAT|makeuse]]' batch files.

=== [[MAKE.BAT|MAKE]] ===
'make' uses the program 'cgupd' to create a list of all files for which the source code date/time is more recent than the object code date/time. It feeds  this list to 'cg' for compilation. Thus, you can make modifications to lots of  files, then type 'make' to recompile 

all of them.

=== [[MAKEUSE.BAT|MAKEUSE]] ===
'Makeuse' is similar to make, but uses 'find' to generate a list of all files containing a given string. If, for example, you change the number corresponding to a given flag, you can update everything by typing:
makeuse flag_name

=== [[BRIEF Macro|MACROS]] ===
The BRIEF macros "[[ALLFILES.M|allfiles.m]]" and "[[MODIFY.M|modify.m]]" allow you to modify all of your source files at once. To use them, edit the file "\brief\macro\modify.m" to do whatever you want done to your files. Compile it (use F9) until it is correct, and automatically loaded. Then press F10 (BRIEF's "command"), and enter "allfiles."

"allfiles" asks for a "modification criterion," which will probably be "[[RM*.CG|rm*.cg]]". It must be a regular BRIEF search string. Allfiles then calls "ls" to read the current directory, searches for files matching the "modification criterion," reads each file into BRIEF, calls the macro "modify," then saves the file. After all files are done, exit BRIEF and do a "cg" with the same "modification criterion."  There should be no need to modify "allfiles"; it is just a general purpose driver that calls "modify."

For example, to modify the action names, set up "modify" with the appropriate "replace/translate" commands, then invoke "allfiles" with a criterion of {[[GAMEDEFS|gamedefs]]}|{*.cg}.

==<br /> THE OBJECT EDITOR ==

{| class="wikitable" width="425"
! align="center" colspan="2"|Lower-Case command keys
|-
|l||set screen block upper-Left corner position.
|-
|r||set screen block lower-Right corner position.
|-
|e||Edit cel (prompts for cel #).
|-
|s||Save cel (prompts for cel #).
|-
|g||Get loop file from DOS (prompts for filename).
|-
|p||Put loop file to DOS (prompts for filename).
|-
|m||Mirror the current cel.
|-
|x||set X-step for current loop (prompts for value).
|-
|y||set Y-step for current loop (prompts for value).
|-
|t||set step-Time for current loop (prompts for value).
|-
|c||set current Color (prompts for color code).
|-
|n||display Next cel at upper-left corner of current block.
|-
|h||Hack current loop's cel count (described below).
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|Upper-Case command keys
|-
|I||set Insert mode (described below).
|-
|D||set Delete mode (described below).
|-
|N||set Normal mode (described below).
|-
|S||set Slow speed mode (described below).
|-
|M||set Med. speed mode (described below).
|-
|F||set Fast speed mode (described below).
|-
|Z||set Zip. speed mode (described below).
|-
|C||Clear screen & re-display colorbar, etc.
|-
|Q||Quit edit session & return to DOS.
|-
|B||Block fill (described below).
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|Cursor control keys
|-
|width="75"|up arrow||Up.
|-
|right arrow||Right.
|-
|down arrow||Down.
|-
|left arrow||Left.
|-
|Pg Up||Up-Right.
|-
|Pg Dn||Down-Right.
|-
|End||Down-Left.
|-
|Home||Up-Left.
|}

Insert, Delete, & Normal modes:
In Insert or Delete modes, a color dot is written at the current cursor position (current color for insert, black for delete) each time the cursor is moved, at each position the cursor crosses. The dot is written at the current cursor position BEFORE moving to the next, 

NOT at the new position. Normal mode does not alter the screen on cursor movement.

{| class="wikitable" 
|-
|ins||Insert current color dot at current cursor position.
|-
|del||Delete dot at current cursor position.
|}

=== Speed modes ===
Each cursor movement key will move the cursor in the direction indicated for the number of positions indicated by the current speed mode selected. Slow speed causes the cursor to move one dot for each cursor movement key. Medium, Fast and Zip move the cursor 2, 3, and 4 dots per cursor movement key, respectively.

'''NOTE:''' In Insert or Delete modes, the screen alteration functions will alter all positions passed over by the cursor in its movement, not just the destination position.

=== Block fill command ===
Fills the area of the screen described by the last Set upper-Left, Set lower-Right commands with the current color.

=== Hack cel count command ===
Will delete the specified cel and all higher-numbered cels from the current loop (prompts for cel number).

==<br /> MAKING VIEWS ==

"[[MAKEVIEW|MAKEVIEW]]" is a utility that creates views out of loops. It reads a text file called VIEWS in the \loops subdirectory for its instructions. A driver batch file, "[[MV.BAT|MV.BAT]]" is used to automatically call makeview and update the \view subdirectory.

The [[VIEWS File|VIEWS file]] must contain an entry for each view, including some (or all) of the following information, in the following format:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
view 3, skip 3: 3r 3l 3f 3b</syntaxhighlight>
<code>skip 3</code>    means this object was drawn with a background color of 3 (default, black 0).
<code>r,l,f,b</code>   gives the number & description of the loop

To make, or fix, a view:

1. Edit the file "VIEWS," in the loops subdiretory.

2. type:
<code>mv ## [##-##]</code>  (where ## is the view number to be made; viewnums can be single, or ranges separated by a "-")

==<br /> THE PICTURE EDITOR ==

{| class="wikitable" width="425"
! align="center" colspan="2"|CURSOR MOVEMENT
|-
|1 pixel||arrow keys
|-
|diagonally 1 pixel||Fn-arrow keys
|-
|10 pixels||ctrl-PgUp,PgDn,left,right
|}

{| class="wikitable" width="570"
! align="center" colspan="4"|PICTURE EDITING
|-
|Space||forward 1 instruction||&nbsp;||&nbsp;
|-
|Backspace||back up 1 instruction||&nbsp;||&nbsp;
|-
|Tab||forward 1 picture code||&nbsp;||&nbsp;
|-
|Shift-tab||backward 1 picture code||&nbsp;||&nbsp;
|-
|Del||delete previous step||&nbsp;||&nbsp;
|-
|B||goto beginning of picture||&nbsp;||&nbsp;
|-
|E||goto end of picture||&nbsp;||&nbsp;
|-
|&nbsp;||&nbsp;||'''Priority'''||'''Color Numbers''':
|-
|H||start horizontal line||align="center"|0||black
|-
|V||start vertical line||align="center"|1||blue
|-
|D||start diagonal line||align="center"|2||green
|-
||C||start curved line||align="center"|3||cyan
|-
|&nbsp;||&nbsp;||align="center"|4||red
|-
|F||start color fill||align="center"|5||magenta
|-
|Fn1||set color||align="center"|6||brown
|-
|Fn2||clear color||align="center"|7||white
|-
|Fn3||set priority||align="center"|8||dark grey
|-
|Fn4||clear priority||align="center"|9||bright blue
|-
|Fn5||toggle rubberband mode||align="center"|10||bright green
|-
|Fn6||toggle status display||align="center"|11||bright cyan
|-
|Fn7||toggle RGB/composite mode||align="center"|12||bright red
|-
|Fn9||show graphics screen||align="center"|13||bright magenta
|-
|Fn10||show priority screen||align="center"|14||yellow
|-
|ESC||to drawing screen from Fn9/Fn10||align="center"|15||bright white
|-
|Shift-Fn1||save screen image as bitmap||&nbsp;||&nbsp;
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|
|-
|G||goto Nth instruction (tab N times)
|-
|L||get picture file from disk
|-
|S||save picture file from disk
|-
|W||wipe out present picture (clear)
|-
|<||delete from beginning to current location
|-
|>||delete to end from current location
|-
|A||appends a picture to end of present picture
|-
|Q||quit (confirm?)
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|On Drawing Screen
|-
|purple lines||priority lines
|-
|white lines||priority & color lines
|-
|green lines||color only
|}

==<br /> THE SOUND EDITOR ==

The four vertical bands represent voice1, voice2, voice3 and the noise channel respectively. Each horizontal bar is one frame of the interpreter (or 1/9-second) in length. The beginning of the sound is at the top of the screen, the end is at the brown line. Voice3 can be linked to the noise channel, or not.

All keys below are non-caps sensitive. Use the number keypad for best results:  the most commonly used keys are on it. Editor must be booted directly from the floppy with DOS 2.10.

{| class="wikitable" width="425"
! align="center" colspan="2"|Disk Access
|-
|G||get a file from disk
|-
|P||put a file on disk
|-
|Esc&nbsp;&nbsp;||cancel current request
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|CURSOR KEYS
|-
|<nowiki>-</nowiki>||back a frame
|-
|+||forward a frame
|-
|Home||back a voice
|-
|PgUp||forward a voice
|-
|Del/.||delete a frame
|-
|Ins||insert a frame (of silence)
|-
|Enter||copy current frame & insert
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|PITCH CONTROL
|-
|Up/Down||adjust volume up/down
|-
|Left/Right||adjust pitch lower/higher
|-
|L||Lengthen current note
|-
|S||Shorten current note
|}

{| class="wikitable" width="425"
! align="center" colspan="2"|MISC. FUNCTIONS
|-
|End||play to the END of the sound
|-
|PgDn||toggle between:  all voices, current voice, no voices
|-
|R||Repeat present sound continuously
|-
|C||Couple voice3 to noise generator
|-
|Q||Quit
|}

==<br /> MUSIC ROUTINES ==

=== Big Picture ===

Name the source files:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
snd##.mt</syntaxhighlight>

(The extension refers to the compiling program, maketune.) After entering the source code, use the "MT" batch file to compile it.
Use the form:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
mt ##</syntaxhighlight>

where ## is the number of the sound that matches the ## in the snd##.mt filename. The batch file calls MASM to assemble the code, LINK to link it, EXE2BIN to convert it, then MAKETUNE to convert it to an adventure game file named snd.##. It may then be tested with the PLAY program:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
PLAY snd.##</syntaxhighlight>

When the file is correct, enter:<br />
<blockquote><code>UPDATEM</code></blockquote>

which will clean the various junk files out of the music directory, and transfer the snd.## files from the \music directory to the ..\snd directory.

==<br /> Source Code Format ==

=== INCLUDES ===
Files must start with:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
include   pitches
include   tempo##</syntaxhighlight>

Files must end with:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
include   musicend</syntaxhighlight>

Somewhere in the file must be the labels:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
voice1
voice2
voice3</syntaxhighlight>


whether the other voices are used or not.

=== Pitches ===
Notes are specified by name and octave number, followed by a rhythm, and an optional integer articulation. A middle B-flat quarter-note, separated from the following note by a two-cycle space would be:
bf3  q,2
Pitch range is from C0 to B5. Accidentals are specified by either "f" or "s" before the octave number.

=== Rhythms ===
The "tempo" files contain the range of rhythms, generally from s for sixteenth to w for whole notes. See them for details.

=== Rests ===
Rests are specified by "rest" and a duration:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
rest q</syntaxhighlight>

=== Volume ===
Volume is specified by:
<div class="CodeBlockHeader">AGI Code:</div>
<syntaxhighlight lang="agi">
atten ##</syntaxhighlight>

where ## is an integer from 0 to 14. Maximum volume = 0;   minimum is 14. Volume remains set until a new atten is specified. Do NOT follow an atten by a rest!

==<br /> To Make a Direct I/O Game Disk ==

1. edit the file "[[DISKINFO|diskinfo]]" to describe every disk in the game. See the "makedisk" subdirectory for example. This file allocates disk space for whatever you will later write to disk.

2. Create a file called "vol0.drv" (and/or "vol1.drv" etc.) that describes volume 0. It must contain, in order:

{| class="wikitable" width="525"
! align="center" colspan="2"|
|-
|volume 0||the name of the volume
|-
|for rm, pic, etc||the pathname to each subdirectory
|-
|files list||the name of every file to be included in the volume
|}

3. Run "[[MAKEDISK|makedisk]]" batch file, with a formatted disk in drive a:.

'''To Update An Old Disk:'''
1. Don't run "[[MAKEDISK|makedisk]]" as it does everything all over, and perhaps you only need to change one small part.

2. Call "[[MKVOL|mkvol]]," giving it as a parameter, the number of the volume to be made. Example, to construct volume 0, type:
<code>MKVOL 0</code>

3. After all [[VOLUME|volumes]] are made, call "[[MKDISK|mkdisk]]" with the following parameters:

{| class="wikitable" width="425"
! align="center" colspan="2"|
|-
|MKDISK all||re-do everything
|-
|p||change interpreters only
|-
|b||change boot files only
|-
|ao||change [[ANIOBJ|aniobj]] and object tables only
|-
|wt||change [[WORDS.TOK|words.tok]] only
|-
|v01||change directories only
|-
|0v||change volume 0 only
|}

==<br /> ERROR MESSAGES ==

Error messages are now contained in a separate dynamic logic, which must be on every disk. They appear in the format:
<code>error # : n</code>

# can't find "where"
# object #n too large in set.view
# view not loaded for set.view
# object #n too large in set.loop
# loop #n too large in set.loop
# view not set
# object #n too large in set.cel
# cel #n too large in set.cel
# message #n not defined in print
# too many logics in load.logics
# too many pictures in load.pic
# too many animated objects
# object #n too large in animate.obj
# object #n too large in get.obj
# object #n too large in drop.obj
# invalid action
# out of memory by #n bytes
# picture not loaded in draw.pic
# object #n too large in draw
# no view of object #n in draw
# object #n too large in erase
# cell size > save size for view #n
# picture not loaded in discard
# view not loaded in discard
# too many views in add.to.pic
# stack overflow
# attempt to set memory mark when one is already set
# start/stop update when obj not drawn

==<br /> References ==

<references />

===<br /> See Also: ===

* [[AGI Specifications]]


[[Media:AGDS.pdf|Download the Adventure Game Development System in PDF Form]]

[[Category:References]]
[[Category:Documentation]]