Scripting Engine

Scripting Engine

References: docs/scripting.md

RustyNES incorporates an optional, sandboxed Lua 5.4 scripting engine designed for Tool-Assisted Speedruns (TAS), debugging, and homebrew development.

Capabilities

The scripting engine allows Lua scripts to interact with the emulator dynamically:

• Memory Access: Read and write CPU RAM, PPU VRAM, and OAM.
• CPU State: Inspect CPU registers (A, X, Y, PC, SP, Status) and the cycle count.
• Event Hooks: Register callbacks for onNmi, onIrq, onFrame, and memory access breakpoints.
• Input Manipulation: Override gamepad inputs natively using setInput().
• UI Drawing: Draw primitive shapes, text, and overlays directly on top of the emulator screen.

Implementation Details

The reference engine (rustynes-script) uses mlua to embed a standard Lua 5.4 interpreter.

Because mlua depends on a C toolchain, scripting is off by default. It can be enabled by building with the scripting feature:

cargo run --release -p rustynes-frontend --features scripting -- path/to/rom.nes

An experimental pure-Rust WebAssembly backend (using the piccolo crate) is also available, ensuring that lightweight embedded environments can still execute basic scripts.

Determinism

Script execution is synchronous and happens exactly at the boundaries requested (e.g., at the end of run_frame or during a specific CPU instruction). This ensures that scripts that manipulate memory or input do so deterministically, maintaining perfect compatibility with the TAS movie format (.rnm).