Pico8 Mcp

pico8-mcp

让大模型 交互式游玩 PICO-8 卡带 的 MCP 服务：按下按钮、确定性地推进帧、查看像素级截图并读取游戏变量——使用真正的 PICO-8 二进制文件，以无头模式运行。

工作原理

LLM ⇄ MCP (stdio) ⇄ pico8-mcp ⇄ pipes ⇄ pico8 -x cart_instrumented.p8

• 卡带会复制到 /tmp/pico8-mcp/<session>/，并在其 __lua__ 部分末尾注入一个小型 Lua harness（不会修改原始文件）。该 harness 会屏蔽 btn/btnp，并将 _update/_update60 替换为命令循环。
• 输入通过 PICO-8 的 serial(0x804, …) stdin 通道传入。在桌面版 PICO-8（0.2.7）中，该读取采用 fread 语义：会阻塞，直到收到恰好 len 个字节。因此，驱动程序使用固定大小的 8 字节数据包（<op:1><a:3 hex><b:3 hex>\n），在命令之间冻结引擎，实现完美的步调同步——批量推进帧时按主机速度运行（不到 30 ms 即可推进约 600 个游戏帧），而非实时运行。
• 输出通过 printh（以 @ 为前缀的文本行）和 serial(0x805, …)（原始二进制：帧缓冲区与调色板转储）传递，并由服务端渲染为 PNG。

要求

• pico8 位于 PATH 中（或设置 PICO8_BIN=/path/to/pico8），版本为 0.2.x
• Node.js ≥ 18
• 卡带必须使用 _update/_update60，并通过 btn/btnp 读取输入 （标准卡带均符合要求；不支持自定义 flip() 主循环）

安装

npm install && npm run build

opencode 配置（opencode.json）：

{
  "mcp": {
    "pico8": {
      "type": "local",
      "command": ["node", "/path/to/pico8-mcp/dist/index.js"]
    }
  }
}

Claude Desktop 和其他任何 MCP 宿主：使用相同命令，通过 stdio 传输。

工具

工具	用途
pico8_boot	在步调同步控制下启动卡带（推进帧前，游戏时间处于冻结状态）。可选的 seed 用于确定性地生成 rnd()。
pico8_step	持续按住按钮（left/right/up/down/o/x），推进 N 帧并获取截图。
pico8_play	在一次调用中执行由 {buttons, frames} 步骤组成的脚本序列。
pico8_screen	当前帧的像素级 PNG（缩放比例为 1–4）。
pico8_read	按点分隔的路径读取 Lua 全局变量（player.x、objects.1.type…）。
pico8_peek	转储 PICO-8 RAM 的十六进制内容（0x6000 帧缓冲区、0x2000 地图…）。
pico8_reset	终止并从原始文件重新启动（应用卡带修改）。
pico8_shutdown / pico8_sessions	生命周期管理 / 会话列表。
pico8_boot_check	使用 pico8 -x 运行未经修改的卡带 N 秒，并报告启动错误（基准测试式检查）。

多个会话可以并行运行；session_id 默认为最近一个仍在运行的会话。

实时查看器

该服务会托管一个本地网页，让你可以 实时观看大模型游玩：在浏览器中打开 http://127.0.0.1:7864/。网页会显示游戏画面（通过 SSE 流式传输）、当前按住的按钮，以及每次工具调用和卡带 printh 输出的日志。

• 浏览器标签页连接期间，批量推进会拆分为较小的分块（默认为 15 帧），并在每块后截取画面，让较长的 pico8_step 调用像快进视频一样播放。没有查看器连接时，不会产生任何额外开销。
• 播放速度由大模型的调用节奏决定（通常远快于实时）。

环境变量：

变量	默认值	效果
PICO8_MCP_VIEWER	1	设为 0 可完全禁用查看器
PICO8_MCP_VIEWER_PORT	7864	监听端口（仅绑定到 127.0.0.1）
PICO8_MCP_VIEWER_CHUNK	15	旁观时每次中间画面截取之间推进的帧数

如果端口已被占用（例如由第二个 MCP 宿主使用），查看器会被禁用，并在 stderr 上输出警告；服务仍会正常运行。

值得了解的语义

• 按钮会在多个步骤之间保持按住状态；btnp() 仅在新按下按钮的第一帧触发。要点按两次：按住按钮执行一步，使用 buttons: [] 执行一步，再次按住按钮执行一步。
• 截图是在最后一步所处帧的 _draw 执行之后拍摄的。
• 卡带发生运行时错误时，-x 进程会终止；错误文本会显示在工具结果中。pico8_reset 会重新开始。
• 测试框架使用 GPIO 内存（0x5f80–0x5fff）作为数据包缓冲区，并覆盖 btn/btnp 全局变量——使用 GPIO 的卡带，或在测试框架加载前缓存 local btn=btn 的卡带，都会出现异常行为。

开发

• 运行 npm run build，然后运行 node test/mcp-probe.mjs [cart.p8]，即可通过真实的 MCP 客户端进行端到端探测（启动 → 游玩 → 读取 → 关闭）。
• PICO8_BIN 用于选择其他 PICO-8 二进制文件。