# vnReader: the reading layer for any visual novel
Everything a player touches while reading a visual novel, as one installable package: the **dialogue box** (name plate, narrator style, typewriter, click-to-continue indicator), **choice cards**, the **backlog** (with voice replay and optional jump-back), **auto** (waits for the voice clip), **skip** (read text only by default), **hide UI**, **save/load slots** with a stage picture, chapter title, play time and date in **four layouts**, **quick save / quick load**, an **autosave** slot, a **gallery**, a **settings** screen, a **system menu**, **nine themes** and **mouse, keyboard, gamepad and touch** input on portrait and landscape screens.
It knows nothing about any one game: the game passes its cast (names, colours), its gallery, and callbacks for its own state, stage snapshot and loading. Every screen is local to the player whose machine draws it and every save, setting and read-line record is kept in **that player's own data** (`runtime_data.player`), so in a multiplayer world nobody's screen or progress touches anyone else's.
Pairs with **vnStage** (staging: cast, backgrounds, moods, transitions, `snapshot()`/`restore()`); the save screen draws a vnStage snapshot as layered pictures.
## Quick start
```lua
local Reader = require("vnReader.reader")
Reader.setup({
id = "mygame", -- storage namespace (per player)
theme = "animeGlass", -- any of Reader.themes()
cast = { mira = { name = "Mira", color = "#f2c46b" }, ren = { name = "Ren", color = "#3ff0e8" } },
snapshot = function() return require("vnStage.stage").snapshot() end,
castTexture = function(id, pose, expr) return "mygame.sprites." .. id .. "_" .. expr end,
placeTexture = function(place) return "mygame.backgrounds." .. place end,
saveData = function() return { chapter = currentChapter, step = currentStep } end,
chapterTitle = function() return "Chapter 1, The Guild" end,
onLoad = function(game, slot) resumeStory(game) end, -- you resume your own story
onTitle = function() showMyTitle() end,
})
Reader.say("narrator", "The lanterns flicker.", function()
Reader.say("mira", "Welcome to the guild!", function()
Reader.choose("Take the job?", {
{ id = "yes", text = "Sign the contract" },
{ id = "no", text = "Walk away", locked = false },
}, function(id) print("picked", id) end)
end, "ch1.002")
end, "ch1.001")
```
## API (`vnReader.reader`)
| Call | What it does |
|---|---|
| `setup(config)` | Configure for a game (fields below). Loads the player's settings and read-lines. |
| `say(speaker, text, onDone, lineId?)` | One line. `lineId` (stable, e.g. `"ch1.004"`) drives read/unread skip, voice and backlog replay. `opts` may also be `{ lineId, voice = false }`. |
| `choose(prompt, options, onPick)` | Choice cards; `options = {{ id, text, locked? }}`. Skip and auto stop here. |
| `hideDialogue()`, `hideChoice()`, `advance()` | Take the box down / the cards down / advance as a click would. |
| `setAuto(on)`, `setSkip(on)`, `setHidden(on)` | Auto mode, skip mode, hide-UI. |
| `openLog()`, `openSaves("save"\|"load")`, `openSettings(tab?)`, `openGallery()`, `openMenu()`, `confirm(text, onYes, onNo?)`, `back()`, `closeAll()` | The overlay screens (a stack; Esc / B goes back). |
| `save(slot)`, `load(slot)`, `slot(slot)`, `deleteSlot(slot)`, `hasSaves()`, `quickSave()`, `quickLoad()`, `capture()` | Slots are numbers `1..pages*perPage`, plus `"quick"` and `"auto"`. |
| `beginSession(seconds?)`, `endSession()`, `playTime()` | Play-time clock shown on slots. |
| `set(key, value)`, `settings()` | Settings (persisted per player). |
| `setTheme(name)`, `themes()`, `registerTheme(name, tokens)` | Themes. |
| `setSaveLayout("grid"\|"list"\|"book"\|"carousel")` | Save-screen layout. |
| `pictureOf(snapshot)` | Stage snapshot → `{ background, layers = {{ src, x, h, aspect, flip }} }`. |
| `showcasePicker(opts?)`, `hidePicker()`, `demo(kind)` | A floating picker that flips every theme and save layout live, with buttons that show a sample line, choice, saves, load, log, settings, menu and gallery. |
| `debugState()` | `{ dialogue, auto, skip, hidden, choice, stack, logLines, theme, saveLayout, playTime }` for tests. |
### `setup` config
`id` (storage namespace), `theme`, `themes` (extra themes by name), `cast` (table or `fn(id)` → `{ name, color, heightScale? }`), `narrators` (speaker ids drawn as narration), `gallery` (list or fn → `{{ id, name, src, unlocked = bool|fn }}`), `pages` (6), `perPage` (6), `snapshot` (fn → stage snapshot), `picture` (fn(snapshot) → picture, overrides the default reader), `castTexture(id, pose, expr)`, `placeTexture(placeId)`, `slots` (slot name → 0..1 across the frame), `spriteAspect` (0.5), `saveData` (fn → your game's state for the slot), `chapterTitle` (fn), `onLoad(game, slotData)`, `onTitle` (adds *Title Screen* to the menu), `canSave` (fn), `blocking` (fn: true while your own screen owns input), `voice = { play(lineId, speaker, text) → seconds|true|nil, stop() }`, `volumes = { set(bus, v) }` (buses `master music sfx voice`), `sfx(kind, vol)` (kinds `blip advance click hover open back save load`), `toast(kind, text)`, `menuItems` (`{{ id, text, icon, onPick }}`), `jump(lineId)` (enables the backlog's jump button), `defaults` (setting defaults), `layers`, `maxBoxWidth`, `fontSize(portrait)`, `previewSpeaker`, `menuTitle`, `wheelAdvances` (true), `centerNarration`.
## Themes
`animeGlass` (frosted glass, pastel light), `fantasy` (dark oak and gilt, wax-red ribbon), `parchment` (paper and ink), `scifi` (holographic cyan, scan line), `pixel` (8-bit RPG window), `minimal` (editorial gradient band, one red accent), `manga` (ink balloon, slab plates), `cozy` (peach and sage, hearts). A game adds its own with `registerTheme(name, tokens)`, tokens it leaves out come from `base`; `buildPlate`, `boxDecor` and `panelDecor` hooks add ornaments. Tokens are listed at the top of each entry in `themes.module`.
## Save layouts
`grid` (3×2 cards; 2×3 on portrait), `list` (rows with a wide thumbnail and the last line), `book` (an open book: the focused slot's picture on the left page, the page's slots listed on the right), `carousel` (one big card with neighbours peeking, dots, arrows / shoulder buttons). Six pages of six slots plus a **Q** page with the quick and auto slots. Overwrite and delete always ask first.
## Input
| | Keyboard / mouse | Gamepad | Touch |
|---|---|---|---|
| Advance | Enter, Space, click, wheel ↓ | A | tap |
| Auto | A | X | Auto button |
| Skip | hold Ctrl; S toggles | hold R2 | Skip button |
| Backlog | L, ↑, wheel ↑ | Y, LB | swipe up (down closes) |
| Hide UI | H, Delete | Select, RB | Hide button |
| Quick save / load | F5 / F9 | menu | menu |
| Menu / back | Esc | Start / B | Menu button |
| Choices | 1–9, ↑↓ + Enter | d-pad + A | tap |
| Pages / tabs | Q / E | LB / RB | tabs |
On touch surfaces and phone-sized screens the quick bar becomes 48 px icon buttons above the box and every menu button grows to 48 px. Layout follows `ui.screenSize()` and `ui.safeArea()` and re-lays out on rotation.
## What's inside
- `reader.module`, the API above, dialogue, choices, input loop, saves.
- `screens.module`, backlog, save/load layouts, gallery, settings, menu, confirm.
- `themes.module`, the nine themes and their tokens.
- `kit.module`, themed node builders, icons, the layered save picture.
- `store.module`, per-player persistence.
- Guides: `vn-reader-text-box-backlog-saves.guide` (how to use it) and `make-a-visual-novel-chapter.guide` (worked example with vnStage).
- `build-visual-novel-chapter.workflow`, the stages of building a chapter, as a runnable workflow.
## Known limits
- Voice length comes from the game's `voice.play` return value; return the clip length for auto to wait exactly.
- The backlog keeps the last 300 lines of the session (not saved with slots).