MonsterMesh

A Game Boy emulator, a monster-battling RPG, and a WiFi/BLE security toy — all running over the Meshtastic LoRa mesh, no internet required.

MonsterMesh is a fan-made, open-source project (GPL-3.0) that turns off-the-shelf mesh-radio hardware into a portable Game Boy that also networks with other players over long-range LoRa radio. Raise a team, earn badges, battle other trainers over the air, and let your monsters socialize in a mesh-wide daycare while you’re away.

No ROMs included. MonsterMesh ships no copyrighted game ROMs, saves, or assets. You supply your own legally-obtained Game Boy .gb ROM. It’s an unofficial, non-commercial fan project, not affiliated with Nintendo, Game Freak, or The Pokémon Company.

Three platforms

MonsterMesh runs on three kinds of hardware, one per branch of the GitHub repository:

• LilyGO T-Deck (ESP32-S3 handheld) — the flagship build: a full Game Boy emulator plus the monster-RPG and mesh daycare, as a Meshtastic firmware module. → branch main
• Raspberry Pi (RetroPie / GPi Case handheld) — the same RPG, daycare, and LoRa battles as a terminal app (mmd daemon + mmterm). → branch mm/monster-mesh-pi
• Pentest Pikachu (Heltec V3 / V4 / T114) — turns the radio into a Pokémon-themed WiFi/BLE security auditor, where nearby wireless vulnerabilities spawn monster battles. → branch pentest-pikachu

All three share one deterministic Generation-1 battle engine and mesh protocol, so T-Deck, Pi, and Heltec players interoperate over the same mesh.

Documentation

Guide	What’s inside
Gameplay	Gyms, the Elite Four, explore, New Game+, the in-game terminal
Architecture	How the module hooks into Meshtastic: threads, mode switching, SPI/SD hygiene
Battle engine	The deterministic Gen-1 engine, desync detection, and data pipeline
Daycare	The mesh daycare: beacons, events, friendship/rivalry, save write-back
Multiplayer	Player-hosted gyms, live PvP battles, and the LoRa wire protocol
Themes	The theme system and fonts
Building & flashing	Build from source, USB/OTA flashing, and safety cautions
Credits	Open-source attributions and licenses

Get the code

git clone https://github.com/GoatsAndMonkeys/monster_mesh.git
cd monster_mesh
pio run -e t-deck-tft          # T-Deck firmware (main branch)

For the Raspberry Pi build see the Pi README; for the Heltec pentest builds check out the pentest-pikachu branch.

---

_{MonsterMesh is a fork of Meshtastic firmware (GPL-3.0). Built on Peanut-GB, Pokémon Showdown data, PokéAPI, and LVGL. See Credits.}