Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
134 lines (101 loc) · 5.43 KB

GETTING_STARTED.md

File metadata and controls

134 lines (101 loc) · 5.43 KB
Raw

Getting Started

Welcome to Ren'Py Story Architect! This guide walks you through your first session.

1. Open the app

bun install
bun run dev

Open http://localhost:3000. On first run you'll see the onboarding dialog. It offers three starting points:

  • Create a new project — start from a template (Blank, Linear VN, or Sandbox/Hub).
  • Open existing project — import .rpy files from your Ren'Py project.
  • Open example project — load the bundled Cafe Stories (Demo) project to explore the Story Graph, Scene Editor, Localization, and Generator without any setup.

2. Explore the Story Graph

The main view shows your project's Story Flow as an interactive graph:

  • Nodes are logical story entities (start, scene, hub, event, choice, milestone, ending, utility).
  • Edges are flow relationships (jump, call, choice, return, planned) plus unlock/requirement relationships.
  • Click a node to inspect its properties in the right-side panel; drag nodes to rearrange them.
  • The FilterBar on top filters by kind/status, searches, shows hidden event returns, and supports Variable Influence and Character focus modes.

Key concept: A StoryNode is NOT a Ren'Py label. A label is an optional implementation binding. New authored nodes automatically get a unique intendedLabel; the generator emits .rpy code from it.

See STORY_GRAPH.md for details.

3. Write a scene

Double-click a planned node (or select it and press Enter) to open the Scene Editor. The editor uses structured blocks:

  • Dialogue — a character speaking. Select a speaker, type, press Enter.
  • Narration — voice-over / narrated text.
  • Background — scene background image change.
  • Music — play/stop music with optional fade in/out.
  • Sound — play a sound effect.
  • Note — author-only note, not emitted as executable Ren'Py.

Keyboard shortcuts: Enter commits the draft, Shift+Enter inserts a newline, Ctrl+Enter commits even while the input is focused. Speaker digits 1–8 switch speakers automatically (zero-config); 9 toggles speaker-lock so you can type numeric dialogue; Alt+1, Alt+2, ... can be bound manually in the Editor Settings popover. Ping-pong mode (in Editor Settings) auto-advances the speaker through a queue on each commit.

The scene toolbar also offers a live read-only Ren'Py preview and a Design Preview (visual stage) of the scene.

See SCENE_EDITOR.md for details.

4. Translate

Click Localization in the header to open the Localization Workspace. Add target languages, then translate each unit. Story Architect uses stable scene-block IDs (not source text) as translation identity, so editing source marks translations stale without deleting them.

For imported Ren'Py projects you can attach the generated game/tl/<lang>/ translation folder and work with the real semantic units, resolve synchronization conflicts, and export a verified translation package.

You can translate with the keyless free machine-translation engine (Google / MyMemory, no account needed) or with the optional AI engine. See LOCALIZATION.md for details.

5. Generate / export

Click Generate Ren'Py project in the header:

  • Authored project — review the Ren'Py scaffold preview (variables, characters, story, and tl/<lang>/ localization files) and download a path-preserving ZIP. Your actual source files are never modified.
  • Imported project — the dialog becomes the Ren'Py Translation Export: pick attached languages and statuses, resolve conflicts, and download a verified translation package.

6. (Optional) Configure AI

Click the AI badge in the header to open AI Settings. Choose:

  • Disabled (default) — no AI features.
  • Direct OpenAI-compatible endpoint — point at a local model server (LM Studio, Ollama, llama.cpp). Direct mode sends only Content-Type: application/json; no API key, bearer token, or Authorization header is ever sent from the browser.
  • Same-origin server proxy — server reads STORY_ARCHITECT_AI_* env vars, the browser never sees the key. Error responses never leak the upstream URL.

See AI_SETUP.md for details.

7. Appearance and interface language

Use the gear icon (Preferences) in the header to:

  • Appearance — choose System, Light, or Dark. The theme preference is stored in your browser (via next-themes localStorage) and is NOT part of your project data. You can also toggle it directly via the sun/moon icon in the header.
  • Interface language — choose one of English, Русский, Español, Deutsch, Français, Português (Brasil). The interface language is stored in a cookie (story-architect-ui-locale) and is independent from the game project's source/target localization languages.

Note: Changing the interface language does NOT change the languages of your game project. Source language and target languages are managed in the Localization Workspace.

8. Other tools

  • Quick Open (Ctrl+P) — search nodes, characters, variables, and scene text from anywhere.
  • Project Health — a review of architecture, scene, localization, and structural issues for your project.
  • Diagnostics — the left-side Diagnostics panel lists structural, architecture, scene, and localization issues; click one to jump to the relevant node.