About

CAMLBOY is a Game Boy emulator that runs in the browser. It is written in OCaml and compiled to JavaScript using js_of_ocaml (edit: After #15 CAMLBOY is now compiled to WASM!).

Try it out in our demo page!

Accompanied Posts and Videos

Posts

• English: https://linoscope.github.io/writing-a-game-boy-emulator-in-ocaml/
• 日本語: https://qiita.com/linoscope/items/244d931aaae07df2c27e

Videos

• Talk at Functional Conf 2025: https://www.youtube.com/watch?v=hFzHqxMar3g

Screenshots

Project goals and non-goals

Goals

• Playable in the browser of middle-tier/high-tier mobile devices
• Readable/maintainable code that follows OCaml's best practices

Stretch goals

• Achieve stable 60fps in low-tier mobile devices
• Serve as a benchmark target for various compile backends, similar to optcarrot in the Ruby world. Would be especially interesting if we can compare the performance of various JS/wasm backends, such as js_of_ocaml, Rescript, Melange, and ocaml-wasm.

Non-goals

• Run all games with high accuracy
• Optimize performance to the limit at the expense of code readability

Current state

• Runs with "playable" FPS in middle-tier mobile devices. (It runs at 60FPS for most games in my Galaxy S9, a smartphone released in 2018)
• Runs with ~1000FPS, with UI, in native
• Supports headless benchmarking mode, both for native and web, that runs without UI
• Passes various test ROMs such as Blargg's cpu_insrts.gb and instr_timing.gb (tests using Blargg's test ROMs can be found here, and tests using Mooneye's test ROMs can be found here).

Benchmark results

We ran the first 1500 frames of Tobu Tobu Girl in headless mode (i.e., without UI) for ten times each and calculated the average FPS. The error bars represent the standard deviation. See benchmark.md for details about the environment/commands used for the benchmark.¹

Architecture diagram

Here is a rough sketch of the various modules and their relationship. You can find details in the accompanied blog post.

Directory Structure

• lib - Main emulator code
• bin - UI code
  • web - Web
  • sdl2 - SDL2
• test
  • unit_test - Unit tests
  • rom_test - Integration tests that use test roms
• resource
  • games - Game roms
  • test_roms - Test roms used in rom_tests

TODO

• Cartridge based save
• Audio Processing Unit (APU)
• Rescript backend
• MBC5
• Game Boy Color mode

Quick Start

Prerequisites

• opam 2.1+

Build

git clone https://github.com/linoscope/CAMLBOY.git
cd CAMLBOY
opam switch create . --locked --with-test
eval $(opam env)
dune build

How to run

Run with SDL2 UI (native)

dune build
# Usage: main.exe [--mode {default|withtrace|no-throttle}] <rom_path>
dune exec bin/sdl2/main.exe -- resource/games/tobu.gb

Run with Web UI (js_of_ocaml/wasm)

dune build
# Serve the web directory
python -m http.server 8000 --directory _build/default/bin/web
# Open localhost:8000 in your browser

How to run benchmarks

Native benchmark

# Usage: bench.exe [--frames <frames>] <rom_path>
dune exec bin/sdl2/bench.exe -- resource/games/tobu.gb --frames 1500

Web benchmark

After starting the web server (see above), open: http://localhost:8000/bench.html?frames=1500&rom_path=./tobu.gb

How to run tests

# Run all tests:
dune runtest
# Run unit tests only:
dune runtest test/unit_test/
# Run integration tests (tests that use test ROMs):
dune runtest test/rom_test/

Updating the lock file

After modifying dependencies in dune-project:

opam pin add camlboy.dev . --no-action
opam lock camlboy

Commit the updated camlboy.opam.locked file.

Resources

• Pandocs
• Game Boy CPU Manual
• gbops
• GBEDG
• Imran Nazar's blog
• codeslinger.co.uk

Source of built-in game ROMs:

• The Bouncing Ball
• Tobu Tobu Girl
• Retroid
• Into The Blue
• Wishing Sarah
• Rocket Man Demo
• SHEET IT UP
• Cavern

Footnotes

1. Note that we can not use this benchmark to compare the FPS with other Game Boy emulators. This is because the performance of an emulator depends significantly on how accurate it is and how much functionality it has. For example, CAMLBOY does not implement the APU (Audio Processing Unit), so there is no point in comparing its FPS with emulators with APU support. ↩