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).
If the project is Ren'Py (current stable 8.5.3): the engine already ships save-anywhere,
rollback, a history (backlog) screen, skip that stops at unseen text by default
(preferences.skip_unseen = False), auto-forward and a text-speed preference. Use and restyle
those through its screens and preferences; apply this skill's design guidance (routes, flags,
reactivity) rather than rebuilding the systems in Patterns 2–3.
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
- Branching script — ordered lines + choices + jumps, with conditions and variables (Ink/Yarn).
- Text box — speaker name, body text, typewriter reveal, advance on click/key.
- Characters — sprites with expressions/poses, positions, show/hide transitions.
- Backgrounds + transitions — scene images, fades/dissolves.
- Choices — present options, gate some on flags, record the pick.
- Story state — flags/variables that branch the script and unlock content.
- Save/load (save-anywhere) — full script position + state; multiple slots; quick save.
- VN conveniences — backlog/history, skip (read text), auto-advance, text-speed setting.
- Audio — music per scene, SFX, optional voice clips.
Design knobs
| Knob |
Effect |
Notes |
| Text speed / instant |
reading comfort |
Always allow instant + a skip. |
| Auto-advance delay |
hands-free reading |
Tunable; pause on choices. |
| Skip scope |
re-reading |
Skip read text only by default. |
| Branch breadth/depth |
replay value vs. cost |
Branches multiply writing/art work. |
| Flag-gated content |
reactivity |
Lines/choices that check past decisions. |
| Route structure |
story shape |
Branch-and-merge vs. distinct routes (refs). |
| Choice visibility |
fairness |
Show locked choices vs. hide them. |
| Backlog length |
convenience |
Keep enough to re-read recent context. |
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":
show_text(node.speaker, node.text) # wait for advance input
elif node.kind == "choice":
options = [o for o in node.options if condition_met(o.condition, flags)] # gate by flags
show_choices(options) # wait for selection
elif node.kind == "set":
flags[node.var] = eval_expr(node.expr, flags)
script.advance(selected_option_or_none)
2. Typewriter reveal + advance (skippable)
# Pseudocode. Lay out the whole line once, then reveal it; a press first completes the line.
def show_text(speaker, text):
name_label.text = speaker
body_label.text = text # full text set up front: wrapping is decided now
shown = 0.0
while shown < visible_length(body_label): # count displayed characters, not markup tags
if advance_pressed(): # first press: reveal the whole line instantly
break
shown += chars_per_second * frame_dt()
body_label.visible_characters = int(shown)
wait_one_frame()
show_all_characters(body_label)
backlog.append((speaker, text)) # once, when the line is complete
wait_for_advance() # second press: go to the next line
Reveal with the label's visible-character count, not by slicing the string: slicing cuts
markup tags in half and re-wraps the text every frame, so a word starts on one line and jumps
to the next. Godot 4.7: RichTextLabel.visible_characters (or visible_ratio) with
visible_characters_behavior = TextServer.VC_CHARS_AFTER_SHAPING; the default
VC_CHARS_BEFORE_SHAPING leaves hidden text out of line breaking, so words still jump. Unity 6.3:
TMP_Text.maxVisibleCharacters (TextMeshPro, part of the uGUI package).
3. Choice sets a flag that branches later content
# Pseudocode. Choices write flags; later conditions read them — that is "reactivity".
def on_choice(option):
if option.set: flags[option.set] = True # e.g. flags["helped_npc"] = True
script.jump(option.target) # follow the branch
# Elsewhere, a line/choice/ending checks the flag:
if flags.get("helped_npc"): play_route("good_ending") else: play_route("neutral_ending")
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. Check
what your runtime can restore: Ink saves the exact position, Yarn Spinner only the node
(refs §4).
- Typewriter text that jumps between lines or shows raw tags → the reveal slices the string.
Set the full text and raise the visible-character count (Pattern 2).
- 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.
1---2name: visual-novel3description: >4 Build a visual novel: a branching script, character and background display, a text box with choices,5 save/load, backlog, and skip/auto. Use for a VN, dating sim, or branching story game.6metadata:7 source: https://skillmd.com/skills/junmystery/visual-novel8---910# Visual Novel1112A playbook for visual novels — the branching script, the presentation (text box, characters,13backgrounds), choices, and the quality-of-life systems players expect (save anywhere, backlog,14skip, auto). This is a **compositional** skill: it drives a dialogue engine and a UI layer. It15does not re-teach the dialogue engine or UI nodes; it defines the script model and the player16conveniences that make a VN pleasant to read.1718## When to use1920- Use when the game is **mostly reading branching text** with character art and backgrounds:21 visual novel, dating sim, branching interactive fiction, story-choice game.22- Use when designing a choice/route structure, story flags, or VN conveniences (backlog,23 skip, auto-advance, save-anywhere).2425**When *not* to use:** dialogue as one feature inside a larger game → `rpg` consuming26`dialogue-systems`. Card/board play → other genres. For the branching-script engine itself,27use `dialogue-systems` (Ink / Yarn Spinner).2829**If the project is Ren'Py** (current stable 8.5.3): the engine already ships save-anywhere,30rollback, a history (backlog) screen, skip that stops at unseen text by default31(`preferences.skip_unseen = False`), auto-forward and a text-speed preference. Use and restyle32those through its screens and preferences; apply this skill's design guidance (routes, flags,33reactivity) rather than rebuilding the systems in Patterns 2–3.3435## Core loop3637**Read a line → advance → (at a branch) make a choice → the story branches on flags/choices →38read on → reach an ending.** The "game" is the *shape of the branching* and whether choices39feel consequential; everything else is presentation and convenience.4041## Must-have systems42431. **Branching script** — ordered lines + choices + jumps, with conditions and variables (Ink/Yarn).442. **Text box** — speaker name, body text, typewriter reveal, advance on click/key.453. **Characters** — sprites with expressions/poses, positions, show/hide transitions.464. **Backgrounds + transitions** — scene images, fades/dissolves.475. **Choices** — present options, gate some on flags, record the pick.486. **Story state** — flags/variables that branch the script and unlock content.497. **Save/load (save-anywhere)** — full script position + state; multiple slots; quick save.508. **VN conveniences** — backlog/history, skip (read text), auto-advance, text-speed setting.519. **Audio** — music per scene, SFX, optional voice clips.5253## Design knobs5455| Knob | Effect | Notes |56|------|--------|-------|57| Text speed / instant | reading comfort | Always allow instant + a skip. |58| Auto-advance delay | hands-free reading | Tunable; pause on choices. |59| Skip scope | re-reading | Skip *read* text only by default. |60| Branch breadth/depth | replay value vs. cost | Branches multiply writing/art work. |61| Flag-gated content | reactivity | Lines/choices that check past decisions. |62| Route structure | story shape | Branch-and-merge vs. distinct routes (refs). |63| Choice visibility | fairness | Show locked choices vs. hide them. |64| Backlog length | convenience | Keep enough to re-read recent context. |6566## Patterns6768### 1. Script as data the engine walks6970```python71# Pseudocode. Lines, choices, and jumps as data — usually authored in Ink/Yarn and stepped72# through by that runtime. The engine asks the script for "the next thing to show".73node = script.current()74if node.kind == "line":75 show_text(node.speaker, node.text) # wait for advance input76elif node.kind == "choice":77 options = [o for o in node.options if condition_met(o.condition, flags)] # gate by flags78 show_choices(options) # wait for selection79elif node.kind == "set":80 flags[node.var] = eval_expr(node.expr, flags)81script.advance(selected_option_or_none)82```8384### 2. Typewriter reveal + advance (skippable)8586```python87# Pseudocode. Lay out the whole line once, then reveal it; a press first completes the line.88def show_text(speaker, text):89 name_label.text = speaker90 body_label.text = text # full text set up front: wrapping is decided now91 shown = 0.092 while shown < visible_length(body_label): # count displayed characters, not markup tags93 if advance_pressed(): # first press: reveal the whole line instantly94 break95 shown += chars_per_second * frame_dt()96 body_label.visible_characters = int(shown)97 wait_one_frame()98 show_all_characters(body_label)99 backlog.append((speaker, text)) # once, when the line is complete100 wait_for_advance() # second press: go to the next line101```102103Reveal with the label's visible-character count, not by slicing the string: slicing cuts104markup tags in half and re-wraps the text every frame, so a word starts on one line and jumps105to the next. Godot 4.7: `RichTextLabel.visible_characters` (or `visible_ratio`) with106`visible_characters_behavior = TextServer.VC_CHARS_AFTER_SHAPING`; the default107`VC_CHARS_BEFORE_SHAPING` leaves hidden text out of line breaking, so words still jump. Unity 6.3:108`TMP_Text.maxVisibleCharacters` (TextMeshPro, part of the uGUI package).109110### 3. Choice sets a flag that branches later content111112```python113# Pseudocode. Choices write flags; later conditions read them — that is "reactivity".114def on_choice(option):115 if option.set: flags[option.set] = True # e.g. flags["helped_npc"] = True116 script.jump(option.target) # follow the branch117118# Elsewhere, a line/choice/ending checks the flag:119if flags.get("helped_npc"): play_route("good_ending") else: play_route("neutral_ending")120```121122## Pitfalls / failure modes123124- **Save that only stores a checkpoint** → VNs need **save-anywhere**. Persist the exact script125 position *and* all flags/variables (and seen-text data) so a load resumes the same line. Check126 what your runtime can restore: Ink saves the exact position, Yarn Spinner only the node127 (refs §4).128- **Typewriter text that jumps between lines or shows raw tags** → the reveal slices the string.129 Set the full text and raise the visible-character count (Pattern 2).130- **Presentation logic baked into the script** → unmaintainable. Keep *content* (text, choices)131 in the script and *how it looks* (sprites, transitions) in the engine layer.132- **No skip/auto/backlog** → readers feel trapped, especially on replays. These are expected133 baseline features, not extras.134- **Skipping unread text** → players miss content. Skip should fast-forward **read** text only.135- **Choices with no consequence** → branches that reconverge instantly feel fake. Set flags that136 visibly change later lines, choices, or endings.137- **Combinatorial branch explosion** → unshippable. Prefer branch-and-merge with a few flagged138 variations over fully distinct trees (refs).139- **Lost reading context** → no backlog to re-read the last lines. Keep a history buffer.140- **Hardcoded language** → no localization path. Keep text in data keyed for translation.141142## Composition (build it from these skills)143144- **Script engine:** `dialogue-systems` (Ink / Yarn Spinner) — branching, conditions, variables, localization hooks.145- **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.146- **Persistence:** `save-systems` for save-anywhere slots, seen-text/skip data, and settings.147- **Audio:** `audio-design` for per-scene music, SFX, and voice playback.148- **Visuals:** the engine animation/`Tween` skill for sprite/background transitions; `shader-programming` for dissolves.149- **Process:** `prototype-fast` to test the branch structure in plain text before adding art.150151## References152153- For the branching data model, route structures (branch-and-merge vs. routes), flags/variables,154 save-anywhere + backlog/skip data, and the content/presentation split, read155 `references/script-and-flow.md`.