game-automation

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

本当のゲームはオラクルです。ループは、起動 → 移動 → シーンのセットアップ → 操作 → スクリーンショットとログの確認 → 判断です。ゲームごとに一度構築すれば、その後の変更はすべて1分で確認できます。

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

um win setup                                   # once: PowerShell tools + an ffmpeg with gfxcapture, picks NVENC/AMF/QSV/x264
um win ps                                      # windowed processes: pid, name, title
um win launch --steam 105600                   # or: um win launch "C:\Games\Foo\Foo.exe" -- -windowed
um win shot --exe Terraria.exe shot.png --scale 0.33   # full frame + a 1/3 copy that's cheap to look at
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> pauses between steps
um win drive --proc Terraria idle              # seconds since the user last touched mouse/keyboard (does not wait)
um win kill <pid>                              # exact PID only
um win reg get "HKCU\Software\..."             # registry (reg set backs the key up first)

長めのスクリプトでは 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；標準入力プロトコル、1行につき1つの応答）。座標は ゲームウィンドウのクライアント領域内のものです。

• マウス：move x y、click x y [right]、mdown／mup、drag x0 y0 x1 y1、rel dx dy（FPS カメラ／ Raw Input）、wheel 120。
• キーボード：key <vk> [tap|down|up]、hold <vk> <ms>、type <text>、scanmode on（仮想キーイベントを無視する DirectInput／ Raw Input ゲーム向け）。
• ウィンドウ：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 から「変更されたバージョンで 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）は、ウィンドウが覆われていても、そのウィンドウの実際のフレームを取得します。最小化されたウィンドウはキャプチャできません。
• HDR ディスプレイ： SDR ゲームで Windows Auto HDR が有効になっていると、キャプチャは白っぽくなり（明るさが2～3倍になり、シアン寄りに色ずれします）、色を判定できません。um win shot／record は有効時に警告を表示します。キャプチャ中はそのゲームの Auto HDR をオフにしてください（Settings > System > Display > Graphics > ゲーム > Auto HDR）。ユーザーが希望する場合は、キャプチャ後に再びオンにしてください。

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

• クライアントサイズを固定してウィンドウモードにします。 どのゲームでも、この設定はどこかにあります。
  • ini ファイル（UE の GameUserSettings.ini にある [/Script/Engine.GameUserSettings]、または Unity の HKCU\Software\<company>\<product> 配下にある Screenmanager Fullscreen mode／Resolution のレジストリ値）；
  • 起動フラグ（-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 で発射）、トリガー付きのシナリオ（AoE2 では AoE2ScenarioParser を使用）、またはクリーンなバックアップを備えた専用テストワールドを用意します。
• エージェントブリッジ： MOD 内の 127.0.0.1 で JSON Lines ソケットを動かします（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 を使います。入力と画面収録を行うには、ターミナルに「アクセシビリティ」と「画面収録」のアクセス許可が必要です。