Ludo Atlas · Engine Tracks · Ren'Py¶

Engine Tracks. Positioning: the dedicated engine of the visual novel field — Python-based scripting with a script-like shape, all the narrative staples built in, and the default starting point for text-driven projects. Companions: Art & Audio Handbook · Multi-platform Launch Playbook · Pitfalls & Anti-patterns · Indie Survival. Principle: this page carries no code snippets and no version numbers; statements and interface details change across engine releases — defer to the official docs and the bundled tutorial.

1. Positioning and Choice¶

Ren'Py is a free, open-source engine built specifically for visual novels, written in a Python-family scripting language, with no license fees or revenue share for commercial use. It makes no "does everything" promise; what it buys instead is doing one thing thoroughly: dialogue advancement, branching choices, save/load, rollback and history, skip and auto-forward, language switching, a CG gallery — every narrative-game staple is built in. The script reads like a screenplay: one line of text with a speaker is one line of dialogue, and a writer can edit content straight from the docs without first learning a general-purpose programming language.

Within the visual novel genre it is the de facto standard: tutorials, assets and community accumulation all revolve around it. The selection judgment compresses into one sentence: if the project's core loop is "read text and make choices," pick it; once gameplay complexity outgrows the narrative itself, look at general-purpose engines (see the Engine Selection Guide and the Visual Novel page in the Genre Handbooks for comparison).

Three bedrock strengths on the engineering side:

Text is the project: script, staging and logic live in the same script files, and the path from editing text to seeing it is short enough to have no translation layer at all;
The staples are complete: saves, rollback, history, skip, auto-forward, multi-language and galleries are built-in capabilities — use them all first, then talk about customization;
The build chain is complete: desktop on three platforms, Android, iOS and Web all export, and PC digital stores have official hooks for achievements and cloud saves.

Who it fits¶

Visual novels, text adventures and dating sims: the engine grew up around this genre, and every engineering hour saved goes into the text.
Writer-led teams: writers edit the script directly; content iteration does not wait on programmer schedules.
An indie's first narrative work: from empty project to shippable build is one of the shortest mainlines among engines.
Narrative prototypes and game jams: dialogue boxes, branches and saves stand up fast, leaving time for the writing itself.
Mid-to-long works that win on text volume and branch depth: the narrative infrastructure is all ready-made — for scale reference see the Visual Novel page in the Genre Handbooks.

Who it does not fit¶

Action and real-time gameplay: no built-in physics, animation state machine or frame-driven system — gameplay is built from zero.
Genre-heavy systems (management sims, strategy, numbers-heavy RPGs): every custom system fights the narrative model.
Heavy 3D or high-density staging: 3D and Live2D-class extensions are possible, but the workload and risk are recalculated as a new project.
Gameplay-module-collection works: the engine provides no gameplay infrastructure — weigh the cost yourself.
Teams that avoid scripts entirely: interfaces and logic are mostly script; pure graphical operation will not get far.

2. Ecosystem and Project Structure¶

2.1 Directories and naming¶

The project skeleton is generated by the launcher with a fixed structure — no need to invent your own:

Location	What goes here
`game/`	All scripts and assets — the "home" of project content
`game/images/`	Images; file names directly determine how they are referenced (see §4.3)
`game/audio/`	Music and sound effects
`game/gui/`	Interface theme assets
`game/tl/`	Translation files
Project root	Project files and launcher scripts — no content

Naming conventions:

Split scripts by chapter or route, starting with one file per scene; labels jump across files — files are organizational units, not runtime units.
Files and labels uniformly lowercase with underscores and numbering (chapter number plus sequence); reading the names in order draws the project map.
Image file names follow the "character plus state" template; the naming convention is the referencing convention (see §4.3).
Write the rules into the repository README; new content benchmarks against the template before it enters.

2.2 Version control¶

Scripts are plain text — diff- and merge-friendly; compiled artifacts and runtime saves stay out of the repository, all regenerable.
Images and audio are the bulk: use Git LFS, with rules set early in the project.
Renaming an image equals changing an interface: search references globally first, then touch the file.
Script, branch table and variable table enter the repository together: which version the text was edited to, and whether branches are registered, stay answerable at any time.

2.3 Community and extensions¶

Official docs are high quality and frequently updated; the engine source is open, so behavioral questions can go straight to the implementation.
A thick community asset base: interface themes, sprite and music assets, interface enhancement plugins — free and paid alike.
Extension directions: platform integrations (achievements, cloud saves), staging enhancements such as Live2D, custom transitions and scripting modules.
Chinese tutorials are plentiful but mix old and new — when they do not line up, the official docs are the arbiter.

3. Core Workflows¶

3.1 From zero to running¶

Create the project: the launcher generates an empty project with a default interface that runs immediately; walk the bundled tutorial first.
Write the first scene: add a label and dialogue to the entry script — the minimal "edit text, see the effect" loop in pure text.
Attach placeholder assets: drop images and audio into the directories per the naming conventions; start with placeholders and free assets to stand up the staging chain.
Branches and variables: define state variables, write the first choice point and two converging endings, and register both in the branch and variable tables.
Field-test the staples: walk through save, load, rollback, history, skip, auto-forward and settings one by one; confirm the defaults are adjustable.
Swap the theme: change the default interface assets and theme config into your own dialogue box, choices and title screen.
Translation and gallery: export text into translation files and fill them back; configure the CG gallery and ending-collection screens.
Package: produce one build each for desktop, mobile and Web; run the engine's built-in checks before release, then full-path test against the branch table.

3.2 Build and distribution¶

Desktop (Windows, macOS, Linux): one pipeline yields zips and installers; signing, stores and channels in the Multi-platform Launch Playbook.
Mobile (Android, iOS): Android needs signing and a dev toolchain; iOS final packaging depends on a macOS environment — non-Mac teams should plan ahead.
Web: it exports a browser-runnable version, but trim features to the browser's capabilities; audio and memory limits require real-device verification.
PC digital stores: achievements and cloud saves have official hooks — configure item by item and test for real.
Automation: builds support the command line and can wire into CI for daily builds.

3.3 Collaboration split¶

Writers edit script files; programmers edit system and interface files — split by file to avoid collisions in the same file.
The writer's hard boundary: do not touch labels, variable names or jump targets; do not touch indentation or statement structure.
Change registration: new branches enter the branch table first, new variables the variable table first; unregistered content does not enter the text.
Proofreading and review happen outside the engine; inside the engine you only integrate and check — confirming expressions, music and pauses land where they were written.

4. Idioms for Key Systems¶

4.1 Labels and jumps: the skeleton of the script¶

A label is an anchor in the script: one per scene, segment or ending; jump transfers unconditionally, call transfers and returns.
Structure speaks through naming: labels named by chapter and scene number — read the names in order and you have the project map.
Jump relationships are registered centrally in the branch table; jumps outside the table are not allowed in the text. A runaway jump web is the first danger signal of a long project.
labels can take parameters to reuse segments (a shared coda for several endings, say); differences come from parameters and variables, not copies.

4.2 Dialogue and narration¶

Dialogue and narration are first-class statements: one line of text with a speaker is one line of dialogue; narration is text on its own.
Characters are declared once in a definition statement: display name, name color and voice prefix hang there; the text references only the character variable.
Staging markers travel with the text: expressions, voice and pauses sit beside the dialogue — reading the script is reading the staging.
No logic mixed into text: conditions and branches go in their own statements, holding the line that "editing lines never touches logic."

4.3 Images and sound: layer stacking¶

scene, show and hide manage the screen: the first swaps the backdrop, the second stacks sprites, the third removes them.
Images are organized as "tag plus attributes": one character's expressions are attributes of one tag — switching attributes switches expressions, with no full set of images per combination.
Images placed in the agreed directories become references automatically by file name; the naming convention is the first design document of the script.
Sound is managed by channel: music, sound effects and voice each run on their own channel; play, stop and queue are three distinct actions, with fades tuned to the staging rhythm.
Transitions are a separate mechanism layered onto scene and sprite switches; use them sparingly — their value is rhythm, not quantity.

4.4 Built-in facilities: use them all first¶

Facility	What it does
Saves and loads	Multiple slots, thumbnails and timestamps, autosaves, quick save/load
Rollback	Step back a number of lines and re-choose — the first insurance against misclicks
History	The full dialogue history, with voice replay and jump-back
Skip	Distinguishes read from unread; repeat segments in later playthroughs skip wholesale
Auto-forward	Advances by text length, optionally linked to voice length
Preferences	Text speed, volume, language and more, managed in one place and persisted

Use them all first, then customize: invest the saved engineering in text and staging, not in reinventing wheels.

4.5 Branches, variables and playthroughs¶

State variables are shared across scripts: affinity, flags and clues all live in variables, and conditions and branches read them to decide.
Menu statements present choices: every choice changes a variable or jumps — do not offer fake choices with no difference.
Variables and branches enter their tables first: the variable table manages definitions and references, the branch table manages entries and convergence points (methods in the Game Design Handbook and the Visual Novel page in the Genre Handbooks).
Cross-save data goes into persistent objects: ending unlocks, galleries and collection progress live here, surviving a new game.
Multiple playthroughs combine variables with persistent data: a second run adds a viewpoint or extra passages without duplicating the script.

4.6 Multi-language and galleries¶

Translation runs through the engine's string system: export text into translation files, fill them in, and language switching is built in.
Verify each language separately: missing glyphs and fallback fonts, line-breaking rules, punctuation rules, interface widths (reserve by the widest language, Chinese among them).
Fix the glossary before translating: names of people, places and moves stay consistent throughout.
CG galleries and music rooms record unlock state in persistent data, with interfaces customized through the engine's screen system; settle gallery cell specs before art delivery.

4.7 The boundary of interface and extension¶

Interfaces are script-defined: saves, history, settings and galleries are all editable default screens — restyle first, restructure as needed.
Extension goes through Python: platform integrations and minigame modules are writable, but each addition must be verified separately on target platforms.
Positioning discipline: the moment gameplay complexity outgrows the narrative, stop and re-evaluate the engine choice — do not make a narrative engine do a general engine's job.

5. Performance and Optimization¶

The visual novel bottleneck is not framerate but loading, memory and bundle size; measure before optimizing, and trust target devices.

5.1 Loading and memory¶

Preloading: read the next scene's images and music before the transition, so staging never breaks on a read.
Residency control: large-resolution CGs and sprites resident at once are the memory bulk — flatten peaks with preload windows and release strategy.
First screen: keep startup scripts and first-scene assets lean; compress the time from click to first line.
Long sessions: leave memory headroom for extended play, mobile and browsers especially — never take dev-machine behavior as the baseline.

5.2 Images and audio¶

Unified specs: plan one spec set for sprites, backgrounds and CGs at the target resolution, avoiding runtime rescaling and misalignment.
Layered sprites: split expressions and outfits into diff layers — saving both bundle size and memory (delivery specs in the Art & Audio Handbook).
Audio division of labor: music streamed, sound effects resident; verify encoding formats and decoding behavior per target platform.
Compress and trim images per platform before packaging — they are the bulk of the bundle; verify browser audio strategy on real devices.

5.3 Staging and text¶

Transitions and full-screen effects only at climax moments; test on low-end devices first, and spend scarce effects where they count.
The bottleneck of text volume is not the engine but organization: keep file splits, naming and translation files tidy.
Read each chapter through end to end once it is final, then run the performance checklist; staging stutters mostly come from asset specs, not code.

6. Learning Path¶

Run through the official tutorial: install the launcher, finish the bundled tutorial project, walking create, edit text, add images and package once each.
Learn the script syntax: dialogue, narration, labels, jumps, variables and conditions — enough for a short piece with choices.
A first complete small work: one chapter, two choices, three endings, covering real use of saves and rollback (workflow in the Visual Novel page of the Genre Handbooks).
Engineering: directory and naming conventions, version control, branch and variable tables, the translation export flow.
Customize the interface: change theme assets and default screens into your own dialogue box, save/load and gallery styling.
Release and beyond: one build per platform line (criteria in the Multi-platform Launch Playbook), then learn Python extensions and staging enhancements as needed.

7. Common Pitfalls¶

Hard-coded text with no external table: lines live only in the script, with no text table or translation export flow — additions, edits and going overseas all mean rework. Avoidance: organize text for translation from day one and get the export/import flow running first.
Branch explosion: a tree of branches with no convergence points doubles the writing and proofreading load over time. Avoidance: register convergence points and variables before writing the text.
Not testing full paths: walking only the mainline means broken jumps deep in branches and uninitialized variables surface at launch. Avoidance: walk every path in the branch table, back it with the engine's built-in checks, and test all convergence points.
Chaotic art specs: sprite canvases, anchors and naming all go their own way, and expression or outfit combinations misalign. Avoidance: a delivery spec sheet up front, one naming template, and a global search before any rename.
Jumps and variables managed ad hoc: chaotic label names, scattered jump targets, no unified variable names — change one place, break a patch. Avoidance: stand up the naming rules and the two tables first.
Rough save compatibility: after a script update old saves will not load, and progress scrambles. Avoidance: decouple saves from content where possible and test with old saves before updating.
Shallow understanding of rollback: irreversible actions (file writes, requests) outside rollback scope leave the state inconsistent after stepping back. Avoidance: manage side effects centrally and be explicit about what gets rolled back.
Using it for out-of-position projects: action, gameplay-heavy or heavy-3D work crammed in — every system fights the engine. Avoidance: switch engines after evaluation, or keep the gameplay light.
Fonts and CJK typesetting: missing glyphs, broken line-breaking, unclear commercial font licenses. Avoidance: prepare fonts and fallbacks per language, confirm licenses one by one, spot-check line breaks by hand.
Packaging and real-device testing too late: Web and mobile audio, performance and touch problems surface only at the end. Avoidance: produce one build per platform early and walk the full flow.