# AGI game data

Everything in this folder except this file is ignored by git. No game's
files are, or should ever be, committed to the repository.

Place each game in its own subdirectory:

```
games/
  agidemo/    # Sierra's promotional AGIDEMO (freely redistributable)
  kq3/        # Local copy extracted from your licensed King's Quest 3
  ...
```

`scripts/test-agi.sh` runs the host tests against every subdirectory that
holds a `LOGDIR` (v2) or a `<prefix>DIR` (v3), and `make
iigs-game-disk-agi` puts `kq3` (or `AGI_GAME=NAME`) on the bootable IIgs
volume. Everywhere else the
interpreter reads the game from its `DATA` folder; `joey-run --data
games/kq3` copies a game there for one run.

Releases for other machines go one level down, in `machines/` (`kq1amiga`,
`kq1gs`, `kq1st`, `kq1mac`, and so on), and the booter disk images in
`booters/`; the host tests do not look there yet (PLAN.md, Phase 5).

`scripts/oracle.sh` plays a game's sessions on the Sierra interpreter in its
folder, so keep Sierra's files (`AGI`, `AGIDATA.OVL`, and the loader) with
each game. One game's interpreter does not run another: each `AGI` is keyed
to its own loader, and a v3 one carries its game's file prefix.

## Required files per game

For an AGI v2 game directory the loader needs:

- `LOGDIR`     - logic script index
- `PICDIR`     - picture (room background) index
- `VIEWDIR`    - view (sprite/animation) index
- `SNDDIR`     - sound index
- `VOL.0`      - resource volume 0 (always present)
- `VOL.1`..`VOL.N` - additional resource volumes (game-dependent)
- `OBJECT`     - inventory table
- `WORDS.TOK`  - parser dictionary

An AGI v3 game instead has one `<prefix>DIR` holding the four indexes and
`<prefix>VOL.0`..`<prefix>VOL.N` (`GRDIR` and `GRVOL.*` for Gold Rush);
the loader knows the prefixes of Sierra's v3 games (`KQ4`, `GR`, `MH`,
`MH2`, `BC`, `DM`). `OBJECT` and `WORDS.TOK` are the same.

The loader reads Sierra's interpreter version from `AGIDATA.OVL` when the
folder has it, to behave as that version did (see `agiQuirk`); without
it the interpreter behaves as 2.435, the version it was measured on (or,
for a v3 game, 3.002.149).

File names are uppercase by AGI convention; the loader looks them up
literally so the directory should match.

## Sourcing AGI data

This repository never ships copyrighted Sierra game data. Two legitimate
sources for development and testing:

1. Sierra's freely-distributed `AGIDEMO` promotional disk -
   redistributable since the late 1980s.
2. Fan-made AGI titles authored with AGI Studio - many are released
   under explicit redistribution licenses.

To test against a commercial Sierra game you legally own, extract
the data files from your own copy and drop them in a new sibling
directory here. Do not commit them.