visual-novel Checked

# 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. Reveal characters over time; a click first completes the line, then advances.
def show_text(speaker, text):
    name_label.text = speaker
    revealed = 0
    while revealed < len(text):
        if advance_pressed():                  # first press: reveal the whole line instantly
            revealed = len(text); break
        revealed += chars_per_second * dt
        body_label.text = text[:int(revealed)]
        push_to_backlog_when_complete(speaker, text)
    wait_for_advance()                          # second press: go to the next line

### 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.

• **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.