io.github.alex-jordan547/renforge

Advance one dialogue event from the currently active queue. Prefer `renforge_control(action="advance")` only when you intentionally need control-command consistency with other navigation actions.

Run static asset validation and return missing/orphaned image or audio references. Useful before build and before submitting translation/build changes.

Auto-play branches by stopping any current manual session and launching a fresh session for every replay. It writes incremental progress to `.renforge/autopilot.json` and may download/cache the required SDK. Best for broad checks; not deterministic and potentially expensive.

Persist the current frame under `.renforge/captures/` and return the output path plus hash. This writes disk and may overwrite an existing name.

Click a coordinate in screenshot or logical space. Use semantic click first (`renforge_click_element`) and fall back when text/id selectors are unavailable. Combine with coordinate space and frame/state guards.

Click a semantic UI element by text/id/screen (preferred). Falls back safely through fresh frame guards and returns focus hints when another element captures the hit test. Use `renforge_click_at` only as coordinate fallback.

Return the same full payload as `renforge_info`, including active project discovery, dashboard/runtime hints, and RenForge version. This is an alias, not a reduced view.

Run a runtime control action (`advance`, `rollback`, `toggle_skip`, `toggle_auto`, `toggle_afm`, `game_menu`, `hide_windows`, `quick_save`, `quick_load`, `reload_script`, `restart_interaction`, `quit`). Use `quick_load` with care: it replaces live state. `quit` stops the active game session. `renforge_advance` is a narrower alternative for pure advance actions. Destructive actions require `authorize=true` when `RENFORGE_POLICY=enforce`.

Diff two PNG frames and return whether pixels changed plus the minimal changed rectangle. Use for regression checks between pre/post actions.

Build desktop distribution packages and write them to destination. This executes packaging toolchains and may download and cache the SDK; it can be slow or destructive when output paths are reused.

Estimate geometric translation between two images for visual text alignment workflows. This is file-only and read-only.

Evaluate an arbitrary Python expression in the running store namespace. This may call project functions and mutate runtime state or access the filesystem, start processes, and use the network with the game process's permissions. Prefer `renforge_get_var` for plain reads and use this only for controlled diagnostics. Pass `authorize=true` when `RENFORGE_POLICY=enforce`, unless this operation is allowlisted.

Export dialogue for translators or external tooling. This may download and cache the SDK, then writes and overwrites `dialogue.txt` at the project root.

Find a template image on the current frame and return matches with bounds in screenshot coordinates. Use this to close the control loop after screenshot capture and click fallback.

Find symbol definitions and references across scripts and templates with the same pagination controls as scan. Useful before editing or renaming project identifiers.

Read full live state for debugging and monitoring. Use this before/after interactions to verify state deltas without changing variables directly. Request optional sections such as `metrics` and `audio`.

Read bounded live state with explicit variable limits and payload caps for large sessions. Use this in loops and scripts to keep responses predictable.

Generate or update translation files under `game/tl/<language>/`. This may download and cache the SDK before writing output. It writes files, so treat it as destructive when run against production trees and prefer checking stats first.

Read placement bounds for a rendered displayable tag by tag name. Use this to diagnose layout changes or anchor calculations before moving elements.

Read a single Ren'Py documentation topic. For discovery, run `renforge_search_docs` and `renforge_list_docs` first to avoid guessing IDs. This may download and cache the SDK before resolving doc content.

Read recent runtime and bridge errors. Run this after risky actions or after a stop to confirm the game did not crash with hidden diagnostics.

Resolve semantic element bounds without clicking. Use this after list output to verify target geometry before any pointer action.

Read one named variable from the live store. JSON-safe values are returned as-is; other objects are replaced by a type label without calling conversion hooks such as `__repr__`. Resolving the name can still run a store property getter. Prefer this over `renforge_eval` when you only need a named lookup.

Inspect which interactive nodes sit under a coordinate. Use this when click targets look stale or overlays may absorb events, and prefer semantic selectors once ambiguity is resolved.

Move cursor over a semantic control by text/id/screen. Prefer this before click when checking hover states or tooltips.

Call this first. It returns the active project target (dashboard, "serve_default" or cwd), plus local runtime hints and RenForge version. Use this to determine the project path you should pass to project-scoped tools.

Inspect a local image file and optionally crop/zoom it before returning PNG bytes. Use this for artifact review without launching the game.

Read-only static analysis of a Ren'Py project: scan metadata and file structure without starting the game engine. Use this for safe project triage before runtime actions.

Inspect a named active screen, including layer, scope and arguments. Useful for branch verification before choosing click or hover selectors.

Restart into a specific label/file position and keep interacting in a fresh game session. If needed, this may download and cache the required SDK before restart. Use for deterministic positioning before scripted checks.

List translation languages currently present under `game/tl/`. Use this before generating or exporting localized files.

Start or attach a running game session with Live Editor enabled by default (pass editor=false for non-editor runtime launch). Launch starts the background startup flow, usually returning while startup is still in progress; poll `renforge_launch_status` and capture with `renforge_screenshot` before interaction. It may download/cache the selected SDK, inject session-owned `.rpy` files and editor assets under `game/`, and publish authenticated ownership/bridge metadata under `.renforge/control/`. `renforge_stop` removes only owned session artifacts.

Poll launch progress and return `idle`, `starting`, `ready`, `failed`, `closing`, or `closed`. Use after any launch start when the first call has not returned an immediate ready state.

List on-screen menu choices with index and text ordering. Call before `renforge_select_choice` to pick valid entries for the current menu state.

List available Ren'Py documentation topics. Use this as the discovery step before any topic-specific docs read. This may download and cache the SDK if docs are not already available.

List focusable UI elements with bounds and element metadata. Use this first for semantic interaction planning; it is narrower than a full scene readout and aligned to click/hover workflows.

Measure geometry between scene nodes without visual inspection. `contrast` samples the live frame and reports a WCAG ratio. Use this to detect layout drift after positional edits.

Restart at `start` and begin a new story progression. This may download and cache the required SDK before the fresh launch. Prefer this for clean scenario entry rather than reusing unstable runtime state.

Parse existing Ren'Py lint output text and return normalized diagnostics. This does not run Ren'Py, does not execute code, and does not touch the runtime.

Read queued runtime events since a stream index. Use this for deterministic event-driven debugging instead of polling live UI repeatedly.

Reposition a shown image tag live and return new logical bounds. This mutates runtime placement only; after converging with scene/measure tools, write the final values into the `.rpy` source.

Run a scripted scenario pipeline of multiple interaction steps in one call and return grouped diagnostics. `eval`, `assert`, and expression-based `wait` steps execute arbitrary Python that may mutate state, access the filesystem, start processes, or use the network. Validate expectations and review capture output on failure. Destructive or open-world steps require `authorize=true` when `RENFORGE_POLICY=enforce`.

List, load, or save named slots in a single command family. `list` is read-only; `load` replaces live state and `save` can overwrite the chosen slot. Verify slot names before mutating gameplay progress. `load` requires `authorize=true` when `RENFORGE_POLICY=enforce`.

Search project scripts with bounded output. Use `sections`, `file_glob`, and `symbol` for focused indexing, then paginate with `offset` and `limit` for stable batches.

Read the full scene graph (logical scene data). Unlike `renforge_list_ui_elements` this is broad and includes non-focusable nodes, so use it for full-tree inspection when semantic selectors are ambiguous. `save_as` or `diff_against` may create `.renforge/scenes/`; `save_as` writes and overwrites the named JSON snapshot. Omit both options for read-only inspection.

Capture the current live frame and return an in-memory image response (no persistent file write). Use this to inspect UI state before clicks or scenario actions.

Search local Ren'Py documentation snippets by keyword before opening results. Use this to identify canonical topic IDs before `renforge_get_doc`. This may download and cache the SDK when docs are not already available.

Select a menu choice by case-insensitive text or zero-based index. Text matching prefers an exact match, then uses the shortest case-insensitive substring match. Use list output first to avoid ambiguous partial text.

Send exactly one input command path (text, key, or scroll object) into the live game. Keep calls scoped and single-purpose; for deterministic workflows prefer one action per invocation.

Write a game variable directly in the live store namespace. This mutates state immediately and should be used after validating the current state snapshot.