101 lines
4.3 KiB
Markdown
101 lines
4.3 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/kpunch/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 game session
|
|
$ scripts/oracle.sh windows parser # or some of them
|
|
```
|
|
|
|
`scripts/oracle.sh` plays the probes on Sierra's own interpreter (the copy in
|
|
`games/kq3`, or the game `ORACLE_INTERP` names) and each game's sessions
|
|
(`tests/GAME/*.scr`) on that game's interpreter, in DOSBox Staging as a fast
|
|
386, 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 sessions run in
|
|
real time on one side and virtual time on the other; `tests/tools/dosDrive.py`
|
|
keeps every step at its time from the interpreter's start, so the two stay in
|
|
step and moving things differ by a cycle at most. STATUS.md has the results.
|