Flowchart

Flowchart visualizes your Ren’Py game’s branching structure so you can immediately see dead ends, unreachable labels, and narrative logic issues — without reading a single line of source code. Every label, jump, call, and menu branch becomes a node you can explore and inspect.

Where you use it

Both are available on all tiers. The VS Code panel is the full experience; HTML is the shareable snapshot.

Pre-release note: Flowchart Plus is currently available to all tiers. When BranchPy reaches general release, Plus will require a Ren’Py Pro license. Standard Flowchart remains on Ren’Py Free.

One command, two modes

Flowchart is one feature that runs in two modes. You always use the same command. The mode activates automatically based on what data your last Analyze run produced.

There is no separate command and no configuration needed. BranchPy checks whether the deeper structural analysis results are present alongside your Analyze run. If they are, the panel title shows Story Flow Visualization Plus and the SCR/RBI narrative signal pills and Narrative layout selector become active. Without them, it opens as Story Flow Visualization with the full interactive feature set. It falls back gracefully — no error, no action required from you.

Licensing: Standard Flowchart is included with Ren’Py Free. Flowchart Plus requires Ren’Py Pro. During the current pre-release period, Plus is available to all tiers.

What Plus adds

When do I need Plus?

For most projects, Standard Flowchart is enough to get started. Here is a practical signal for when Plus becomes valuable:

In short: Standard gives you the map. Plus tells you what the map is trying to tell you.

When to use Flowchart

• After Analyze, to understand your narrative’s overall shape at a glance.
• To spot dead ends, disconnected areas, or unexpected branch structure before playtesting.
• To navigate quickly to any label in your source without a text search.
• To prepare a visual map for a sprint review, design discussion, or co-author handoff.

How to open

1. Run Analyze from the BranchPy Control Center.
2. Wait for the report to finish.
3. Click Open Flowchart in the report or the control center.

To get Plus mode, enable D9 Narrative Analysis in your Analyze settings before running. For a full Plus-eligible run from the CLI:

branchpy --project <path> analyze
branchpy --project <path> pilot
branchpy omega --project-root <path>

Flowchart always reflects the last completed Analyze run. If you edit .rpy files afterwards, re-run Analyze first, then reopen the panel to pick up the latest data. The timestamp shown at the top tells you when the analysis was taken.

Opening a Flowchart after restart

The full interactive graph requires a session run — an Analyze that completed during the current VS Code session. The Control Center button is labelled Open Session Flowchart to make this clear.

When the dialog appears, you have two choices:

• Run Flowchart — triggers a fresh Analyze run and opens the graph when complete
• Open Last Summary — opens a read-only text summary from the previous run without re-running

The Open Last Summary path is always available and requires no re-run. Use it when you only want to review counts and metrics from the last run without loading a visual graph.

Why session-scoped? The interactive graph is generated fresh during each Analyze run. BranchPy does not persist the full graph between VS Code sessions because graph data can be large and may be stale. The summary is always available from disk; the graph requires a live run.

Navigating the panel

The panel is divided into a graph canvas (centre) and a control panel (right, accessed via tabs).

Inspecting a label

Click any node to open its detail popup.

The popup shows:

• Type — Entry, Narrative, Routing, System, Exit, Unknown
• File and line — exact location in your .rpy source
• Incoming / Outgoing — edge counts
• Open in Editor — jumps straight to that label in VS Code
• Element Customisation — change colour, shape, display name, or save a reusable style template

Multi-selecting labels

Hold Shift and drag to draw a selection box, or hold Ctrl and click to toggle individual nodes. The selection count appears in the Analysis tab.

With nodes selected you can:

• Highlight all (yellow overlay)
• Hide all (temporarily remove from view)
• Fit view to the selection
• Collapse into a group node (see below)

Grouping and collapsing labels

Any set of selected labels can be folded into a compact group node to reduce clutter on busy graphs. All edges reroute automatically. This is a visual-only operation — your .rpy source is never changed.

To collapse: Select 2+ nodes, then right-click → Collapse Highlighted Nodes, or click the ▲ Collapse toolbar button.

The group node is labelled name +N where N is the count of hidden labels. You can collapse multiple independent paths simultaneously.

Nested groups: Collapse a group node together with other nodes to fold further. The label stacks the counts — for example path_a_start +4 +1.

To expand: Right-click a group node → Expand This Group. Or click Expand All in the toolbar to restore every group at once.

Every collapse and expand is tracked in the undo history — Ctrl+Z / Ctrl+Y work as expected.

Visual editor

The Editor tab provides tools that never modify your .rpy source:

Narrative signals — Plus only

When Flowchart opens in Plus mode, two compact pills appear immediately below the project name:

These values come directly from D9 Narrative Analysis — the same values shown in analyze --summary and analyze --html reports. Seeing them inline in the graph means you don’t need to switch to the text report for a structural health check.

Narrative layout mode (Plus only): a Classic | Narrative selector appears in the panel header. Classic is the default. Narrative mode switches to a backend-computed layout using semantic summary positions, and activates the Narrative analysis panel showing fallback_mode, cleanup_tier, performance.node_count, and coordinate determinism data.

Saving and loading layouts

Use the 💾 Save / 📂 Load toolbar buttons to manage up to 10 named layout slots. Each slot preserves:

• Node positions
• Filter state (which types are visible)
• All graphics (custom arrows, annotations, highlights, display names)
• Visualization settings

Slots persist across VS Code restarts.

Export

From the Settings tab:

From the CLI:

branchpy --project <path> flowchart --out <file>.html

Standalone HTML report

The HTML export includes grouping, collapsing, node details, and the label-to-editor link — all working in any modern browser with no VS Code or BranchPy installed.

The hint bar reads: Shift-drag to select · Ctrl+Click to add · right-click to collapse · right-click group to expand.

See also

• Technical: Flowchart semantics
• Analyze
• Omega