game-automation

ゲーム自動化：エージェントの手と目

実際のゲームこそがオラクル（判断基準）です。ループは「起動 → ナビゲート → シーン設定 → 動作 → スクリーンショット撮影とログ読み取り → 判断」です。ゲームごとに一度構築すれば、以降の変更はすべて1分以内に確認できます。

Windows（ネイティブまたはWSLから）：um win

um win setup                                   # 一度だけ：PowerShellツールとgfxcapture対応ffmpeg、NVENC/AMF/QSV/x264を自動選択
um win ps                                      # ウィンドウプロセスの一覧：pid, name, title
um win launch --steam 105600                   # または：um win launch "C:\Games\Foo\Foo.exe" -- -windowed
um win shot --exe Terraria.exe shot.png --scale 0.33   # 全体フレーム＋1/3サイズの確認用軽量コピー
um win drive --proc Terraria "focus" "click 640 360" "key 0x1B" "type hello" "hold 0x44 1500"
um win drive --proc Terraria "hold 0x20 150" "sleep 200" "hold 0x20 150"   # sleep <ms> はステップ間の待機（ミリ秒）
um win drive --proc Terraria idle              # ユーザーが最後にマウス/キーボードに触れてからの経過秒数（待機しない）
um win kill <pid>                              # 正確なPIDのみ
um win reg get "HKCU\Software\..."             # レジストリ読み取り（reg set は事前にキーをバックアップ）

Python（長いスクリプト用）では from um.win import Drive, shot, Recorder として、d = Drive("AoE2DE_s")、d.focus()、d.click(x, y)、d.key("0x0D") と使います。

WinDrive コマンド（um/ps1/WinDrive.ps1、stdin プロトコル、各応答は1行）。座標はゲームウィンドウのクライアント領域を基準とします。

• マウス：move x y、click x y [right]、mdown/mup、drag x0 y0 x1 y1、rel dx dy（FPSカメラ/生入力用）、wheel 120。
• キーボード：key <vk> [tap|down|up]、hold <vk> <ms>、type <text>、scanmode on（仮想キーイベントを無視するDirectInput/生入力ゲーム用）。
• ウィンドウ：focus、rect、size <w> <h>（クライアントサイズ設定）、title、fg、idle、untop。
• タイミング：sleep <ms> は1回の呼び出し内のステップ間で待機します。各 um win drive 呼び出しは PowerShell を起動するため（1～2秒）、時間指定のあるコンボは1回の呼び出しにまとめてください。
• 仮想キーコード：Esc 0x1B、Enter 0x0D、Space 0x20、W/A/S/D 0x57/0x41/0x53/0x44、F1 0x70、Shift 0x10、Ctrl 0x11、矢印 0x25～0x28。

ルール

• 人間が入力中のオンラインモードのゲームにフォーカスを当てないこと。 実際にGTA Vで発生しました。エージェントがストーリーモードをクリックするためにGTAにフォーカスを当てたところ、人間のキー入力がGTAのランディングページに送られ、「改造バージョンでGTA Onlineサーバーにアクセスしようとしている」という警告が出ました。ScriptHookVがブロックしましたが、それに頼らないでください。idle を確認し、人間にクリックを依頼するか、起動時にアンチチートをオフにしてオンラインが起動しないようにしてください。詳細は knowledge/techniques/driving-real-games-safely.md を参照。
• 入力はゲームにのみ送られます。 WinDrive は、他のアプリケーションが前面にある場合は送信を拒否します。唯一の例外は、前面アプリがなく、カーソルがゲーム上にある場合です（ウィンドウモードのゲームでは、クリック時に前面が外れることがあります）。
• ユーザーがPCの前にいる可能性があります。 idle が1分未満の場合は、操作前に確認し、セッションを短く保ってください。ユーザーが許可した場合は無人実行も問題ありません。
• スクリーンショットはトークンを消費します。 --scale 0.33 のコピーを確認してください。クリック座標は逆算して×3に変換し、メニューのクリックポイントは一度測定して MODLOG.md に表として保存してください。
• gfxcapture の理由： GPU レンダリングされたゲームは、GDI キャプチャでは真っ黒になります。gfxcapture（Windows.Graphics.Capture）は、カバーされている場合でも1つのウィンドウの実際のフレームを取得します。最小化されたウィンドウはキャプチャできません。
• HDR ディスプレイ： SDR ゲームで Windows Auto HDR が有効な場合、キャプチャは色あせて表示されます（2～3倍明るく、シアンシフト）。色の判断ができなくなります。um win shot/record は有効時に警告を表示します。キャプチャ中はゲームの Auto HDR をオフにし（設定 > システム > 表示 > グラフィック > 該当ゲーム > Auto HDR）、ユーザーが希望する場合はキャプチャ後に再度オンにしてください。

ウィンドウを予測可能にする

• 固定クライアントサイズのウィンドウモード。 すべてのゲームにこの設定がどこかに隠れています：
  • ini ファイル（UE の GameUserSettings.ini の [/Script/Engine.GameUserSettings]、Unity の Screenmanager Fullscreen mode / Resolution レジストリ値 HKCU\Software\<company>\<product>）；
  • 起動フラグ（-windowed -w 1920 -h 1080、Unity -screen-fullscreen 0 -screen-width 1920 -screen-height 1080、Source -sw -w 1920 -h 1080）；
  • またはゲーム固有のレジストリ（AoE2：Mode Display 0 + Windowed Width/Height）。
  • um win drive --proc X "size 1920 1080" でほとんどのウィンドウモードゲームをリサイズできます。
• イントロをスキップ： 起動フラグ（-skipintro、-nosplash、Unity -popupwindow）、またはゲームのコピーでイントロ動画を削除/リネーム。
• 直接ゲームを開始： ローダーフラグ（tModLoader -skipselect Player:World）、テスト用セーブ、シナリオ自動読み込み、開発コンソールコマンド。
• バックグラウンドスロットリング： 多くのゲームはフォーカスがないとスロットリングや一時停止を行います。設定を探してください（Terraria：Main.instance.InactiveSleepTime = TimeSpan.Zero；Unity：Application.runInBackground = true；UE：t.IdleWhenNotForeground 0）。

クリックより優れた方法：スクリプト化されたシーンまたはブリッジ

• Mod内のチャットまたはコンソールコマンドでアイテムを付与、敵をスポーン、テレポートできます。テストは1行で済みます（/arsenal、/mothership）。
• テストシーン： Mod側のタイムライン（フレームNでウェーブをスポーン、N+30で発射）、トリガー付きシナリオ（AoE2ScenarioParser を使用した AoE2）、バックアップ付きの専用テストワールド。
• エージェントブリッジ： Mod内の 127.0.0.1 上のJSONラインソケット（examples/terraria-tmodloader/reference/AgentBridge.cs 参照）。
  • コマンド例：observe（メニューオプションまたはワールド状態をテキストで返す）、click <id>、controls、step。
  • すべてのリクエストはゲームのメインスレッドで更新後に処理され、応答が一貫するようになります。
  • UIツリーからメニューを汎用的に読み取り、エージェントがプレイヤーと同じものを認識できるようにします。破壊的なボタン（削除など）は除外してください。
  • エージェントはピクセルを使わずにプレイできるようになります。
• プロセス外バックエンド： ゲーム内部分は薄く保ち、頭脳（HTTP/ファイルドロップ）は外部に置きます。このパターンはAI NPCやクロスゲームマッシュアップにも拡張できます。

クラッシュとクリーンアップ

• クラッシュレポーター（BugSplat BsSndRpt64.exe、CrashReportClient.exe、UnityCrashHandler64.exe）が残留し、Steamに「既に実行中」と表示させることがあります。um win ps で特定し、um win kill <pid> でクリアしてください。
• pkill -f やワイルドカード taskkill /IM は絶対に使用しないでください。パターンが自分のシェルや他のアプリケーションに一致する可能性があります。
• クラッシュ後は、最初にローダーまたはゲームのログ（mod-any-game スキルにリストあり）を読み、次にWindowsイベントビューア（アプリケーションログ）でネイティブクラッシュを確認してください。

Linux と macOS

• Linux（X11）： xdotool search --name "Game" windowactivate --sync key Escape、xdotool mousemove --window $W 640 360 click 1。スクリーンショット：import -window $(xdotool search --name Game) shot.png、または ffmpeg x11grab。
• Linux（Wayland）： ydotool + grim。Proton ゲームはWine上のWindowsゲームです。起動オプション（WINEDLLOVERRIDES、PROTON_LOG=1）はSteamに設定します。
• macOS： screencapture -l <windowid> shot.png（ウィンドウIDは GetWindowID またはAppleScriptで取得）、osascript / cliclick で入力。入力と画面録画には、ターミナルに対するアクセシビリティと画面録画の許可が必要です。