mazegame/projects/kissaten_yugure/CLAUDE.md

Kissaten Yūgure — MSX2 cozy game

Project overview

A cozy coffee-shop (kissaten) simulation for MSX2, set in a provincial Japanese town in 1987. Target audience: adult retro gamers who love Japanese art and computers. Written in C using the MSXgl library. Working title: "Kissaten Yūgure" (Twilight Coffee Shop).

Read docs/DESIGN.md before making any design or architecture decisions. Read docs/CONVERSATION.md for the original design discussion and rationale.

Design pillars (never violate)

• Cozy contract: no fail states, no bankruptcy, no time pressure outside the brew minigame. Progression is always forward.
• Atmosphere over mechanics: palette work, music, and character writing carry the game.
• Static-heavy rendering: no scrolling. Only sprites and small blits move.
• Small, finishable scope. When in doubt, cut.

Tech stack

• Target: MSX2, SCREEN 5 (G4, 256×212, 16 colors from 512)
• ROM format: ASCII16 MegaROM (banked) — plan bank layout from day one
• Library: MSXgl (C) — https://github.com/aoineko-fr/MSXgl
• Compiler: SDC C via MSXgl build system
• Music: unresolved — this line is stale. It describes a PSG / MML → NDP pipeline, but the working pipeline used for projects/mazegame is the msx-music-generator repo emitting lVGM + ayFX, on MSX-Music (YM2413). This project targets plain MSX2, where FM is not standard hardware. Decision deferred to M9; see docs/PLAN.md §8 item 15.
• Dialogue: authored in YAML/JSON, compiled to C arrays / binary banks by tools/compile_dialogue.js (Node.js)
• Emulator for testing: openMSX (also verify on real hardware profiles)

Build & test

• Build: ./build.sh (MSXgl build_tool; ROM → out/ and emul/rom/kissaten.rom)
• Run: ./build.sh run → builds and launches openMSX
• Requires node on PATH, else build.sh falls back to the bundled Windows/Linux binary and dies: export PATH="/opt/homebrew/opt/node@24/bin:$PATH"
• Headless verification: drive openMSX with a Tcl script — openmsx -machine C-BIOS_MSX2 -carta emul/rom/kissaten.rom -script test.tcl using after time <s> {screenshot f.png} and keymatrixdown 8 1 (SPACE). Add set throttle off to the script: emulated time then runs many times faster than wall clock, so a 200-second play-through takes a couple of seconds. after time still counts emulated seconds, so timings hold.
• Boot is slow — budget for it. ROMDelayBoot = true (needed for disk access, see below) means the game only appears at roughly 40-90s of emulated time. Screenshots before that show a blue BASIC screen, which looks exactly like a hang and is not one. Test with a disk machine: openmsx -machine Philips_NMS_8250 -carta emul/rom/kissaten.rom -diska save.dsk
• Dialogue data (stage 3): node tools/compile_dialogue.js data/dialogue/*.yaml
• Music data (stage 3+): node tools/generate_mml.js → NDP compiler → data/music/

Platform gotchas (learned the hard way)

• Keyboard: read the matrix row inside DisableInterrupt()/EnableInterrupt(). Keyboard_Read() is an out (row select) then in; the BIOS ISR scans the matrix too, and if it lands between the two you get phantom keypresses. INPUT_KB_UPDATE (buffered mode) is not a fix — it reads the BIOS NEWKEY/OLDKEY area, which C-BIOS does not maintain in the standard format.
• BankedCall = true is off until banked code actually exists. With it on and nothing banked, RAM globals were corrupted at runtime (state machine ran wild, counters garbage). Re-enable deliberately at stage 3.
• Erase blits must repaint the actual background at that spot — the counter area has three bands (wainscot / counter top highlight / counter top).

Disk saving from a cartridge ROM — WORKING

Saves go to a real file on a real disk: KISSAT00.SAV in the root of the disk in drive A. The disk stays a normal FAT disk you can inspect and copy.

Use engine/src/tool/disk_save.h. MSXgl v1.3.0 added this module specifically for "save to disk from a ROM application". Do not hand-roll sector I/O — an earlier attempt using PHYDIO (Main ROM 0144h) and a direct CALSLT to DSKIO (4010h) had both entry points return carry-clear while transferring nothing, proven with a sentinel that survived the call intact.

Four things are required, none of them obvious:

1. LibModules must include both "tool/disk_save" and "dos". The module alone will not link. See projects/samples/s_save.js for the reference configuration, and s_save.c for usage.
2. ROMDelayBoot = true. A cartridge's INIT normally runs during the BIOS slot scan and MSXgl never returns from it, so the Disk ROM's own INIT never happens and there is no disk system to talk to. This option installs an H.STKE hook and returns to the scan instead.
3. Boot becomes slow. The game appears at roughly 40-90s of emulated time. Screenshots before that show a blue BASIC screen and look exactly like a hang. Use set throttle off in the test script so this costs seconds of wall clock, not minutes.
4. DiskSave_Check() returns SAVEDATA_UNSIGNED for perfectly good files. With AppSignature = true (-DAPPSIGN), DiskSave_Check() requires the file's first four bytes to equal g_AppSignature — but DiskSave_Save() writes the payload raw and never adds it. Treat SAVEDATA_UNSIGNED as success; SaveState carries its own magic, version and checksum, which is a stronger check regardless.

Save timing: written in AdvanceDay() after the day counter increments, so the file always describes the morning the player wakes to. Saving during the evening instead makes a reload replay the day just finished and double-count its cups.

Absent or unusable disk is not an error the player has to handle — it just means nothing persists, and the morning card says so.

Test:

openmsx -machine Philips_NMS_8250 -carta emul/rom/kissaten.rom -diska save.dsk

Create a blank 720K disk with tools/build/msxtar/msxtar -cf save.dsk --dos1 --size=720K.

RTC CMOS is not an alternative for a save this size, despite RTC_USE_SAVEDATA being TRUE in msxgl_config.h. Block 3 of the RP-5C01 is 13 nibbles and MSXgl's RTC_SaveData() stores exactly 6 bytes, against a ~40-byte SaveState. (MSXgl has no cartridge-SRAM mapper target either; the PAC module's FM-PAC SRAM, 8 x 1024 bytes, is the other real option.)