jurjen.ladeniusandClaude Opus 5
70b42f6da1
tool/disk_save already indexes every call by entry, so multiple save files cost almost nothing on the storage side — KISSAT00.SAV, KISSAT01.SAV, and DiskSave_Check/Delete/GetFreeEntries already exist per entry. The work is the boot-time slot screen, which is why it sits late: it is easier to design once there is real save content to display. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
176 lines
7.7 KiB
Markdown
176 lines
7.7 KiB
Markdown
# 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."
|