Ren'Py Story Architect

A visual planning and authoring companion for nonlinear Ren'Py visual novels.

Ren'Py Story Architect helps authors understand routes, variables, hubs, scenes, and localization — without replacing Ren'Py itself. It imports your existing .rpy project, builds an independent Game Model, and shows you Story Flow, variable influence, and character routes. You can also author new planned content, write structured dialogue in the Scene Editor, translate by stable scene-block identity, and optionally use AI to propose text changes.

AI features are optional and proposal-based. The public web version only proposes text changes; the author decides what to apply.

Public Alpha warning: This is early-access software. Expect rough edges, breaking changes between releases, and missing features. Do not rely on it as your only authoring tool yet. When testing Alpha software, back up important Ren'Py projects first.

Status

Public Alpha 0.1.0-alpha.1.

Free and open-source — released under the MIT License (see LICENSE).

The web edition continues to receive features that can be implemented in the browser. Desktop development (native filesystem, Codex/MCP, ComfyUI, Forge Neo, asset management) comes later — see docs/ROADMAP.md.

Features

• Story Graph — labels, jumps, menus, and conditions rendered as an interactive graph. Hub/event patterns detected automatically. Plan routes, hubs, events, and choices.
• Scene Editor — write dialogue without manually typing Ren'Py syntax. Structured blocks (dialogue, narration, background, music, sound, note) with stable IDs that survive edits and reordering.
• Localization — translate by stable scene-block identity, not by source text. Source edits mark translations stale without deleting them. Ren'Py text-tag QA, glossary, translation memory, deterministic automatic review, bulk status actions, and bounded contextual batch AI translation (max 20 units per request).
• Imported Ren'Py translation — import a Ren'Py project and attach its generated game/tl/<lang>/ translation folder. Work with semantic units, resolve synchronization conflicts, and export a safe translation package with exact paths. Free machine translation (Google / MyMemory, keyless) with Fast / Balanced / Safe modes is available for authored and imported projects.
• Rendering compatibility guidance — content-driven font / RTL advice for translated scripts (Cyrillic, Japanese, Chinese, Korean, Arabic, Hebrew), including a setup README shipped inside the exported package.
• Optional AI Assistant — propose dialogue rewrites, continuations, and translations. Provider-neutral: direct OpenAI-compatible endpoint or same-origin server proxy. The browser never holds a secret API key or bearer token; direct mode sends no Authorization header.
• Generator / Export — produce an authored Ren'Py scaffold (story_architect_variables.rpy, story_architect_characters.rpy, story_architect_story.rpy, tl/<lang>/*.rpy) or a verified imported-translation package, downloaded as a path-preserving ZIP. Optional language-menu and per-language font compatibility helpers. Preview only — your .rpy files are never modified.
• Structural Diagnostics — broken jump targets, unreachable labels, undefined variables, duplicate labels, blocking scene/localization issues.
• Light / Dark / System appearance — choose your preferred theme from the header. Theme is a UI preference; it is not stored in your project.
• Interface languages: EN, RU, ES, DE, FR, PT-BR — choose the interface language from the header. Interface language is independent from the game's localization languages.

Screenshots

Project workspace Create a new visual novel or import an existing Ren'Py project.	Localization Translate full stories with free MT, cloud AI, or local models.
Local and cloud AI Ollama, LM Studio, proxy, and OpenAI-compatible providers.	Project Health Detect structural issues before they become runtime problems.

Quick start

bun install
bun run dev

Open http://localhost:3000.

On first run, the onboarding dialog offers three choices:

• Create a new project — start from scratch with a template.
• Open existing project — import .rpy files.
• Open example project — load the bundled "Cafe Stories" demo.

Changing appearance and interface language

Use the gear icon in the header to open the Preferences menu. Choose System / Light / Dark for appearance, or pick one of the six interface languages (English, Русский, Español, Deutsch, Français, Português (Brasil)).

Interface language is independent from the game's localization languages — changing the UI language does not affect your project's source or target languages.

Open existing Ren'Py project

Click Open .rpy Files in the landing screen and select one or more .rpy files. Story Architect parses them in your browser and builds a Game Model. Nothing is uploaded; your source files are never modified.

See docs/GETTING_STARTED.md and docs/STORY_GRAPH.md.

Create project from scratch

Click New Project and pick a template (Blank, Linear VN, or Sandbox/Hub). You can then add planned nodes, edges, variables, characters, routes, stages, and groups from the left-side panels, and write scene content in the Scene Editor.

Scene Editor

Double-click a planned node (or select it and press Enter) to open the Scene Editor. Write dialogue by selecting a speaker and typing — Enter commits the block. Speaker shortcuts (Alt+1, Alt+2, ...) can be bound in the Editor Settings popover.

See docs/SCENE_EDITOR.md.

Localization

Click Localization in the header to open the Localization Workspace. Add target languages, then translate each unit. Source edits mark translations stale without deleting them. Run deterministic Ren'Py text-tag QA on every translation. Use the glossary for consistent term translations.

See docs/LOCALIZATION.md.

Optional AI

AI is optional and disabled by default. Configure it via the AI badge in the header:

• Direct OpenAI-compatible endpoint — point at a local model server (LM Studio, Ollama, llama.cpp) or your own CORS-enabled proxy. Direct mode sends only Content-Type: application/json — no API key, no bearer token, no Authorization header in the browser.
• Same-origin server proxy — the browser calls /api/ai/chat; the server reads STORY_ARCHITECT_AI_* env vars and forwards the request. The key never reaches the browser, and error responses never leak the upstream URL.

AI proposes changes; you accept or reject them in a diff dialog. Accepted changes create normal undoable project commands.

See docs/AI_SETUP.md.

Privacy / security

• Your .rpy files are never modified.
• Everything runs in your browser; nothing is uploaded unless you run an AI operation (server proxy or your own direct endpoint) or the keyless free machine-translation feature, which sends text through the same-origin /api/translate/free proxy to Google / MyMemory.
• The browser never holds a secret provider API key.
• AI proposals are validated before apply; stale proposals are rejected.
• Accepted AI changes go through the normal undo/redo history.

See SECURITY.md and docs/AI_SETUP.md.

Current limitations

• Safe parser subset, not arbitrary Python/Ren'Py. See docs/parser-support.md.
• Imported .rpy is read-only; Story Architect does not patch source files.
• Structured Scene Editor is for authored/planned scenes, not for editing imported source content.
• Folder access depends on browser capabilities (File System Access API where available; falls back to file picker).
• Direct AI endpoint requires compatible CORS and no browser-held secret.
• No ComfyUI / Forge / Codex / MCP integration in the web Public Alpha.
• No desktop filesystem writes.

See docs/LIMITATIONS.md.

Documentation

• docs/GETTING_STARTED.md — first session walkthrough.
• docs/STORY_GRAPH.md — nodes, edges, hub/event pattern, filters, diagnostics.
• docs/SCENE_EDITOR.md — structured blocks, shortcuts, preview, AI.
• docs/LOCALIZATION.md — translation model, imported Ren'Py units, batch, review, export.
• docs/AI_SETUP.md — AI modes, security model, proxy configuration.
• docs/PROJECT_FORMAT.md — the ArchitectProjectDocumentV4 JSON schema.
• docs/parser-support.md — Ren'Py parser support matrix.
• docs/architecture.md — module boundaries, pipeline, invariants.
• docs/LIMITATIONS.md — current limitations.
• docs/ROADMAP.md — roadmap and desktop milestones.

Development

bun install
bun run test         # vitest
bun run typecheck    # tsc --noEmit
bun run build        # next build
bun run dev          # next dev -p 3000

See CONTRIBUTING.md.

Roadmap

The web edition keeps receiving features that make sense in the browser. Desktop development comes later — native filesystem, safe writer/patching, Codex/MCP, ComfyUI, Forge Neo, asset management, advanced AI permission profiles.

See docs/ROADMAP.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md.

License

Ren'Py Story Architect is released under the MIT License. See LICENSE for details.