# AGI port — session handoff

This document captures the state of the AGI interpreter port as of
2026-05-15. Hand it to a fresh Claude Code session to pick up where
the previous one left off.

## Project context

JoeyLib is a unified C game-dev library targeting Apple IIgs (perf
floor / reference), Amiga, Atari ST, MS-DOS. The AGI port is a
from-scratch reimplementation of Sierra's Adventure Game Interpreter
v2 on top of JoeyLib's surface / draw / input APIs. Written from
public AGI format specs only -- NOT derived from ScummVM / NAGI /
Sarien (those are GPL'd; JoeyLib is not).

Test data: KQ3 v2, locally installed at
`examples/agi/gamedata/kq3/`. The user owns the game and is not
distributing it; gamedata is gitignored.

## Current phase

**Phase 1 sub-D** (callback-driven rendering): verified working.
Logic.0 + room 45 init paint KQ3's title screen on every supported
port. Ego sprite (VIEW 0, Graham) draws on top with priority masking,
WASD/arrow keys move him, ESC quits.

What's next: **Phase 1 sub-E** (input + animation opcodes). The
title screen does not auto-advance because the VM still stubs ~150
opcodes including `wait`, `set.menu`, `accept.input`, animation
timers, etc. Real KQ3 progression past the title requires implementing
enough of those to let logic.45 complete its intro and call new.room.

Phase 2 sub-A onward: parser, NPC actors, sound (NTP / PSG).

## What works (verified)

- Resource loader (LOGDIR / PICDIR / VIEWDIR / SNDDIR / VOL.x)
- PIC decoder (visual + priority planes, flood fill, vector draw)
- VIEW decoder (cel parse + RLE blit + priority masking + mirror)
- LOGIC VM: 256 vars, 256 flags, 8-deep call stack
  - Real handlers: arithmetic (0x00-0x11), OP_IF (0xFF), OP_GOTO
    (0xFE), OP_NEW_ROOM (0x12/0x13), OP_LOAD_LOGIC (0x14/0x15),
    OP_CALL (0x16/0x17), OP_LOAD_PIC (0x18), OP_DRAW_PIC (0x19),
    OP_SHOW_PIC (0x1A), OP_DISCARD_PIC (0x1B), OP_OVERLAY_PIC (0x1C)
  - All ~180 other action opcodes are stubs (skip their arg bytes
    via `kActionArgBytes[256]` table)
- Host callbacks: fetchLogic / loadPic / drawPic / showPic /
  discardPic / overlayPic
- Per-platform save-under for the ego sprite (no full-stage memcpy
  per frame; IIgs uses MVN-based codegen)
- Cross-platform binary works on all 4 ports (`AGI.EXE`,
  `AGI.PRG`, `Agi`, IIgs `AGI`)

## What does NOT work

- **Title screen never advances.** Stubs the input / timer opcodes
  the title uses. Workaround: starting-room override (argv[2]).
- **No NPC actors.** animate.obj / set.cel / set.loop are stubs.
- **No parser.** said() and the word-tokenize opcodes are stubs.
- **No sound.** Phase 3 work.
- **IIgs run path for AGI** is not wired. `scripts/run-agi.sh iigs`
  prints an explicit "not yet wired" message describing the missing
  disk-packager work (need bigger 2mg volume + case-folded ProDOS
  names + game-data argument to `package-disk.sh`).
- **ST / Amiga can't pass argv.** Hatari `--auto` and Amiga
  startup-sequence don't forward args, so the starting-room override
  only works on DOS. ST / Amiga AGI starts at the title screen.
  Fix needs either a config-file stage (`ROOM.TXT` read at startup)
  or enough title opcodes for the title to advance naturally.

## How to test

```bash
source toolchains/env.sh

# Host-side parsers + VM (fast iteration, no emulator)
./scripts/test-agi.sh

# Cross-platform binary in DOSBox
./scripts/run-agi.sh dos                # title screen
./scripts/run-agi.sh dos kq3 1          # jump to room 1
./scripts/run-agi.sh dos kq3 3          # jump to room 3

# Other platforms (no argv support yet, always title)
./scripts/run-agi.sh atarist
./scripts/run-agi.sh amiga
./scripts/run-agi.sh iigs               # prints "not wired" message
```

## Files touched (this session)

New:

- `src/core/random.c` — xorshift32 PRNG (jlRandom / jlRandomRange / jlRandomSeed)
- `examples/agi/*.c` — agi.c, agiRes.c, agiPic.c, agiView.c, agiVm.c
- `examples/agi/agi.h` — all AGI types + public API
- `tests/agi/*.c` — testAgiRes / testAgiPic / testAgiView / testAgiVm / testAgiPipeline
- `scripts/test-agi.sh` — host-build runner for all five tests
- `scripts/run-agi.sh` — cross-platform emulator launcher (dos | amiga | atarist | iigs)

Modified:

- `include/joey/core.h` — random prototypes
- `include/joey/platform.h` — auto-detect from compiler defines
- `.gitignore` — examples/agi/gamedata/
- All four make/*.mk — added agi to EXAMPLES list

## Architectural decisions worth remembering

### Render loop: save-under, not full stage copy

The naive per-frame `jlSurfaceCopy(stage, gBackdrop)` is 32 KB of
memcpy + present overhead -- not acceptable on a 2.8 MHz IIgs. The
current code:

1. `cbShowPic` paints the picture onto the stage ONCE and snapshots
   it as `gBackdrop`. Sets `gPicReady = true` and invalidates any
   prior ego save-under.
2. Per frame: `jlSpriteRestoreUnder` the last-frame ego rect (puts
   clean backdrop bytes back), `jlSpriteSaveUnder` the new ego rect,
   then `agiViewDraw` paints the cel with priority masking.
3. Placeholder sprite for save-under is 4x5 tiles = 32x40 stage
   pixels, sized to cover any AGI v2 ego cel. Compiled via
   `jlSpriteCompile` so save/restore use the platform's compiled
   fast path (MVN block-copy on IIgs, etc.) instead of the C
   interpreter fallback.

Per-frame memory traffic: ~1.3 KB save+restore vs ~32 KB full copy.

### VM throttling

AGI's native cycle is ~6 Hz. Running logic.0 every frame (60 Hz) is
6800-byte switch dispatcher × 60 = ~400k opcodes/sec for nothing.
`agi.c` now runs runVmCycle once every 10 frames (~6 Hz on 60 Hz
refresh, ~5 Hz on 50 Hz PAL). Input polling, ego movement, render
still run at full refresh -- only the bytecode interp is throttled.

Startup pumps the VM until `gPicReady` (or 32 cycles) so the user
never sees a flash of COLOR_MISSING before the first room paints.

### VIEW mirror handling

Sierra's encoder writes `mirror=1, src=N` on BOTH loops in a mirror
pair, where N is the lower-numbered loop. `agiView.c:resolveMirror`
must only treat a cel as mirrored when `src != current_loop`. KQ3
view 0 hit this directly: both loop 0 (right) and loop 1 (left) had
`mirror=1, src=0`, and our original code flipped both -- so pressing
left and right both faced left. Fixed.

### Starting-room override

`agi.c` argv[2] = starting room number 1..255. When set,
`runVmCycle`'s NEW_ROOM handler substitutes the override for
`vm.newRoomId` on the FIRST NEW_ROOM halt only (one-shot). Lets the
user skip past KQ3's title room (45) into the actual game. Once the
override fires, subsequent transitions go through unchanged.

`scripts/run-agi.sh` accepts `<platform> [game] [room]` and forwards
the room to DOS via dosbox `-c "AGI.EXE . <room>"`. ST and Amiga
can't pass argv via autostart so their AGI starts at the title.

### Default game dir is "." not "agidemo"

`resolveGameDir` defaults to "." (CWD). On platforms whose autostart
can't pass argv (Hatari, AmigaDOS), `run-agi.sh` stages the AGI
binary plus the v2 game data files (LOGDIR / PICDIR / etc.) flat in
a temp directory and points the emulator at it; AGI runs from CWD =
that temp dir and finds the data files relative to "./".

## Likely next-step work

The user's natural next ask is "implement enough title opcodes to
let KQ3's title screen auto-advance." That probably means:

- `wait` (cycle.time gate)
- `input.line` / `accept.input`
- Animation timers: `cycle.time`, `current.loop`, etc.
- `set.menu` / `disable.item` (KQ3 title shows a menu)

Alternative path: skip the title work and implement enough core
opcodes to make a gameplay room functional. animate.obj,
set.view.v, set.cel, set.loop, position, draw, erase. That gets us
walking around KQ3 room 1 (Manannan's house) with Graham instead
of a static title.

The user should pick which to prioritize.

## Memory entries you should know about

The repo's auto-memory at
`~/.claude/projects/-home-scott-claude-joeylib/memory/` includes
JoeyLib-wide context (CMake quirks, ORCA-C gotchas, perf
constraints) plus `project_joeylib_agi_plan.md` which describes the
overall AGI port plan. All persist into the next session
automatically; no need to reload.

Specifically relevant to the AGI port:

- `project_joeylib_agi_plan.md` — overall plan, 3-4 month estimate
- `feedback_orca_c_atoi_segment.md` — don't use atoi in AGI code
  (it pushes the IIgs ORCA-C stdio cluster past 64 KB; we use a
  manual parseArgU8 instead)
- `project_perf_directive.md` — IIgs is the perf floor; every
  other target must match or beat it
- `feedback_iigs_speed.md` — IIgs must be absolute fastest
  technically possible; the save-under decision was made under
  this constraint.

## Git / user preferences

- The user manages git themselves -- do NOT commit / push / branch
  on JoeyLib without explicit ask (see memory
  `feedback_git.md`).
- Always `source toolchains/env.sh` before any `make` -- the user
  has added that to .claude/settings.local.json allow list.
- DJGPP / ORCA / vasm / m68k-atari-mint paths come from env.sh.
- The user does NOT need hand-holding -- they're an expert C dev.
  Skip excessive explanation; describe what was done and move on.