AI_Slop/joeyagi
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
joeyagi/PLAN.md
Scott Duensing 6814d22929 A lot more AGI games added for testing.
2026-10-21 01:16:19 -05:00

14 KiB
Raw Blame History

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.

Two of Scott's collections added to them (both read, never changed):

  • eXo ScummVM (~/Downloads/eXo/eXoScummVM/eXo/eXoScummVM, 2026-10-20): the data of nine releases, and the other machines' releases in games/machines/ (Phase 5; test-agi.sh does not look there yet): 13 Amiga, 11 Apple IIgs, 10 Atari ST, and 10 Macintosh.
  • A TOSEC-style set of Sierra's DOS floppies (~/Downloads/20220303_20220303_0527, 2026-10-21), each named with its interpreter. Its disk images were copied out with mtools, taking the cracked first disk where the original is copy-protected (DOSBox cannot run the disk check). It gave the eXo releases their own interpreters, fifteen more releases, and the booters in games/booters/ (Phase 5).

Every DOS folder now runs on its own Sierra interpreter. The one exception is King's Quest IV's three releases: Sierra's first asks a word from the manual, picked at random, so their sessions are JoeyAGI's alone.

Still to obtain: the Christmas card's version 1 (interpreter 2.230, 1986-10-13), King's Quest II 2.1, Donald Duck's Playground 1.50 as files, and the demos ScummVM lists that games/ lacks (King's Quest III and Space Quest I, Demo 2 for the Tandy, the King's Quest IV and Larry demos).

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" (its sound 36 shipped cut to 1035 of its 2281 bytes) 2.936 643 KB
sq2v20f Space Quest II 2.0F, 1989-01-05, 3.5" 2.936 637 KB
pq1v20g Police Quest 2.0G, 1987-12-03 2.917 694 KB
bcv210 Black Cauldron 2.10, 1988-11-10, 5.25" (AGI 3; the interpreter is one SIERRA.EXE) 3.002.098 (ScummVM takes 3.002.149) 300 KB
mh2v303 Manhunter 2 3.03, 1989-08-17, 5.25" 3.002.149 1183 KB
grv201 Gold Rush 2.01, 1988-12-22, 3.5", the original. 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 1169 KB
grv30 Gold Rush 3.0, 1998-12-22, The Software Farm's re-release: its logic 129 goes from the speed test straight to room 73, past the quiz 3.002.149 1193 KB
kq4 King's Quest IV 2.3, 1988-09-27 3.002.086 1360 KB
kq4v20 King's Quest IV 2.0, 1988-07-27 3.002.086 1358 KB
kq4v22 King's Quest IV 2.2, 1988-09-27 3.002.086 1367 KB
kq1v10u King's Quest 1.0U, 1986 2.272 332 KB
kq3v101 King's Quest III 1.01, 1986-11-08 2.272 642 KB
sq1v11a Space Quest 1.1A, 1986-11-13 2.272 520 KB
sq1v10x Space Quest 1.0X, 1986-09-24 2.089 574 KB
pq1v20e Police Quest 2.0E, 1987-11-17 2.915 694 KB
sq2v20c Space Quest II 2.0C, 3.5" 2.917 636 KB
sq2v20d Space Quest II 2.0D, 1988-03-14, 3.5" 2.936 637 KB
kq1i425 King's Quest 2.0F (kq1's data) 2.425 337 KB
kq2i426 King's Quest II 2.2 (kq2's data) 2.426 481 KB
lsl1i917 Leisure Suit Larry 1.00 (lsl1's data) 2.917 448 KB
sq1i917 Space Quest 2.2 (sq1's data) 2.917 522 KB
mh1i102 Manhunter 1.22 (mh1's data) 3.002.102 1026 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). Its interpreter says 2.936 but is 512 bytes larger than Sierra's 2.936 1258 KB
booters/ Phase 5: Black Cauldron 1.1J, 1.1K, 1.1M, and Tandy; Donald Duck's Playground 1.0Q (2.001); King's Quest 1984 for CGA, CGA+RGB, PCjr, Tandy, and Tandy+PCjr (the Game Adaptation Language); King's Quest II 1.0W, 1.1H, and Tandy v1 and earlier 7.3 MB of images

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 new releases (above) start as on their own Sierra interpreters (STATUS.md, "Gates"), with three fixes (STATUS.md, bugs 35 to 37): 2.089's status line, Manhunter 1's Field Guide question skipped, and oracle.sh's choice of program. test-agi.sh 124/124.

Phase 0: a test bench for every game

  1. scripts/oracle.sh for any game, each run on its own interpreter (each DOS game folder ships Sierra's: seventeen versions, 2.089 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: King's Quest IV, Gold Rush, and Manhunter 1 so far, agiPatch.c); Larry's age quiz has its own way past, Alt+X (a set.key that sets f109). An oracle session for King's Quest IV must read its random question and answer from the manual.

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.