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 — status: UNRESOLVED

M2 wants saves on a real `.dsk`. The game is a cartridge MegaROM, which makes
this awkward. What is established so far, all verified on
`Philips_NMS_8250` + `-carta` + `-diska`:

- **A cartridge ROM does boot fine on a disk machine.** Not a problem.
- **`ROMDelayBoot = true` is required.** 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, `NMBDRV` stays 0 and the disk hooks are never
  patched. This option installs an H.STKE hook and returns to the scan
  instead. **Boot becomes much slower** — the game appears at ~40-90s of
  emulated time, so early screenshots will show a blue BASIC screen and look
  like a hang when they are not.
- **Any call into the disk system must be made from RAM.** Both PHYDIO and
  CALSLT reach the Disk ROM at 4000h — the same page as this cartridge — so
  the calling instruction is switched out mid-call unless it lives elsewhere.
  `Disk_InitStub()` copies a small stub to RAM for exactly this. Calling
  directly from ROM black-screens the machine.
- With the above in place, `NMBDRV` reads 2 and `MASTER` is non-zero, so the
  Disk ROM *has* initialised by the time the game runs.

**The remaining blocker:** both `PHYDIO` (Main ROM 0144h) and a direct
`CALSLT` to `DSKIO` (Disk ROM 4010h) return **carry clear — "success" — while
never touching the destination buffer.** Proven with a 0xAA sentinel that
survives the call intact. Page 0 is confirmed to be the Main ROM at call time
(0x002D reads 1 = MSX2, 0x0144 holds 0xC3 = `JP`), so the entry points
themselves are addressable.

Because a clean error code is *not* proof that a read happened, `Disk_Probe()`
now verifies the buffer actually changed and treats "no change" as no disk.
The game degrades gracefully: no disk means day 1, nothing persists, and the
evening card says so. Nothing crashes on either C-BIOS or a real-BIOS machine.

Next things to try: check whether the H.PHYD RAM hook is genuinely patched at
that moment; try a different disk machine profile; or reconsider the medium
(see PLAN.md §8 item 1).

**RTC CMOS is not a viable fallback**, despite `RTC_USE_SAVEDATA` being TRUE
in `msxgl_config.h`. Block 3 of the RP-5C01 is 13 nibbles, and MSXgl's
`RTC_SaveData()` (`engine/src/clock.c`) stores exactly **6 bytes** — against a
~40-byte `SaveState`. `RTC_SaveDataSigned()` is tighter still. Remaining
options are cartridge SRAM, the FM-PAC SRAM (MSXgl has a `PAC` module), or
shrinking the save to a 6-byte fingerprint — which would cost per-character
affinity and money, so it is a design decision, not just a storage one.
Reference: MSX2 Technical Handbook ch.5, CLOCK-IC section.

## Architecture conventions
- VRAM page 0: visible shop scene bitmap. Page 1: asset warehouse (sprite
  frames, portraits, UI tiles) blitted with VDP commands (HMMM/HMMV).
- Seasons and time-of-day are palette swaps only (32-byte tables); never
  duplicate background art per season.
- Sprite mode 2, two layered 16×16 sprites per customer (outline + fill).
- Portraits are 48×48, three expressions per character max.
- Game state lives in a single `SaveState` struct (~40 bytes); see DESIGN.md.
  Implemented in `kissaten.c` with a magic word, version byte and checksum;
  a failed or absent load is not an error, it just means day one.
- The day is a three-phase machine (morning / open / evening) and the clock is
  **event-driven** — customers are the clock. `CUSTOMERS_PER_DAY` is the
  single pacing dial.
- Dialogue scenes are data, not code: trigger conditions → portrait,
  expression, text, optional choice, effects.

## Code style
- C99, MSXgl idioms (u8/u16 types, `msxgl_` module prefixes)
- Keep ISR/VBlank work minimal; game logic in main loop
- Comment bank-switching boundaries explicitly
- Tools are Node.js (plain JS, no framework), living in `tools/`

## Scope ladder (build in this order; every stage must be playable)
1. ✅ Shop scene + one customer + brew minigame + serve loop (no story)
2. ◐ Day/night cycle + save + money — day counter, three phases and the
   journal line work; **persistence is blocked** (see the disk section below).
   Money deliberately deferred to stage 5, since nothing gates on it before.
3. Dialogue engine + two regulars with short arcs  ← real milestone
4. Seasons/weather/palette system
5. Remaining cast, upgrades, endings

`docs/PLAN.md` expands this into ten milestones with per-stage requirements
and a decision queue. `docs/SCRIPT.md` holds the full first-draft script.