Skip to content
Screenshot published by the gebeh project
Screenshot published in the gebeh project's official README. Image source: gebeh project on GitHub.

gebeh

EMULATOR DATABASE

gebeh

gebeh — a browser-based Game Boy (DMG/CGB) emulator written to run in WebAssembly with optional native components and online multiplayer features.

6.0 / 10

Game Boy

Download Tutorials & guides

Sign in to download. Files are hosted by the emulator project.

Game Boy Color
SYSTEM SPOTLIGHTGame Boy ColorArtwork from the Retro Replay system database

About gebeh

gebeh provides an in-browser Game Boy (DMG/CGB) implementation with a focus on accuracy (passes a number of Mealybug and mooneye tests) and built-in online multiplayer. It's suitable for trying Game Boy ROMs quickly in a browser and for developers interested in the emulator's Rust/WASM code and networking.

Running Game Boy (DMG / Game Boy Color) ROMs in a browser or building the project from source to run the web or native frontends; experimenting with WebAssembly Rust emulator cores and the project's networked multiplayer features.

The people behind gebeh / history

The project is hosted on GitHub under the user itytophile and contains multiple subprojects (gebeh-core, gebeh-web, gebeh-native, gebeh-server, gebeh-network, etc.). The repository documents its test targets (Mealybug Tearoom tests, much of the mooneye acceptance suite) and references common GB documentation and test-ROM suites. The repository is active enough to include many commits and supporting tooling (Dockerfile, docker-compose, CI/workflow files). The project is licensed under GPL-3.0. Current activity, releases, and issue status should be checked on the GitHub repository for the most recent state before relying on it in production.

Screenshots

Screenshot published by the gebeh project
Screenshot published in the gebeh project's official README. Image source: gebeh project on GitHub.
Tetris gameplay on Game Boy
Gameplay from Tetris on Game Boy.

Tutorials & guides

gebeh setup guide (click to expand)

Setup note: Two common ways to run gebeh: 1) use the hosted web build (if available) for quick testing, or 2) build and run from source to run the web frontend locally or build the native frontend and server. The steps below focus on building from source and running locally; they reference the repository structure and available components.

  1. Try the hosted build (quick): If the project's hosted site is available, open the web frontend to load ROMs and use the emulator in your browser. The README points to a hosted instance (gebeh.ovh). The hosted site availability varies; if it's down, proceed to building locally.
  2. Fetch the source: Clone the official repository from GitHub: the repository contains folders such as gebeh-core, gebeh-web, gebeh-native, gebeh-server, and other helpers. Inspect the README and subproject READMEs for component-specific build instructions.
  3. Install prerequisites: For the web build: install Rust and wasm32 target tooling (rustup, cargo). The project uses Rust and compiles to WASM for the browser. For native builds: install the system toolchain described in gebeh-native's README (likely a Rust toolchain and platform-specific build tools). For the server component: install Docker or the language runtime indicated in the server subproject if you prefer to run it without Docker.
  4. Build the web frontend (WASM): From the repo root, follow the gebeh-web and gebeh-core README/build steps. Add the wasm target with rustup if not already present (rustup target add wasm32-unknown-unknown) and use the project's build script or cargo workspace commands to compile the core to WASM. The repository includes a Dockerfile and docker-compose that can build and serve the web frontend if you prefer containerized builds.
  5. Run locally (web): Serve the built web assets on a local HTTP server (some browsers restrict WASM and fetch under file://). The repository's web subproject or docker-compose provides guidance and tooling to serve the site locally. Open the served URL in a modern browser (Chrome recommended on Android).
  6. Optional: build and run native frontend and server: If you want a native executable or to host multiplayer sessions, follow the gebeh-native and gebeh-server subproject READMEs. The server component is provided in the repository and can be run to enable the emulator's online multiplayer features; the README and docker-compose file are starting points for deployment.
  7. ROMs, BIOS, and legal notes: The project does not include commercial game ROMs, copyrighted firmware, or BIOS files. You must obtain any ROMs, BIOS, or proprietary files legally and provide them when running the emulator. The repository contains a folder named boot-rom which suggests places to supply boot ROMs if the software supports them — consult the core documentation before adding any files.
  8. Testing & verification: The project references Mealybug and mooneye test suites and includes a geheb-test-roms subfolder. Use the documented test ROMs and the project's test harnesses to verify accuracy if you are developing or modifying the core.

Software reminder: Read the repository and subproject READMEs carefully. The project is GPL-3.0 licensed; redistribution of modified builds must comply with that license. Check GitHub Issues and Releases for the latest status and downloadable artifacts.

Additional information

What gebeh supports

  • Web (Browser via WebAssembly) — primary
  • Android (browser; Chrome noted as performing better)
  • Native builds (gebeh-native) — desktop via provided native component
  • Server-side component for multiplayer (gebeh-server)

READMEs & documentation

gebeh official project README
# gebeh

![gebeh logo. Two Game Boys connected with a Link cable. There is a fried egg on them.](./gebeh_256px.png)

Pronounced gebeh.

gebeh is a browser based Game Boy (DMG/CGB) emulator with online multiplayer. You can try it here https://gebeh.ovh/

On Android, gebeh runs better on Chrome.
gebeh is "accurate" enough to pass 31 Mealybug Tearoom tests and the majority of the mooneye acceptance test suite.
It doesn't support all cartridge types but the support can easily be added (hopefully).

## Screenshots

Tetris multiplayer
![Tetris multiplayer](./screenshots/tetris.png)

Dr. Mario multiplayer
![Dr. Mario multiplayer](./screenshots/dr_mario.png)

## Bibliography

### General resources

- [Pan Docs](https://gbdev.io/pandocs/)
- [Game Boy: Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf)
- [gbz80(7) — Game Boy CPU instruction reference](https://rgbds.gbdev.io/docs/v1.0.0/gbz80.7)

### CPU important details

- [Game Boy CPU internals](https://gist.github.com/SonoSooS/c0055300670d678b5ae8433e20bea595) - Very helpful document to understand HALT and interrupt handling (and other things).

### About PPU timings

- [The Timing of LYC STAT Handlers](https://gbdev.io/guides/lyc_timing.html)
- [The Cycle-Accurate Game Boy Docs](https://raw.githubusercontent.com/geaz/emu-gameboy/master/docs/The%20Cycle-Accurate%20Game%20Boy%20Docs.pdf) - Useful information about STAT register/interrupts behavior.
- [Nitty Gritty Gameboy Cycle Timing](http://blog.kevtris.org/blogfiles/Nitty%20Gritty%20Gameboy%20VRAM%20Timing.txt) - To know exactly what the PPU is doing during Mode 3 (Drawing). I still can't explain the difference between the "classic" 172 dots duration and the 173.5 (or 174 dots in the current implementation) duration described by the document.
- [Trying to understand Sprite FIFO behavior in the PPU (Reddit)](https://www.reddit.com/r/EmuDev/comments/s6cpis/gameboy_trying_to_understand_sprite_fifo_behavior/) - About sprite fetching timing and FIFOs.
- https://www.reddit.com/r/EmuDev/comments/6h2asw/stat_register_and_stat_interrupt_delay_in_dmgcgb/
- https://github.com/msinger/dmg-schematics

### Test roms

- [Mooneye Test Suite](https://github.com/Gekkio/mooneye-test-suite)
- [Blargg's Gameboy hardware test ROMs](https://github.com/retrio/gb-test-roms)
- [Acid2](https://github.com/mattcurrie/dmg-acid2)
- [Mealybug Tearoom Tests](https://github.com/mattcurrie/mealybug-tearoom-tests)

### Reference emulators

- [Mooneye GB](https://github.com/Gekkio/mooneye-gb) - Used for comparison to know why gebeh was failing some tests.
- [SameBoy](https://github.com/LIJI32/SameBoy) - Used to see how roms are supposed to run. Still can't understand the code, but there are interesting comments about STAT.
- [Boytacean](https://github.com/joamag/boytacean) - Can be used in the browser directly. ~~MBC and some instructions implementation stolen from here.~~ (replaced with new code, thanks Boytacean!)
- [RGY](https://github.com/YushiOMOTE/rgy) no-std emulator - Used its PPU implementation to test the CPU at first.

### Debugger & Disassembler

- [Gameroy](https://github.com/Rodrigodd/gameroy). It's an emulator too! Used it to know what Snorpung demos were doing. Used as a reference to pass blargg sound test roms.

### Stress test roms

- [Beautiful demos](https://files.scene.org/browse/demos/groups/snorpung/) by Snorpung.
Download original README

Original project README source

Release log

Selected releases and changes, with coverage from our weekly emulation roundup.

    Sources & further reading

    FROM THE COMMUNITY

    Player reviews

    0 reviews
    6.0/ 10

    Overall rating

    Provisional site rating and approved member scores, each counted once.

    Starting site scores are provisional editorial scores. Established mainstream projects receive a higher starting score; other imported entries begin at a neutral 6/10 pending individual review. Member scores change the average after approval.

    Your take on gebeh

    Spam has been overwhelming. To help us approve your review, sign up and introduce yourself in the Introductions forum so we know you’re not a bot.

    Sign in with your Retro Replay account to rate this project and share your experience.

    Sign in to review