# Design conversation record — Kissaten Yūgure

A record of the original brainstorm and design discussion (Claude ↔ Jurjen,
July 2026) that led to this project. Kept for rationale and context; the
distilled result lives in `DESIGN.md`.

---

## 1. The brief

Jurjen wanted a new MSX2 game idea: **a cozy game targeted mainly at male
adults who love Japanese art and retro games**, built with MSXgl.

Claude's read on the audience: nostalgia for late-80s Japan, quiet melancholy,
craftsmanship, and pixel art in the style of MSX magazine covers / Konami and
Compile titles. The MSX2 itself is a Japanese cultural artifact, so the
platform is part of the appeal. Reference vibe: *A Short Hike* energy,
rendered like an MSX2 classic.

## 2. Four concepts pitched

1. **Showa-era shopkeeper sim** — run a tiny kissaten, sento, or ramen stall
   in a sleepy 1980s town. Regulars with small stories, seasons change the
   palette (SCREEN 5 palette swaps per season = big atmosphere, low cost).
   Simple state machines + dialogue, MSXgl-friendly; PSG/NDP pipeline fits
   gentle city-pop-adjacent loops. Hits the demographic dead center.

2. **Bonsai / garden tending game** — shape a tree or karesansui garden over
   in-game years via a simple L-system-ish growth model. Minimal input,
   maximal zen, sumi-e visuals, persistent growth via save. Smallest and most
   distinctive option; nobody has made it on MSX.

3. **Rural train journey game** — conductor/passenger on a one-car local
   line; each station is a vignette. Landscapes are the star, but horizontal
   scrolling is work on MSX2 (vertical scroll register is free), so it would
   need screen-by-screen scenes or parallax-lite. Densha + inaka nostalgia.

4. **Yokai postman / errand game** — cozy-spooky letter delivery between
   friendly yokai at dusk. Iconic character material, light fetch-quest
   structure, Ghibli / Mizuki Shigeru vibe.

**Recommendation:** #1 or #2, because scope kills hobby projects. #1 had the
strongest emotional hook and marketing appeal ("run a coffee shop on real
MSX2 hardware"); #2 was the most achievable and distinctive.

**Cross-cutting principles:** lean into palette work (MSX2's superpower),
keep text minimal or bilingual-friendly for the Japanese retro community,
and let the MML → NDP music pipeline carry the mood.

## 3. Decision

Jurjen picked **#1, the kissaten sim**. Working title: **Kissaten Yūgure**
("Twilight Coffee Shop") — you inherit a small kissaten in a fictional
provincial town, 1987.

## 4. Design deep-dive (summary — full detail in DESIGN.md)

- **Core loop:** one day ≈ 5–10 real minutes. Morning prep (menu focus,
  radio weather, stock) → open hours (serve + siphon-brew timing minigame +
  dialogue with regulars) → evening close (till, journal, save).
- **Cozy contract:** no fail states, no bankruptcy; money gates cosmetic and
  menu upgrades (grinder, jazz records, a cat). Progression = story + seasons.
- **Regulars:** 6–8 characters (retired stationmaster, exam student, manga
  artist, widow...), each with 12–20 short scenes triggered by day count,
  season, weather, or what you serve. Right order at the right moment
  advances arcs.
- **Screen layout (SCREEN 5, 256×212):** 16 px status bar (day/season,
  clock, ¥) · 132 px shop scene (door, counter with customer sprites,
  siphon rig) · 64 px dialogue window (48×48 portrait, 3 lines × 26 chars,
  typewriter reveal). Static-heavy on purpose: only sprites move — no
  scrolling — the biggest scope-saver in the design.
- **Hardware mapping:** VRAM page 0 = scene bitmap, page 1 = asset warehouse
  blitted via HMMM/HMMV. Seasonal palette trick: one background authored
  around palette slots (sky in 8–11, wood tones in 4–7); each season/time of
  day is a 32-byte palette table, optionally lerped across the day. Sprite
  mode 2, two layered 16×16 sprites per customer. Portraits 48×48 × 3
  expressions — where the pixel-art budget goes.
- **Data model:** tiny `SaveState` (~40 bytes) with day, season, weather,
  money, unlock bitmask, and 8 `Regular` structs (arc_stage, affinity,
  last_visit_day). Dialogue as data: YAML/JSON compiled by a Node.js tool to
  C arrays / binary banks. ASCII16 MegaROM layout from day one.
- **Visitor logic:** weighted table per tick, filtered by season / weather /
  time / days-since-last-visit — tunable in a spreadsheet, produces
  noticeable patterns ("the stationmaster always comes when it rains").
- **Music:** 6–8 short cozy PSG loops via the existing MML → NDP →
  `ndp_player` pipeline (`generate_mml.js` for AI-assisted MML). Diegetic
  jukebox upgrade lets the player pick the shop's track.
- **Scope ladder:** (1) scene + one customer + brew + serve → (2) day cycle
  + save + money → (3) dialogue engine + two regulars ← real milestone →
  (4) seasons/weather/palettes → (5) full cast, upgrades, endings. Every
  stage playable.

## 5. Moving to Claude Desktop / Claude Code

Jurjen asked about continuing the project in Claude Desktop with context
files. Plan:

- Put a lean **CLAUDE.md** in the project root — Claude Code reads it at the
  start of every session. It holds build commands, toolchain quirks (SDCC,
  MSXgl paths, openMSX), conventions, and design pillars; kept under ~200
  lines, referencing deeper docs instead of duplicating them.
- Full design lives in **docs/DESIGN.md**; this file (**CONVERSATION.md**)
  preserves the original discussion and rationale.
- Claude Code's auto memory will additionally accumulate learned corrections
  (e.g. bank layout details) over time.
- The dialogue compiler (`compile_dialogue.js`) will live in `tools/` next to
  the existing `generate_mml.js`.

## 6. Open threads (not yet designed)

- Dialogue script format spec + compiler implementation
- Brew minigame detailed design
- Palette / day-cycle system implementation details
- Character roster finalization and story arcs
- Bank layout plan for the ASCII16 MegaROM