DOCSEARCHbyAlgolia
Submit Docs

Boytacean

repository·master·Indexed 20 days ago

https://github.com/joamag/boytacean

A Game Boy (DMG) and Game Boy Color (CGB) emulator written in Rust, designed for educational purposes. It supports multiple front-ends including Web (via boytacean-react), SDL, and Libretro, with cross-compilation support for WASM-WASI, Arm64 Linux, and Android.

Tokens
36.6K
Snippets
150
Records
193
Agent score
71%

What's inside boytacean

  1. Configure thumbnail selection with `useThumbnail`

    master

    The playlist-level useThumbnail flag (boolean) determines which image is prioritized for entries. This allows you to balance visual richness against list performance.

    • useThumbnail: false (default): Prefers thumbnailSmall. If thumbnailSmall is missing, it falls back to thumbnail.
    • useThumbnail: true: Prefers the larger thumbnail. If thumbnail is missing, it falls back to thumbnailSmall.

    If neither field is provided for an entry, no image is displayed.

  2. Playlist search and ROM naming behavior

    master

    Search

    The search box performs a case-insensitive filter across both the name and description fields of the entries.

    ROM Naming

    When an entry is booted, the display name for the ROM is derived from the last path segment of its url (with the query string stripped). To ensure a clean display name, use meaningful filenames and extensions (e.g., game.gb) in your URLs.

  3. Configure Serial Devices

    master

    The Boytacean emulator supports different serial devices for handling output. You can specify the device using the --device flag.

    Supported devices:

    • null: A null device that discards output.
    • stdout: Redirects output to the standard output stream.
    • printer: A specialized device that captures the frame buffer and saves it as a timestamped PNG file (e.g., printer-20231027-120000.png).
    # Example: Use stdout for serial output
./boytacean_sdl my_game.gb --device stdout

  4. Run performance benchmarks with bench_headless

    master

    To measure the performance of the Boytacean emulation core, use the bench_headless example. This benchmark runs the emulator as fast as possible by disabling the APU (unless specified) and skipping frame-buffer extraction.

    To run a benchmark on a ROM, use the following command structure. You can optionally enable the APU and CGB mode to test specific workloads.

    # Standard benchmark (no APU, DMG mode)
./target/release/examples/bench_headless <rom.gb> [frames]

# Benchmark with APU and CGB enabled
./target/release/examples/bench_headless <rom.gb> [frames] --apu --cgb

  7. Build the Boytacean React Example

    master

    To build the example, you must first generate the WASM binary, then build the web front-end from the frontends/web directory. The build process relies on the WASM binary located in lib and the adjacent packages.

    # 1. Generate the WASM binary
wasm-pack build --release --target=web --out-dir=frontends/web/lib -- --features wasm

# 2. Build the example
cd frontends/web
npx parcel build example/index.html --dist-dir example/dist --cache-dir .parcel-cache-example --public-url .

  9. Compare Boytacean performance against mGBA and SameBoy

    master

    When benchmarking Boytacean against other emulators, use the following standardized harnesses to ensure comparable results:

    EmulatorRecommended Harness / CommandNotes
    Boytaceanbench_headlessBest of 3 runs, 12000 frames, 600 warmup. Use --apu to include audio.
    mGBAmgba-perf -F 120003 runs, audio always emulated (no audio sync).
    SameBoysameboy_tester --dmg --length 200200 emulated seconds (~12000 frames). Full accuracy mode, audio emulated, simulates button presses.

    Key Performance Observations:

    • Rendering-bound DMG: Boytacean is typically faster than mGBA when audio is enabled.
    • Interrupt/HALT heavy workloads: mGBA may outperform Boytacean because it uses an event-driven scheduler to skip idle emulation work, whereas Boytacean ticks through cycles.
    • Accuracy vs Throughput: SameBoy prioritizes per-T-cycle accuracy and runs significantly slower than Boytacean or mGBA.

  10. Full 2BPP compression and decompression workflow

    master

    To perform a complete cycle of PNG conversion, compression using pb12.py, and subsequent decompression back to PNG, follow this sequence of commands:

    1. Convert PNG to 2BPP.
    2. Compress the 2BPP file to .pb12 format using python pb12.py compress.
    3. Decompress the .pb12 file back to 2BPP using python pb12.py decompress.
    4. Convert the resulting 2BPP back to PNG.
    rgbgfx -Z -c embedded -t logo.tilemap -o logo.2bpp logo.png
python pb12.py compress logo.2bpp logo.pb12
python pb12.py decompress logo.pb12 logo.decompress.2bpp
rgbgfx -Z -r 16 -o logo.decompress.2bpp -t logo.tilemap logo.reverse.png

  11. Run Boytacean benchmarks using the bench_headless harness

    master

    To measure Boytacean's performance, use the bench_headless example. This harness is designed for high-throughput, headless testing.

    Default Configuration:

    • Frames per run: 12,000
    • Warmup frames: 600
    • Mode: DMG (unless specified otherwise)
    • APU: Disabled by default.

    CLI Flags for Benchmarking:

    • --apu: Enables the APU (Audio Processing Unit). Note that enabling the APU significantly reduces frame throughput compared to the default headless mode.
    • --cgb: Enables CGB (Color Game Boy) mode.
    • --profile: Enables internal profiling hooks (used for instrumentation like measuring render_map() time).
    # Example: Running the headless benchmark with APU and CGB enabled
# (Note: exact command depends on how the bench_headless binary is compiled/exposed)
./bench_headless --apu --cgb

  12. Convert PNG to 2BPP format

    master

    To convert a PNG image into the 2BPP (2-bit per pixel) format used by Boytacean Boot ROMs, use the rgbgfx tool from the rgbds suite. The -Z flag is used for the conversion, -c embedded specifies the mode, -t defines the tilemap, and -o specifies the output file.

    rgbgfx -Z -c embedded -t logo.tilemap -o logo.2bpp logo.png