BranchPy
Log in

Quick Start in 3 Minutes

This page gets you from install to useful output fast.

Time required: ~3 minutes
Works with: Ren’Py 7.x and 8.x
Recommended path: VS Code with BranchPy Control Center

What BranchPy does in 30 seconds

BranchPy analyzes Ren’Py projects to:

  • detect structural issues and unreachable paths,
  • visualize story flow and branching,
  • find media problems like missing or unused assets,
  • generate reports you can use for debugging and QA.

Core workflow (most users stop here):

branchpy --project <path> analyze    # full analysis + report
branchpy --project <path> flowchart  # interactive story graph

Improve your project:

branchpy --project <path> doctor     # diagnose setup and config issues
branchpy --project <path> compare    # diff two analysis runs

Advanced analysis (when you need it):

branchpy --project <path> pilot      # path-focused, variable tracking
branchpy omega --project-root <path> # variable bounds and co-occurrence
branchpy --project <path> pfi        # function/jump index

What you should see after 3 minutes

  • Story analysis summary with errors and warnings.
  • Separate Flowchart view of your narrative structure.
  • Media findings (for example, unused or missing assets).
  • Click-to-open navigation from finding to code location.

Example output preview:

branchpy --project my-game analyze --open

Analyze complete
- labels detected: 52
- warnings found: 12
- errors found: 4
- flow outputs available: yes

Analyze report summary

Who this is for:

  • First-time users who want a guided first run.
  • Teams that need a predictable baseline before deeper tuning.

Before you start

  • Install BranchPy from Download.
  • Use a valid Ren’Py project root (the folder that contains game/ and .rpy files).

If something fails, BranchPy will explain what is missing or incorrect (invalid path, missing files, unrecognised structure). Follow the message — most first-run issues are path or project-root problems and resolve in one step.

Expected project shape:

my-game/
	game/
		script.rpy
		characters.rpy
		images/

First Run in VS Code

Step 1: Install and open project

  1. Install Python 3.11+.
  2. Unzip your BranchPy pre-release package and run the installer:
    • Windows: double-click install_branchpy.bat
    • macOS / Linux: chmod +x install_branchpy.sh && ./install_branchpy.sh
  3. The installer detects VS Code and offers to install the extension automatically.
  4. Open your Ren’Py project root in VS Code.

Step 2: Run Analyze

  1. Open BranchPy Control Center.
  2. Select your project.
  3. Click Analyze.

What you should see:

  • Error/warning summary
  • Links to flow and stats views
  • Jump-to-code actions for findings

Step 3: Review flow output

  1. After Analyze completes, click Open Flowchart.
  2. Review the graph to spot disconnected nodes, dead ends, and branch shape problems.

Flowchart overview

Step 4: Fix one issue and confirm with Compare

  1. Open one high-impact issue from Analyze.
  2. Apply the fix.
  3. Rerun Analyze — confirm the count improves.
  4. Use Compare to verify no regressions were introduced.

First Run in CLI

First useful command

branchpy --project path/to/project analyze --open

--open generates a standalone HTML report and opens it in your default browser. No VS Code required.

Example result pattern:

Analyze complete
- labels detected: 
- warnings found: 
- errors found: 
- flow outputs available: yes

Step 1: Install

pip install branchpy

Step 2: Run first analysis

branchpy --project path/to/project analyze --open

Step 3: Run a quick health pass

branchpy --project path/to/project stats --open

Step 4: Open flow and media triage

branchpy --project path/to/project flowchart --open
branchpy --project path/to/project media --open

flowchart --open generates an interactive HTML flowchart and opens it in your browser. If you are running inside VS Code with the BranchPy extension, the Control Center panel opens instead.

For deterministic local development, prefer:

.venv\Scripts\python.exe -m branchpy --project path/to/project analyze --open

What to fix first

  • Start with new errors before warnings.
  • Resolve broken jumps/labels before optimization work.
  • Re-run Analyze after each meaningful batch of changes.

Common first-run mistakes

  • Wrong folder selected (parent folder instead of Ren’Py project root).
  • Assuming old reports are current after edits.
  • Mixing environments (user-site branchpy binary vs active .venv).

If it does not work

Common causes:

  • Ren’Py project folder not detected correctly.
  • Python environment mismatch.
  • Running the command from the wrong working directory.

Troubleshooting references:

Next steps