ミニステージ

ミニステージは自分で書く小さなシナリオです。原作のマップを 1 つ選び、必要な味方と敵のユニットを配置し、イベントスクリプト（開幕の会話、ターン開始、増援、勝利条件など）をいくつか書きます。読み込むと、ゲームはシナリオの枠を 1 つ借りてそのステージに直接入ります。ニューゲーム・プロローグ・主人公選択を通らないので、数秒でマップに立てます。

開発では、特定の戦闘や画面の再現に使っています。指定した 2 体を隣り合わせにして戦闘前の命中率を確かめる、敵を画面外に置いて L2／R2 の切り替えを試す、シナリオ命令を 1 つだけ実行して何をするのか調べる、といった使い方です。リポジトリには 60 以上の既成ステージがあり、参考にできます。

ミニステージはデバッグ用の機能で、ゲーム内のメニューからは入れません。デバッグインターフェースをオンにしたうえで、MCP から読み込むときだけ使えます。接続方法は AI エージェントでゲームを操作する（MCP） をご覧ください。

AI エージェント向け：llms.txt

/docs/mini-stage/llms.txt は、ミニステージを書くのに必要なことを AI エージェント向けに 1 つのテキストファイルにまとめたものです。作業の流れ、コンパイラが確認するすべての制限、キャラクターや機体の番号の調べ方、命令・条件命令・マーカー・イベントの種類・出撃データの項目の詳しい解説（英語名と中国語の根拠・検証結果）を収録しています。Claude Code のように、ページ取得時に Markdown を求めるツールは、このページのアドレスを開くだけで自動的にこのファイルを受け取ります。それ以外のツールにはアドレスを渡してください。ゲームに接続したら、たとえば次のように頼めます。

https://srw64.dreamquest.club/docs/mini-stage/llms.txt を読んでから、味方 1 機と、その隣に敵 2 機を置いたミニステージを書いて。コンパイルして srw64_mini_stage_load で読み込み、入ったらスクリーンショットを撮って。

必要なもの

• MCP の記事 のとおりにゲームと接続できていること（srw64_attach が使える状態）。
• ステージ定義を、ゲームが読むイメージにコンパイルするための ソースリポジトリ と Python 3。
• 原作の出撃データやイベントを参照するステージ（後述の template、deployments_from、copy_from）では、ご自分の ROM を rom.z64 としてリポジトリに置き、make recomp-data を一度実行して原作のデータを取り出しておく必要があります。自分で書いた項目だけのステージなら不要です。

1. ステージ定義を書く

ステージ定義は schema が srw64.mini-stage.v1 の JSON ファイルです。以下はリポジトリの move-jump.json を簡略化したもので、マップ 20 に味方 1 体と敵 1 体を置き、開幕でカメラを味方に合わせてから味方フェイズに移ります。

{
  "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 で別のフォルダを使ってください。
• 主人公選択を通りません。 主人公とパートナーの名前・ルートは空のままです。イベントで必要なら、ステージの中で設定するか、ふつうにニューゲームを始めてから試してください。
• 乱数は通常のプレイと変わります。 直接入ると、ふつうのニューゲームより数百フレーム早くなるため、敵の行動や命中判定も変わります。結果を再現したいときは、同じイメージ・同じ操作で最初からやり直してください。
• ステージは一度に 1 つだけです。 別のステージを読み込むと前のものと入れ替わります。終わったら srw64_quit で終了するか、タイトルに戻って次のステージを読み込んでください。