Pebbleboy is a Game Boy and Game Boy Color emulator for Pebble Time 2. It uses Peanut-GB for the CPU and LCD core, a native 16 kHz/16-bit PCM mixer for audio, and the touchscreen for directional controls. Pebble Time 2 is the only supported watch.
Pebbleboy does not contain or distribute commercial Game Boy ROMs. You must provide ROM images that you are legally entitled to use.
During a game:
| Pebble input | Game Boy input |
|---|---|
| Select button | A |
| Down button | B |
| Up button | Start |
| Back click | Select |
| Touchscreen direction | D-pad |
To toggle best-effort 2× fast-forward, press the Game Boy Start+Select twice within one second (hold the watch's Up button and double-click Back). Fast-forward pauses audio until normal speed is restored.
Pebbleboy has one emulator build and two ways to deliver a ROM:
| Package | ROM delivery | Firmware |
|---|---|---|
| Loader/ROM chooser | Configure a URL; the phone downloads the selected ROM once and installs it into watch flash | Pebbleboy CFW |
| Personal preloaded PBW | Run the Linux build script with a ROM from your own filesystem | Stock Firmware (no sound rn) |
Both use the same 192-line cache. The loader requires Pebbleboy CFW for the app-blob API and speaker fixes. Personal preloaded PBWs run on stock firmware with sound disabled.
About audio: The CFW includes speaker and scheduler fixes submitted in audio PR #2039. Preloaded PBWs keep sound disabled until the required audio fixes land upstream.
The file Pebbleboy.pbw in releases is the ROM-free CFW build and can be shared.
THE LOADER REQUIRES SIDELOADED FIRMWARE
ROM-free CloudPebble and local SDK builds produce the CFW-compatible loader. Once the required firmware APIs are official, the compatibility stamp and temporary veneers can be removed without changing the emulator cache.
Anyway...
- Sideload the Pebbleboy CFW and connect the watch to its companion phone.
- Open Pebbleboy's settings in the Pebble mobile app.
- Add one or more game names and direct-download ROM URLs (or base64 text URLs).
- Choose display scaling and whether speaker audio is enabled, then tap Save and launch. One game starts automatically; multiple games appear in the watch menu, where Up/Down and Select choose a game.
- The phone transfers the selected ROM once; subsequent launches read it directly from watch flash. Opening settings pauses emulation and shows a message on the watch until settings closes.
Each URL must return either a binary .gb/.gbc file or plain base64. Indirect downloads
from random ROM website's won't work. I won't tell you where to find ROMs that
are hosted in this way, unfortunately...
If hosting a distribution URL yourself for your homebrew roms for example, the
host must allow the Pebble phone JavaScript to fetch the URL. HTTPS and an
Access-Control-Allow-Origin: * response header are recommended.
The settings editor is hosted at https://ptv.netcavy.net/gb/. Existing ROM
names and URLs are passed to it in the URL fragment, which browsers do not send
to the web server. The static source for the page is in config/index.html.
The library supports up to 12 entries. One selected ROM is installed on the watch at a time. The phone may also cache the active download. Each game keeps its own save in watch storage, and saves sync to the phone. Switching ROMs preserves those saves. Gameplay and saving do not depend on a Bluetooth connection; see Loader ROMs and saves below.
In the loader build, the phone fetches the selected 32 KB–8 MB cartridge and transfers it in checked AppMessage chunks. I'm so sorry. CFW then stores it in a filesystem blob owned by Pebbleboy's UUID. This is a CFW-unique app-blob API to persist and read up to 8 MB from watch flash. The blob is committed only after its size and CRC32 verify so the transfer knows it got everything. The emulator then reads cartridge banks locally from flash through its RAM cache. Installing another game replaces the installed ROM and preserves each game's separate save; it does not require a new PBW.
In a personal build, the cartridge is packaged as a PBW resource instead. That PBW is personal to the supplied ROM and has no runtime downloader. It still uses the same 24 KiB cache and reads ROM and SRAM from flash.
Prebuilt DVT and PVT firmware containing the app-blob API and speaker scheduling/DMA fixes (audio PR #2039) is published from my PebbleOS fork. The firmware notes explain hardware selection, sideload precautions, source patches, and the automatic upstream-sync process. Each release contains a merged PBZ with both firmware slots done by github actions for each upstream release, but feel free to compile it yourself if you want to feel extra safe after reading the code yourself :) I accept no liabilities if my app rewrites something it wasn't supposed to when loading your ROM into it.
The current Time 2 speaker API accepts Pebbleboy's mono signed 16 kHz/16-bit PCM format. Disabling audio reduces CPU load so it might improve performance, but most issues are just a bottleneck from the flash or screen scaling.
You need official Pebble SDK 4.33 or newer. To build the universal CFW loader:
pebble buildLinux users can package a ROM from their own filesystem into a personal PBW:
tools/build-rom.sh /path/to/game.gbcThe script uses the normally installed pebble command and active official SDK
from PATH. It builds in a temporary directory and writes the finished PBW to
dist/ by default. Pass --output FILE to choose another destination.
Personal preloaded PBWs support ROMs up to 8 MB and use the 24 KiB cartridge cache. They run on stock firmware with sound disabled; no CFW option is needed.
Please ensure you are allowed to distribute the ROM you bundle with Pebbleboy if you plan to share your own release.
For low-level development, the equivalent manual embedded-ROM environment is
PEBBLEBOY_EMBED_ROM=1 pebble build, with the ROM at
resources/data/cartridge.gb.
Each game can have its own save slot. Save in-game as usual; switching games keeps your saves, and saving works without your phone nearby. Saves sync with the phone when connected, using the most recent in-game save or import.
- Import: Add a save slot and upload a matching
.savfile (up to 32 KiB). It replaces that game's save and loads when you launch the game. - Export: Choose Export .sav, copy the download link into Chrome or Safari, then tap Download .sav.
Export important saves before clearing phone app data or changing phones.
The emulator core is based on Peanut-GB by Mahyar Koshkouei and contains
credited MIT-licensed portions from SameBoy. See src/c/peanut_gb.h for its
licence and notices.
Pebbleboy is distributed under the MIT License. Third-party copyright and licence information is collected in THIRD_PARTY_NOTICES.md and retained in the relevant source files.