joeyagi/README.md

JoeyAGI

An interpreter for Sierra's Adventure Game Interpreter (AGI) v2 games -- King's Quest III and its contemporaries -- written from the public AGI format descriptions on JoeyLib, so it runs on every machine JoeyLib targets: the Apple IIgs, Commodore Amiga, Atari ST, MS-DOS, Sharp X68000 and DVX. It decodes the games' own resource files (LOGIC, PICTURE, VIEW, SOUND, OBJECT, WORDS.TOK); it ships no game.

Setting up

JoeyAGI builds with JoeyLib, which owns the cross compilers, the library and every machine's build rules. Check JoeyLib out beside this repository and install its toolchains (its README covers the installer):

games/
    joeylib/      a JoeyLib checkout, set up with ./install.sh
    joeyagi/      this repository

$ cd ../joeylib
$ ./install.sh install toolchains        # the cross compilers
$ ./install.sh install emulators         # to run it and for the gates

JOEYLIB=PATH on the make command line (or in the environment, for the scripts) points at a checkout somewhere else.

Games

The interpreter needs an AGI v2 game's files. Put each game in its own folder under games/ (games/kq3/, ...), which git ignores; games/README.md lists the files and where legitimate copies come from.

Building

$ make                      # every machine whose toolchain is installed
$ make dos                  # one: iigs amiga atarist dos x68000 dvx
$ make iigs-game-disk-agi   # the bootable IIgs volume, with games/kq3 on it
$ make clean

The programs land in build/<machine>/bin/: AGI (IIgs), Agi (Amiga), AGI.PRG, AGI.EXE, AGI.X, and on DVX apps/joeylib/agi/. make iigs-game-disk-agi writes build/iigs/bin/AGI.2mg, a 2 MB bootable volume holding the interpreter and the game (AGI_GAME=NAME puts games/NAME on it instead). JoeyLib's library is built on demand in the JoeyLib checkout's own build/.

Running

The interpreter reads the game from its DATA folder; JoeyLib's joey-run copies a game there for the run:

$ ../joeylib/joey-run --project . --port dos --data games/kq3 agi
$ ../joeylib/joey-run --ram 8M build/iigs/bin/AGI.2mg

The IIgs volume boots off a CFFA2 card in MAME and wants 8 MB of memory.

The gates

$ make check                # build, then every gate
$ scripts/verify.sh host    # or name the ones to run

Gate	What it proves
host	The whole interpreter, built for the build machine on JoeyLib's headless port, plays scripted sessions and every frame asked for must hash as expected: every resource of every game in games/ loads and decodes (KQ3's pictures hash as Sierra's interpreter draws them); twenty probe games built from scratch by tests/probes.py (pictures, windows, motion, control lines, priority, the parser, menus, inventory, sound timing, ...); and, with games/kq3, four KQ3 sessions (the opening, play, save/restore/restart, debug teleports) (scripts/test-agi.sh)
disk	AGI.2mg with King's Quest III boots on a IIgs, launches the interpreter and draws

scripts/verify.sh exits 0 when every gate passed, 1 when one failed, and 3 when none failed but one was skipped (no game in games/, or the IIgs toolchain or emulator missing).

The expected hashes live in tests/expected/; scripts/test-agi.sh --update records new ones once a change has been checked. Every run leaves its frames in build/tests/out/.

Checking against Sierra's interpreter

$ scripts/oracle.sh                 # every probe and KQ3 session
$ scripts/oracle.sh windows parser  # or some of them

scripts/oracle.sh plays the probes (and tests/kq3/*.scr) on Sierra's own interpreter -- the copy in games/kq3, in DOSBox Staging at 386SX-16 speed -- and on JoeyAGI, then compares the frames with tests/tools/compareFrames.py, which reads text with each interpreter's font (JoeyAGI's is its own). The probes record what happened into variables and print them, so their frames match whatever the timing; the KQ3 sessions run in real time on one side and virtual time on the other, so moving things differ by a cycle or two. STATUS.md has the results.