play96 0.2.0

Programmable libretro harness for *96 fantasy-console cores
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# 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

```sh
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:

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

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

```rust,no_run
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);

    // Audio is interleaved signed 16-bit stereo PCM from the latest frame.
    assert_eq!(game.audio_sample_rate(), 48_000.0);
    game.assert_audio_sample(100, 0, 1200, 10)?;
    game.assert_audio_hash(0xfedc_ba98_7654_3210)?;
    let left_sample = game.audio_frame(100)?[0];
    assert_eq!(left_sample, game.audio_samples()[200]);
    game.write_png("actual.png")?;
    Ok(())
}
```

`pixel` and `pixel_xrgb` return colors for custom assertions. `audio_samples`
returns the latest frame's interleaved stereo waveform, while `audio_frame`,
`assert_audio_sample`, and `assert_audio_hash` support exact deterministic
sound tests. Failed built-in assertions report expected and actual values.

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`:

```cpp
#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

```sh
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" \
  --assert-pixel 12,20,ff0000 \
  --assert-audio-sample 100,0,1200,10 \
  --assert-audio-hash fedcba9876543210 \
  --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`.