ROM control

Observe-and-decorate is the common case, but a script can also control the host game and its own connection. All of these are client-side.

pause_rom / resume_rom

pause_rom()
resume_rom()

pause_rom() halts the emulator's CPU — game state stops advancing and read_* observes frozen RAM. Your script keeps running: event frame keeps firing, networking keeps flowing, timers keep ticking, so your overlay UI (lobby, pause menu, debug HUD) can update on top of the frozen picture. The framebuffer is preserved at the pause moment, so each overlay frame composites onto the still game image.

resume_rom() continues execution from where it halted. It's a no-op if the ROM is already running.

if menu_open { pause_rom() } else { resume_rom() }

This is the foundation of any modal UI — see the pause-menu pattern in Input & pausing the ROM.

v1 surface

Pause/resume is the v1 control surface. Broader control — soft-reset, frame-stepping, save-state hooks, input injection — will be added as specific mods need it.

local_rom_hash

local_rom_hash(): string

Returns the lowercase hex SHA-1 of the loaded ROM file. The script has no other way to identify the cartridge (read_* sees mapped CPU memory, not the ROM file). What a hash means ("this is Super Mario Bros.") is a per-script convention — keep your own hash→label table, refuse to run on an unexpected ROM, or ignore the hash entirely. An empty string means the harness supplied no ROM (e.g. a headless test run).

if local_rom_hash() == "ea343f4e445a9050d4b4fbac2c77d0693b1d0922" {
    // it's the ROM we built this mod for
}

disconnect

disconnect()

Self-unload: closes the WebSocket, stops the frame loop, and tears down the script. After it runs, no further events fire and no socket activity happens — the script is fully offline, though the underlying ROM keeps running on its emulator host. Used to drop from a networked session into pure local play (e.g. leaving a lobby).

The script gets no chance to act after disconnect(), so do any cleanup first — for instance resume_rom() to lift a pause before unloading.