CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• README.md for the boytacean-react package, documenting the components, props, hooks and keys, with a quick start, a complete emulation page example and copy and paste instructions to build one from scratch

Changed

• Faster and more resilient release builds through caching of native dependencies

Fixed

• Resolution of the default WASM binary path in boytacean-core, which pointed at a lib directory that only exists in the repository and therefore failed whenever the package was installed from npm
• Build of the web front-end, which was broken by the resolution of the WASM binary through a bare specifier, as Parcel resolves those at build time and the boytacean package is aliased to a local file

[0.13.2] - 2026-07-28

Added

Changed

Fixed

• Publish of the core and React packages, which failed as the deploy job did not install the dependencies required by their build

[0.13.1] - 2026-07-28

Added

• Keyboard navigation in the game playlist (arrow keys to browse results, Enter to load)
• Performance profiling support with per-frame timings, render timings and memory access counters - #34
• Performance audit document with benchmark comparisons against other emulators - #34
• Headless boytacean-core package with a GameBoyCore that carries the emulation logic without any React, EmuKit UI or bundler-specific dependency - #2
• StorageAdapter abstraction for the persistence of battery-backed RAM and settings, allowing embedders to replace the Web Storage API - #2
• boytacean-react package with a drop-in Boytacean component, rendering the display, binding the physical keyboard and showing an on screen game pad out of the box - #2
• Boytacean.Provider, Boytacean.Screen, Boytacean.Gamepad and Boytacean.Keyboard components, allowing the complete presentation to be replaced by the embedder - #2
• useBoytacean(), useBoytaceanStatus() and useBoytaceanStats() hooks, keeping the context identity stable so that consumers are never re-rendered by the emulation - #2
• Embedding example covering the out of the box usage, a custom layout with a remapped keyboard and a fully custom game pad - #2
• Unit test suites for both the core and the React packages, run as part of the WASM continuous integration jobs - #2
• loadedRomName, loadedRomSize and loaded accessors in GameBoyCore, exposing the currently loaded ROM to embedders - #2

Changed

• Faster background rendering and main loop clocking with identical emulation output - #34
• GameboyEmulator reduced to an EmuKit adapter over the headless core, keeping only the UI-bound surface - #2
• WASM path and extra settings are provided as core options instead of being resolved through bundler-specific require calls - #2
• Both web packages are now built into plain JavaScript with type declarations, so that they are resolvable outside of a TypeScript aware bundler - #2
• The deploy-npm job publishes the core and React packages alongside the WASM one - #2

Fixed

• Physical keys stayed pressed whenever the page lost focus, as the key up event is not delivered in that situation - #2
• Build of the web packages, which failed while EmuKit could not be compiled by TypeScript 5.7 or newer - #2
• Type error in buildRomData() when unpacking a zipped ROM, which prevented the type check of the web front-end
• Freeze with a blank screen (music still playing) in demos that wait for the first V-Blank line
• Garbled graphics in demos that change video registers in the middle of a scanline (raster effects)

[0.12.1] - 2026-05-31

Changed

• Raised the minimum supported Rust version to 1.86

[0.12.0] - 2026-05-31

Added

• JSON-based game playlist support with search and remote ROM loading via playlist_url parameter
• Documentation describing the playlist file format and how to build one
• High-pass audio filter options (Preserve, Accurate, Disable) with save-state support
• SDL frontend shader loading support via --shader-path
• PyBoy 2.x compatible Python interface (PyBoyV2) with tick(count, render), button/button_press/button_release, screen.ndarray/screen.image, memory[addr] bracket accessor, mb.cpu.registers register file, set_color_palette and a generic GameWrapper
• Tile, Sprite and TileMap API objects with bracket access, slice/2D indexing and use_tile_objects(True) toggle; tilemap_background/tilemap_window attributes plus get_tile/get_sprite/get_sprite_by_tile_identifier helpers on PyBoyV2
• Standalone game wrappers (GameWrapperTetris, GameWrapperSuperMarioLand, GameWrapperKirbyDreamLand) auto-selected by cartridge title, plus game_area/game_area_collision/game_area_mapping/game_area_dimensions helpers
• .sym symbol-file loader and symbol_lookup(name) returning (bank, addr) on PyBoyV2
• Lightweight pure-Python hook_register/hook_deregister over per-frame PC checks (no opcode patching, zero cost when no hooks are registered)
• MemoryScanner with EXACT/LESS_THAN/GREATER_THAN scans plus CHANGED/UNCHANGED/INCREASED/DECREASED/MATCH rescans
• GameShark cheat manager applying 8-bit RAM-write codes (ttvvaaaa format) every frame, with add/remove/clear_all
• PyBoyV1.botsupport_manager() returning a BotSupportManager proxy with screen(), sprite(), sprite_by_tile_identifier(), tile(), tilemap_background() and tilemap_window() methods
• LegacyScreen exposing the 1.x 3-channel RGB screen_image, screen_ndarray, raw_screen_buffer* and tilemap_position* shapes used by older AI scripts
• PyBoyV1.override_memory_value(rom_bank, addr, value) for legacy memory-patching scripts (RAM addresses only — ROM patching surfaces a clear RuntimeError until the core exposes cartridge writes)
• GameBoy.next_frames(count) and frame_buffer_rgba() Rust bridges; PyBoyV2.tick(count, ...) now batches the loop entirely inside Rust when no hooks/cheats/recorders are active, and screen.ndarray/screen.image/screen.raw_buffer consume the native 4-channel buffer directly
• HBlank HDMA transfer support
• Python 3.14 support via pyo3 0.25
• boytacean.test package shipped with installs, with automatic skip guards when numpy/Pillow are missing or required test ROMs are absent
• GameBoy.cpu_f / set_cpu_f accessors and a matching PyBoyV2.register_file.F property that reads and writes the real flag byte
• Tile(..., bank=) kwarg and CGB-aware Sprite initialisation that routes bank-1 OAM sprites to the right VRAM bank instead of silently reading bank 0
• Coverage for the PyBoy compatibility layer: 8 new Python unit tests (V1/V2 set_emulation_speed, banked memory rejection, applied game_area_mapping, per-tick post_tick, banked hook rejection, multi-byte rescan_memory, overlapping GameShark codes) and a Rust unit test for Cartridge::title() on an unloaded cartridge

Changed

• Python extension defaults to release builds (debug=False in setup.py), making pip install and pip install -e . produce optimised binaries out of the box
• Inlined the per-cycle dispatch chain (GameBoy::clock, *_clock wrappers and Mmu/GameBoy accessors for ppu/apu/dma/pad/timer/serial); native baseline frame rate on Tetris improved from ~7900 fps to ~8700 fps (+10%) and the cost of clocking idle serial hardware dropped from ~12% of frame time to ~1%
• Promoted hot dispatch-chain hints from #[inline] to #[inline(always)] across gb.rs, mmu.rs and ppu_fast.rs so the inlining is no longer left to the optimiser
• PyBoy compatibility surface reorganised into a boytacean.pyboy subpackage (api, core, debug, wrappers); import paths from boytacean.pyboy (e.g. from boytacean.pyboy import PyBoy) remain stable
• Standalone PyBoy 1.x compatible class (PyBoyV1) with WindowEvent, send_input, screen_image, get_memory_value/set_memory_value and cartridge_title() method
• PyBoy alias resolving to PyBoyV2 so the modern surface is the default for from boytacean.pyboy import PyBoy
• Python bindings for VRAM, OAM, HRAM, ROM/RAM data, ROM/RAM banks, CPU register file, mode predicates and clock frequency
• PyBoyV1.set_emulation_speed / PyBoyV2.set_emulation_speed now compute against a captured base clock rather than the current clock_freq, so repeated calls no longer compound; speed=0 follows the PyBoy 2.x convention and means "unbounded", speed<0 raises ValueError
• PyBoyV2.game_area_mapping(mapping, sprite_offset) actually applies the mapping inside GameWrapper.game_area() instead of silently storing it; agents that pass a tile-id remap table now receive the remapped observation
• MemoryScanner.rescan_memory reuses the original scan's byte_width / value_type / byteorder so dynamic comparisons on 2-byte/4-byte/BCD scans no longer fall back to a single-byte read
• GameShark.add / remove reference-count the pre-cheat snapshot per address, so overlapping codes on the same byte share one snapshot and removing one cheat no longer prematurely restores the original value
• HookRegistry.register rejects bank-aware registrations (bank != 0) with NotImplementedError rather than silently colliding with bank-0 entries at the same address
• Memory._read / _write raise NotImplementedError when called with a non-None bank instead of silently returning the flat-bus value
• Display.set_hud(frame_index=...) accepts a baseline so the first FPS sample doesn't include frames that ran before HUD activation

Fixed

• boytacean.pyboy subpackage was missing from shipped wheels/sdists
• Cartridge::title() now returns "UNKNOWN" and guards against out-of-range title_offset instead of returning an empty string (or panicking on rom_data.len() < 0x0134) for unloaded cartridges
• PyBoyV1.screen_image() was calling a non-existent self.image() and raising AttributeError; it now produces the 3-channel RGB image PyBoy 1.x callers expect
• PyBoyV1.tick() / PyBoyV2.tick() invoke self.game_wrapper.post_tick() after advancing frames, so wrapper-cached fields (score, level, world, ...) no longer stay stale during normal emulation
• Fixed audio_ch1_enabled returning the wrong channel status
• Shader program was not applied to SDL output
• SDL shader rendering failed due to lifetime issues
• SDL shader context version mismatch caused blank output
• Major issue with the VBlank STAT, should fix many visual glitches in games
• Issues with the LCD STAT interrupt not triggering correctly due to incorrect handling of the internal STAT line state and edge detection
• WX and WY constants address in the code

[0.11.5] - 2025-03-18

Fixed

• Dependency issues with the Web frontend

[0.11.4] - 2025-03-18

Added

• BOSC decompressor utility documentation and usage

Changed

• Bumped some packages

[0.11.3] - 2025-03-05

Fixed

• Process package reference in GitHub Action workflow

[0.11.2] - 2025-03-05

Added

• BOSC decompressor utility documentation and usage

[0.11.1] - 2025-03-05

Fixed

• Add new dependency to fix GitHub Action workflow

[0.11.0] - 2025-03-05

Added

• State management support for: pad, ppu and cpu

Changed

• Structure of the BOS save file format, breaking change!

Fixed

• Major bug related to OAM masking

[0.10.14] - 2024-10-21

Added

• Greatly improved state management in BOS
• Support for MBC2

[0.10.13] - 2024-09-02

Changed

• Bumped EmuKit to improve Web runtime performance

[0.10.12] - 2024-08-30

Fixed

• Extra react reference

[0.10.11] - 2024-08-30

Fixed

• Major PPU related issue in state loading, which used to create PPU mode related issues

[0.10.10] - 2024-08-30

Fixed

• Warning message in wasm-bindgen loading

[0.10.9] - 2024-08-30

Fixed

• Unit test issue

[0.10.8] - 2024-08-30

Changed

• Memoised some of the class generation process
• Updated Emukit version, for faster performance

Fixed

• Issue related with DMA transfer being triggered while loading state
• Sound glitch in loading save state, by setting proper sound raw values

[0.10.7] - 2024-08-08

Fixed

• Unit test that was failing

[0.10.6] - 2024-08-08

Changed

• Improved Zippy format to include opaque feature support, for future proof

[0.10.5] - 2024-08-08

Added

• Licensee enumeration with the description of the publisher of the ROM
• Support for Zippy encoding format for fast compression
• New hashing crate that includes CRC-32 and CRC-32C implementations

Fixed

• Issue with the web frontend and hardReset() implementation

[0.10.4] - 2024-07-16

Added

• Support for cartridge region detection

Changed

• Bumped web packages

[0.10.3] - 2024-07-16

Added

• Support for SIMD based color space conversion - #45
• Support for window.requestAnimationFrame() and game loop inversion of control - #26
• Custom Boot ROM support for CGB - #34

[0.10.2] - 2024-06-07

Fixed

• Removed binary distribution from PyPi

[0.10.1] - 2024-06-07

Fixed

• Bumped base rust version to fix issue with GitHub Action Deploy workflow

[0.10.0] - 2024-06-07

Added

• Initial support for the PyBoy compatibility layer - #36
• Support for PyPi registry for the PyO3 package - #43
• Python interface file for base boytacean (boytacean.pyi)
• Interface to custom boot ROM loading in Python

Changed

• Better boot_dump.py script with support for other string output formats
• Improved error handling using the Error enum

Fixed

• Issue related to interrupt timing, reduce interrupt to 20 cycles instead of 24
• Libretro issue with the loading of the base emulator info retro_get_system_info()

[0.9.18] - 2024-01-02

Added

• Support for Python 3 API - #36
• next_frame() method for frame by frame navigation
• Support for palette switching option in Libretro - #37

Changed

• Made part of the frontend code conditional on NODE_ENV = "development"
• Re-release of version 0.9.17

[0.9.17] - 2024-01-02

Added

• Support for Python 3 API - #36
• next_frame() method for frame by frame navigation
• Support for palette switching option in Libretro - #37

Changed

• Made part of the frontend code conditional on NODE_ENV = "development"

[0.9.16] - 2023-10-30

Fixed

• Bumped emukit version to fix a bug with zip file handling

[0.9.15] - 2023-10-30

Added

• Support for ROM in zip files (Web frontend)
• Support for raw frame buffer
• Lazy evaluation of frame_buffer (on-demand) for DMG

[0.9.14] - 2023-08-24

Added

• XRGB8888 support for Libretro frontend, for better color fidelity and faster render
• Support for save state - #7
• LibRetro save state support - #7
• Support for fast mode in SDL frontend
• Support for GameShark cheat codes - #33

Changed

• Made audio flush for libretro and sdl frontends flush by the end of the frame
• Improved MBC5 to support 9 bit ROM bank addresses

Fixed

• Breaking issue with Libretro frontend and Linux
• Fix window_counter issue in PPU
• Issue with BESS header testing

[0.9.13] - 2023-08-01

Changed

• Improved command line parsing with positional ROM path value
• Better CI/CD for releases
• Hidden test panel in Web UI

Fixed

• Small issue with command line arguments

[0.9.12] - 2023-08-01

Added

• New WASM build

[0.9.11] - 2023-08-01

Fixed

• Build of a new release

[0.9.10] - 2023-08-01

Fixed

• Issue with release life-cycle

[0.9.9] - 2023-08-01

Fixed

• Issue with release life-cycle

[0.9.8] - 2023-08-01

Added

• Better release life-cycle

[0.9.7] - 2023-08-01

Added

• Support for Libretro core - #14

[0.9.6] - 2023-06-20

Added

• Support for image based testing
• Support for rumble, works for both mobile devices and Gamepads (web APIs)

Changed

• Bumped emukit to 0.8.8

Fixed

• CGB-ACID2 test passing - #30

[0.9.5] - 2023-06-05

Added

• Support for the clock_m() function
• Benchmark CLI option in SDL

Changed

• Major performance improvements for the DMG specific code

[0.9.4] - 2023-06-04

Added

• Support for displaying speed at which the CPU is running in Web mode, for debug purposes
• Headless execution mode in Boytacean SDL
• Many more parameters added for Boytacean SDL

[0.9.3] - 2023-05-18

Fixed

• Small panic recovering issue

[0.9.2] - 2023-05-18

Added

• Support for auto emulation mode selection

[0.9.1] - 2023-05-18

Added

• Support for enabling and disabling audio channels

Fixed

• Issue with CH2 envelope initialization

[0.9.0] - 2023-05-18

Added

• Support for Game Boy Color (CGB) emulation! 🥳 - #8
• Support for CLI params in Boytacean SDL
• Support for GameBoyConfig structure that is passed to some comments
• New DMA component

[0.8.0] - 2023-04-20

Added

• Support for serial data transfer - #19
• Support for printing of images using Printer emulation - #19
• Support for display of logger and printer in Web panels
• Converted serial-sections strategy to event driven

Fixed

• ButtonSwitch issues by updating the value strategy nad bumping emukit
• AudioGB with display of canvas with no visibility

[0.7.5] - 2023-04-11

Added

• Support for variable clock speed for APU, means variable audio speed
• Moved debug into the base emulator (from emukit)

[0.7.4] - 2023-04-08

Added

• Support for audio channel 4 (noise) 🔈
• Better trigger support for audio channels 🔈

Changed

• Added CH4 public API method for WASM

Fixed

• Envelope support for both channel 2 and 4 🔈
• Issue related to the wave length stop flag 🔈

[0.7.3] - 2023-04-02

Added

• Support for CGB flag parsing
• Waveform plotting support

Fixed

• Major JoyPad issue with Action/Select read in register
• Small issue with channel 3 audio and DAC disable

[0.7.2] - 2023-03-04

Added

• Support for stereo sound 🔊

Changed

• APU clock() method with cycles parameter, improving performance by an order of magnitude 💪

Fixed

• Added reset of APU, which fixes annoying "garbage" data in buffer when restarting the state of the emulator

[0.7.1] - 2023-03-02

Changed

• Bumped emukit, fixing a lot of bugs

[0.7.0] - 2023-03-01

Added

• Support for Audio 🔈!!! - #12
• Support for WASM engine version printing

[0.6.12] - 2023-02-21

Fixed

• Build process for the docs.rs website

[0.6.11] - 2023-02-21

Fixed

• Unused code issue

[0.6.10] - 2023-02-21

Fixed

• Old compilation problem with NUM_CPUS generation

[0.6.9] - 2023-02-21

Changed

• Bumped emukit dependency

[0.6.8] - 2023-02-21

Added

• Support for the build.rs generation file that creates the gen.rs file
• Support for benchmark in the SDL frontend
• Palette switching for the SDL frontend

Fixed

• Bug with ROM title that included 0x0 characters in it
• V-Sync issue with SDL

[0.6.7] - 2023-02-13

Changed

• Bumped base emukit version

[0.6.6] - 2022-12-04

Added

• Support for theme and palette selection
• Theme stored in localStorage

[0.6.5] - 2022-11-27

Added

• Canonical URL support for boytacean.joao.me

Changed

• Small help changes regarding Gamepad

[0.6.4] - 2022-11-22

Fixed

• Emukit version bump

[0.6.3] - 2022-11-21

Fixed

• Emukit version bump

[0.6.2] - 2022-11-21

Changed

• Made UI generic by extracting components into EmuKit 🎉
• More generic help panels

[0.6.1] - 2022-11-19

Fixed

• Exclusion of files from Cargo.toml

[0.6.0] - 2022-11-19

Added

• Support for Ctrl+D (Speedup) and Ctrl+K (Keyboard toggle) shortcuts
• Initial help panel
• Palette debugging panel

Fixed

• Android highlight color in buttons
• Android issue with arrow pointers

[0.5.7] - 2022-11-17

Fixed

• More issues related with bad PPU handling

[0.5.6] - 2022-11-17

Fixed

• Issue with background color and change of palette colors
• Issue related with STAT interrupt not being triggered for all conditions

[0.5.5] - 2022-11-17

Fixed

• PPU issue related to the maximum number of objects/sprite per line being 10, issue detected by ACID test
• Object pixel drawing priority issue, issue detected by ACID test
• Issue associated with the wrongful flipping of 8x16 sprites, issue detected by ACID test
• Issue associated with drawing of window tiles, due to extra update_stat() operations, issue detected by ACID test

[0.5.4] - 2022-11-15

Fixed

• Critical issue with loading of Boot ROM

[0.5.3] - 2022-11-15

Changed

• New default demo ROM

[0.5.2] - 2022-11-14

Added

• Support for Gamepad Web API - #9
• Support for palette changing using GET param - #10

Fixed

• Start and Select buttons order

[0.5.1] - 2022-11-14

Changed

• Small cosmetic changes

[0.5.0] - 2022-11-14

Added

• Support for true fullscreen at a browser level
• Support for more flexible palette colors
• Support for setting palette colors using WASM
• Local storage usage for saving battery backed RAM

[0.4.5] - 2022-11-12

Fixed

• Critical error that prevented physical keyboard from working ⌨️

[0.4.4] - 2022-11-12

Added

• Support for responsive physical keyboard

[0.4.3] - 2022-11-11

Added

• Better debug panel support
• Support for some GET parameters
• Support for fullscreen on screen keyboard mode

[0.4.2] - 2022-11-09

Fixed

• Arrow keys usage for on-screen Gamepad
• Wrong UX for keyboard focus and fullscreen

[0.4.1] - 2022-11-06

Added

• Logic frequency control using on click UI and keyboard
• Support for on screen keyboard for Game Boy
• Support for remote ROM loading using URL - #3

[0.4.0] - 2022-11-01

Added

• A whole new layout implemented using React.JS 🔥
• Instant boot support using the GameBoy.boot() method
• Support for pending cycles in web version

Changed

• Improved drawing speed at the SDL example
• Better handling of panic!() in web version

Fixed

• Issue related to STAT interrupt and H-Blank
• Issue related to overflow in sprite drawing
• Issue related to the RAM bank selection in some of the MBCs

[0.3.0] - 2022-07-11

Added

• Support for 8x16 sprites
• Support for MBC5, think Pokemon Yellow

Fixed

• Issue with MBC1 and Advanced ROM Banking Mode
• Issue related to LDC power of and return mode

[0.2.0] - 2022-07-10

Added

• Support for drag and drop loading in SDL
• SDL fixes related to timing
• Support for drawing windows
• Initial experimental support for MBC3 (for Pokemon Red/Blue)

Fixed

• Timer related issue, made test on inst timing pass
• Clear first frame issue, with first_frame flag

[0.1.1] - 2022-07-08

Fixed

• License name in the Cargo.toml file

[0.1.0] - 2022-07-08

Added

• Support for sprite drawing, works with Tetris
• Support for timers
• Initial working version 🥳

Fixed

• Problem in the switching of the LCD mode