迷你關卡

迷你關卡是一份自己寫的小關卡：選一張原版地圖，擺上要用的我方和敵方單位，再寫幾段事件指令碼（開場對白、回合開始、增援、勝利條件等）。載入後遊戲會借用一話的位置直接進入這個關卡，不經過新遊戲、序章和主角選擇，幾秒鐘就能站到地圖上。

我們開發時用它來復現特定的戰鬥和畫面：比如讓兩臺指定機體相鄰，檢查戰前確認的命中率；把敵人放到畫面外，檢查 L2／R2 切換；或者單獨跑一條劇情指令，看它到底做了什麼。倉庫裡有六十多個現成的關卡可以參考。

迷你關卡是除錯工具，遊戲裡沒有進入它的選單：只能在開啟除錯介面後，通過 MCP 載入。怎麼連線見用 AI 智慧體操作遊戲（MCP）。

想把幾關串成玩家能安裝遊玩的戰役，見追加劇本 MOD。

給 AI 智慧體：llms.txt

/docs/mini-stage/llms.txt 把寫迷你關卡需要的一切放進一個純文本檔案，專門給 AI 智慧體讀：使用流程、編譯器檢查的每條限制、去哪裡查人物和機體編號，以及全部指令、條件指令、標記、事件型別和出擊記錄欄位的詳細解析（英文名稱加中文的實現依據與實測）。Claude Code 這類抓網頁時聲明想要 Markdown 的工具，直接開啟本頁地址也會自動拿到這份檔案；其他工具把地址交給它即可。連上游戲後可以這樣說：

先讀 https://srw64.dreamquest.club/docs/mini-stage/llms.txt，然後寫一個迷你關卡：我方一臺機體和兩臺相鄰的敵人，編譯後用 srw64_mini_stage_load 載入，進去後截圖。

需要什麼

• 已經按 MCP 那一篇 連上游戲（srw64_attach 能用）。
• 原始碼倉庫和 Python 3，用來把關卡定義編譯成遊戲讀的映象。
• 關卡里引用了原版的出擊記錄或事件（下文的 template、deployments_from、copy_from）時，還要在倉庫裡放好你自己的 ROM（rom.z64），執行一次 make recomp-data，從 ROM 提取原版資料。只用自己寫的欄位時不需要。

1. 寫關卡定義

關卡定義是一個 JSON 檔案，schema 固定為 srw64.mini-stage.v1。下面是倉庫裡 move-jump.json 的簡化版：第 20 號地圖上放一臺我方機體、一臺敵方機體，開場把鏡頭對準我方，然後進入我方回合。

{
  "schema": "srw64.mini-stage.v1",
  "name": "my-test",
  "note": "隨便寫，說明這個關卡測什麼",
  "map": 20,
  "deployments": [
    {"template": "base:stage_deployments:001f0f1c", "group": 0, "x": 8, "y": 8, "faction": 0},
    {"template": "base:stage_deployments:001f2720", "group": 1, "x": 12, "y": 8, "faction": 1}
  ],
  "events": [
    {"name": "opening", "type": 12, "header": [0, 0, 0, 0], "commands": [
      {"op": "3DD0"},
      {"op": "3D32", "args": [4]},
      {"op": "3D4D"},
      {"op": "3D65", "args": [17, 31]},
      {"op": "3D3B", "args": [1]},
      {"op": "3D45", "args": [0]},
      {"op": "3D45", "args": [1]},
      {"op": "3D35", "args": [16384, 0]},
      {"op": "3D48"}
    ]},
    {"name": "ending", "type": 14, "header": [0, 0, 0, 0], "commands": [
      {"op": "3DD0"},
      {"op": "3D4B", "args": [4]}
    ]}
  ]
}

各欄位：

每條指令、條件指令、事件型別和出擊記錄欄位見關卡指令碼指令參考；更早的研究過程在倉庫裡（中文）：關卡指令碼與事件型別、指令寫法、迷你關卡研究記錄。最省事的辦法是從 config/recomp/mini-stages/ 裡挑一個接近的關卡改，每個檔案的 note 都寫了它測什麼。

2. 編譯成映象

在倉庫目錄裡執行：

python3 tools/recomp/script_lab/mini_stage.py compile my-test.json --out my-test.image.json

生成的映象（srw64.mini-stage-image.v1）就是遊戲直接讀取的格式。超過 63 個事件、事件或出擊記錄超出遊戲的緩衝區時，編譯會報錯並說明原因。

映象裡含有從你的 ROM 複製來的原版資料，只在自己的電腦上用，不要分發。

3. 載入並進入

讓遊戲停在標題畫面的主選單（「ニューゲーム／コンティニュー」那一層），然後讓智慧體載入映象：

等遊戲到標題主選單，用 srw64_mini_stage_load 載入 /你的路徑/my-test.image.json，等關卡就緒後截圖。

• srw64_mini_stage_load 的 path 是遊戲所在那臺機器上的路徑。連 Steam Deck 時，映象要先拷到 Deck 上。
• 載入後遊戲立刻進入關卡：先播開場事件，然後停在地圖上等你操作。srw64_status 裡的 mini_stage.ready 變成 true 表示已經可以操作了。
• 不在標題主選單、檔案讀不到或格式不對時，載入會被拒絕，返回原因。
• 已安裝的遊戲只能載入編譯好的映象。用 srw64_launch 從原始碼啟動的開發會話還可以直接載入關卡定義，遊戲會自己調用編譯器；srw64_launch 的 mini_stage 參數則在啟動時就帶上關卡，到主選單後按 F8 進入。

之後就可以按工具一覽裡的工具操作：選單位、攻擊、看戰前確認、截圖或錄影。

注意事項

• 用的是你自己的存檔目錄。 關卡里如果手動存檔，或者開著自動存檔，進度會寫進平常的存檔欄。測試前先備份使用者目錄下的 saves/，或者按 MCP 那一篇的做法用 --user-dir 另開一套目錄。
• 不經過主角選擇。 主角與搭檔的名字和路線都是空的；需要它們的事件請在關卡里自己設好，或者先正常開新遊戲再測。
• 隨機數和原版不同。 直接進入比正常開新遊戲早了幾百幀，敵方的行動和命中判定會跟著變化。要復現某次的結果，就從同一個映象、同樣的操作重新開始。
• 一次只有一個關卡。 再載入一個會替換掉前一個。測完用 srw64_quit 退出，或者回到標題再載入下一個。