# Kissaten Yūgure — Design document

Working title: **Kissaten Yūgure** ("Twilight Coffee Shop")
Platform: MSX2 · Library: MSXgl (C) · ROM: ASCII16 MegaROM

> **Amendments.** This document still describes the game's intent and is the
> place to start. A few specifics have since been decided differently — where
> they conflict, the documents below win:
>
> - **Cast size: four, not six to eight** (§3). The four examples in §3 became
>   the entire roster. Rationale in `PLAN.md` §6; full arcs in `SCRIPT.md`.
> - **Endings: one**, not several (§8 stage 5). `PLAN.md` §6.
> - **Saving: a real save disk** (`.dsk`), not yet working — see the disk
>   section in `../CLAUDE.md`. Note the RP-5C01 CMOS holds only 6 bytes
>   through MSXgl, so it is not an alternative for a ~40-byte `SaveState`.
> - **Music (§7) is out of date.** It describes a PSG / MML → NDP pipeline;
>   the working pipeline is `msx-music-generator` → lVGM + ayFX. Which chip
>   this game targets is still open — `PLAN.md` §8 item 15.
> - **The brew minigame is coffee-only.** Aki's cream soda is poured, not
>   brewed, so her visits skip it — `SCRIPT.md` §8.
>
> Build order and per-stage requirements live in `PLAN.md`, which supersedes
> the scope ladder in §8 below with a finer eleven-milestone breakdown.

## 1. Concept

You inherit a small kissaten (coffee shop) in a fictional provincial Japanese
town in 1987. A cozy, no-fail-state game about serving regulars, learning
their stories, and watching the town and seasons change.

**Audience:** adult retro gamers with a love of Japanese art, computers, and
late-80s Japan nostalgia. The MSX2 itself is part of the fantasy — the game
should look like it came off an MSX magazine cover.

**Tone references:** A Short Hike (pace and warmth), Konami/Compile-era MSX2
pixel art, Showa-era kissaten culture, gentle city-pop-adjacent PSG music.

**The cozy contract:** no fail states. You cannot go bankrupt. Money gates
cosmetic and menu upgrades (better grinder, jazz records, a cat), not
survival. Progression = unlocking regulars' stories and seasonal change.

## 2. Core loop

One in-game day ≈ 5–10 real minutes, in three phases:

1. **Morning (prep):** choose today's menu focus (coffee blend, toast set,
   curry), check the radio for weather (weather affects who visits), buy stock.
2. **Open hours (the heart):** customers arrive one or two at a time. Take
   orders, brew/cook via a timing minigame, and — most importantly — talk.
   Regulars have multi-day story arcs told in short dialogue beats.
3. **Evening (close):** count the till, journal entry summarizing the day, save.

**Brew minigame:** a siphon coffee brew with a "release at the right moment"
mechanic. One-button friendly, thematic, satisfying to master. Quality result
feeds into customer affinity slightly (never punishingly).

## 3. The regulars

Six to eight recurring characters; this is where the game lives. Examples:

- The retired stationmaster
- A high-schooler studying for entrance exams
- A manga artist missing deadlines
- A widow who orders the same thing daily

Each has a story arc of ~12–20 short scenes, triggered by day count, season,
weather, or what you serve them. Serving the *right* thing at the right moment
advances arcs — the player learns preferences by paying attention, which
mechanically rewards the "regulars at my shop" fantasy.

**Visitor logic per open-hours tick:** roll against a weighted table filtered
by (season, weather, time-of-day, days-since-last-visit). Simple, tunable in
a spreadsheet, and it naturally produces patterns players notice and love
("the stationmaster always comes when it rains").

## 4. Screen layout — SCREEN 5 (256×212)

| Region | Height | Contents |
|---|---|---|
| Status bar | 16 px | Day + season · clock · money (¥) |
| Shop scene | 132 px | Tile/bitmap background: window, shelves, radio. Door zone (customer entry), counter zone (16×16 layered customer sprites), siphon rig zone (brew minigame). |
| Dialogue window | 64 px | 48×48 portrait left; 3 lines × 26 chars text with typewriter reveal; choice cursor on line 3 when needed. |

Deliberately static-heavy: only sprites move, so the MSX2's weak scrolling is
sidestepped entirely. Status bar and dialogue window redraw rarely — only the
scene needs per-frame attention. This is the single biggest scope-saver.

## 5. Hardware / MSXgl mapping

**Video.** SCREEN 5 (G4), 16 colors from 512.
- VRAM page 0: visible shop background bitmap.
- VRAM page 1: asset warehouse — customer sprite frames, portraits, UI tiles,
  blitted with VDP commands (HMMM); dialogue box open/close is HMMV rectangle
  fill + font rendering, never touching the scene.

**Seasonal palette trick.** Author the background once, designed around
palette slots: sky-through-window colors in slots 8–11, wood/warm tones in
4–7. Each season *and* time of day is then just a 32-byte palette table —
morning spring light vs. rainy autumn dusk on the same bitmap, basically
free. Optionally lerp between palettes across the in-game day for a slow
ambient shift. This is the most atmospheric feature in the game.

**Sprites.** Sprite mode 2 (per-line colors on 16×16). Two layered sprites
per customer (outline + fill) for the classic MSX2 look. Max two customers
on screen plus player hands/steam effects — nowhere near the 8-per-line limit.

**Portraits.** 48×48 with three expressions per character (neutral, happy,
troubled), copied from page 1 into the dialogue box. Portraits are where the
pixel-art budget goes; they sell the characters.

**ROM.** ASCII16 MegaROM from day one — dialogue, portraits, and music banks
will not fit in 32KB. MSXgl supports banked ROMs well.

## 6. Data model

```c
typedef struct {
    u8  id;
    u8  arc_stage;        // progress through their story
    u8  affinity;         // 0-255, raised by right orders
    u8  last_visit_day;
} Regular;

typedef struct {
    u16 day;
    u8  season;           // derives palette set
    u8  weather;          // affects visitor table
    u16 money;
    u8  unlocked_items;   // bitmask: grinder, records, cat...
    Regular regulars[8];
} SaveState;              // ~40 bytes → trivial to save
```

**Dialogue** is the biggest data mass. Scenes stored in a flat script format:

```
(trigger conditions) → (portrait id, expression, text lines,
                        optional choice, effects)
```

Authored in YAML/JSON; a small Node.js compiler (`tools/compile_dialogue.js`)
emits C arrays or a binary blob for a MegaROM bank. Budget: ~8 characters ×
~15 scenes plus ambient lines.

## 7. Music

PSG via the MML → NDP compiler → `ndp_player` pipeline, with AI-assisted MML
generation through `tools/generate_mml.js` (Anthropic API).

Needs: 6–8 short cozy loops rather than driving action tracks — morning,
afternoon, evening, rain, plus one theme per major story beat.

**Diegetic jukebox:** the record-player upgrade lets the player choose the
shop's background track — a feature and a home for all generated music in one.

## 8. Scope ladder

Build in this order so every stage is a playable game:

1. Shop scene + one customer + brew minigame + serve loop, no story
2. Day/night + save + money
3. Dialogue engine + two regulars with short arcs ← **the real milestone**
4. Seasons/weather/palettes
5. Remaining cast, upgrades, endings

If serving the exam student his usual and getting one new line of his story
feels good at stage 3, the game works.

## 9. Other principles

- Lean hard into palette work — the MSX2's superpower.
- Keep text minimal or bilingual-friendly; the Japanese retro community is a
  big chunk of the real audience.
- Let the soundtrack carry the mood — cozy games live or die on music.
- Marketing hook: "run a coffee shop on real MSX2 hardware."