gamedev-skills/awesome-gamedev-agent-skills / skills/genres/visual-novel
visual-novel
VerifiedBuilds 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
- 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. - 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.
- 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.
- 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.
- Saves resume the exact line with all flags, and seen-text data lives in a persistent store shared by all saves (refs §4).
- 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> testfor scripted test cases; - Ink:
inklecate -o story.json story.ink(exit 1 on compile errors;-sprints word counts), then a breadth-first walk with inkjs:Continue()whilecanContinue, savestate.ToJson()at each choice,LoadJson()andChooseChoiceIndex(i)for each branch, and collectcurrentTagsat 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.
- Ren'Py:
Reader systems
| System | Default | Notes |
|---|---|---|
| Text speed | instant or fast by default, with a slider | Ren'Py's own default is instant (preferences.text_cps = 0) |
| Skip | read text only; stops at choices and unseen lines | Ren'Py: preferences.skip_unseen = False |
| Auto-forward | delay scaled by line length; pauses at choices | Ren'Py: preferences.afm_time = 15 |
| Backlog | 100-200 lines, with voice replay | rollback in Ren'Py doubles as backlog |
| Saves | many slots with thumbnail, date and chapter, plus quick save | autosave at chapter starts and before choices |
| Galleries | CG, music and ending lists unlocked across all saves | Ren'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 ofdefault. Story state usesdefault. - 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.
- Ren'Py 8.5.3 is the current stable release (8.6.0 is a prerelease, updated 2026-11-01):
https://www.renpy.org/latest.html. Preference defaults (
text_cps = 0,afm_time = 15,skip_unseen = False): https://www.renpy.org/doc/html/preferences.html.lint --error-codeandtest: https://www.renpy.org/doc/html/cli.html. - inklecate exits 1 on compile errors and
-sprints story stats (inklecate/CommandLineTool.cs in https://github.com/inkle/ink, ink 1.2.1). - inkjs 2.4.0 typings:
Continue(),canContinue,currentChoices,currentTags,ChooseChoiceIndex(),state.ToJson(),state.LoadJson(). - Yarn Spinner for Unity 3.2.8 is the latest release (GitHub releases).
- Reading speed and words-per-hour figures are rough design estimates.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |