# 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 resource loader, the PICTURE and VIEW decoders, the LOGIC VM and the VM pipeline, built for the host against JoeyLib's headers and run on every game in `games/` (`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).