gm0

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.

Status

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.

Building

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.

Embedded games

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.

Usage

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

ESPboy

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.

Controls

  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.

Platform differences

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)

Accuracy

gm0 targets the hardware rather than other emulators: parity with the original TypeScript emulator was dropped deliberately in October 2026.

Performance

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.

Debugging

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

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.

Known limitations

Planned and investigated work is tracked in TODO.md.

Development

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.

Credits and references

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.

License

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.

Gamebuino AKA

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.