Skip to content

STORY_GRAPH.md

Latest commit

 

History

History
94 lines (73 loc) · 3.53 KB

STORY_GRAPH.md

File metadata and controls

94 lines (73 loc) · 3.53 KB
Raw

Story Graph

The Story Graph is the central view of Ren'Py Story Architect. It shows your project's Story Flow as an interactive graph of nodes and edges.

Nodes

A StoryNode is a logical game-architecture entity. It is NOT the same as a Ren'Py label — a label is an optional implementation binding.

Node kinds:

  • start — the entry point of the game.
  • scene — a linear sequence of dialogue/narration.
  • choice — a branching point.
  • hub — a sandbox location the player can return to.
  • event — a scene triggered from a hub.
  • milestone — a significant story beat.
  • ending — a terminal node.
  • utility — a technical label (e.g. save/load screen).

Node status:

  • planned — authored, not yet implemented in source.
  • in_progress — being worked on.
  • implemented — bound to a Ren'Py label and source.

New authored nodes automatically receive a unique intendedLabel (a valid, unique ASCII Ren'Py identifier derived from the title). A missing, invalid, or duplicate label is a blocking validation error: generation is refused until it is fixed.

Edges

An Edge represents a flow relationship between two nodes.

Edge kinds:

  • flow — normal transition.
  • unlock — one node unlocks another.
  • requirement — one node requires another to have been visited.

Transfer kinds (for flow edges):

  • jump — Ren'Py jump statement.
  • call — Ren'Py call statement (returns).
  • choice — Ren'Py menu choice.
  • return — Ren'Py return statement.
  • planned — intended but not yet implemented.
  • none — no transfer (e.g. unlock/requirement).

Flow edges may carry a condition (e.g. if affection_lisa >= 5) and an isFallback flag for else/fallback branches.

Hub / Event pattern

Sandbox games use a hub/event pattern:

  • A hub node is a location the player can return to (e.g. home).
  • An event node is triggered from the hub and returns to it.
  • Events have hubNodeId and returnTargetNodeId metadata (EventMetadata).

Story Architect detects this pattern automatically from imported source and lets you author it explicitly for planned content. Event→hub returns are marked hidden by default so the graph does not become a "star of return arrows"; the FilterBar can reveal them.

Filters

The FilterBar at the top of the graph view lets you:

  • Filter by node kind and status.
  • Search nodes by title/label (free text).
  • Show/hide hidden event returns (edges with hiddenByDefault).
  • Variable Influence Focus — pick a variable; the graph classifies each node as WRITE / READ / READ+WRITE / UNRELATED and mutes unrelated nodes (backed by the Variable Usage Index).
  • Character Focus — pick a character; unrelated nodes are muted (backed by the Character Usage Index).

The two focus modes are mutually exclusive; a badge shows the active focus with read/write counts or scene/dialogue counts, and a clear button resets it.

Diagnostics

The Diagnostics panel (left sidebar, "Diagnostics" tab) groups issues by category:

  • Structural — broken jump/call targets, unreachable labels, undefined variables, duplicate labels.
  • Architecture — authored-project validation issues.
  • Scene — scene validation issues.
  • Localization — localization validation issues.

Cyclic sandbox hubs are not reported as errors merely for being cyclic — a home label that jumps back to itself is valid sandbox architecture.

Click a diagnostic to jump to the relevant node. The Project Health panel offers a broader health review.