play96

play96 is a Rust library and CLI for running *96 libretro fantasy-console cores in automated test harnesses. It can step cartridges frame by frame, control input, inspect framebuffer pixels, make assertions, capture PNG files, exercise save states, and compare deterministic frame logs.

Build and test

git submodule update --init --recursive
cargo test
cargo build --release

The build produces the play96-cli executable and Rust, C, and C++ compatible libraries. C headers are in include/.

Rust library

Add the repository dependency to a test harness or library:

[dev-dependencies]
play96 = { git = "https://codeberg.org/compu96/play96.git" }

For a packaged release, use play96 = "0.1" after publishing it to the configured Cargo registry.

use play96::{Button, Color, Session};

fn main() -> Result<(), play96::Error> {
    let mut game = Session::new("wasm96_libretro.dll", "cartridge.wasm")?;
    game.set_button(Button::A, true);
    game.run_frames(10)?;

    assert_eq!(game.framebuffer_width(), 320);
    game.assert_pixel(12, 20, Color::rgb(255, 0, 0))?;
    game.assert_pixel_xrgb(13, 20, 0x00ff00)?;
    assert_eq!(game.frame_hash(), 0x0123_4567_89ab_cdef);
    game.write_png("actual.png")?;
    Ok(())
}

pixel and pixel_xrgb return colors for custom assertions. Failed built-in assertions report the coordinate and both expected and actual colors.

Only one Session may execute at a time because libretro callbacks are global to the dynamically loaded core.

C++ wrapper

Link against the generated play96 library and include include/play96.hpp:

#include <play96.hpp>

int main() {
    play96::Session game("wasm96_libretro.dll", "cartridge.wasm");
    game.run_frames(10);
    game.assert_pixel(12, 20, {255, 0, 0});
    game.assert_pixel_xrgb(13, 20, 0x00ff00);
}

The wrapper throws std::runtime_error when loading, execution, or an assertion fails. include/play96.h provides the underlying exception-free C ABI for other languages.

CLI

play96-cli --core ../wasm96/zig-out/bin/wasm96_libretro.dll \
  --cart ../wasm96/templates/cartridge-c/cartridge.wasm \
  --frames 30 --shot-every 15 --macro "0-10:p1.a" \
  --netplay-log wasm96.netplay

Screenshots are written as PNG files. A recorded netplay log can be checked by running the same command with --netplay-check instead of --netplay-log.