Docs! Getting ready for more platforms.
This commit is contained in:
Scott Duensing
parent
94cc14ff28
commit
28d8852bbe
1 changed files with 0 additions and 217 deletions
|
|
@ -1,217 +0,0 @@
|
||||||
# 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, IIgs toolchain 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
|
|
||||||
- AGI code uses a manual `parseArgU8` instead of atoi to keep the
|
|
||||||
IIgs link budget small.
|
|
||||||
- `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 / llvm-mos / 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.
|
|
||||||
Loading…
Add table
Reference in a new issue