padme-core

GAME BOY COLOR EMULATOR

padme-core

Padme-core is an open-source Rust-based Game Boy / Game Boy Color emulator engine (library/crate) intended to be embedded in applications or used in demos — not a full standalone GUI player. It focuses on a compact, no_std-friendly implementation of the CPU, PPU, APU and cartridge banking (MBC1, MBC3) with examples for desktop and WebAssembly.

Jump to download ↓Jump to setup guide ↓

padme-core emulator screenshot.

game boy colorPRIMARY SYSTEM

History documentedPROJECT BEGAN

Open sourcePROJECT MODEL

WHY IT MATTERS

Why this project exists

padme-core is written to be a compact, embeddable Game Boy emulator engine (Pixel As Dot-Matrix Emulator). The crate avoids depending on the Rust standard library and dynamic allocation, making it suitable for embedded targets and WebAssembly. It provides a System API, simple hardware interface traits (Screen, AudioSpeaker, SerialOutput, Button) and example frontends (desktop demo and browser demo) so developers can integrate Game Boy / Game Boy Color emulation into custom projects.

BEST FOR

Best for

Developers who want a small, embeddable Rust emulator engine to integrate into custom frontends, embedded devices, or WebAssembly projects; or contributors who want a Rust-native, test-driven Game Boy implementation to extend (more MBCs, additional tests).

Gameplay from Wario Land 3 on Game Boy Color.

The people behind padme-core

Project status & history

The project is hosted on GitHub (shaoner/padme-core). The repository identifies itself as a "Cross-platform gameboy emulator engine" and includes source for CPU, PPU (pixel FIFO), APU, timers, DMA, basic cartridge handling and a small set of integration/unit tests. The README documents example usage showing how to implement platform-specific Screen/Audio/Serial components and how to load a ROM into padme_core::Rom and run frames via System::update_frame() or step() loops. The feature list in the README lists support for MBC1 and MBC3, and notes MBC2/MBC4/MBC5/MBC6/MBC7 as TODO. It also advertises no_std compatibility and references two example frontends: padme-demo (desktop) and padme-browser (WebAssembly). The repo is actively viewable on GitHub with commit history and an MIT license; releases are present in the GitHub releases page area but no formal packaged release binaries are required to use the crate (use cargo build). The project is not packaged as a libretro core and is intended as an engine library rather than a plug-and-play emulator frontend.

What padme-core supports

Game Boy (DMG) emulation (CPU, PPU, APU)
Game Boy Color (GBC) runtime behavior
Cartridge: ROM loading, MBC1, MBC3 support (RAM/RTC partly supported per README)
No external BIOS required (engine implements behavior internally)
Example frontends: padme-demo (desktop), padme-browser (WebAssembly)

Download and availability

OFFICIAL DOWNLOADS

Get padme-core

Official source and packaged artifacts are provided from the project's GitHub repository. Typical usage is via cloning the repository or adding the crate to a Rust project and building with cargo. The project README and GitHub releases page are the authoritative places to fetch source and any release tarballs.

Get padme-core ↗

DOCUMENTATION

Official documentation

Read the official configuration, compatibility, and troubleshooting material before changing advanced options.

Read official documentation ↗

Broken or missing download? Emulator projects move and official links sometimes change. Please contact Retro Replay so the source can be verified and updated.

padme-core setup guide

Setup note: This guide covers using padme-core as a Rust crate engine, building the provided examples, and embedding it into your own application. It assumes familiarity with Rust and cargo and that you will provide your own game ROM files (not included).

1) Get the source or add as a dependency: Clone the repository: git clone https://github.com/shaoner/padme-core.git, or add the crate to your Cargo.toml if published. The README and examples live in the repository root. If you plan to run the included demos, clone the repo so you can build the padme-demo and padme-browser example projects referenced in the README.
2) Install Rust toolchain: Install Rust (rustup) and a recent stable toolchain. Ensure cargo is available. For WebAssembly examples, add the wasm32 target (rustup target add wasm32-unknown-unknown) and any wasm bundler (wasm-bindgen, wasm-pack) required by the padme-browser example.
3) Build and run the desktop demo (padme-demo): From the repository, change into the example/demo folder referenced in the README (padme-demo). Build with cargo build –release (or cargo run –release) and provide a path to a .gb/.gbc ROM when the demo accepts it. The demo implements platform-specific Screen/Audio/Serial traits and shows how to feed button inputs into the System API.
4) Run the WebAssembly example (padme-browser): Follow the instructions in the repository's docs or the padme-browser folder to build the WebAssembly target. Typical steps: add wasm32-unknown-unknown target, build the wasm example, and use wasm-bindgen/wasm-pack to produce bindings and an HTML wrapper. The README states the project can be compiled to web assembly (wasm) and includes padme-browser as an example implementation.
5) Embedding padme-core in your own project: Implement the required traits in your target environment: Screen (set_pixel), AudioSpeaker (set_samples), SerialOutput (putchar) and provide a button input mapping using padme_core::Button. Load a ROM into padme_core::Rom (Rom::load expects a byte vector), create System::new(rom, MyScreen, MySerialConsole, MySpeaker), set frame rate with set_frame_rate(60) then call update_frame() each frame or manually run cycles with step()/CLOCK_SPEED logic as shown in README example.
6) Cartridge and BIOS notes: padme-core includes its own behavior to run ROMs and does not require user-supplied BIOS files according to its README. The crate implements MBC1 and MBC3; additional MBC types are listed as TODO. Test your target ROMs; if a game uses an unsupported MBC type the engine will not run it correctly.
7) Testing and development: The repository includes unit and integration tests. Run cargo test for fast tests and cargo test — –ignored (or cargo test — –include-ignored) for more expensive tests. If you modify hardware traits or add MBC support add targeted unit tests as the project encourages.
8) Licensing and redistribution: padme-core is licensed under the MIT License (LICENSE.txt in the repository). The project does not include commercial ROMs, BIOS, or firmware. Distribute only what you have legal rights to (your own binaries, or user-provided ROMs).

Software reminder: You must supply your own Game Boy / Game Boy Color ROM files. padme-core is source code (Rust crate) — build with cargo and provide platform-specific implementations for display/audio/input. It is not a libretro core and not a prepackaged emulator application.