NAGI Documentation
By Nick Sonneveld


Contents

  1. What is NAGI?
  2. Installation
  3. Identifying and Isolating an AGI Game
  4. Running 
  5. Configuring
  6. Adding a New Game to the CRC List
  7. Submitting an Unknown Game's Details
  8. Warnings
  9. Bugs in Sierra's Interpreter
  10. External Font Format (NBF)
  11. Credits
  12. Other Texts

What is NAGI?

NAGI (New Adventure Game Interpreter) is a clone of Sierra's own AGI which they created and used through the 80's to produce a whole bunch of great adventure games like Space Quest, Leisure Suit Larry and Kings Quest. NAGI was created by disassembling the original AGI executable and writing equivalent C code that would run under SDL which is a free generic library for low-level access to graphics and audio. It can read both v2 and v3 game data for the PC.

I started working on this (disassembling and learning stuff) around November 1999. I didn't really do much work on it until the start of 2001 when I finished the picture rendering code. So I started with a program that draws agi pics to this... I actually got the initial idea from the guy who recreated an old game called Digger . He did the same thing by disassembling the original game and recoding it all in C.

The original name for NAGI was GI-Jay.. like GI-Joe only different.  It evolved from JayGI.  NAGI sounds a bit more sophisticated anyway and can be confused with a whole bunch of things!

From the "3D Animated Adventure Game Reference Card For MS-DOS":

Sierra's 3D animated adventures represent a totally new approach to computer gaming -- a third generation in computer adventure.  They feature colourful hi-res graphics, with animated characters moving through three dimensional background screens.  The improved parser lets you talk to the computer in whole sentences.

Sierra's new series of adventures are interactive, changing as you explore and solve the puzzles.  New facets are revealed as you delved into the game.  In fact, you can play the game many times over and never play the same game twice.


Installation

Installing NAGI:
Download the SDL Windows DLL runtime from the SDL website.  Extract DLL into the Windows system directory.
Extract NAGI into any folder you wish.

Installing games:
By default, NAGI will search one folder level up for games.. unless you change the defaults set in nagi.ini/[nagi]/dir_search_list

Unzip your games into the NAGI folder in their own separate game folders.  The name does not matter but a unique name will help you identify your game if it was not automatically recognised.

Eg:
\NAGI
\NAGI\KQ
\NAGI\KQ2
\NAGI\SQ
\NAGI\V

Executing NAGI:
To execute NAGI, run the “n.exe” executable.  You do not need to be in the same directory for NAGI to find all it’s files.

Identifying and Isolating an AGI Game

Of all the AGI games I have encountered, they all follow a few basic file name arrangements.
Where <GAMEID> is replaced by the game's actual id (eg "KQ4" for Kings Quest 4).

The original Sierra interpreter used these files and are not used by NAGI:
agi, sierra.com, agidata.ovl, cga_graf.ovl, ega_graf.ovl, hgc_font, hgc_graf.ovl, hgc_objs.ovl, ibm_objs.ovl, jr_graf.ovl, vg_graf.ovl
They can be safely deleted or moved to another directory to save space.

Sierra also has a later interpreter called SCI.  NAGI does not run these data files but FreeSCI does!  You can pick out these files because they follow the format:
resource.XXX, resource.map
Very tidy.

NAGI also runs Amiga games.  They can be handily found at Back 2 the Roots .  Just search for "Sierra".  The last I heard, they were given permission to distribute the old Amiga versions of the games.  However, they first have to be extracted from the amiga disk image (ADF) first. There's a nice program called ADF Opus that does this work for you.  Just extract all the files found in the "data" directory and NAGI should be able to run those files with no trouble at all.

There are some slight differences between the Amiga games and the PC games.  Some of the older games don't support the "ESC" key to access the menu, instead it just pauses the game.  To access the menu you will have to click on the status bar with the mouse, just like the Amigians had to do.  Older Amiga games accepted the "ESC" key properly.

Running

Mostly from the "3D Animated Adventure Game Reference Card For MS-DOS" with some americanisms and irrelevant information removed.  I've added NAGI and mouse information.

Startup
On startup, NAGI will search for games and display them in a list.  You can select your game with the arrow keys and execute it by pressing “enter”.  If you wish to leave the menu, press “ESC” any time in the menu.

If only one game if found, NAGI will skip the menu and go straight into the game.

Commands for your Hero
A joystick or the number pad/arrow keys on your keyboard moves the main character north, south, east, west or diagnolly.  To halt your character's steps with the keypad, press the last diection key again or the number 5.

During the game you many change control modes by stopping the main character (see above) and resuming either joystick or keyboard control.  (If you've never used the joystick before in the game, pres Control-J to activate it)

Your mouse will be useful to you in mvoing your character.  To move your character using the mouse, position the arrow to where you want the character to move, then click the left mouse button.  If you click on the status bar, the pop-down menu will appear.  Clicking any mouse button when a message box appears will clear it.

Talk to your computer in commands of one or two words, or even simple sentences.  Unless otherwise instructed, follow all commands with the ENTER key.

You may meet others who have message for you.  Command them to speak.  Type:
TALK TO THE GNOME

You may later need objects you see along the way.  Type:
GET THE KEY

Pay attention to details.  To see an object closely, type:
LOOK AT THE SHIP

Use the objects you find along the way.  Type:
GIVE THE BASKET TO THE GIRL

To fully savour a scene you enjoy watching or negotiate a narrow path, you can slow down the animation.  Speed up the animation to make the main character walk faster.  To change the speed, type "slow" or "fast" and press ENTER.  To return to the original speed, type "normal" and press ENTER.  Function and control keys shortcut these common commands:

F1
Help: shows list of control keys (including some specific to your game which may not be mentioned here)
F2
Toggle sound on/off
F3
Echo (repeat) previous command)
F5
Save game
F7
Restore game
F9
Restart game
CTRL-C
Cancel typed input
CTRL-J
Reset joystick
CTRL-R
Toggle RGB/composite graphics mode (most MS-DOS machines)
ALT-Z
Quit game
TAB
Inventory
CTRL-ALT-
right or left arrow
Shift display (right or left)

Pop up Menus
Press ESC or click on the status bar with your mouse and a menu bar will appear at the top of your screen.  Use the left or right arrow keys to choose a menu.  Use the up or down arrow keys to highlight a menu item.  Press ENTER to select a highlighted item or press ESC to go back to the game.

ESC
Pops up menus
ARROW KEYS
Highlights menu/menu items
ENTER
Chooses highlighted item.
HOME/END
Jump to first/last menu
PGUP/PGDN
Jump to first/last menu item

Saving and Restoring The Game
To allow for errors in judgment, and also for some pretty creative exploration, we make it possible for you to save and restore the game.  Before you try something that looks dangerous, or just because you've been playing awhile and you don't want to lose what progress you've made through some chance encounter, save your game.

Saving a Game
Type "save game" and press ENTER, or press F5 to save your current game location.  This can be done at any time during your game.

You need only to press ENTER when prompted about the directory in which to save your game position.  If you want to save more than 12 games, create additional saved game directories.  Consult your DOS manual to make new directories on your hard disk.

In General
Although your game position is stored on disk as a normal DOS file, we do not require you to follow MS DOS file naming conventions in identifying your saved game position.  If you are standing before a tree when you save a game, call your saved game "STANDING BEFORE A TREE" or whatever has meaning to you.  You are permitted to save up to 12 different game locations per directory.

If you "run out" of saved game positions (you want to save more than 12 games), just use a different saved game directory, save game disk, or reuse (save over) one of the 12 positions you've already saved.  To change the name of a previously saved game, just enter Control-C and type a new name.

Restoring a Game
Type "restore game" and press ENTER.  (You can also press F7.)

You will be asked wheere you saved the game.  To accept the default directory, press ENTER.  Otherwise, clear the line with Control-C, type the drive or directory on which you saved the game (example: "b:"), and press ENTER.  Now select the game you wish to restore by moving the pointer and pressing ENTER.

NOTE: If the game shows up on a colour system in black and white:
Inside your computer you can have a graphics card installed known as the Colour Graphics Adapter.  With an RGB monitor, you will be unable to produce 16 colour graphics.  (a composite colour monitor will produce 16 colour graphics with a CGA card.)  The most your CGA/RGB configuration can produce is 4 colour graphics.  To toggle graphics modes enter CTRL-R at any point during play.  An alternate graphics card, the Enhanced Graphics Adapter, is now available from many sources.  this will upgrade your computer to 16 colour capability.  This EGA card is definitely recommended for Sierra games and you will find it also has advantages with other software.

From Space Quest 4, Quest For Glory 2 and Space Quest Manuals:

Tips and Advice
If you haven't played on of Sierra's 3D animated adventure games before, here are a few suggestions to help you get on the right track...

LOOK everywhere. When you go somewhere you haven't been before, or where you think you may have missed something the first time, the first thing you should do is look around.  When you type "look" on entering an area, you will receive a description of the general area.  Read this description carefully -- often there is a clue to the game or an indication that something in the scene bears further investigation

Thoroughly explore your surroundings.  Open doors and drawers, look under things and behind things for valuable objects and clues.  Look closely at all objects you encounter or you may miss important details.  If you are standing close enough to a particular object you can take a close look at the specific thing.  EXAMPLE: "look at spaceship."  Press ENTER each time you type a command to enter that command.

EXPLORE each area of the game very carefully, and DRAW A MAP as you progress through the game.  Make a note of each area you visit, and include information about objects found there and dangerous areas nearby.  If you miss an area, you may miss an important clue!

TALK to almost everyone you meet, but use discretion!  Some characters will be friendly and helpful.  They will give you valuable information and advice.  Others may mislead, capture, or even kill you.  At times it maybe be necessary to fight at others, to run away, hide or try to outwit your opponent.

GET anything that isn't nailed down.  You'll come across a number of objects that will be of use later in the game.  Some of these can be picked up, other may have to be bought or traded for.  You can see an inventory of items on hand by pressing the TAB key at any time.

USE the items you have picked up to solve problems in the game, or to help you to make progress and discover more clues.  Different approaches to a puzzle may bring about a different outcome.  Some problems have obvious solutions; if you're thirsty, take a drink of water.  To purchase an item, you'll need some money.  Other problems require more imagination to solve.

BE CAREFUL, and remain alert at all times - disaster may strike in the most unlikely of places!

SAVE YOUR GAME OFTEN, especially when you are about to try something new or potentialy dangerous.  This way, if the worst should happen, you won't have to start all over again from the beginning.  Save games at different points, so you will always be able to return to a desired point in the game.  In effect, this will enable you to travel backwards through time and do things differently if you wish.  NOTE: You cannot save your game during certain critical times, so remember: SAVE EARLY, AND SAVE OFTEN!

DON'T GET DISCOURAGED.  If you come to an obstacle that seems insurmountable, don't despair.  Spend some time exploring another area, and come back later.  Every problem in the game has at least one solution, and some have more than one.  Sometimes solving a problem one way will make it harder to solve the next, and sometimes it will make it easier. If you get stuck, you might try backtracking to an earlier point in the game, then choosing a different path.

If all else fails, you can write to other players for hints.  Try the AGI Messageboard or the Subspace Channel and ask for help in the game you're playing.  Please be polite and give enough information for other people to follow.  Don't resort to using a walkthrough, this will ruin the enjoyment and puzzles of the game.

BRING ALONG SOME HELP.  You may find it helpful (and fun) to play the game with a friend.  Two (or more) heads are better than one at interpreting clues and solving problems, and heroes throughout history have worked in teams.

Configuring

There are two configuration files used by NAGI.  Nagi.ini and standard.ini.

nagi.ini

Used to configured options related to NAGI only.  Graphics, sound and input are the main things here

Options in nagi.ini are:

[nagi] Section
console
Determines whether standard output and errors will go to the console window (console=1) or to two separate text files.  Handy if you want to record debug messages that occur.
crc_print
Prints the CRC of all games detected.  Handy to add an unknown game to NAGI’s CRC list.  Use with console=0 to save them to a file.
dir_list
a list of directories, separated by ‘;’ that NAGI will search to find AGI games.  If it is not a full path, it will search from the folder N.EXE exists in.  ie, if you define dir_Search_list to equal “.;games” it will search nagi’s main folder and a folder called games, also in nagi’s main folder.
sort
when NAGI has a list of games.. this is what is used to sort it.  0 = no sort.  1 = alpha sort  2= reverse alpha

[vid] Section
driver
at the moment NAGI only supports SDL for it’s video driver but it will hopfully support other drivers in the future.
scale
a multiplier used to define the screen.  320x200 is the resolution used when scale = 1.    Depends on whether a font is available for a certain scale.
full_screen
display the game in full screen.
renderer
supports cga0, cga1 and ega.  You can now emulate what your games used to look like on your old pc that only had a CGA adapter.  Set renderer to cga0 or cga1 to see them.
fonts_bitmap
files with extensions .nbf are used to define external fonts for nagi. This will be a list of filenames separated by ‘;’

[snd] section
driver set this to "sdl" for NAGI to use SDL's sound drivers.  SDL is currently only supported.
enable
enable sound.. might speed up for some systems if disabled
single
do you wish for the single channel days of the PC?  if "single" is set, then NAGI will only play the first channel of sound resources. Might be a bit loud too.. turn the volume down a bit if your ears are bleeding
dissolve
AGI fades notes away to give them more impact.  The data used to fade notes varies between interpreter versions.  It's probably an envelope.. but I don't know what either is really... not into music
0 = no dissolve.. just play for as long as it's meant to be played.  This was used in older v2.4xx (and older) games I THINK
1 = not used
2 = v2.9xx games used a shorter dissolve
3 (default) = v3 games used this dissolve pattern.. slightly longer
Note: dissolve does not affect the noise channel in the original interpreter and NAGI follows this faithfully.
read_var
AGI will read a variable (23) which will contribute to the volume calculations.  The problem is 0=max volume, 0xF=silence.  Guess which games don't set this correctly.  Yup... almost every single bloody game that uses the AGI template.  To Chris Cromer's credit: he's fixed it in his version of the template.
Set this to 1 if you run sierra games (or fan games that have this set correctly)
volume
volume for square wave.  The maximum is 0x7FFF (max for a signed word) (around 32000).  Set this lower if you want a quieter game.  Remember, the actual volume will be this variable divided by the number of channels.

[sdl] section
If a sound or video section is defined to use SDL.. it will read some options from this section.
drv_video
supports directx and windib
drv_sound
supports directx and waveout.  Waveout sounds a lot better on my PC.

standard.ini

Used to define different agi standards.  There are many different versions of AGI and they all differ slightly.  Standard.ini defines some known PC and Amiga standards and also provides a CRC system to help identify games and associate them with the correct agi standard.

This config file has been designed to be helpful for any interpreter.. not just NAGI.  Only game related information should be in this section.

It has two types of sections defined in it.  The first is [standard] which is the core of standard.ini.  it defines all the sections that will contain crc’s to match known games and other options.  There is only one [standard].  The second type are sections defining games or standard default interpreters.   It is designed so sections that inherit other sections.  So if you define a game section called [donald], you can let it inherit an interpreter called [pc_v2_440] instead of having to define all of the options to emulate a v2.440 interpreter.

CRC_LIST -> GAME -> INTERPRETER


Options for [standard]

crc_list
list of all sections that contain game crc matching information.  Each section is separated by a ';'.
agi_list
list of all sections that default a default interpreter.  Each section is separated by a ';'.
force
force nagi to not search for games but just use a specific game standard in the main working folder.  Useful for fan games.
v2_default
if there are no crc matches and it has been determined to be a v2 game.. use this standard
v3_default
if there are no crc matches and it has been determined to be a v3 game.. use this standard
amiga_v2_default
if game has been determined to be an Amiga v2 game, use this standard
amiga_v3_default
if game has been determined to be an Amiga v3 game, use this standard

Options for games [game_name]

name
the name used in the game selection menus and the window title bar.
inherits
if a key in not found in this section.. it will check the section defined in inherits.  You can use inherits for as many sections as you want.  
id
used for save games.  Not used for copy protection anymore
protection
protection hacks.. not implemented but will bypass tests and copy protection later on


version_info
used for when a user requests the interpereter version.
mouse There are different variations of interfaces to access the mouse.  0=no mouse 1=sierra v2 automouse 2=sierra v3 extra mouse commands 10=brian buff’s mouse support
loop_update
if you let the interpreter automatically pick the loop of an animated moving object, it will only do it if it has under 4 loops maximum in version 2 interpreters, any number of loops in early v3 interpreters and only if a flag is set for any number for later v3. 1=four, 2=all, 3=flag
object_decrypt if set to 1, nagi will try and decrypt the object file before trying to read it.
object_packed determines whether the object is word packed (amiga) or not (pc)
compression determines whether the interpreter will try and use decompression on the volume files or not.
dir_type
are the dir files separated or joined up into one. 0=none 1=separated 2=combined 3=combined amiga style
crc_vol_X
a 32 bit crc of a volume file.  Use winzip’s crcs or nagi’s crc_print to determine the crc’s.  Will try crc_vol_0 to crc_vol_15.
crc_dir
for version 3 interpreter files.. crc of the combined dir file
crc_dir_log
crc of a log dir
crc_dir_view
crc of a view dir
crc_dir_pic
crc of a pic dir
crc_dir_snd
crc of a snd dir
crc_object
crc of an objects file
crc_words
crc of a token file

Adding a New Game to the CRC List

The point of adding a new game to the list is to correctly identify the game.  If you correctly identify it, you can specify the name and the interpreter to use.

A good example for this is Kings Quest 4.  It uses a version 3 interpreter that requires slightly different operations or else Rosella will moon walk all over the screen.  All over v3 games don’t need this however.

Normally if you were adding a new game would you just have this defined in standard.ini

[new_game]
name=My new Game v1.0 2001-10-12
inherits=pc_v2_939
crc_vol_0=0xE6CBCDAE
crc_dir=0xAC18F6EA
crc_object=0x6F8E1901
crc_words=0x6F42A9A1

and then add “new_game” to the crc_list at the top of the standard.ini.

Now when NAGI searches directories and finds this game.. it will be corrrectly named instead of using a default best-guess naming scheme.

The “pc_v2_939” will have the other options such as compresion or directory/object structure.

I have tried to have a common naming scheme in the order of: name, version, date (YYYY-MM-DD).
The CRC values for a particular game can be determined by using WinZip’s CRC checksums (they are the same) or by using the “crc_print” option in nagi.ini

Submitting an Unknown Game's Details

The information I need is included in this list in order of necessity (ie, if you can't get the file sizes or interpreter version.. that's ok) There can be slight differences between games versions and I think that some of these differences can be attributed to copy protection removal. I believe the games that have copy protection are: Kings Quest 4, Gold Rush, Man Hunter 1/2 and Kings Quest 3.  If your game has copy protection or protection removed, that would be useful to note as well.

Once you have all or some of this information, please send an email with this information to sonneveld@hotmail.com and i'll add it to the next version of NAGI that's released.  If you include your name and email address, I'll add you to the credits too.

NAGI Warnings

The original Sierra interpeter let a lot of things slide whenever the logic programmer makes a mistake.  While this is nice when you're playing a game and you don't want to be hassled by warnings, it's not so useful when you're the logic programmer.  NAGI is slowly adding warnings to it's code to help programmers prevent easy mistakes.

Object Loading Warnings
"object_file_load(): and the baby bear said, "this object is too small!""
Object files have to be a certain size or else they're no longer object file.  This is just a quick sanity check.

"object_file_load(): default options invalid.  Attempting alternative decryption/packing methods..."
There are several different types of object files available (encryption, word packing) so NAGI tries the default option first.  If this option does not work this means it probably is under the wrong agi standard in standard.ini but it will try different methods anyway.

"object_file_load(): invalid object file"
After trying different methods to open the object file, if it doesn't look correct then NAGI will assume it's an invalid object file and stop loading.

"object_file_load(): number of animated object's defined = XXX"
This is just a handy way of comparing the number of animated objects defined between games.

"object_file_load(): warning! object string does not end in '\0'. "
This means that the last string in the object file does not end with an EOL character.  Usually nothing points to the last string in the object file but this is just in case because if something does and a function tries to read it, it won't stop and will keep on reading into unknown memory.

Directory Warnings
"dir_load(): original dir option failed.  Trying alternative dir options."
If the original dir option does not work, NAGI will print this message and then try other dir names/methods to load it up.

"dir_load(): unable to load an AGI directory."
After trying different directory names, NAGI will give up and print this error

Other Warnings
"obj_loop_set(): "just out of range" loop bug occured with anim obj XXX"
A warning to the bug mentioned in the "Bugs in Sierra's Interpreter" section.  NAGI will then silently set the loop to the last loop available in the view object

"mstack max = XXX"
The Brian Buff mouse support uses a stack so if two button presses occur between a game loop, it won't lose any data.  This is just a reminder of what the largest size of the stack is for debugging purposes. (ie, if it keeps on getting bigger then you're not checking it often enough)

"no cmd=CMD NAME"
"no eval=EVAL NAME"

Prints this warning if a command was not implemented in NAGI and it had to ignore it.  There are a handful of commands and evaluations that NAGI does not support.  Namely the Amiga specific ones and some debugging commands.

"cmd_clear_lines(): warning, upper and lower in wrong order."
Some games try and reverse the upper and lower bounds but it's not correct and it used to crash NAGI until it checked it.  If this error occurs, NAGI will only clear the first line at upper to prevent screen clearage in some games.

Bugs in Sierra’s Interpreter

If you do not define a logic for debug tracing command names.. it is meant to just print out the command numbers.  But because of a bug, it does not do this and prints garbage.

When using set.loop or set.loop.v the allowed loop range should be 0…(LOOP_TOTAL – 1).. but because of a missing equals sign somewhere in their code.. if you set the loop to be equal to loop_total (or one above the maximum), it will not cause an error and keep on going.  However, the animated object have a loop data pointing to a random location.  Real life example: bow before the king in KQ1

The command set.pri.base goes through an array but goes past it a bit and starts reading other bits of the stack I believe.  Through sheer luck, it doesn't do anything strangely in the original interpreter.  It crashed NAGI in it’s original form.  Real life example: KQ4

The message box function barfs if there's a very long string placed just after a control code or new line.  It won't properly wrap unless you make sure there's a space just before the very long string.

The animated object code differs between versions.  If you run the XMAS demo on a real v2.9 interpreter there will be bits missing on the scrolling text.  The bits reappear in earlier interpreters.  Some other differences show in the old Donald Duck game too. In other games, sprites can go missing in newer versions of AGI, and then reappear in older versions.

You should only call restore.game from logic.0.  If you call restore from a called logic function, it may cause problems because it will be returning back through logics that have been unloaded and loaded again.  The logic may not be in the exact place as before.

External Font Format (NBF)

NAGI uses external fonts to help reduce executable size and to save memory.  Also, users can create their own fonts and use them for higher or lower resolutions.

When choosing the correct font to display, NAGI looks at all the available fonts and picks the best one that will represent the current renderer standard in the selected scale.  If there isn't a font large enough for the renderer/scale then it will try smaller scales until one fits.

When the format of the format has stabalised, it will be documented.

Credits

Justin Kerk - suggesting bug fixes and new features for NAGI.
Charles Irwin - comments and CRC submissions for some games I did not have
Chris Cromer - For testing NAGI with a LOT of games.
AGI Messageboard - interesting conversations, comments and a place to announce new versions of NAGI.
#agi at dalnet
#sarien at opennet
Tim Pitman - testing out earlier versions of NAGI for a stupid malloc size bug.
Dark Fiber - helpful comments and testing.

NAGI uses SDL which is a cross-platform media library that supports video and sound amongst other things.

Here's their blurb:
The Simple DirectMedia Layer (SDL for short) is a cross-platfrom library designed to make it easy to write multi-media software, such as games and emulators.

The Simple DirectMedia Layer library source code is available from:
http://www.libsdl.org/
This library is distributed under the terms of the GNU LGPL license:http://www.gnu.org/copyleft/lesser.html

Other Texts