Skip to content

gamedev-skills/awesome-gamedev-agent-skills / skills/genres/visual-novel

visual-novel

Verified

Builds visual novels and choice-driven stories in Ren'Py or any engine: routes and endings, save-anywhere, backlog, skip-read-only and typewriter text. Use for a VN or dating sim, or loads at the wrong line, skip running through unread text or an unreachable ending. Not for dialogue in a larger game or Ink and Yarn (`dialogue-systems`) or text box widgets (`godot-ui-control`).

Visual novel

Owns the shape of a branching story and the reading conveniences players expect. The script runtime (Ren'Py, Ink, Yarn Spinner) does the stepping; this skill decides routes, flags, saves and the reader-facing systems, and checks them.

When to use

  • The game is mostly reading text with character art, backgrounds and choices.
  • Planning routes and endings, affection systems, save behaviour, backlog, skip and auto, or checking that every ending can be reached.

When not to use: NPC conversations inside another genre (dialogue-systems, with rpg for quests); Ink or Yarn integration code (dialogue-systems); the text box and choice menu widgets (godot-ui-control, game-ui-ux).

Workflow

  1. Find the engine. In Ren'Py (game/*.rpy), the engine already has save-anywhere, rollback, history, skip, auto-forward and text speed: restyle its screens and preferences, and spend the effort on routes and flags. Elsewhere, build those systems from refs §4-5.
  2. Draw the route map before writing: common route, the lock-in point (often about a third of the way through), each route's endings, and a true ending gated on finishing others if wanted. Write the flags and the thresholds each ending needs next to it.
  3. Size the script. Readers average roughly 200-250 words per minute, so 1,000 words is about 4-5 minutes; a 2-hour VN is about 25,000-30,000 words. Give a meaningful choice or reaction every 5-15 minutes of reading, and make at least one later line visibly react to each important choice.
  4. Track state as booleans for one-off decisions and counters for affection. For each route, add up the maximum affection the choices can give and set the ending threshold below it, with some slack for missed choices.
  5. Saves resume the exact line with all flags, and seen-text data lives in a persistent store shared by all saves (refs §4).
  6. Check it. Run what applies and report the output:
    • Ren'Py: ./renpy.sh <project> lint --error-code (exit 1 on lint errors), and ./renpy.sh <project> test for scripted test cases;
    • Ink: inklecate -o story.json story.ink (exit 1 on compile errors; -s prints word counts), then a breadth-first walk with inkjs: Continue() while canContinue, save state.ToJson() at each choice, LoadJson() and ChooseChoiceIndex(i) for each branch, and collect currentTags at each end. Tag ending lines (for example # ending: alice_good) and assert every planned ending appears. Cap the depth and dedupe states for big scripts;
    • any engine: save at a choice, quit, load, and confirm the same line and choices appear; enable skip on a fresh profile and confirm it stops at the first unseen line.

Reader systems

SystemDefaultNotes
Text speedinstant or fast by default, with a sliderRen'Py's own default is instant (preferences.text_cps = 0)
Skipread text only; stops at choices and unseen linesRen'Py: preferences.skip_unseen = False
Auto-forwarddelay scaled by line length; pauses at choicesRen'Py: preferences.afm_time = 15
Backlog100-200 lines, with voice replayrollback in Ren'Py doubles as backlog
Savesmany slots with thumbnail, date and chapter, plus quick saveautosave at chapter starts and before choices
GalleriesCG, music and ending lists unlocked across all savesRen'Py persistent data

Pattern 1: typewriter reveal that does not jump

# Set the full text once, then reveal by visible-character count.
def show_line(speaker, text):
    name_label.text = speaker
    body.text = text                         # wrapping decided once, on the full text
    shown = 0.0
    while shown < visible_length(body) and not advance_pressed():
        shown += cps * frame_dt()
        body.visible_characters = int(shown)
        wait_frame()
    body.visible_characters = -1             # first press completes the line
    backlog.append((speaker, text)); seen.add(line_id)
    wait_for_advance()                       # second press moves on

Godot 4.7: RichTextLabel.visible_characters with visible_characters_behavior = TextServer.VC_CHARS_AFTER_SHAPING (the default leaves hidden text out of line breaking, so words still jump). Unity 6.3: TMP_Text.maxVisibleCharacters.

Gotchas

  • Load resumes at the start of a scene → only a checkpoint or node name is saved. Ink saves the exact position with state.ToJson(); Yarn Spinner restores only the node (refs §4).
  • Old saves break after an update → lines moved or edited under a save. Give lines stable IDs, keep released labels, and test loading saves from the previous build.
  • Ren'Py flag not saved or reset on load → declared with define (meant for constants) instead of default. Story state uses default.
  • Skip runs through new text → seen-text stored per save, or skip set to "all". Store seen line IDs in persistent data shared by all saves.
  • An ending is unreachable → thresholds above the maximum the choices can give, or a flag set on one branch and read on another. Run the reachability walk (step 6).
  • Choices feel fake → branches merge back immediately with no reaction. Pay each choice off with at least one later line, sprite or option.
  • Text jumps between lines or shows raw tags → the reveal slices the string (Pattern 1).
  • Branch explosion → fully separate trees for every choice. Branch and merge, with flags that vary lines, and reserve full routes for the big decisions.
  • Text baked into code or images → no translation path. Keep strings in the script or a table keyed by line ID, and leave room for 30% longer text in the box.

References

  • references/script-and-flow.md: read when designing the script data model, choosing a route structure, picking ending logic from flags, writing save-anywhere data (Ink, Yarn Spinner and Ren'Py specifics), backlog, skip and auto behaviour, staging conventions or localisation.

Related: dialogue-systems (Ink and Yarn runtimes), save-systems (slots, versioning), game-ui-ux with godot-ui-control (text box, choices, backlog screen), audio-design (music, voice), prototype-fast (test the branch map in plain text first).

Version notes

Last verified: 2026-11-11.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall