renpy-language-server
Language server and formatter for Ren'Py scripts, built with pygls and managed with uv. Part of renpy-zed (Ren'Py support for Zed), but it speaks standard LSP and works with any client.
Requires Python 3.10 or newer.
Unofficial project, not affiliated with Ren'Py.
Features
textDocument/formattingandtextDocument/rangeFormatting, returned as minimal line edits (the cursor does not jump)textDocument/completionfor statements, labels, images (including automatic images fromgame/images), screens, characters, transforms, transitions, audio channels/assets and the bundled Ren'Py API namespaces. Screen bodies complete elements, properties and property values, dialogue completes image attributes, and$/ conditions / declarations complete Python keywords and built-instextDocument/documentSymbolfor labels, screens, transforms, images, characters, styles, layered images,define/defaultvariables, and for Python classes, functions, methods, properties, fields, stores, persistent variables, test cases and translations. Class and store members are nested in the outlinetextDocument/definitionfor labels, screens, transforms, images, layered images, characters, styles and variables, including local labels (.local) resolved against the most recent global label and images aftershow/scene/hide(declared images or automatic image files)- Definition also follows Python member access where it is unambiguous:
self.field,Class.member,persistent.value,store.valueand class base names textDocument/hoverfor labels, screens, transforms, images, characters and other declarations, for references such asjump,show,useandat, for automatic images fromgame/images, and for the bundled Ren'Py API (signature, documentation and source location)- Hover includes comment-block documentation above a declaration and works for references across files
textDocument/prepareRenameandtextDocument/renamefor labels (global, dotted and local), screens, transforms, images, layered images, characters, styles anddefine/defaultvariables, across every indexed file. Class/function/member rename is deliberately deferredtextDocument/documentHighlightfor the symbol under the cursor, so Zed shades declarations and references while editing and renamingtextDocument/referencesfor the same families as rename, across every indexed file, withincludeDeclarationrespectedworkspace/symbolfor workspace-wide symbol search across labels, screens, images, characters, styles, variables, classes, members, stores, persistent variables, test cases and translationstextDocument/signatureHelpfor bundled Ren'Py API calls, labels, screens, user classes/functions andself./Class.methodstextDocument/codeActionquick fixes for comparison typos, stray$, leading tabs and unknown labelstextDocument/semanticTokens/full(opt-in) for declarations, references, built-ins, obsolete APIs, keywords, parameters and literals- Completion of class members after
Class.andself., persistent fields afterpersistent., variables afterstore., and API names afterrenpy.,renpy.music.,renpy.audio.,config.andgui. - Callable built-ins insert their parentheses (
Character()), and completion is available from spaces,.,(,@and- - Completion documentation is sent as Markdown, so signature fences and inline code render as code blocks in the editor
- configurable diagnostics for indentation, tabs, filenames, variable names,
comparisons, stray
$, obsolete APIs, unknown labels and images, undefined screens, persistent/store variables and duplicate labels, with per-rule severity and open-file or workspace modes (see Settings) textDocument/foldingRangefor labels, menus, menu choices, screens, transforms and other indented blocksrenpy-language-server dap, a launch-only Debug Adapter Protocol server that starts a project through an installed Ren'Py SDK, supportswarp, streams output and terminates the game. Breakpoints, stepping, variables and attach are not implemented yetrenpy-language-server formatcommand for scripts and CI (--check,--diff)- Safe formatting by default: whitespace, quote delimiters and numeric duration literals only; string values and non-duration numbers are never touched
- Inline spacing for Python-ish statements (
$ points=1becomes$ points = 1) and insidepython:blocks - Single-quoted strings become double-quoted unless the value contains an
unescaped
"(--no-quotes/normalize_quotes: falsedisables it) - Duration arguments in
pause, ATL, screentimer, audio fades and testcases get one spelling (pause 1becomespause 1.0, orpause (1.0)with the parenthesised style) - Optional Ruff formatting for
python:block bodies
Install
uv tool install renpy-language-server
uv tool install "renpy-language-server[python-format]" # with optional Ruff formatting
# for development, from a clone:
uv tool install --editable .
uv tool install --editable ".[python-format]"
Use
renpy-language-server format game/ # format every .rpy under game/ in place
renpy-language-server format --check game/ # exit 1 if anything would change (CI)
renpy-language-server format --diff script.rpy
renpy-language-server format --python game/ # also format python: blocks with Ruff
renpy-language-server format --numeric-style parens game/
renpy-language-server format --no-numeric game/ # keep numeric durations as written
cat script.rpy | renpy-language-server format -
renpy-language-server # start the language server on stdio
renpy-language-server dap # start the launch-only debug adapter on stdio
To enforce formatting on every pull request, see Format-check Ren'Py scripts in GitHub Actions.
Debug adapter
renpy-language-server dap speaks DAP over stdin/stdout. It is normally launched by the
renpy-zed Zed extension, but any DAP client can start it. A launch
configuration accepts:
| Field | Default | Meaning |
|---|---|---|
request |
launch | Only launch is accepted |
sdk |
auto | SDK directory or a launcher inside it |
project |
auto | Directory containing game/; inferred from warp or the cwd |
warp |
none | file:line, made project-relative when possible |
command |
run |
Ren'Py CLI command (run, lint, compile, ...) |
args |
[] |
Extra arguments appended to the Ren'Py command line |
env |
{} |
Extra environment variables for the game process |
The SDK is resolved from sdk, then RENPY_SDK, then renpy-*-sdk
directories in the home directory, Documents, Downloads, Desktop,
Applications and /Applications, newest version first. RENPY_SDK may name
the SDK directory or a launcher inside it.
terminate and disconnect stop the game, escalating to a forced kill after
three seconds. setBreakpoints reports the requested lines as unverified and
stepping, pause and evaluate return a clear "launch-only" error. attach is
rejected.
In Zed
Until the renpy-zed extension is published, point Zed at the binary
(which renpy-language-server) in settings.json:
{
"lsp": {
"renpy-language-server": {
"binary": { "path": "/home/you/.local/bin/renpy-language-server" }
}
}
}
The language itself (.rpy files) must be registered by the extension first.
Zed uses LSP folding ranges only when its document_folding_ranges setting is
enabled. Without it, Zed falls back to indentation-based folding, which can
attach a menu choice's fold to the next choice:
{
"languages": {
"Ren'Py": { "document_folding_ranges": "on" }
}
}
Settings
The server accepts settings from the language client's initializationOptions
(under renpyLanguageServer, or flat) and from
workspace/didChangeConfiguration:
{
"renpyLanguageServer": {
"indent": 4,
"max_blank_lines": 2,
"align_equals": true,
"normalize_spacing": true,
"normalize_quotes": true,
"normalize_numeric_args": true,
"numeric_style": "bare",
"numeric_floats": true,
"numeric_families": ["pause", "atl", "timer", "audio", "testcase"],
"numeric_warpers": [],
"format_python": false,
"diagnostics": true,
"code_actions": true,
"unknown_label_diagnostics": true,
"diagnostics_mode": "open",
"diagnostic_rules": {
"indentation": "warning",
"tabs": "warning",
"unknown_label": "warning"
},
"completion": true,
"automatic_assets": true,
"semantic_tokens": false,
"workspace_symbols": true,
"hover": true,
"rename": true,
"references": true,
"highlight": true,
"signature": true,
"extended_index": true,
"member_references": true
}
}
| Setting | Default | Meaning |
|---|---|---|
indent |
4 |
Fallback spaces per indentation level |
max_blank_lines |
2 |
Maximum consecutive blank lines |
align_equals |
true |
Align consecutive assignment = |
normalize_spacing |
true |
Inline operator spacing |
normalize_quotes |
true |
Rewrite single-quoted strings to double quotes |
normalize_numeric_args |
true |
Normalize numeric duration arguments |
numeric_style |
"bare" |
"bare" (pause 1.0) or "parens" (pause (1.0)) |
numeric_floats |
true |
Add .0 to integer duration literals |
numeric_families |
all | Duration families: pause, atl, timer, audio, testcase |
numeric_warpers |
[] |
Extra ATL warper names, in addition to the built-ins |
format_python |
false |
Format python: bodies with Ruff |
diagnostics |
true |
Enable all diagnostics |
code_actions |
true |
Enable diagnostic quick fixes |
unknown_label_diagnostics |
true |
Legacy switch for the unknown-label rule |
diagnostics_mode |
"open" |
Check open files (open) or the workspace |
diagnostic_rules |
see below | Per-rule error, warning or off |
completion |
true |
Enable completion |
automatic_assets |
true |
Offer images/audio found on disk in completion |
semantic_tokens |
false |
Enable semantic tokens (opt-in) |
workspace_symbols |
true |
Enable workspace/symbol search |
hover |
true |
Enable hover information |
rename |
true |
Enable prepare-rename and rename |
references |
true |
Enable find-references |
highlight |
true |
Enable occurrence highlights |
signature |
true |
Enable signature help |
extended_index |
true |
Index Python classes, stores and related declaration families |
member_references |
true |
Index self.x / Class.x / persistent.x / store.x |
diagnostic_rules accepts these keys: indentation, tabs, filename,
invalid_variable, reserved_names, comparison, stray_dollar,
obsolete_api, undefined_persistent, undefined_store, duplicate_label,
unknown_label, unknown_image and undefined_screen. The two pre-existing
rules (indentation, unknown_label) and tabs default to warning; all
newer rules default to off until they have been validated on real projects.
Set a rule to error for stricter projects, or to off to silence it. The
legacy unknown_label_diagnostics flag still maps to the unknown_label rule.
Semantic tokens are disabled by default because Zed already highlights Ren'Py
through tree-sitter and the two layers should be validated together. Set
semantic_tokens to true to let the server add declaration, reference,
built-in and obsolete-API tokens; the capability and legend are always
advertised, and the provider returns an empty stream while disabled.
Diagnostics have the source renpy-language-server and a stable code such as
renpy-language-server.unknown-image. In workspace mode the server publishes diagnostics
for every indexed file on startup and after configuration, save and watched-file
events; normal typing only rechecks the current document.
Rename follows the indexed references: jump / call, screen statements,
show / scene / hide, at, dialogue speakers and style parents. Variables
are renamed in code, dialogue interpolation ("[var]"), and across files,
including declarations with an init priority (define -1 foo = ...) and the
+= / |= operators.
Rename protects Ren'Py syntax: statement and screen-language keywords, audio
channel names, with / as / onlayer / behind clauses, dialogue
attributes, screen-local default variables and ordinary strings. Dynamic
targets such as jump expression, automatic image files and arbitrary
attribute access are not renamed. Store-qualified declarations such as
define config.name, variable names passed as strings (for example
SetVariable("points", ...)), and local names that shadow a store variable
inside Python functions are not handled. If several declarations share a name,
all of them are renamed together.
Classes, functions, methods, fields, properties, stores, persistent variables, test cases and translations are indexed for navigation and completion, but class/function/member rename is intentionally deferred to a later release.
Occurrence highlights use Zed's editor.document_highlight.write_background
for declarations and editor.document_highlight.read_background for
references. Adjust those keys in the theme overrides if the shade is too
subtle.
Hover documentation for Ren'Py built-ins comes from the MIT-licensed
vscode-language-renpy data; see NOTICE.md.
Logs
The server writes logs to stderr, never stdout. Normal runs print only a startup line; pygls protocol logs, which include full document contents, are disabled by default. To inspect the JSON-RPC traffic, launch Zed with:
RENPY_LANGUAGE_SERVER_DEBUG=1 zed .
Formatting rules
| Rule | Detail |
|---|---|
| Indentation | tabSize from the editor (default 4) spaces per level; tabs are expanded |
| Trailing whitespace | removed |
| Assignments | the = of consecutive assignment lines at the same indentation level is aligned into one column |
| Inline spacing | assignment and comparison operators in $, define, default, if, elif, while, return and assert lines |
| Keyword arguments | spaces around = are removed (color = "#fff" becomes color="#fff"); real assignments keep them |
| Quotes | single-quoted strings become double-quoted unless the value contains an unescaped "; comments and values are untouched |
| Numeric durations | pause 1 becomes pause 1.0 (or pause (1.0)); applies to pause, ATL warpers/time/delay/number statements, screen timer, audio fadein/fadeout and testcase pause/timeout |
| Python blocks | assignment, comparison, arithmetic and bitwise operators inside python: blocks |
| Ruff (opt-in) | --python formats python: bodies with Ruff, changing more than the default rules |
| Blank lines | runs capped at 2; none at the start of the file |
| Block spacing | a blank line before top-level label, screen, init, transform; a comment block directly above stays attached |
| End of file | exactly one newline |
| Line endings | LF or CRLF is kept as found |
| Comments | re-indented to the block they sit in; a comment right after label x: joins the body |
String contents are never edited: a single-quoted literal is only rewritten to
double quotes when it contains no unescaped ", and quoted text in comments is
skipped. Indentation and alignment rules never touch dialogue, screen
properties, ATL property values or ATL interpolation lines; continuation lines
of open brackets or backslashes are shifted together with their first line,
keeping their relative alignment. Numeric normalization only rewrites a
duration when the whole argument is a pure number (optionally wrapped in
parentheses); counts, coordinates, sizes, volumes, ATL property values and
complex expressions are left alone. Keyword and default-parameter = inside
brackets is the only operator the spacing pass tightens; top-level assignment
= still gets spaces.
Known assumptions and limits
- A string opened with a single
"or'that is still open at the end of a line is assumed to continue on the next line. A stray, unbalanced quote outside a string or comment can therefore make the rest of the file look like string content; the formatter leaves that part alone instead of guessing. - Inline spacing outside
python:blocks is limited to assignment and comparison operators. Arithmetic spacing is applied insidepython:blocks, but not to every Ren'Py expression. Use--no-spacingto disable the pass. - Quote normalization is on by default. Use
--no-quotesornormalize_quotes: falseto keep single quotes. Literals containing an unescaped"and unterminated literals are left unchanged. Range formatting converts a multi-line literal only when both delimiters are in the selected lines, so it is never left half-converted. - Numeric duration normalization is on by default. Use
--no-numericornormalize_numeric_args: falseto disable it. Only pure numeric literals are rewritten;pause delay,1 + 2,max(1, 2)and other expressions keep their spelling. Custom ATL warpers can be listed innumeric_warpers; they are added to the built-in warper names. - Diagnostics are intentionally conservative. Newer rules are opt-in, and each rule can be reduced to a warning or disabled independently.
- Ruff formatting changes more than whitespace, so it is opt-in and failure-safe.
Development
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run pyright
scanner.py: tracks strings, comments and brackets across physical linesanalysis.py: logical lines and the block treeindex.py: workspace symbol index for Ren'Py declarations, references and related declaration familiespython_index.py: conservative indentation parser forpython:blocksresolve.py: shared target and occurrence resolutionreferences.py: find-references providersignature.py: signature-help providercompletion.py: context-aware completion for statements, screen bodies, API namespaces, audio, dialogue attributes and Python expressionscompletion_data.pyanddata/completion.json: versioned screen, ATL and keyword/value vocabularystrings.py: physical-line string spans shared by semantic tokenssemantic.py: opt-in semantic tokens and UTF-16 delta encodingdefinition.py: literaljump/calltarget resolutiondiagnostics.py: configurable per-rule diagnostics and workspace publishingcode_actions.py: safe quick fixes for diagnosticssymbols.py: LSP document and workspace symbolspositions.py: client-position conversion helpersfolding.py: explicit block fold rangesspacing.py: inline operator spacingnumeric_args.py: numeric duration argument normalizationpython_format.py: optional Ruff bridgeformatter.py: indentation, blank lines, commentsedits.py: old text to minimal LSP editsserver.py: pygls glue (stdout carries the protocol, so log to stderr only)dap.py: launch-only Debug Adapter Protocol server, SDK/project discovery, output streaming and process terminationtests/test_formatter_renpy.py: formatter cases, idempotency and "only whitespace changed" checkstests/test_pipeline.py: scanner, edits and CLI teststests/test_server_e2e.py: starts the real server and formats over stdiotests/test_dap.py: launch configuration, SDK discovery and a fixture-SDK DAP session over stdio
CI runs the test suite on Python 3.10 through 3.14.
Checked against real scripts
Run on six files from the renpy/renpy repository (the_question, tutorial,
launcher; about 4,000 lines): in every file only whitespace changed and a
second pass changed nothing. Four were already formatted and came out unchanged.
License
MIT. See LICENSE.
Metadata
Release files for renpy-language-server 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| renpy_language_server-0.2.2.tar.gz | 257.5 kB | With provenance | Details for renpy_language_server-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| renpy_language_server-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for renpy_language_server-0.2.2-py3-none-any.whl |
Total release size: 524.4 kB
Release files / renpy_language_server-0.2.2.tar.gz
| Download URL | renpy_language_server-0.2.2.tar.gz |
|---|---|
| Size | 257.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee0ffc2d08bc13c18da1a282b9842859c85c595289423bbc34f36f80abe96434
|
|
BLAKE2b-256 checksum How to use checksums |
ecfb821ec086ccf9ae9628a19df78b6286796c7c41e85353bb4664afa506f09c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / renpy_language_server-0.2.2-py3-none-any.whl
| Download URL | renpy_language_server-0.2.2-py3-none-any.whl |
|---|---|
| Size | 266.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f389beef3cae08ef8c99ff1dcb7d9aaa1f1add43451186d96044b8aa6ab5bd4d
|
|
BLAKE2b-256 checksum How to use checksums |
a7a4bf7a460d7490c4f137d84dcfeef2921ce7ee526b16a9897782f6515e53ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for renpy-language-server 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for renpy_language_server-0.2.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.