English | Русский

"Notice me, Senpy! (⁄ ⁄>⁄ ▽ ⁄<⁄ ⁄)"
Senpy — Fast static analyzer, semantic linter, control-flow analyzer and VS Code language server for Ren'Py visual novels. Detects undefined variables, broken labels, control-flow bugs, rollback/save issues, translation errors, and more.

CLI / CI / Linux / macOS:

pip install senpy-linter

VS Code Extension (Windows, zero Python setup): Download the latest senpy-vscode-X.X.X.vsix from the Releases page → Install from VSIX in VS Code.

Full changelog: CHANGELOG.md

renpy lint catches syntax errors, but does not catch the bugs that actually ship to players. These are real bugs that Senpy would have caught before release:

define player_gold = 100

label spend_gold:
    $ player_gold -= 50    # ← mutates a `define`
    "You have [player_gold] gold."

Symptom: Game works in dev. Players report Exception: define player_gold is not revertable on rollback, or save files silently corrupt after loading an old save.

Senpy catches it: RPY105 (define mutation) fires at lint time.

label start:
    jump intro

label intro:
    $ greeted = True
    "Hello!"

label continue_story:
    if greeted:    # ← `greeted` not declared with `default`
        "Hi again!"

Symptom: Game works on first playthrough. Players who load a save at continue_story (skipping intro) hit NameError: name 'greeted' is not defined.

Senpy catches it: RPY104 (dynamic assignment without default).

label branch_demo:
    menu:
        "Take the sword":
            $ has_sword = True
        "Leave it":
            pass       # ← has_sword never set in this branch

    if has_sword:       # ← MAYBE_SET read
        "You swing!"

Symptom: Game works for players who take the sword. Players who leave it hit NameError: name 'has_sword' is not defined (or in rollback, the variable silently retains a previous playthrough's value).

Senpy catches it: RPY404 (reading MAYBE_SET variable) and RPY401 (branch asymmetry).

label add_item:
    $ inventory.add("sword")    # ← list has no .add() method

Symptom: AttributeError: 'list' object has no attribute 'add' the first time a player picks up an item. Tested paths miss it; untested paths crash.

Senpy catches it: RPY108 (incompatible collection method) with QuickFix suggesting .append().

# 200 image definitions, only 30 ever shown on screen
image bg_old_castle = "old_castle.png"   # ← left over from cut content
image bg_old_forest = "old_forest.png"   # ← unused

Symptom: Build size balloons. Players download 500MB instead of 200MB. Nobody notices until a Steam reviewer complains about download size.

Senpy catches it: RPY701 (unused define), RPY702 (unused transform), RPY703 (unused screen).

# game/script.rpy
$ player_name = "Hero"
"Welcome, [player_name]!"     # ← English source

# game/tl/russian/script.rpy
translate russian welcome_1:
    "Добро пожаловать, [player]!"   # ← typo: player instead of player_name

Symptom: Russian players see Добро пожаловать, [player]! literally (interpolation variable doesn't exist). English build works fine.

Senpy catches it: RPY601 (broken interpolation variable in translation).

Every bug above:

1. Slips past renpy lint (which only checks syntax + label targets).
2. Survives dev playtesting (devs always pick the "interesting" branch).
3. Surfaces only after release — via Steam reviews, Discord screenshots, or itch.io bug reports.
4. Costs hours of "works on my machine" debugging because the player can't reproduce it in front of you.

Senpy catches them at lint time — before they ship. That's why you need it.

For the full list of 45+ rules with examples, see RULES.md.

The standard built-in renpy lint command only checks for basic syntax errors and broken label targets. It is blind to deep runtime Python execution issues, rollback desynchronizations, and save-file corruptions. Consequently, critical NameError and KeyError crashes often slip into production builds and are only discovered after dozens of hours of manual playtesting.

Senpy provides comprehensive static semantic analysis without requiring the Ren'Py SDK runtime:

• Zero-Setup Standalone VSIX: Windows extension packages bundle a self-contained runtime — writers and narrative designers don't need Python, virtual environments, or pip installed.
• High Throughput & Disk Serialization: Analyzes 77,000+ lines in ~3.5s on cold start and 0.04s incrementally via two-tier .senpy_cache/ disk serialization.
• Save Game & Rollback Safety: Catches dangerous define mutations (RPY105), non-revertable types (RPY106), dynamic assignments missing default (RPY104), and type-taint conflicts (RPY108).
• Init Phase Dependency Graph: Analyzes alphabetical file loading order in init python: to prevent runtime NameError crashes on startup (RPY109).
• Arity & Signature Checking: Verifies parameter counts and keyword arguments on call label(...) (RPY310) and use screen(...) (RPY207).
• Branching Dataflow Analysis: Traces nested if/elif/else and menu: branches to ensure variables aren't evaluated in an uninitialized MAYBE_SET state (RPY401, RPY404).
• Screen & UI Action Inspector: Catches predictive state mutations (RPY201), imperative loops (RPY205), dead buttons (RPY203), function calls in actions (RPY206), and inspects string targets in screen Actions (SetVariable, ToggleVariable, Show, ShowMenu, Hide) for typos and missing declarations (RPY202, RPY204).
• ATL Transforms & Transitions: Validates custom and built-in positions/transforms in show ... at <transform> and transitions in with <transition>, catching runtime NameError typos with QuickFix suggestions (RPY502).
• Collection Method Guard: Detects incompatible method invocations on known types (list.add() → .append(), dict.append(), str.pop()) before runtime AttributeError crashes occur (RPY108).
• Translation Validator & Coverage: Audits game/tl/ formatting, catches broken interpolation variables (RPY601), and calculates localization completion metrics via senpy --coverage.
• Runtime Crash Inspector: Parses traceback.txt post-mortem crash logs, explaining failures in human-readable terms (senpy --traceback).
• Dead Code Detection: Finds unused define constants (RPY701), unused transform definitions (RPY702), and unused screen definitions (RPY703).

Ren'Py ships with a built-in lint command (renpy.exe lint), but it launches the entire Pygame runtime and only catches syntax-level issues. Senpy is a standalone static analyzer that runs without the Ren'Py SDK and catches a different class of bugs.

The two tools are complementary, not replacements. Senpy catches a class of bugs that built-in lint cannot see (semantic, save/rollback, translation, control-flow). Run both: built-in lint for SDK-level checks, Senpy for everything else.

vscode-language-renpy is the official Ren'Py extension for VS Code (152 ⭐, maintained by the Ren'Py team). It provides syntax highlighting and basic snippets. Senpy provides semantic analysis on top of that — it understands variables, control flow, screens, and translation files, not just text.

The two extensions are complementary and can be installed side-by-side. If you want both syntax highlighting (official) and semantic diagnostics (Senpy), install both.

Senpy includes a full Language Server Protocol implementation with 20+ handlers:

Senpy 0.6.0 introduces a plugin system — write your own lint rules as pip packages.

# 1. Create a plugin project (see example below)
cd examples/my_senpy_plugin
pip install -e .

# 2. Run Senpy — it discovers your plugin automatically
senpy /path/to/game
# First run: "Plugin 'my-senpy-plugin' wants to load. Trust and enable? [y/N]"

This rule (from examples/my_senpy_plugin/) flags dialogue lines that are not wrapped in _() for translation:

from senpy.api import Diagnostic
from senpy.plugins import Rule, RuleContext, RuleMeta, register_rule

PLUGIN_API_VERSION = "1.0"


@register_rule("RPY901")
class HardcodedDialogueRule(Rule):
    meta = RuleMeta(
        code="RPY901",
        docs="Detects dialogue lines without _() for translation",
        severity="WARNING",
        tags=["translations", "accessibility"],
    )

    def check(self, ctx: RuleContext) -> list[Diagnostic]:
        diags = []
        for line_no, raw in enumerate(ctx.lines, start=1):
            stripped = raw.lstrip(" \t")
            if not stripped or stripped[0] not in ('"', "'"):
                continue
            if stripped.startswith('_("') or stripped.startswith("_('"):
                continue  # already translated
            diags.append(
                Diagnostic(
                    file_path=ctx.file_path,
                    line_number=line_no,
                    line_content=raw.rstrip(),
                    code="RPY901",
                    message=f"Hardcoded dialogue without _() for translation",
                    severity="WARNING",
                )
            )
        return diags

Full guide: Plugin Development README

# Analyze a Ren'Py game directory
senpy "path/to/game"

# Automatically apply safe fixes (unclosed tags, smart quotes, tab indents)
senpy "path/to/game" --fix

# Show what was fixed (detailed report)
senpy "path/to/game" --fix --show-fixes

# Calculate translation completion metrics
senpy "path/to/game" --coverage

# Generate project documentation (GDD / Wiki)
senpy "path/to/game" --export-wiki "PROJECT_WIKI.md"

# Generate Python type stubs (.pyi) for Pylance / MyPy
senpy "path/to/game" --stubs

# Inspect a Ren'Py runtime crash log
senpy --traceback "path/to/traceback.txt"

# One-click GitHub Actions workflow generator
senpy --init-ci

# Generate 'senpy_defaults.rpy' for missing default variables
senpy "path/to/game" --defaults

# Export story flow as Mermaid.js diagram
senpy "path/to/game" --graph-file "story_graph.md"

# Generate HTML report with interactive story graph
senpy "path/to/game" --export-html "report.html"

# Output in SARIF, JSON, JUnit XML, or GitHub Actions format
senpy "path/to/game" --output-format sarif --output-file senpy.sarif
senpy "path/to/game" --output-format json
senpy "path/to/game" --output-format junit
senpy "path/to/game" --output-format github

# List all available rules
senpy --rules

# Enable tsundere mode
senpy "path/to/game" --tsundere

Senpy includes 45 specialized semantic rules across 8 categories:

Full descriptions, rationale, and examples: RULES.md

[tool.senpy]
decompile = true
max_errors = 50

ignore = [
    "RPY104",  # Dynamic assignments without default
    "RPY303",  # Unreferenced labels (dynamic routers)
]

[tool.senpy.severity]
RPY104 = "ERROR"   # Elevate to build-breaking
RPY308 = "INFO"    # Demote fallthrough to info

"Warning: {b}unclosed style"  # noqa
$ dynamic_var = 1             # noqa: RPY104

For bulk rule exclusions, create a .senpy-ignore file in the project root (next to senpy.toml). Each line is a rule code to suppress:

# .senpy-ignore — one rule code per line
RPY101  # typo in dialogue variable
RPY104
# RPY105  # commented out — rule will fire
RPY301

Lines starting with # are comments. Inline comments (after the rule code) are allowed. Codes are case-insensitive (normalized to uppercase).

senpy --init-ci  # generates .github/workflows/senpy.yml

Or manually create .github/workflows/senpy.yml:

name: Senpy Code Scanning
on:
  pull_request:
    branches: [ "main", "master" ]
jobs:
  lint:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install senpy-linter
      - run: senpy game/ --output-format sarif --output-file senpy.sarif
        continue-on-error: true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: senpy.sarif

Senpy ships a pre-commit hook that runs senpy --check on every commit. Add this to your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Xilleet/senpy
    rev: v0.7.5   # use the latest tag
    hooks:
      - id: senpy

The hook is non-mutating — it only reports issues, never auto-fixes them. This is deliberate: an auto-fixing hook combined with git's autocrlf on Windows creates an infinite loop (the formatter normalizes line endings, git converts them back, the formatter runs again). Run senpy --fix manually if you want auto-fixes.

When analyzing game distributions or mods without source code, Senpy detects standalone .rpyc files:

1. Copies .rpyc into an isolated OS temporary directory.
2. Prompts to download unrpyc automatically if not present.
3. Analyzes decompiled scripts entirely within the sandbox.
4. Cleans up — your project directory stays unmodified.

Senpy catches runtime crashes before you launch the game. Here are common errors and the Senpy rules that prevent them:

Tip: Run senpy path/to/game --fix to auto-fix the safe ones (RPY001, RPY002, RPY301), or use QuickFix (Ctrl+.) directly in VS Code.

Contributions, bug reports, and rule suggestions are welcome.

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/NewRule).
3. Commit your changes (git commit -m 'feat: add RPY901 check').
4. Ensure test suite passes (pytest).
5. Open a pull request.

Want to write a plugin instead of contributing to core? See the Plugin Development Guide.

Senpy is a passion project — I needed a semantic linter for my own Ren'Py visual novel, and none existed. So I built one.

How it's made: I read and review Python code fluently, but I don't enjoy typing boilerplate. So I let AI tools do the typing, while I do:

• Architecture (what rules to add, how the LSP server should work)
• Code review (every line — I catch bugs the AI misses)
• Testing on real Ren'Py projects
• Bug report triage and fixes
• Release management

The AI doesn't decide what to build, doesn't push code, doesn't choose features. I do. The AI is my fast typist.

If you're curious about this workflow, I'm happy to discuss in Discussions. If you find a bug, report it — I read every issue and fix what matters to users.

Also check out ScreenTale, another tool from me.

The name senpy is shared with several unrelated projects. If you landed here looking for one of those, here's a disambiguation:

This project (Xilleet/senpy) is the only one related to Ren'Py. The naming collision is unfortunate — if you came here from a search for sentiment analysis or sensitivity testing, please follow the corresponding link above.

Distributed under the MIT License. Free for commercial and non-commercial visual novel development.