A cycle-counted emulator for the Gamebuino META (SAMD21, Cortex-M0+), the Pokitto (LPC11U6x, Cortex-M0+) and the ESPboy (ESP8266, Xtensa LX106), written in C with an SDL2 frontend and a WebAssembly build.
Version française : README.fr.md
gm0 runs unmodified firmware for the three consoles from a single binary. The
target is detected from the firmware image (initial stack pointer in SAMD21
or LPC SRAM; 0xE9 image header or ELF for the ESPboy) and can be forced with
--target (META and Pokitto). The same C core is compiled
natively and to WebAssembly.
.pop container support.ets_*, flash functions, timer1, GPIO and the sigma-delta
audio output, SPI1 to the ST7735 (128×128), the MCP23017 buttons..zip, or a host folder
converted to FAT16 on the fly; saves written by games are written back.| Target | State | Tested titles |
|---|---|---|
| Gamebuino META | Playable | lapinou (bare-metal drivers), Celeste, Cats & Coins, Picomon, Yatzy, Reuben Quest, site loaders, converted Game Boy firmwares (DMA/SPI protocols 0.4.0+) |
| Pokitto | Playable | Pandemic, Galaxy Fighters (.pop with music streamed from the card) |
| ESPboy | Boots and plays m0boy firmwares (Game Boy, SG-1000, Game Gear, Master System) | firmwares converted by m0boy; not checked against a console |
| WebAssembly | Playable | same core; served page or single self-contained HTML file |
The repository ships no games or firmware.
Native build with CMake (requires SDL2 and zlib; Linux, macOS, Windows via MSYS2 MinGW-w64):
cmake -B build .
cmake --build build # produces build/bin/gm0
The interface is in English by default; configure with -DGM0_FR=ON for
French. Short on-screen messages (reset, filter, scale, load) are on by
default; -DGM0_OSD=OFF removes them.
WebAssembly build (requires emsdk with emcc on PATH):
make wasm # produces wasm/gm0.html
The output is a single file with the wasm module embedded; it can be opened
directly from file://. A hosted build is available at
https://r043v.github.io/gm0/ (emulator only — load your own games).
Windows, cross-compiled from Linux with MinGW-w64, as a single gm0.exe (SDL2
linked in). With the native packages installed (mingw-w64-gcc,
mingw-w64-binutils, mingw-w64-crt, mingw-w64-headers,
mingw-w64-winpthreads, mingw-w64-sdl2 and mingw-w64-zlib from the AUR):
make win # build-win/bin/gm0.exe
Without them, make win-setup installs the same toolchain under
~/.local/mingw-w64 (about 440 MB, no root), then make win works the same
way. make win WIN_STATIC=OFF keeps SDL2 in a separate SDL2.dll.
main runs META/Pokitto firmwares. Direct SG-1000 cartridge support lives on
z80.
Build a native executable that starts your game without arguments:
cmake -G Ninja -S . -B build-bundle -DGM0_BUNDLE=/path/game.zip
cmake --build build-bundle
GM0_BUNDLE accepts a .bin or .pop firmware, or a ZIP containing the
firmware and its SD assets (including any ROM needed by the firmware).
Use a ZIP for games that read files from the card. A raw Game Boy ROM must
first be converted to a META/Pokitto firmware with m0boy. An explicit game
or card argument overrides the embedded game. Windows builds use static
SDL2 by default when available.
For a single HTML that starts the embedded game (emsdk required):
emcmake cmake -G Ninja -S . -B build-wasm -DGM0_WEB_GAME=/path/game.zip
cmake --build build-wasm # build-wasm/gm0.html
GM0_WEB_GAME accepts the same game formats. The module and game are embedded
in the HTML for offline use; browser audio still requires a user gesture.
Keep user-provided games and generated builds outside tracked sources.
gm0 [firmware] [card] [options]
| Argument | Meaning |
|---|---|
firmware |
.bin, or .pop (Pokitto) |
card |
.img raw image, .zip (full card), or a folder (FAT16 built on the fly). On the META the card defaults to the firmware’s folder. |
--target meta\|pokitto |
force the target |
--rom file, --sym file |
ESPboy: ROM image (rom.bin, flash 0x100000) and symbol file of a .bin (default: rom.bin and <name>.sym / firmware.sym next to it) |
--frames N |
run N frames, then exit |
--shot file.ppm |
write a screenshot at exit |
--wav file.wav |
record the session audio (48 kHz, rendered from emulated time) |
--out-img file.img |
export the card on exit if it was modified |
--eeprom-ro |
Pokitto: load the .eeprom next to the firmware but never write it back (reproducible runs) |
--record-input file |
record the session: held keys per gm0 frame (k lines) and, for an m0boy firmware, the buttons the emulated game receives with the game’s frame number (g lines), read through the firmware’s m0input descriptor; r marks a restart, e the end |
--play-input file |
replay the keys (k lines) of a recorded session, frame for frame |
--play-guest file |
replay a session by game frame (its g lines, m0boy firmwares): each time the firmware writes the emulated game’s buttons, they become the recorded state for the game’s current frame, so a faster or slower firmware plays the very same game (firmware comparisons; META and Pokitto) |
--until-guest N |
stop when the game’s frame counter reaches N; --dump-ram then holds the RAM of that instant |
--resume-at N |
with --play-input: fast forward (no pacing, one screen in thirty) to gm0 frame N, then hand over to the player; N is a snapshot |
--dump-ram file |
write the main RAM at exit (META SRAM from 0x20000000, Pokitto from 0x10000000, ESPboy DRAM from 0x3FFE8000): counters of the firmware, read by symbol |
-w [n], -W |
Pokitto: ignore the next n (or all) faulting flash writes instead of raising a HardFault |
Started without arguments, the window opens empty; games can be dropped onto
it (.bin, .img, .zip, folder). The run ends with a [bench] line
reporting raw emulation speed.
Headless runs (tests, captures):
SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy \
gm0 game.bin card/ --frames 300 --shot shot.ppm
gm0 game.zip # firmware.bin + firmware.sym [+ rom.bin], as m0boy's compile.sh packs it
gm0 firmware.bin --rom rom.bin # firmware.sym is looked up next to it
gm0 firmware.elf [--rom rom.bin] # the ELF carries the symbols
The ESPboy build keeps the machine honest where the code is the firmware’s
(Xtensa core, memory map with the chip’s access rules: byte and halfword loads
from IRAM or the mapped flash stop the run, as LoadStoreError does on the
chip) and approximate where the code is Espressif’s: the boot ROM and the SDK
are not shipped here, so what the firmware calls of them is emulated by
function. Start-up (eboot, app_entry, user_init) is not run: the
machine does what it leaves behind (cont stack, timer1 ISR, C++ constructors)
and calls setup() then loop(). Hooked by symbol name (firmware.sym, or the
ELF): micros, delay, system_update_cpu_freq, twi_writeTo/readFrom,
spi_flash_read/write/erase_sector, system_restart, watchdog and Wi-Fi mode
calls. Anything else of the ROM that is called and not emulated stops the run
with its name.
MULL,
+2 per taken branch or call (RET +3), +1 when the next instruction uses a
register a load has just filled, MEMW 4 after a store, +5 per load from
IRAM, ROM or the mapped flash (literals included), +15 per peripheral
register read and +10 per write (half in cycles at 80 MHz, bus time), none
from DRAM. Not validated here, and not in that reference: the cost of an
instruction-cache miss (GM0_ESP_FLASH_MISS=<cycles per 32-byte line> turns
on a 32 KiB direct-mapped model, off by default), SPI bytes at the clock the
firmware programs, flash erase 45 ms and program 0.7 ms per page. So these
are estimates built on measured instruction costs, not measurements of this
firmware on the chip.MADCTL
mirroring, 12/16/18-bit pixels) with what the ESPboy’s panel does:
column and row addresses keep only their low byte, SWRESET keeps MADCTL
and COLMOD, the panel is BGR (MADCTL.BGR clear swaps red and blue at scan
time, memory already written included), white while asleep or off, and it
listens only while MCP23017 B0 (chip select) is low. With TFT_eSPI’s setup
(MADCTL 0xC8, window column 2, row 3, as m0boy’s firmware) the glass pixel
(x, y) is memory (129 − x, 128 − y). Partial mode, scrolling and idle are not
modelled.0x3C0000-0x3FB000) persist in <name>.sav next
to the firmware (or the zip).tests/esp/run_tests.py compares the Xtensa core and the ROM
functions with the host on C programs built for lx106 at several
optimisation levels; tests/test_esp.py runs a small firmware through the
whole machine (display, buttons, timer1 audio, flash saves). Both need
PlatformIO’s toolchain-xtensa and are skipped without it.| META | Pokitto | |
|---|---|---|
| D-pad | arrows | arrows |
| A / B | Space / Ctrl | Space / Ctrl |
| MENU / menu key (m0boy) | Enter / H (HOME) | Enter / H (C) |
| HOME / backlight | * or I (hold 3 s to reset the game) |
F |
ESPboy (META keys): D-pad as the META, A = ACT (J), B = ESC (K), MENU (U) = right auxiliary button (Start), HOME (I) = left auxiliary button (Select; hold for the Game Boy frontend’s menu).
| Key | Action |
|---|---|
| F2 | snapshot: the gm0 frame, noted (s line) in the --record-input recording |
| F4 | back to the last snapshot: gm0 starts again cold (same process) and fast-forwards the keys held until then; the recording, rewritten from power-on, goes on (META, Pokitto) |
| F5 | reset |
| F8 | display filter, cycled: pixel (default), Game Boy green (DMG), LCD RGB, scanlines, grid, none |
| F10 | scaling mode: integer, fitted, stretched |
| F11 | fullscreen |
Game controllers are supported through SDL_GameController with hot-plug, on
both targets. The META button shift-register bit order follows the SPI speed
the game reads it at; EMU_BTN_ORDER=lapinou forces the homebrew order.
| Feature | Native | WebAssembly |
|---|---|---|
| Audio | SDL2, locked to emulated time (±0.5 % rate regulation) | WebAudio, starts on first user gesture |
| Saves | .SAV/.STA written back to disk; Pokitto EEPROM persisted as <game>.eeprom |
in memory, lost when the tab closes |
| Flash self-programming (loaders) | emulated | ignored |
| Game list | — | one-click dock (wasm/games.js), games can be embedded in the standalone file |
| Pause | — | dock buttons (pause, stop) |
gm0 targets the hardware rather than other emulators: parity with the original TypeScript emulator was dropped deliberately in October 2026.
Measured on the development machine (x86-64, GCC 16, -O3 -flto), raw speed
without frame pacing, as a multiple of real time:
| Title | Target | Speed |
|---|---|---|
| lapinou | META | 4.4× |
| Celeste | META | 4.6× |
| Cats & Coins | META | 5.5× |
| converted Game Boy firmware (sml) | META | 5.0× |
| Pandemic | Pokitto | 4.1× |
| converted Game Boy firmware (sml) | ESPboy | 1.6× |
Numbers depend on the host and its load. The WebAssembly build runs at full speed in current browsers.
Diagnostics are enabled through environment variables; the most useful:
| Variable | Effect |
|---|---|
EMU_INPUT="frame:keys:len,..." |
scripted input (keys among UDLRABMH), e.g. 200:A:5,300:R:40; H is the m0boy menu key on every console (the META’s HOME, the Pokitto’s C). Aka also accepts C (C), X (D), Q (L1), E (R1) |
EMU_NOPACE=1 |
run as fast as possible (benchmarks) |
EMU_TRACE=1 |
screen hash every 60 frames, periodic CPU trace |
TRACE_TAIL=N |
keep the last N executed instructions, dumped on a wild PC |
EMU_PROF=file |
per-address cycle profile written at exit |
EMU_AUDIO_STATS=1 |
audio producer/consumer statistics |
EMU_FIXED_RTC=t, ADC_FIXED=1 |
deterministic RTC and ADC |
EMU_DEBUG=1, SD_DEBUG=1, NVM_DEBUG=1, EMU_DMA_DEBUG=1, EMU_LCD_DEBUG=1, EMU_SYSCTRL_DEBUG=1 |
peripheral traces |
FAT_DUMP=file, FAT_DUMP_EXIT=file |
write the FAT image as built at mount, or the card at exit |
FLASH_DUMP=file |
write the META flash at exit (after any self-programming) |
tests/unit/run.sh # core unit tests (flash programming)
GM0_GAMES=dir tests/parity/run.sh build/bin/gm0 # bit-exact parity on local games
tests/parity/run.sh runs each game listed in tests/parity/games.txt
(1500 frames, scripted input) and compares three SHA-256 fingerprints with
tests/parity/refs.txt: the screen (EMU_TRACE lines), the --wav
recording and the --shot capture. The games are not in the repository
(GM0_GAMES defaults to wasm/). Each game runs alone in a throwaway
directory, with --eeprom-ro, so no saved EEPROM is inherited. Rewrite the
references (-u) only after a change that is meant to alter the output.
dirent.h); MSVC is untested.Planned and investigated work is tracked in TODO.md.
gm0 was written entirely by AI coding agents; no C code was typed by hand. The first version — about 5,800 lines of C and 66 commits, from September 30 to October 6, 2026 — was produced by GLM-5.3-Flash through the ZCode agent. Statistics for that week, from the session database:
Later refactoring, hardware-accuracy fixes and performance work were co-authored with Claude Opus 5.5 in Claude Code.
Jicehel shared the Aka QEMU emulator. Its expander and ADC models, image checker, and Launcher sources clarified the Aka CORE v1.4 input wiring and ESP image format used in gm0. See Aka support.
Logic was ported from two MIT-licensed emulators:
Everything else follows the vendor documentation:
Hardware behaviour was also established by analysing real software, without reusing any of its code: the lapinou source (bare-metal display, SD and audio drivers, which exposed the display DMA/SPI protocol, TC4 clocking and the chip-select pull-ups), META binaries, and the official Gamebuino META library (SdFat stack, DMAC descriptors, TC5 audio), stepped through in the emulator.
Ecosystems: gamebuino.com for the META, PokittoLib for the Pokitto.
gm0 is released under CC BY-NC-SA 4.0 (© 2026 r043v): attribution, non-commercial, share-alike.
Logic derived from the two MIT-licensed emulators remains under MIT; their notices are reproduced in LICENSE: aoneill01/gamebuino-emulator (Andy O’Neill, 2017) and felipemanga/PokittoEmu (Felipe Manga, 2017). Implementing behaviour described in vendor datasheets (Microchip, NXP, Sitronix, Arm) does not create a derivative of those documents, and no code was taken from the lapinou source, META binaries, or the official library.
Thanks to Jicehel for sharing his QEMU-based Aka emulator: its expander and ADC models, image checker and Launcher sources improved gm0’s buttons, joystick, battery and ESP image loading.
gm0 executes the firmware’s own Xtensa code (experimental application-level
emulation): an ELF with symbols, or a .bin/.zip shipped with its
firmware.sym (gm0 game.zip). Platform services are hooked by name; an
unknown instruction or service stops with a diagnostic.
The optional full-system mode boots the bootloader, FreeRTOS and drivers in Jicehel’s QEMU emulator, installed separately (Linux and other POSIX hosts):
gm0 game.bin --aka-system /path/to/aka-emulator [--aka-sd card-folder] [--aka-flash file]
--aka-sd serves a folder as the Launcher’s SD card (one sub-folder per
application: firmware.bin, meta.json); --aka-flash keeps the flash —
installed games and saves — between runs.
See usage, services and limits.