Home › Ren’Py (visual novels) › Ren’Py visual novel AGENTS.md

Ren’Py visual novel AGENTS.md

AGENTS.md for Ren’Py visual novels: script layout, define vs default for save-safe state, labels and flow, screen language, Lint, and translation-ready text.

AGENTS.mdRen’Py (visual novels)

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Ren’Py visual novel

## Commands
- Lint after every change: run "Check Script (Lint)" from the launcher, or `renpy.sh <project-dir> lint` (`renpy.exe` on Windows) using the SDK path the README gives.
- Launch for manual testing: `renpy.sh <project-dir>`. Say when you couldn't launch the game here.
- Don't upgrade the Ren'Py SDK version as part of another change.

## Script layout
- `game/script.rpy` holds `label start`; story chapters in `game/story/<chapter>.rpy`, characters in `game/characters.rpy`, screens in `game/screens.rpy`, settings in `game/options.rpy`.
- Labels are unique, snake_case and namespaced by chapter (`ch2_market`). Flow with `jump` for scene changes and `call`/`return` for reusable scenes.

## State
- `define` for constants that never change after init (characters, config). `default` for anything that changes during play (flags, affection, inventory) so it is saved, rolled back and initialized in old saves.
- Never create story variables with plain `$ x = ...` before declaring them with `default`.
- Keep Python in `init python:` blocks or `.rpy` helper modules; story files stay readable dialogue.
- Changing or removing a label or `default` that existing saves rely on needs a migration plan (`after_load` label) noted in the PR.

## Presentation
- Declare images by filename convention under `game/images/` (lowercase, space-separated tags) or explicit `image` statements; use `show`/`scene`/`hide` with transitions (`with dissolve`) consistently.
- Screens use screen language with styles from `gui.rpy`; no hardcoded pixel sizes when gui variables exist. Buttons have hover/focus states and work with keyboard and controller.
- Audio through `play music`/`play sound` with channels defined once; respect mixer volumes.

## Text
Dialogue is plain strings Ren'Py can extract for translation (`renpy.sh <project> translate <language>`); no string building that hides text from the translator. Add self-voicing friendly `alt` text for images that carry meaning.