12 KiB
12 KiB
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: 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 .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
scripts/oracle.shfor 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).- 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.
- A logic trace (rooms, logics called, commands) for finding hangs.
- Smoke sessions for every game in
scripts/test-agi.sh, as King's Quest III has. - 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>DIRwith 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
dirsandvol.Nfile 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.