Mosaico Gamer · 关于我在 Mosaico 上爽玩童年游戏这件事

把 ESP-Mosaico 变成一台掌机：一套固件里装着四个引擎，GBA（gpSP）、Game Boy / Game Boy Color（gnuboy）、Doom 和 Quake 1。游戏文件存在板载 NAND 上，在游戏列表里选一个就能开玩。有声音，GBA 存档会自动写回 NAND，关机也不会丢。

需要至少插一个摇杆子板才能玩，插两个体验更好：左边管移动，右边管按键和视角，握起来和双手柄掌机差不多。固件不附带任何游戏，请自备合法取得的 ROM、WAD 或 PAK 文件。

更新日志

相对 2026-09-30 已发布的版本：

• 配网：进入「Upload over Wi-Fi」时，如果 Recovery 页面或本应用已经保存过 Wi-Fi，会直接连接并显示地址，不必再扫描和输入密码。要换网络，在这个页面按 A。
• 存档：GBA 和 GB/GBC 在游戏写完存档、安静大约 0.3 秒后把存档写入 NAND，退出时也会再写一次。不再每隔约 30 秒整段检查并写入，游戏中也不会因此卡一下。
• 时间：设备一拿到网络地址就向 NTP 对时。上传页一打开就把浏览器时区发过来，快捷设置显示本地时间；时区会记住，下次联网直接沿用。
• 列表标注：游戏行右侧按文件格式标注。.wad 显示 WAD，.pak 显示 PAK，不再和 GB 游戏共用 GB 标记。

操作指南

准备：插上摇杆子板

1. 一个摇杆子板
   插在左槽或右槽都可以。画面会跟着摇杆转到你握着的那一侧。摇杆控制方向，旁边一圈四个按键依次是 A、Start、Select、B，方向和你看到的画面一致。

2. 两个摇杆子板（推荐）
   左右各插一个，画面回到正放。左摇杆控制方向或移动，右子板的四个按键是 A / Start / Select / B，右摇杆在 Quake 里用来转视角。左子板的四个按键另有用途，见下文 Quake 部分。同一对摇杆也可以玩 Mosaico 上的另一款应用《浴火木星》（Jupiter on Fire）：左摇杆驾驶，右摇杆环视。

3. 首次校准
   插上后先松手，别碰摇杆，固件会用大约半秒测量摇杆的中心位置。然后把摇杆沿边缘转满一圈，摇杆的行程范围会被记住，下次开机直接沿用。

放入游戏文件

两种方式任选一种。

1. Upload over Wi-Fi

   • 配网：在游戏列表里选中「Upload over Wi-Fi」，按 A。如果 Recovery 页面或本应用已经保存过 Wi-Fi，设备会直接连接，屏幕出现 http:// 地址。还没有保存过网络时，画面会提示按 A 进入扫描：从结果里选一个网络，用屏幕键盘输入密码，可以点按屏幕上的字母，也可以用摇杆移动再按 A 输入；B 删除一个字符，Select 切换输入框，Start 开始连接。已经连上时再按 A，可以改连另一个网络。Wi-Fi 密码会被记住。
   • 时间：一拿到 IP 就向 NTP 对时。电脑上的上传页一打开，会立刻把浏览器时区发给设备，快捷设置里的时钟按本地时间走。
   • 网页上传：在同一网络下的电脑上用浏览器打开屏幕上的地址，选文件上传。传完后回到游戏列表就能看到。

2. USB disk on PC
   选中「USB disk on PC」，按 A，用 USB 线连接电脑。这里用的是 ESP-MSC：设备通过 USB 把自己报成一块移动磁盘，电脑按普通 U 盘来读写；每一次读写都落到板载 SPI NAND 的对应扇区上，上面是一个 FAT 卷。整片 NAND 都交给这块盘，容量大约 120 MB。把文件直接拖进去即可。

两种方式都认这些文件：.gb、.gbc、.gba、.wad，以及 Quake 的 .pak。Quake 的数据包要保持原名 pak0.pak、pak1.pak……放在磁盘根目录。引擎从 pak0.pak 开始按编号依次加载，所以 pak0.pak 必须有，编号中间不能断。游戏列表里选任意一个 .pak 都能启动 Quake。每一行右侧标着格式：GB、GBC、GBA、WAD 或 PAK。

游戏列表

1. 选择：摇杆上推、下拉移动光标，到顶或到底会循环。
2. 开始：按 A 或 Start，启动选中的游戏；在上传入口上按则进入对应页面。
3. 删除：在某个游戏上按 Select，会弹出「THIS CANNOT BE UNDONE」确认框。按 A 确认删除，按 B 或 Select 取消。删掉之后无法恢复。
4. 退出页面：在上传页面按 B 返回上一级。在屏幕键盘里 B 是删除字符，点按 AI 键取消输入。不要按住 AI 键，按住会进入 Recovery。

GBA / GB / GBC

1. 方向键：摇杆。需要推过一定幅度才算按下，轻微抖动不会误触。
2. A / B / Start / Select：按键环上的四个键。
3. L / R 肩键：按住屏幕底部左半边是 L，右半边是 R。两边可以同时按住。
4. 存档：游戏里正常存档即可。写完并安静大约 0.3 秒后，固件把这次存档写入 NAND，退出游戏时如果还有没写完的也会再写一次。不会再每隔约 30 秒停下来检查整段存档。
5. 退出：点按 AI 键，回到游戏列表。不要按住，按住会进入 Recovery。

Doom

1. 移动与转向：摇杆前推前进、后拉后退，左右转身。
2. A：开火；在菜单里是确认。
3. B：开门、按开关；在菜单里也是确认。
4. Start：按住奔跑。
5. Select：打开或关闭自动地图。
6. L / R：按住屏幕底部左右两块区域左右平移。
7. 按下摇杆：摇杆中键。弹出「是否退出」时相当于按 Y 确认。
8. AI 键：点按打开 Doom 菜单。不要按住，按住会进入 Recovery。

Quake

1. 移动：左摇杆前后移动和左右平移，推得越远走得越快。
2. 视角：右摇杆左右转身、上下抬头低头，推得越多转得越快。只插一个子板时没有视角摇杆。
3. A：攻击。
4. B：跳跃。
5. Start：按住奔跑。
6. Select：查看计分板。
7. 切换武器：左子板的四个按键里，上和右切到下一把武器，下和左切回上一把。
8. 按下左摇杆：在退出确认里相当于按 Y。
9. AI 键：点按打开 Quake 菜单。不要按住，按住会进入 Recovery。

快捷设置（任何时候都能打开）

1. 打开：从屏幕上边缘往下滑。
2. 调节：在亮度或音量滑条上左右拖动。设置会被保存，下次开机仍然有效。
3. 状态：面板上还显示时间和电量。
4. 关闭：向上滑，或点面板外的区域。面板打开时，游戏列表不响应开始和删除。

后续更新

• 设备之间的磁吸交互，模仿 GBA / GBC 的联机对战和交换。
• 继续适配更多模拟器。

技术一览

• 目标硬件：ESP-Mosaico（ESP32-S31）+ 摇杆子板（至少一个，推荐两个）
• 引擎：gpSP（GBA）、gnuboy（GB/GBC）、Doom、Quake 1（WinQuake）
• 分类：显示与 HMI / 音频 / 通信
• 固件格式：Iris
• 许可证：GPL-3.0-or-later。各引擎为 GPL-2.0-or-later，应用代码为 Apache-2.0，详见工程里的 NOTICE。
• 不包含任何游戏 ROM、WAD 或 PAK 文件。