--- name: msx-play description: Play the shared MSX machine through image observation, sequential key input, disk changes and persistent checkpoints; learn game menus from their visible results. --- # MSX play This attached Add-on provides the machine shared with the TUI and other Keepers. Agree on a handoff with the current driver before changing it. Calls are serialized, but no enforced driver lease protects a sequence across calls. If another caller intervenes, discard the remaining planned inputs, capture the current screen and coordinate who continues. Watching is not exclusive ownership. Preserve an existing campaign before taking it over; do not restart at each wake. ## Primitive tools - `masc_msx_screen` observes without advancing time. Calls return a PNG image block, dimensions and frame number together. Read that returned image; if the current model cannot interpret it, report the limitation. Bitmap `screen_text` is name-table data, not OCR; `halted` or a constant PC alone does not identify an input prompt. The sprite attribute table rides only with `sprites=true` — pass it when you really need sprite positions, not by habit. - `masc_msx_press` holds all `keys` together for `hold_frames` — a chord, like a direction plus fire — then releases them for the rest of `frames`. Set `sequence=true` to instead tap the keys one after another, each in its own frame window, so a menu path or a multi-digit command is one call; end a command entry with Return. Use short holds for a single press and observe at decision boundaries. - `masc_msx_step` advances time without held keys. Use it for an observed transition or animation. Respect the current schema's per-call frame limit; do not repeatedly step an unchanged menu. - `masc_msx_step_until_change` advances until the screen settles (two near-equal coarse views in a row; a blinking cursor alone is not movement) or the frame budget runs out. One call replaces repeated step+screen while a title, fade or level intro plays out. `changed=false` with `stable=true` means the screen did not move — the scene likely waits for a key, so read it and press; `stable=false` means the budget ran out mid-animation and another call continues it. - `masc_msx_save` and `masc_msx_restore` use named slots containing machine state and the input ledger. Saving replaces that slot: use your campaign prefix plus a fresh unique suffix for each retained checkpoint, within the tool's slot format, and verify the save receipt names the requested slot and intended state. Keep the last good checkpoint. A restore rewinds the shared machine, not just your view; confirm the driving handoff still holds before restoring. - `masc_msx_change_disk` changes the floppy without rebooting and preserves modified media in checkpoints. Follow the game's disk prompt and confirm it with the key the game requests. Read the requested disk letter from the current image before choosing a catalog entry. An unchanged screen, missing prompt, or guessed transition is not a disk-change request. Preserve a fresh checkpoint before changing media; replacing it can invalidate open game files even though the CPU keeps running. If the requested letter is unreadable, retain that uncertainty and obtain a clearer observation instead of trying disks. - `masc_msx_load` boots a new cartridge or disk and replaces the current machine/ledger. Calling it without `cart` still boots the BIOS: it is not a read-only inventory query. Read the inventory through the available inventory surface, or use already supplied media names. Do not load just to discover what is running. - `masc_msx_peek` reads bytes at a logical address (`address` as hex like "e000", `length` up to 256) and returns hex pairs; it also takes the 64K snapshot that the diff below compares against. Read-only by design: there is no write tool, and writing memory is the cheat the lane refuses. - `masc_msx_ram_diff` reports what changed since the last peek: consecutive differing bytes as runs with address, length and before/after hex, capped at 64 runs (`truncated` says more existed). The snapshot survives a machine swap, so a reload after a peek reads as wholesale change — which it is. Use the `observe-act-verify` Skill for unfamiliar screens: capture, identify the prompt, choose an action, then verify the resulting screen and values. A successful key call proves delivery, not that the requested action succeeded. All key edges are retained in the machine ledger with their frame and caller. After a transport timeout, observe before retrying; a changed screen alone cannot identify whose input caused it when another driver may be active. Consult the caller-tagged ledger when accessible, or retain that uncertainty and coordinate before further input. ## Finding state in memory The screen is the expensive way to ask what changed; memory answers in bytes. To locate where a game keeps a value: 1. `masc_msx_peek` any address to take the snapshot. 2. Make exactly one meaningful input — one menu choice, one command — with `sequence=true` where a path is involved. 3. `masc_msx_ram_diff`: the changed runs are candidates for that action's state. 4. Confirm meaning against the screen (the returned PNG image): the run whose before/after matches the visible change — a menu id, a cursor, gold — is that state's address. 5. Record confirmed addresses in keeper memory as the game's address table. A few peeked bytes then answer routine questions; image reads stay for evidence, unfamiliar screens and periodic confirmation. Re-verify a saved address after a reload or restore: the layout is usually the same, but confirm with one diff before trusting the table. If a diff after a clearly one-step action shows wholesale change, someone else drove the machine — treat the snapshot as lost and take a fresh peek. ## Per-game Skills Game facts — menu tables, in-game save flows, media-change pitfalls, verified key sequences — live in a Skill named after the game, not here. Before playing a loaded game, open its row in the Skill list; `sangokushi-2` is the first. Where no row exists, learn from the actual screens and report what repeated, so the knowledge can be distilled into one. Keep local media filenames and the current campaign slot in session memory rather than treating one operator's inventory as universal. ## Recover from a suspected bad transition Save the abnormal state to a fresh slot before stepping again or restoring. Retain the last good slot, media identity, exact accepted inputs, frame numbers and images. Treat values displayed after corruption as untrusted; a later year or a BIOS logo does not prove a completed turn or a deliberate reboot.