99 lines
4.1 KiB
Markdown
99 lines
4.1 KiB
Markdown
# 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](../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
|
|
```
|
|
|
|
```console
|
|
$ 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
|
|
|
|
```console
|
|
$ 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:
|
|
|
|
```console
|
|
$ ../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
|
|
|
|
```console
|
|
$ 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
|
|
|
|
```console
|
|
$ 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.
|