visual-novel

Visual Novel

A playbook for visual novels — the branching script, the presentation (text box, characters, backgrounds), choices, and the quality-of-life systems players expect (save anywhere, backlog, skip, auto). This is a compositional skill: it drives a dialogue engine and a UI layer. It does not re-teach the dialogue engine or UI nodes; it defines the script model and the player conveniences that make a VN pleasant to read.

When to use

• Use when the game is mostly reading branching text with character art and backgrounds: visual novel, dating sim, branching interactive fiction, story-choice game.
• Use when designing a choice/route structure, story flags, or VN conveniences (backlog, skip, auto-advance, save-anywhere).

When not to use: dialogue as one feature inside a larger game → rpg consuming dialogue-systems. Card/board play → other genres. For the branching-script engine itself, use dialogue-systems (Ink / Yarn Spinner).

Core loop

Read a line → advance → (at a branch) make a choice → the story branches on flags/choices → read on → reach an ending. The "game" is the shape of the branching and whether choices feel consequential; everything else is presentation and convenience.

Must-have systems

1. Branching script — ordered lines + choices + jumps, with conditions and variables (Ink/Yarn).
2. Text box — speaker name, body text, typewriter reveal, advance on click/key.
3. Characters — sprites with expressions/poses, positions, show/hide transitions.
4. Backgrounds + transitions — scene images, fades/dissolves.
5. Choices — present options, gate some on flags, record the pick.
6. Story state — flags/variables that branch the script and unlock content.
7. Save/load (save-anywhere) — full script position + state; multiple slots; quick save.
8. VN conveniences — backlog/history, skip (read text), auto-advance, text-speed setting.
9. Audio — music per scene, SFX, optional voice clips.

Design knobs

Patterns

1. Script as data the engine walks

# Pseudocode. Lines, choices, and jumps as data — usually authored in Ink/Yarn and stepped
# through by that runtime. The engine asks the script for "the next thing to show".
node = script.current()
if node.kind == "line"

2. Typewriter reveal + advance (skippable)

3. Choice sets a flag that branches later content

Pitfalls / failure modes

• Save that only stores a checkpoint → VNs need save-anywhere. Persist the exact script position and all flags/variables (and seen-text data) so a load resumes the same line.
• Presentation logic baked into the script → unmaintainable. Keep content (text, choices) in the script and how it looks (sprites, transitions) in the engine layer.
• No skip/auto/backlog → readers feel trapped, especially on replays. These are expected baseline features, not extras.
• Skipping unread text → players miss content. Skip should fast-forward read text only.
• Choices with no consequence → branches that reconverge instantly feel fake. Set flags that visibly change later lines, choices, or endings.
• Combinatorial branch explosion → unshippable. Prefer branch-and-merge with a few flagged variations over fully distinct trees (refs).
• Lost reading context → no backlog to re-read the last lines. Keep a history buffer.
• Hardcoded language → no localization path. Keep text in data keyed for translation.

Composition (build it from these skills)

• Script engine: dialogue-systems (Ink / Yarn Spinner) — branching, conditions, variables, localization hooks.
• Presentation: game-ui-ux for text-box/choice-menu layout, scaling, and safe areas; godot-ui-control for the concrete text box, choice menu, name plate, and backlog UI.
• Persistence: save-systems for save-anywhere slots, seen-text/skip data, and settings.
• Audio: audio-design for per-scene music, SFX, and voice playback.
• Visuals: the engine animation/Tween skill for sprite/background transitions; shader-programming for dissolves.
• Process: prototype-fast to test the branch structure in plain text before adding art.

References

• For the branching data model, route structures (branch-and-merge vs. routes), flags/variables, save-anywhere + backlog/skip data, and the content/presentation split, read references/script-and-flow.md.