繁
← 技術文件

用 AI 智慧體操作遊戲（MCP）

讓 Claude Code 等支援 MCP 的 AI 工具連上正在執行的遊戲：讀取狀態、截圖、按鍵、操作介面、讀寫記憶體。

更新於 2026-10-21

Marchwind 64 內建一個除錯介面。在選項裡開啟後，遊戲會在本機開一個埠，倉庫裡的 MCP 伺服器通過它把遊戲變成一組工具，交給支援 Model Context Protocol 的 AI 客戶端使用（Claude Code、Codex、Cursor 等）。

接上之後，智慧體可以：

  • 讀取當前畫面在做什麼：標題、對白、場間畫面、戰前確認、設定視窗等狀態；
  • 截圖、錄一段 MP4；
  • 像玩家一樣按鍵，或者直接操作原生介面上的按鈕和輸入框；
  • 切換語言、圖片模式、規則和介面大小；
  • 讀寫遊戲記憶體（排查問題用）。

我們自己開發時就是這樣讓 AI 跑流程、復現 bug、核對翻譯排版的。玩家也可以拿它來寫自動化指令碼、錄影片，或者讓 AI 幫忙看出了什麼問題。

需要什麼

  • 遊戲：Windows、macOS、Linux 或 Steam Deck 版都可以。

  • Python 3：系統自帶的就行，不用裝額外的包。Windows 上從 python.org 安裝，命令是 python。

  • MCP 伺服器指令碼：在原始碼倉庫裡，克隆下來即可，不需要編譯：

    git clone https://github.com/dyzz/srw64-recomp.git

    用到的檔案是 tools/recomp/debug/mcp_server.py 和它旁邊的 session.py。

  • 一個支援 MCP 的 AI 客戶端。

1. 在遊戲裡開啟除錯介面

開啟「選項 → 關於」，把「AI 除錯介面（MCP）」設為「開」。立即生效，不用重啟；設定會儲存，以後每次啟動遊戲都會在畫面上方提示一次，提醒你它還開著。不用時在同一個地方關掉，已有的連線會馬上斷開。

開著的時候，這一行下面會顯示正在監聽的地址和這次執行的目錄，旁邊的「複製執行目錄」按鈕可以把完整路徑複製到剪貼簿。

遊戲只在本機（127.0.0.1）上開一個埠，並在執行目錄裡寫一個 debug.json，記下埠號和一串隨機令牌。連線時必須先出示令牌，而這個檔案只有你自己的賬戶讀得到。遊戲退出或關掉開關時，這個檔案會被刪掉。

也可以用啟動參數 --debug 開啟（只對這一次執行有效）
  • macOS：/Applications/Marchwind64.app/Contents/MacOS/srw64-gfx-host --play --rom ~/Games/srw64.z64 --debug（.z64、.v64、.n64 都可以）
  • Windows：在解壓出的資料夾裡執行 Marchwind64.cmd --debug
  • Linux：./marchwind64.sh --debug
  • Steam Deck：Steam 裡這個遊戲的「屬性 → 啟動選項」填 %command% --debug

用參數開啟時，選項裡的開關顯示為「開」，本次執行不能在那裡關閉。

各系統的執行目錄：

系統 執行目錄
Windows %LOCALAPPDATA%\SRW64Recomp\sessions\<會話>\run\
macOS ~/Library/Application Support/SRW64Recomp/sessions/<會話>/run/
Linux / Steam Deck ~/.local/share/srw64-recomp/sessions/<會話>/run/

2. 把 MCP 伺服器加到 AI 客戶端

MCP 伺服器是一個通過標準輸入輸出通訊的 Python 指令碼。

Claude Code：

claude mcp add srw64 -- python3 /你的路徑/srw64-recomp/tools/recomp/debug/mcp_server.py

其他客戶端：大多用類似下面的 JSON 配置（檔案位置和外層鍵名以各客戶端的說明為準）：

{
  "mcpServers": {
    "srw64": {
      "command": "python3",
      "args": ["/你的路徑/srw64-recomp/tools/recomp/debug/mcp_server.py"]
    }
  }
}

Windows 上把 python3 換成 python，路徑寫成 C:\\你的路徑\\srw64-recomp\\tools\\recomp\\debug\\mcp_server.py（JSON 裡反斜槓要寫兩個）。

加好後客戶端裡應該能看到一組以 srw64_ 開頭的工具。

3. 連線並開始使用

直接讓智慧體連上游戲就行，不用告訴它路徑：

用 srw64_attach 連上游戲，截一張圖告訴我現在在哪個畫面。

srw64_attach 不帶參數時，會在你的使用者目錄裡找開著除錯介面的遊戲，連上最新啟動、而且能應答的那一個。同時開著好幾個遊戲，或者想指定某一個時，把「複製執行目錄」得到的路徑傳給它的 run 參數。

連上以後就可以用自然語言佈置任務，比如：

  • 「等到主選單出現後開始新遊戲，一路快進到第一次選擇。」
  • 「把語言切成英文，截圖對照中文版同一個畫面，看有沒有文字溢出。」
  • 「錄 10 秒，我要看這段戰鬥動畫哪裡卡了。」
  • 「對白卡住不動了，讀一下狀態和最近的事件日誌，看看停在哪條指令。」

智慧體一般會先看 srw64_status 和截圖判斷畫面，再用 srw64_wait 等條件滿足，避免盲目等待。

工具一覽

工具 用途
srw64_attach 連線一個執行中的遊戲。不填參數時自動找最新的那個；run 填執行目錄可以指定。
srw64_launch 從原始碼構建並啟動一個隔離的開發會話（需要完整的開發環境，見下文）。
srw64_status 當前狀態：幀數、視窗、語言、圖片模式、規則、標題與序章、對白（頁、字號、速度、快進）、各原生頁面、提示條、按住的鍵。
srw64_screenshot 擷取下一幀（含原生疊加介面），直接返回圖片；也可以截設定視窗等其他視窗。
srw64_record 錄接下來若干秒的 MP4，返回檔案路徑。
srw64_record_start / srw64_record_stop 開始 / 結束一段不定長錄影。
srw64_wait 等待條件成立：幀數、對白出現、某個頁面開啟、回到主選單、對白裡出現某段文字、事件日誌裡出現某類事件。
srw64_events 讀取事件日誌（對白、序章、規則、設定、各場間畫面、指令碼等）。
srw64_keys 遊戲鍵盤。固定使用經典佈局，不受玩家改鍵影響：Z＝A、X＝B、Enter＝START、方向鍵、Q/E＝L/R、I/K＝C 上/下、WASD＝搖桿。支援組合鍵和按住時長，比如 e+z 快進。
srw64_pad 虛擬手柄，按鍵名用 Steam Deck 的叫法，效果與預設繫結一致（View 開啟設定等）。
srw64_buttons 直接按 N64 手柄按鍵，跳過鍵盤層。
srw64_ui_tree 列出原生介面（姓名頁、設定視窗、選單欄等）上的控制元件、位置和文字。
srw64_click / srw64_type / srw64_ui_key 按文字或座標點選控制元件、在輸入框裡打字（支援輸入法組字）、給介面發按鍵。
srw64_menu 按路徑點選單欄項目，或列出選單。
srw64_window 調整視窗大小、置前或關閉。
srw64_settings 直接改規則、語言、圖片模式、介面大小、寬高比和各畫面的原版/現代模式。
srw64_mini_stage_load 載入並進入一個迷你關卡映象，見迷你關卡。
srw64_viewer_start 在戰鬥檢視器裡播放指定的一場戰鬥動畫。
srw64_game_over / srw64_victory 讓當前關卡直接 GAME OVER / 直接勝利，和劇本里的敗北、過關指令走同一條路（GAME OVER 畫面與重試、結算與結束事件都是遊戲自己的）。只在我方階段、戰術地圖空閒、沒有事件在跑時生效；條件不滿足時返回原因。
srw64_memory / srw64_memory_write 讀 / 寫遊戲記憶體（十六進位制）。寫入一次最多 4096 位元組。
srw64_quit 正常退出遊戲，返回本次執行的報告。

工具出錯時以錯誤結果返回，不會讓 MCP 伺服器退出。

注意事項

  • 這是你真正的遊戲和存檔。 智慧體連上的就是你平常玩的遊戲，讀寫的是平常那套存檔和設定，智慧體存檔、改設定都會真的生效。想放心折騰，先備份使用者目錄下的 saves/，或者用 --user-dir 指定一套單獨的目錄（把 ROM 路徑和需要的存檔複製過去）。
  • srw64_memory_write 可能讓遊戲出錯。 它繞過遊戲邏輯直接改記憶體，只在你清楚自己在做什麼時使用。
  • srw64_game_over / srw64_victory 是真的結束關卡。 連的是你自己的遊戲時，勝利會照常進幕間、可以存檔，GAME OVER 也是真的；測試最好用單獨的 --user-dir。
  • 介面只對本機開放。 遊戲只監聽 127.0.0.1，區域網裡的其他裝置連不上；本機的其他程式也要拿到 debug.json 裡的令牌才能操作。不要把這個檔案發給別人。遠端連線要靠 ssh 轉發（見下）。
  • srw64_quit 會關掉遊戲。 只想斷開、繼續玩的話，在「選項 → 關於」把開關關掉就行。
  • 不用時關掉開關。 開關會一直儲存，啟動時的提示就是提醒這一點。

從電腦連 Steam Deck

前提：電腦能用 ssh 登入 Deck（例如 ~/.ssh/config 裡配好了一個叫 Deck 的主機），Deck 上的遊戲已在「選項 → 關於」開啟除錯介面（或者按上文帶 --debug 啟動）。在電腦的倉庫目錄裡執行：

python3 tools/release/linux/attach.py --host Deck

它會在 Deck 上找到正在執行的遊戲，用 ssh -L 把埠轉發到本地，並設為「當前會話」。之後智慧體直接調用 srw64_attach（不帶參數）就能連上 Deck。截圖、錄影和事件日誌是遊戲寫在 Deck 上的檔案，會通過同一條連線自動取回。

attach.py --start 會通過 ssh 帶 --debug 啟動遊戲；再加 --data-dir '~/srw64-debug' 則使用一套單獨的資料目錄（ROM 和 HD 包用連結，存檔和設定是複製的），除錯不會寫你自己的存檔。

安卓

安卓版同樣在「選項 → 關於」開啟。手機和電腦之間要靠 adb：先在手機的開發者選項裡開啟 USB 除錯（或無線除錯），用 adb 連上電腦，然後在倉庫目錄裡執行：

python3 tools/release/android/attach.py --no-start

它用 adb forward 把遊戲的介面轉發到電腦，並設為「當前會話」，之後同樣調用 srw64_attach。截圖、錄影和事件日誌也會通過這條連線取回。安卓上不用令牌，電腦通過 adb 轉發訪問介面。

開發者：從原始碼啟動

如果你在本地搭好了完整的構建環境（見倉庫裡的構建文件），srw64_launch 會按需構建並啟動一個獨立的除錯會話。它的執行目錄在倉庫的 build/recomp/debug/ 下，不碰你平常玩的存檔；還可以直接指定語言、圖片模式、規則、存檔或迷你關卡。會話隨 MCP 伺服器一起退出。

倉庫裡的 docs/guide/debug-interface.md 有更完整的說明，包括命令行工具 srw64ctl.py、Python 指令碼介面和介面覆蓋範圍。