gamedev-skills/awesome-gamedev-agent-skills

visual-novel

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.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill visual-novel

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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.

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

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

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

  1. Saves resume the exact line with all flags, and seen-text data lives in a persistent

store shared by all saves (refs §4).

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

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

  • 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-code and test: https://www.renpy.org/doc/html/cli.html.

  • inklecate exits 1 on compile errors and -s prints 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.
from this repository

More skills

All skills
gamedev-skills
Community

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

24h installs
433
GitHub stars
10K
Updated
Nov 12
gamedev-skills
Community

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

24h installs
431
GitHub stars
10K
Updated
Nov 12
gamedev-skills
Community

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

24h installs
365
GitHub stars
10K
Updated
Nov 12
gamedev-skills
Community

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

24h installs
360
GitHub stars
10K
Updated
Nov 12