BBK (步步高) A-series electronic dictionary game emulator written in Rust. Plays .gam game files from BBK A4980 and A4988 dictionaries.
- Complete 6502 CPU emulation — using the mos6502 crate for accurate instruction execution
- Bank-switched memory — full memory map with flash, RAM, and ROM support
- LCD display — 159×96 monochrome framebuffer with ghosting effects
- Keyboard input — complete BBK key matrix emulation
- Audio system — tone generation with configurable frequency and duration
- GAM file support — loads BBK game files with automatic header parsing
- Multiple models — supports BBK A4980 and A4988 dictionaries
- RetroArch integration — libretro core for use with RetroArch frontend
- Developer tools — debugger with breakpoints, watchpoints, and syscall logging
- Save states — serialization support for save/load functionality
BBKEmu requires ROM files from a physical BBK dictionary to run games:
- 8.BIN — Font ROM (2 MiB)
- E.BIN — OS ROM (2 MiB)
These files are not distributed with the emulator and must be obtained separately.
Download the latest binary from the Releases page.
The basic usage is listed below, but there are many more options for controlling the behavior of the emulator. See the Command-line Options documentation for the full list of options.
# Basic usage with ROM files
bbkemu game.gam -8 8.BIN -e E.BIN
# If ROM files are in system/BBKEmu/<model>/
bbkemu game.gam
# With common options
bbkemu game.gam --scale 4 --fullscreen --model 4980
# Headless mode for testing
bbkemu game.gam --frames 100 --output screenshot.pngKeyboard shortcuts: F5 Save state | F8 Load state | F12 Screenshot | Escape Exit
BBKEmu can be used as a libretro core with RetroArch, allowing you to play BBK games with RetroArch's features like shaders and save states.
Install the core — choose one of the following methods:
- Online Updater: Open RetroArch → Main Menu → Online Updater → Core Downloader → select BBKEmu
- Manual: Download the core from the Releases page, copy
bbkemu_libretro.dll(or.so/.dylib) to RetroArch'scores/directory, andbbkemu_libretro.infoto theinfo/directory
Load the core in RetroArch:
- Open RetroArch
- Select "Load Core" → "BBKEmu"
- Select "Load Content" and choose a
.gamgame file - ROM files should be placed in
system/BBKEmu/<model>/(e.g.,system/BBKEmu/A4980/)
The libretro core also runs on Android and can be reused by most Android RetroArch-based frontends. See Android Libretro Core for install and build instructions.
The libretro core also runs on iOS (iPhone / iPad). iOS currently requires manual core injection — see iOS Libretro Core for install and build instructions.
- ✅ Video output (RGB565 pixel format)
- ✅ Audio output (tone generation)
- ✅ Input handling (keyboard mapping)
- ✅ Game loading (.gam files)
- ✅ Save states
- ✅ LCD orientation option (portrait/landscape)
- ✅ CPU/Timer clock rate adjustment
- ✅ SRAM support (flash memory)
- ✅ Cheat codes support
Configurable from RetroArch's Quick Menu → Core Options (LCD orientation, CPU/Timer clock rate, key repeat interval). See Core Options for the full list.
| RetroPad Button | BBK Key | Action |
|---|---|---|
| D-Pad Left | Left | Navigate left |
| D-Pad Right | Right | Navigate right |
| D-Pad Up | Up | Navigate up |
| D-Pad Down | Down | Navigate down |
| A | Enter | Confirm |
| B | Exit | Back / Cancel |
Requires Rust (stable).
cargo build -p bbkemu --release
cargo run -p bbkemu --release -- game.gamThe binary is produced at target/release/bbkemu (or bbkemu.exe on Windows).
cargo build -p bbkemu-libretro --releaseCargo names the cdylib after its lib target, so this produces bbkemu.dll
on Windows (libbbkemu.so on Linux, libbbkemu.dylib on macOS) under
target/release/. Rename it to bbkemu_libretro.<ext> before dropping it into
RetroArch's cores/ directory.
For Android cross-compilation, see Android Libretro Core. For iOS, see iOS Libretro Core.
Run the unit tests:
cargo test --workspaceThere is also a smoke test that loads every available game, runs it for a number
of frames, and checks that the emulator neither panics nor produces a blank
frame. It needs the (non-distributed) game assets, so it is #[ignore]d by
default and run on demand:
# Uses <repo>/tmp/games by default, or set BBK_GAME_DIR
cargo test -p bbkemu-core --test smoke -- --ignored --nocapturecrates/
├── bbkemu-core/ # Platform-independent emulator engine (library)
│ └── src/
│ ├── lib.rs # Crate root (module declarations)
│ ├── emulator.rs # Main emulator orchestrator
│ ├── cpu.rs # 6502 CPU wrapper (mos6502 crate)
│ ├── memory.rs # Memory bus with bank switching
│ ├── lcd.rs # LCD framebuffer (159×96 monochrome)
│ ├── input.rs # Keyboard input handling
│ ├── audio.rs # Audio tone generation
│ ├── font.rs # Font rendering
│ ├── font_data.rs # Built-in font bitmap data
│ ├── gam.rs # GAM file loader and parser
│ ├── model.rs # BBK model definitions (A4980, A4988)
│ ├── debug.rs # Debugger with breakpoints and watchpoints
│ └── save.rs # Save state serialization
├── bbkemu/ # Standalone binary (-> bbkemu)
│ └── src/
│ └── main.rs # Window loop and CLI frontend
├── bbkemu-libretro/ # libretro cdylib (-> bbkemu_libretro.{dll,so,dylib})
│ └── src/
│ └── lib.rs # libretro API implementation
└── bbkemu-rom-analyzer/ # ROM analysis tool
└── src/
└── main.rs # OS ROM analyzer
BBK games are compiled 6502 machine code running on the BBK dictionary hardware. The emulator executes the actual OS ROM code (E.BIN) and font ROM (8.BIN) to provide the runtime environment for games:
Game → JSR to OS address → Execute OS ROM code → Hardware emulation
The 6502 CPU executes instructions from the memory-mapped ROM, while the emulator provides hardware register emulation for LCD, keyboard, audio, and timers.
Game resources can be downloaded from Baidu Netdisk.
For detailed game list with screenshots and compatibility status, see Game Compatibility.
Contributions are welcome! Whether you're interested in fixing bugs, adding features, improving documentation, or testing game compatibility, we'd love your help. See CONTRIBUTING.md for details.
Some code is based on gam4980 and BBK-simulator, and this project relies heavily on mos6502 for accurate 6502 CPU emulation. Thanks to all related developers for their contributions.
This project is licensed under the GNU General Public License v3.0 or later.