Scripting Engine

Scripting Engine

Specification and API reference: docs/scripting.md. Decisions: ADR 0010 (the engine), ADR 0012 (the browser backend), ADR 0016 (host IPC). Crate: crates/rustynes-script.

RustyNES has an optional, sandboxed Lua 5.4 engine for tool-assisted speedruns, debugging, automation and homebrew development. Scripts can read and write emulator memory, inspect CPU and PPU state, register per-frame and per-access callbacks, draw an overlay, override input, and drive the TAStudio editor.

Backends

• Native (scripting feature): embeds Lua 5.4 through mlua, which needs a C toolchain. It is off in a default source build and included in the release binaries since v2.9.7. The script-ipc feature adds host-mediated IPC for automation.
• Browser (script-wasm feature, experimental): a pure-Rust piccolo VM. It is explicitly not at parity with the native engine; docs/scripting.md has the capability table.

The two backends are mutually exclusive features, which is one reason the workspace is never built with --all-features.

Safety and determinism

The sandbox exposes only the table, string, math and coroutine libraries, so a script cannot reach the filesystem, the process or the network, and a per-frame instruction budget stops runaway scripts. Writes to memory and input overrides are disabled during netplay, movie recording and playback, and RetroAchievements hardcore mode, so a script cannot perturb a session that has to stay deterministic. Reads and drawing are always allowed.