205 lines
12 KiB
Markdown
205 lines
12 KiB
Markdown
# JoeyAGI plan: every Sierra AGI game
|
|
|
|
The goal is to run every Sierra AGI release. STATUS.md records where each
|
|
subsystem and command stands; this file is the road there. References:
|
|
Sierra's own interpreters, run as black boxes in DOSBox (`scripts/oracle.sh`),
|
|
and, since October 2026, the open-source implementations, ScummVM's AGI engine
|
|
first. They are read for behavior, never copied: ScummVM is GPL and JoeyAGI is
|
|
MIT. Where a source and Sierra's interpreter disagree, Sierra's interpreter
|
|
wins.
|
|
|
|
## Decisions (Scott, 2026-10-19)
|
|
|
|
| Question | Decision |
|
|
|----------|----------|
|
|
| Scope | Every DOS release of the 16 Sierra AGI titles, then the other releases (Phase 5) |
|
|
| Bugs in Sierra's game scripts that ScummVM patches | Patch them |
|
|
| Copy protection | Skip it, as ScummVM does for Gold Rush |
|
|
| Mouse | Add AGI v3's mouse: click-to-walk, the mouse commands, mouse menus |
|
|
| Save games | Keep JoeyAGI's own format; do not read Sierra's `*SG.n` files |
|
|
| Random numbers | Match Sierra's generator, so runs can be compared exactly |
|
|
|
|
## The games
|
|
|
|
Sixteen titles: King's Quest 1 to 4, Space Quest 1 and 2, Police Quest 1,
|
|
Leisure Suit Larry 1, Black Cauldron, Gold Rush, Manhunter 1 and 2, Mixed-Up
|
|
Mother Goose, Donald Duck's Playground, the AGI demos, and the 1986 Christmas
|
|
card. `games/` holds all sixteen and four fan games. ScummVM's detection
|
|
table (~/claude/scratch/joeyagi/scummvmAgi) names the known releases by
|
|
their directory files' MD5s.
|
|
|
|
On 2026-10-20 Scott's copy of the eXo ScummVM collection
|
|
(~/Downloads/eXo/eXoScummVM/eXo/eXoScummVM: read, never changed) added nine
|
|
releases to `games/` and the other machines' releases to `games/machines/`
|
|
(Phase 5, which test-agi.sh does not run yet): 13 Amiga, 11 Apple IIgs, 10
|
|
Atari ST, and 10 Macintosh. eXo's folders hold only the data, because eXo plays
|
|
them in ScummVM. Where a release lacks Sierra's interpreter, one of the same
|
|
version stands in (the "Interpreter" column), so the oracle can run it.
|
|
|
|
Still to obtain (asked of Scott 2026-10-20), each with Sierra's interpreter
|
|
files:
|
|
- Sierra's 3.002.086 (any DOS King's Quest IV AGI as shipped);
|
|
- 2.089 (Space Quest 1 1.0X, 1986-09-24) and 2.230 (the Christmas card's
|
|
version 1, 1986-10-13);
|
|
- a stock 2.936 (King's Quest III 2.14 or Space Quest II 2.0D/2.0F as
|
|
shipped), to confirm the copy in Caitlyn's Destiny;
|
|
- older releases on interpreters already covered (King's Quest 1 1.0U, King's
|
|
Quest III 1.01, Space Quest 1 1.1A, King's Quest 2 2.1, Donald Duck's
|
|
Playground 1.50, Police Quest 2.0E, the demos);
|
|
- the booter disk images (Phase 5).
|
|
|
|
| Folder | Game | Interpreter (AGIDATA.OVL) | Data |
|
|
|--------|------|---------------------------|------|
|
|
| bc | Black Cauldron | 2.439 | 386 KB |
|
|
| kq1 | King's Quest 1 | 2.917 | 344 KB |
|
|
| kq2 | King's Quest 2 | 2.917 | 488 KB |
|
|
| kq3 | King's Quest 3 | 2.435 | 651 KB |
|
|
| lsl1 | Leisure Suit Larry 1 | 2.440 | 455 KB |
|
|
| mmg | Mixed-Up Mother Goose | 2.915 | 401 KB |
|
|
| pq1 | Police Quest 1 | 2.903 | 700 KB |
|
|
| sq1 | Space Quest 1 | 2.426 | 529 KB |
|
|
| sq2 | Space Quest 2 | 2.912 | 644 KB |
|
|
| gr | Gold Rush | 3.002.149 (v3) | 1174 KB |
|
|
| mh1 | Manhunter: New York | 3.002.107 (v3) | 1034 KB |
|
|
| mh2 | Manhunter 2: San Francisco | 3.002.149 (v3) | 1189 KB |
|
|
| agidemo1 | AGI Demo 1, 1987-05-20 | 2.425 | 168 KB |
|
|
| agidemo2a | AGI Demo 2, 1987-11-24, 5.25" version 1 (its VOL.3, the second disk, is agidemo2b's: every entry matches) | 2.915 | 385 KB |
|
|
| agidemo2b | AGI Demo 2, 1987-11-24, 3.5" | 2.915 | 382 KB |
|
|
| agidemo2c | AGI Demo 2, 1987-11-25, 5.25" version 2 | 2.917 | 276 KB |
|
|
| agidemo3 | AGI Demo 3, 1988-09-13 | 3.002.102 (v3, DMDIR) | 247 KB |
|
|
| kq4gs | King's Quest IV, Apple IIgs 1.0K, 1988-11-22 (three 800K disks; IIgs font AGIFONT and instruments SIERRASTANDARD; Sierra's IIgs interpreter KQ4.SYS16) | IIgs 2.006, as DOS 3.002.086 (v3, KQ4DIR) | 1417 KB |
|
|
| xmas | The Christmas card, 1986-11-13 (version 2) | 2.272 | 178 KB |
|
|
| ddp | Donald Duck's Playground: a cracked PC booter image (DONALD.IMG) and its DOS launcher | booter (Phase 5) | 273 KB |
|
|
| kq6agi | King's Quest VI AGI demake (fan, Brandon Kouri) | 2.917 | 1469 KB |
|
|
| sqtlc | Space Quest: The Lost Chapter, mouse version (fan; AGI Mouse interpreter) | 2.917 | 1550 KB |
|
|
| sq0 | Space Quest 0: Replicated (fan; its interpreter is a Windows program) | none (2.435 assumed) | 1032 KB |
|
|
| kq3v214 | King's Quest III 2.14, 1988-03-15, 3.5" (eXo; its sound 36 shipped cut to 1035 of its 2281 bytes) | 2.936, from caitlyn | 643 KB |
|
|
| sq2v20f | Space Quest II 2.0F, 1989-01-05, 3.5" (eXo) | 2.936, from caitlyn | 637 KB |
|
|
| pq1v20g | Police Quest 2.0G, 1987-12-03 (eXo) | 2.917, AGI Tetris's (fan; kq1's quits at once on this game) | 694 KB |
|
|
| bcv210 | Black Cauldron 2.10, 1988-11-10, 5.25" (eXo; AGI 3) | 3.002.149: gr's, its built-in file prefix changed from GR to BC (a v3 interpreter carries its game's prefix, at 0x60D7) | 300 KB |
|
|
| mh2v303 | Manhunter 2 3.03, 1989-08-17, 5.25" (eXo) | 3.002.149, mh2's (3.02) | 1183 KB |
|
|
| grv201 | Gold Rush 2.01, 1988-12-22, 3.5", the original (eXo). gr, which ScummVM lists as pirated, is a cracked copy: its logic 129, the speed test, is the original's logic 73 | 3.002.149 (its own) | 1169 KB |
|
|
| kq4 | King's Quest IV 2.3, 1988-09-27, DOS (eXo) | none here (3.002.086, by its KQ4 prefix) | 1360 KB |
|
|
| ddpst | Donald Duck's Playground 1.0A, 1986-08-08: the Atari ST release's files, which eXo files as DOS | none (2.435 assumed; ScummVM takes 2.272) | 165 KB |
|
|
| caitlyn | Caitlyn's Destiny (fan, eXo): the source of the 2.936 interpreter (its AGI.COM is Sierra's SIERRA.COM; no fan hack files) | 2.936 | 1258 KB |
|
|
|
|
Starting point (2026-10-19): every v2 game but Mixed-Up Mother Goose boots
|
|
through its title into play on the host harness; Mother Goose stays black; the
|
|
v3 games cannot load yet.
|
|
|
|
Progress (2026-10-19, end of day):
|
|
|
|
- Phase 0: oracle.sh runs any game's sessions (tests/GAME/*.scr) on that
|
|
game's own loader and interpreter, and the probes on any v2 interpreter
|
|
(ORACLE_INTERP). Every v2 game has a start session in test-agi.sh
|
|
(49/49). The logic trace is AGI_HOST_VM_TRACE. Sierra's random generator
|
|
is in (read from 2.915; see STATUS.md). The timing and clock probes match
|
|
on 2.426 and 2.439; the other probes on the other interpreters are still
|
|
to run.
|
|
- Phase 1: Mother Goose plays (start, set.simple's pointer list of
|
|
players, the name, the face, the bedroom, the first room, F5 saving
|
|
under the name, restoring it). 0xAA to 0xB6 and test 0x13 are in, each
|
|
in its versions; the version keeps all three parts; the cycle and motion
|
|
modes share Sierra's four bytes; wander and follow.ego are Sierra's. Six
|
|
more differences found and fixed (STATUS.md, bugs 21 to 26).
|
|
- The oracle's shots drifted: each DOSBox screenshot's real cost was added
|
|
to the script's waits (about 1.5 s over twelve shots). Fixed: dosDrive.py
|
|
keeps each step at its time from the interpreter's start (DOSBox's log
|
|
line for the graphics mode), as the host harness's virtual clock does.
|
|
- Phase 2 (2026-10-20): done but for speed and memory (Phase 4).
|
|
- The v3 loader (agiRes.c: <prefix>DIR, LZW, nibble pictures, clear
|
|
messages in packed logics). Gold Rush, Manhunter 1 and 2, Demo 3, Black
|
|
Cauldron 2.10, and King's Quest IV (DOS and Apple IIgs) load every
|
|
resource and start. Every DOS v3 release with an interpreter here starts
|
|
as on Sierra's, run as <prefix>.COM.
|
|
- 3.002.086's rules for King's Quest IV and v3's draw and new.room rules.
|
|
- The mouse (agiMouse.c): the pointer, click-to-walk, the mouse commands,
|
|
and the menus and message windows by pointer (tests/kq3/mouse.scr, on
|
|
the host).
|
|
- agiPatch.c: King's Quest IV's zombie distance; its manual question and
|
|
Gold Rush's quiz skipped; Gold Rush's clock fed the real cycle rates.
|
|
- The eXo releases (above): King's Quest III 2.14 and Space Quest II 2.0F
|
|
match Sierra's 2.936 at the start, and Police Quest 2.0G, Black Cauldron
|
|
2.10, and Manhunter 2 3.03 match theirs. test-agi.sh 94/94.
|
|
|
|
## Phase 0: a test bench for every game
|
|
|
|
1. `scripts/oracle.sh` for any game, each run on its own interpreter (each game
|
|
folder ships one, or one of the same version stands in: fourteen versions
|
|
from 2.272 to 3.002.149).
|
|
2. The probe games run on every one of those interpreters, to measure what
|
|
differs between real versions (ScummVM treats every 2.426 to 2.440
|
|
interpreter as one); v3 interpreters need the probes in v3 format.
|
|
3. A logic trace (rooms, logics called, commands) for finding hangs.
|
|
4. Smoke sessions for every game in `scripts/test-agi.sh`, as King's Quest III
|
|
has.
|
|
5. Sierra's random number generator, matched (decision 6).
|
|
|
|
## Phase 1: every DOS v2 game (interpreters 2.089 to 2.936)
|
|
|
|
- Mixed-Up Mother Goose's black screen. Leads: the startup flags, hold.key,
|
|
set.simple, a window over the menu bar, writing v11.
|
|
- Commands 0xAA to 0xB6 and test 0x13, each in the versions that have it:
|
|
set.simple, push.script, pop.script, hold.key, set.pri.base, discard.sound,
|
|
hide.mouse, allow.menu, show.mouse, fence.mouse, get.mse.posn, release.key,
|
|
adj.ego.move.to.x.y, in.motion.using.mouse.
|
|
- Version rules: print.at with 3 arguments below 2.089 and quit with none on
|
|
2.089; move.obj's first step at once only above 2.272; loop changes that
|
|
ignore step time at 2.272 and below; save and restore stop the sound from
|
|
2.272; the 2.230 view mirror format; the note envelopes of 2.900 and 3.000.
|
|
- What some games rely on: motion and cycling sharing storage (King's Quest 1's
|
|
eagle, Black Cauldron's witches), strings surviving restart (Space Quest 2),
|
|
stopping a sound setting its flag (Police Quest 1), a tight clock-polling loop
|
|
yielding (Police Quest 1's poker).
|
|
- Sierra's script bugs, patched (decision 2): King's Quest 1's bow to the king,
|
|
King's Quest III's endless fall, the Rosella staircase and the room 77 talk,
|
|
Larry's leaving the store without paying, Space Quest 1's spider droid and
|
|
its exploding Roger (f103 still set when picture 20 is drawn).
|
|
- The interpreter version keeps all three parts (3.002.086 against 3.002.149).
|
|
|
|
## Phase 2: AGI v3 (Gold Rush, Manhunter 1 and 2, King's Quest IV, later Black Cauldron)
|
|
|
|
- The loader: `<prefix>DIR` with four section offsets, `<prefix>VOL.n`, the
|
|
7-byte resource header, LZW (9 to 11 bits, 0x100 resets, 0x101 ends),
|
|
pictures with 4-bit arguments to F0 and F2, messages not encrypted in
|
|
compressed logics.
|
|
- 3.002.086 (King's Quest IV): loops chosen for any loop count, the x <= 0 left
|
|
border, the priority-to-row glitch, one-argument hide.mouse and hold.key, the
|
|
zombie's distance (patched).
|
|
- v3 rules: draw reapplies loop and cel; new.room cancels a mouse walk;
|
|
allow.menu and release.key from 3.098.
|
|
- The mouse (decision 4): click-to-walk, the mouse commands, clicking the menu
|
|
bar and message windows, on every port.
|
|
- Game rules (done 2026-10-20): Gold Rush's clock fed the real cycle rates
|
|
(v165 and v167, which its speed test sets for a 1988 PC), and its book quiz
|
|
skipped (decision 3). ScummVM's Manhunter rule, Enter as Space when the
|
|
input line is off, is not needed: both games map Enter to Space's
|
|
controller themselves.
|
|
- Speed and memory: LZW on the 8 MHz machines, 1.2 MB of data.
|
|
|
|
## Phase 3: every game played through
|
|
|
|
- A scripted walkthrough per game on the host harness (virtual time): the main
|
|
path, deaths, the score, the endings, checked at checkpoints against the
|
|
game's own interpreter.
|
|
- Copy-protection quizzes skipped (decision 3); Larry's age quiz has its
|
|
own way past, Alt+X (a set.key that sets f109).
|
|
|
|
## Phase 4: every game on every machine
|
|
|
|
IIgs, Amiga, ST, X68000, DOS, and the hosted ports: memory, speed at 8 MHz,
|
|
disks (a CFFA2 volume per game on the IIgs; every game fits in 2 MB), and the
|
|
four-voice sound by ear.
|
|
|
|
## Phase 5: the other releases
|
|
|
|
- Amiga, Atari ST, Apple IIgs, Macintosh, and CoCo3 data: 4-byte OBJECT entries
|
|
on the Amiga, the `dirs` and `vol.N` file names, each machine's palettes and
|
|
font, and its sound: the IIgs's sampled instruments and MIDI-like music, the
|
|
CoCo3's and Apple II's own note formats.
|
|
- The v1 booter disk images: King's Quest 2, Black Cauldron, Donald Duck's
|
|
Playground (directories on disk sectors, the v1 command set, v1 words and
|
|
sound).
|
|
- The Apple II disk images.
|
|
- The Game Adaptation Language games (King's Quest 1 of 1984, Apple II King's
|
|
Quest 1), which ScummVM does not run either.
|