Rhai scripting

Bizmuth embeds a Rhai scripting layer that reacts to hardware activity and reads live machine state. A single script replaces the ad-hoc bash + adp.py loops you’d otherwise write, and it runs both windowed and fully headless (alongside --screenshot).

The model is simple: you define on_* handler functions; Bizmuth calls them when the matching hardware event fires. Inside a handler you read live state through host functions, log() diagnostics, and return ADP command line(s) for the debugger to run. The scripting surface is the ADP command surface — anything you can type at the ADP prompt, a handler can return.

Loading & running

Scripts run with a 5,000,000-operation cap per handler call, so a runaway loop can’t wedge the emulator. The script scope persists across calls — top-level let globals (counters, flags, accumulators) survive from one event to the next.

// The scope is shared across handler calls, so globals keep state.
let hits = 0;
fn on_frame(n) {
    hits += 1;
    if n == 1000 { return "savestate /tmp/f1000.azst"; }   // return an ADP command
}

Return values

A handler may return:

• () — nothing (the common case: read state, log, done);
• a single command string — e.g. "state", "continue", "enter";
• an array of command strings — run in order, e.g. ["state", "bt"].

fn on_breakpoint(id, pc) { return ["state", "bt"]; }   // dump CPU + backtrace on every hit
fn on_menu_idle(pc)      { return "enter"; }           // launch the highlighted browser entry

Events

Every handler is optional — define only the ones you need. All events fire at an instruction boundary (never mid-instruction) with live, coherent state, except on_frame / on_menu_idle, which fire once per frame.

// Watch who remaps the $C000 slots (6/7) and which interrupt source fires each frame:
fn on_paging(d)    { if d.slot >= 6 { log(`slot ${d.slot} = bank ${d.bank} (src ${d.source}) @pc ${d.pc}`); } }
fn on_interrupt(d) { log(`INT src ${d.source} vec ${d.vector} @line ${d.line}`); }

The d state-map argument

The richer events (on_dma_*, on_interrupt, on_reti, on_paging, on_rst, on_divmmc) pass a single state-map d whose fields carry the specifics of that event. Read them as d.field.

on_dma_xfer_start(d) / on_dma_xfer_end(d)

on_interrupt(d) · on_reti(d) · on_paging(d)

on_rst(vector, d) · on_divmmc(d) — the RST targets are the DivMMC automap entry points, so these pair up to make the esxDOS interrupt-hook / automap timing legible.

// Trace the esxDOS interrupt hook: each RST 38 + every DivMMC overlay change.
fn on_rst(vector, d) { if vector == 0x38 { log(`RST 38 @pc ${d.pc} dm=${d.dm_active}`); } }
fn on_divmmc(d)      { log(`DivMMC automap=${d.automap} conmem=${d.conmem} bank=${d.bank} @pc ${d.pc} line ${d.line}`); }

Host functions

Handlers read live machine state through host functions (backed by a thread-scoped debug context installed only for the handler’s duration) and emit diagnostics with log. Reading outside an event (e.g. script eval reg("ix")) returns -1 — no context is installed there yet.

breakpoint() works in the headless --script path too — the run loop resumes the frame after firing. Each hit runs the handler, so very hot addresses (a tight inner-loop PC) are slow; pick an address hit a bounded number of times.

fn on_breakpoint(id, pc) {
    if reg("i") != 0xBD { return "continue"; }     // skip the look-alike $0000 pass-throughs
    log(`crash: sp=${reg("sp")} ix=${reg("ix")} bdbd=${mem(0xBDBD)} @frame ${frame()}`);
    return ["continue", "enter"];                  // capture + relaunch
}

watch_mem + on_mem_write

on_mem_write only fires for addresses you’ve armed. Call watch_mem(lo, hi) once at top level (it runs when the script loads), then define the handler:

watch_mem(0x5B00, 0x5BFF);                 // arm the system-variables page
fn on_mem_write(addr, val, pc) {
    log(`write ${val} -> ${addr} by pc ${pc}`);
}

See scripts/watch-mem.rhai and scripts/determinism.rhai for complete, runnable examples that replace the old bash + adp.py loops.

get_machine_state() — one lazy handle for the whole state surface

When a handler needs a field the event args don’t carry (and the piecemeal functions above feel scattered), get_machine_state() returns a lazy MachineState handle grouping the whole surface under one object. Every field reads live on access — so it’s cheap (.pc reads one register; s.nr[0xC0] reads exactly one nextreg, not all 256) and coherent (the machine is paused for the handler’s duration).

fn on_breakpoint(id, pc) {
    let s = get_machine_state();
    log(`pc=${s.pc} sp=${s.sp} iff1=${s.iff1} im=${s.im} halt=${s.halt}`);
    log(`port_ff=${s.port_ff} C0=${s.nr[0xC0]} slot5=${s.slots[5]}`);
    let saved_sp = s.sp;          // store the SCALAR to compare at a later breakpoint
}

The handle is only valid inside the handler that created it — it reads live through the paused context. Don’t stash s in a global to read at a later event (you’d get the new event’s state); store the queried scalar values instead.

See also

• The ADP debugger — the command surface handlers return into.
• Conditional breakpoints — for a single stateful compare without a full script (bp add pc <addr> if <cond>).
• Headless & automation — running --script with no window.