GoatsAndMonkeys/monster_mesh
GitHub: GoatsAndMonkeys/monster_mesh
基于 Meshtastic LoRa mesh 网络的嵌入式 Game Boy 模拟器与第一代怪物对战 RPG 项目，支持离线多人对战和跨平台互通。
Stars: 12 | Forks: 1
# MonsterMesh
**一款作为 Meshtastic 模块运行在 LilyGO T-Deck 上的 Game Boy 模拟器和怪物对战 RPG —— 培养你的团队、赢取徽章，并通过 LoRa 无线电与其他训练家对战，无需网络连接。**
**版本：** pre-alpha · **状态：** 积极开发中 —— 预计会有 bug 和破坏性更新。
## 这是什么？
MonsterMesh 能将 [LilyGO T-Deck](https://www.lilygo.cc/products/t-deck)（配备 QWERTY 键盘、彩色 TFT 屏幕、SX1262 LoRa 无线电模块和 SD 卡的 ESP32-S3）变成一台便携式 Game Boy，同时还能通过 [Meshtastic](https://meshtastic.org) mesh 网络与其他 T-Deck 进行网络通信 —— 无需服务器，无需网络，仅依靠远距离 LoRa 无线电。
它是 **Meshtastic 固件的一个分支**，仅添加了一个额外的模块（`src/modules/monstermesh/`）。Meshtastic 原有的所有功能 —— 消息传递、GPS、遥测、节点地图 —— 都能正常工作。按下一个按键，同一台设备就会变成一台 Game Boy；模拟器和一整套怪物 RPG/社交层将与 mesh 协议栈并行运行。
在原始模拟器的基础之上，MonsterMesh 添加了原生的**第一代战斗引擎**、一个覆盖整个 mesh 的**托管所**（当你不玩游戏时，你的队伍会与附近节点上的怪物进行社交）、**“喷火龙传说”**（Legend of Charizard）道馆与徽章 RPG（八个道馆加上四天王）、**玩家托管的道馆**（其他训练家可以在 mesh 网络上发现并挑战），以及通过无线电进行的**实时训练家对战**。
## MonsterMesh 项目 —— 三个平台，三个分支
MonsterMesh 是一个运行在三种不同类型硬件上的游戏世界。每一种都位于本仓库的独立分支上：
| 平台 | 分支 | 硬件 | 它是什么 | 构建 |
|----------|--------|----------|------------|-------|
| **T-Deck**（此分支） | [`main`](https://github.com/GoatsAndMonkeys/monster_mesh/tree/main) | LilyGO T-Deck (ESP32-S3) | 作为 Meshtastic 模块的 Game Boy 模拟器 + 第一代战斗 RPG + mesh 托管所 | `pio run -e t-deck-tft` |
| **Raspberry Pi** | [`mm/monster-mesh-pi`](https://github.com/GoatsAndMonkeys/monster_mesh/tree/mm/monster-mesh-pi) | Raspberry Pi / RetroPie 掌机（例如 GPi Case 2W） | 作为 ncurses 终端（`mmd` 守护进程 + `mmterm`）的相同 RPG/托管所/战斗层，通过 USB 与 Meshtastic 节点通信 | `cmake` —— 参见 [Pi README](https://github.com/GoatsAndMonkeys/monster_mesh/blob/mm/monster-mesh-pi/monster_mesh_pi/README.md) |
| **Pentest Pikachu** | [`pentest-pikachu`](https://github.com/GoatsAndMonkeys/monster_mesh/tree/pentest-pikachu) | Heltec V3 / V4 (WiFi) · Heltec T114 (BLE) | 将无线电设备变成一个 Pokémon 主题的 WiFi/BLE 安全审计器 —— 附近的漏洞会触发怪物对战 | `pio run -e heltec-v3` / `-e heltec-v4` / `-e heltec-t114-pet` |
这三者共享相同的确定性第一代战斗引擎和 mesh 协议，因此 T-Deck、Pi 和 Heltec 玩家可以在同一个 LoRa mesh 上互联互通。**本 README 介绍的是 T-Deck 的构建版本。**
## 目录
- [功能](#features)
- [硬件](#hardware)
- [控制](#controls)
- [终端命令参考](#terminal-command-reference)
- [入门指南](#getting-started)
- [从源码构建](#building-from-source)
- [文档](#documentation)
- [项目结构](#project-structure)
- [致谢与开源声明](#credits--open-source-acknowledgements)
- [法律与商标](#legal--trademarks)
- [许可证](#license)
## 功能
### 🎮 Game Boy 模拟器
- 在 ESP32-S3 上全速运行第一代怪物游戏（以及其他 GB/GBC 游戏），由 [Peanut-GB](https://github.com/deltabeard/Peanut-GB) 提供支持。
- T-Deck 的 QWERTY 键盘映射为 Game Boy 控制按键。
- SD 卡**文件浏览器**用于选择 ROM；ROM 和电池存档（`.sav`）可直接从卡中加载。
- 通过板载 I2S 音频输出声音（[minigb_apu](https://github.com/deltabeard/Peanut-GB)）。
- 当你切换回 Meshtastic UI 时，模拟器会在后台继续运行。
### 🧬 mesh 网络上的托管所
当你没有主动玩游戏时，你的六只队伍怪物会向一个覆盖全 mesh 的托管所“签到”。
- 直接从你的 Game Boy 存档（第一代 SRAM）中读取物种、等级、昵称、招式和经验值（XP）。
- 通过 LoRa 广播紧凑的队伍信标；附近的节点会成为托管所邻居。
- 一个**双层事件生成器**（手写模板 + 组合式句子拼接）会叙述你的怪物在其他节点上的怪物那里做了什么，并通过私信发送给另一位训练家的节点。
- 特定组合对之间的**友谊与竞争**得分会在整个 mesh 中增长。
- 在托管所中获得的经验值（XP）会被**写回你的存档文件**（包含第一代经验曲线 + SRAM 校验和修复），因此进度会在你下次启动游戏时显示出来。
- **34 项成就**，其中稀有的成就会广播到整个 mesh 网络。
- 可选的受 WiFi 限制的**天气**事件和基于 GPS 的**日/夜**事件。
参见 [docs/DAYCARE.md](docs/DAYCARE.md)。
### ⚔️ 原生第一代战斗引擎
- 一个从零开始用 C++ 编写的第一代战斗引擎（`Gen1BattleEngine`）—— 包含属性克制、本系加成（STAB）、击中要害、能力阶以及第一代的平局和命中度判定特性。
- 能力值根据基础能力值 + 等级进行计算；真实的招式集会从你加载的存档中读取。
- **确定性和纯输入驱动**，因此它可以在两个节点上仅通过交换招式（加上用于检测状态不同步的定期状态哈希值）来运行*相同*的战斗。
- 战斗数据（基础能力值、招式）来源于 [Pokémon Showdown](https://github.com/smogon/pokemon-showdown)。
参见 [docs/BATTLE_ENGINE.md](docs/BATTLE_ENGINE.md)。
### 🏆 喷火龙传说 —— 道馆 RPG
一个构建在战斗引擎之上、类似门游戏的 RPG 层，其状态在重启后依然保留，并且每天重置：
- **1–9 号道馆** —— 逐一挑战八个关都风格的道馆以赢取徽章，然后挑战**9 号道馆：石英高原**（Indigo Plateau）（四天王 + 冠军）。
- **探索** —— 在某条路线上进行每日的野生遭遇战。
- **二周目（New Game+）** —— 一旦你通关了联盟，道馆和四天王就会升级，开启新一轮的挑战。
- 持久化的**徽章**、一个**新闻**轮播以及每次挑战的统计数据。
参见 [docs/GAMEPLAY.md](docs/GAMEPLAY.md)。
### 📡 LoRa 上的多人游戏
- **MonsterMesh 道馆（`mmg`）** —— 将你自己的队伍作为道馆托管，供其他训练家发现；`mmg` 会发现 mesh 上的道馆，而 `mmg fight N` 会挑战已发现道馆的**五人阶梯赛**。
- **MonsterMesh 对战（`mmb`）** —— 一场**实时**的训练家之间的对战：通过私信发起挑战/接受的握手过程，然后进行一场确定性的网络战斗，双方仅通过无线电交换招式。
- **本地 `fight`** —— 一场针对附近训练家发布的信标队伍的即时 CPU 对战（一场“镜像战”），无需任何协调。
参见 [docs/MULTIPLAYER.md](docs/MULTIPLAYER.md)。
### 🎨 七种 Game Boy 主题
一个覆盖全设备的主题系统：**Dark**（深色）、**Light**（浅色）、**DMG**（经典 LCD 绿）、**GBC**（Color 青色）、**Pocket**（高对比度绿）、**Poke Blue**（宝可蓝）和 **Poke Red**（宝可红）。绿色主题会将整个 UI 切换为清晰的 [Cozette](https://github.com/slavfox/Cozette) 位图字体。可以通过 Meshtastic 的“设置 → 主题”下拉菜单进行更改。
参见 [docs/THEMES.md](docs/THEMES.md)。
## 硬件
- **LilyGO T-Deck** —— ESP32-S3、16 MB 闪存、8 MB PSRAM、320×240 TFT 屏幕、QWERTY 键盘、SX1262 LoRa、micro-SD 卡槽、I2S 扬声器。
- 一张 **micro-SD 卡**（FAT32 格式），用于存放你自己的 `.gb` ROM 和 `.sav` 存档文件。
- 需要**两台（或更多）T-Deck** 才能使用多人游戏功能。
MonsterMesh 仅针对 T-Deck 目标平台（`-D T_DECK`）进行构建；该模块在所有其他 Meshtastic 板型上均会被略过编译。
## 控制
### 切换模式
| 按键 | 操作 |
|-----|--------|
| **Ctrl+E**（或 **SYM+E**） | 在模拟器和 Meshtastic UI 之间切换 |
| **ALT**（在 Meshtastic UI 中） | 打开 SD 卡 ROM 浏览器 |
| **SYM+ALT** | 退出卡带（暂停并返回浏览器） |
| **麦克风按键** | 开启/关闭声音 |
| 工具 → **MonsterMesh Terminal** | 打开游戏内终端（RPG / 对战 / 托管所） |
### 模拟器控制
| T-Deck 按键 | Game Boy 按钮 |
|-----------|------------------|
| **W / A / S / D** | 方向键（上 / 左 / 下 / 右） |
| **K** | A |
| **L** | B |
| **Enter** | Start |
| **Space** | Select |
## 终端命令参考
在 Meshtastic UI 的 **Tools → MonsterMesh Terminal** 中打开终端，然后输入命令。`help` 用于列出游戏命令；`help sys` 用于列出系统命令。
### 游戏命令
| 命令 | 效果 |
|---------|--------|
| `party` | 显示从存档文件中加载的你的队伍 |
| `daycare` | 托管所状态 + 邻居列表 |
| `gym` | 列出本地的关都道馆阶梯赛及你的徽章 |
| `gym fight ` | 挑战第 N 个道馆（1–9）；**9 号道馆为石英高原**（四天王 + 冠军） |
| `explore` | 在附近的路线进行野生遭遇战 |
| `fight` | 与附近训练家的队伍进行本地 CPU 对战 |
| `mmg` | 发现由其他节点托管的 **MonsterMesh 道馆** |
| `mmg fight ` | 挑战已发现的 MM 道馆的五人阶梯赛 |
| `mmb` | 列出当前在线可对战的对等节点 |
| `mmb ` | **MonsterMesh 对战** —— 与某位对手进行实时 PvP |
| `news` | 喷火龙传说新闻轮播 |
| `achievements` | 列出你已获得的成就 |
### 系统命令 (`help sys`)
| 命令 | 效果 |
|---------|--------|
| `version` | 固件构建字符串 |
| `echo ` | 打印文本 |
| `clear` | 清空屏幕 |
| `beacon` | 立即广播存在状态（托管所 + 对战发现） |
## 入门指南
1. 将一张 micro-SD 卡格式化为 **FAT32**，并将你自己的 Game Boy ROM（`.gb`）及其存档（`.sav`）拷贝到其中。将其插入 T-Deck。
2. 刷入 MonsterMesh 构建版本（参见 [docs/BUILD.md](docs/BUILD.md)）。
3. 启动 T-Deck。它将进入正常的 Meshtastic UI。
4. 按下 **ALT** 键打开 ROM 浏览器，选择你的 ROM —— 模拟器随即启动。
5. 随时按下 **Ctrl+E** 即可在游戏和 Meshtastic UI 之间来回切换。
6. 打开 **Tools → MonsterMesh Terminal** 并输入 `help` 以启动 RPG/托管所/对战层。
## 从源码构建
MonsterMesh 使用 PlatformIO 针对 T-Deck 环境进行构建：
```
# 从 repo 根目录起，在一个支持 PlatformIO 的 Python venv 中
pio run -e t-deck-tft
```
完整的设置干净构建、USB 和 OTA（M5/bmorcelli-Launcher）刷机流程以及设备 UI 的补丁工作流均记录在 **[docs/BUILD.md](docs/BUILD.md)** 中。
## 文档
| 文档 | 内容 |
|-----|----------|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 模块如何接入 Meshtastic：线程、模式切换、LoRa 频道、SD/SPI 的稳定性维护 |
| [docs/GAMEPLAY.md](docs/GAMEPLAY.md) | 面向玩家的指南：道馆、四天王、探索、NG+、终端 |
| [docs/BATTLE_ENGINE.md](docs/BATTLE_ENGINE.md) | 第一代引擎：确定性、状态不同步检测、数据流水线 |
| [docs/DAYCARE.md](docs/DAYCARE.md) | mesh 网络上的托管所：信标、事件、友谊/竞争关系、SAV 回写、成就 |
| [docs/MULTIPLAYER.md](docs/MULTIPLAYER.md) | `mmg` 玩家托管道馆、`mmb` 实时 PvP、本地 `fight`、通信协议 |
| [docs/THEMES.md](docs/THEMES.md) | 7 种主题系统和 Cozette 字体 |
| [docs/BUILD.md](docs/BUILD.md) | 构建、刷机（USB + OTA）、设备 UI 补丁、安全注意事项 |
| [docs/CREDITS.md](docs/CREDITS.md) | 完整的开源署名和许可证 |
## 项目结构
```
src/modules/monstermesh/
MonsterMeshModule.{cpp,h} Main Meshtastic module: emulator host, UI/mode switching, LoRa wiring
MonsterMeshEmulator.{cpp,h} Game Boy emulator wrapper around peanut_gb
MonsterMeshFileBrowser.h SD-card ROM browser
MonsterMeshAudio.{cpp,h} I2S audio output
MonsterMeshTerminal.{cpp,h} In-game LVGL terminal + command handler (RPG/battle/daycare)
MonsterMeshTextBattle.{cpp,h} Battle "client": local CPU, gym, explore, and networked battles
Gen1BattleEngine.cpp Deterministic Gen-1 battle resolution engine
Gen1Species.h / PokemonData.h Species name table + party data structures
MeshtasticTransport.h Sends MonsterMesh packets over the Meshtastic mesh
PokemonDaycare.{cpp,h} Daycare orchestrator + beacon broadcast
DaycareEventGen.{cpp,h} Dual-layer event generator
DaycareTypes.h Daycare data structures, beacon format, persistence
DaycareAchievements.h 34 achievement definitions
DaycareSavPatcher.h Gen-1 SRAM read/write, checksum, XP & move patching
DaycareData.h Species profiles (generated from PokeAPI)
LordGyms.{cpp,h} The eight Kanto gym rosters
LordE4.{cpp,h} Indigo Plateau roster (Elite Four + Champion)
LordRoutes.{cpp,h} Wild-encounter route pools for `explore`
LordLogic.{cpp,h} RPG logic: daily reset, run stats, badge/unlock/NG+ rules
LordSave.h RPG persistence (badges, news, stats)
peanut_gb.h Game Boy CPU/PPU/APU emulator core (Peanut-GB)
minigb_apu.{c,h} Game Boy audio processing unit (minigb_apu)
showdown_gen1_basestats.h Gen-1 base stats — generated battle data (gitignored)
showdown_gen1_moves.h Gen-1 move data — generated battle data (gitignored)
patches/device-ui/ Patched into the meshtastic-device-ui library at build time
.../TFT/Themes.{cpp,h} 7-theme color system with cozette-font support
generated/ui_320x240/screens.c themed LVGL screens
generated/ui_320x240/lv_font_cozette_* Cozette bitmap fonts for the green themes
```
## 法律与商标
MonsterMesh 是一个**非官方的、非商业性的粉丝项目**。它**不隶属于、不受认可也不受赞助于** Nintendo、Game Freak、Creatures Inc. 或 The Pokémon Company。“Pokémon”、“Game Boy”以及相关的名称、角色和游戏数据均为其各自所有者的商标和版权。
- **本项目不包含也不分发任何游戏 ROM、存档文件、精灵图或其他受版权保护的游戏资产**。模拟器仅运行由你自己从合法获取的卡带中提供的 ROM。
- 第一代战斗/物种数据来源于开源项目 [Pokémon Showdown](https://github.com/smogon/pokemon-showdown) 和 [PokéAPI](https://pokeapi.co)，仅用于互联互通和游戏玩法模拟。
- 如果您是权利持有人并对本项目有任何疑虑，请提交一个 issue。
## 许可证
MonsterMesh 是 [Meshtastic firmware](https://github.com/meshtastic/firmware) 的一个分支，基于 **GNU General Public License v3.0**（`LICENSE`）进行分发，与上游固件使用的许可证相同。位于 `src/modules/monstermesh/` 下的 MonsterMesh 模块源代码遵循相同的许可证，除非个别文件带有各自的 SPDX/MIT 头部声明（Peanut-GB、minigb_apu、Showdown 和字体文件保留其原始的上游许可证 —— 参见 [docs/CREDITS.md](docs/CREDITS.md)）。
标签：Bash脚本, LoRa通信, Meshtastic, 代码生成, 嵌入式系统, 渗透测试工具, 游戏模拟器, 物联网硬件, 角色扮演游戏