遊戲自動化

遊戲自動化：Agent 的手與眼

真正的遊戲是 Oracle。流程是：啟動 → 導航 → 設定場景 → 操作 → 截圖並讀取紀錄 → 決定。每個遊戲只需建立一次，之後的每次改動都能在一分鐘內完成驗證。

Windows（原生或從 WSL）：um win

um win setup                                   # 一次性設定：PowerShell 工具 + 支援 gfxcapture 的 ffmpeg，自動選擇 NVENC/AMF/QSV/x264
um win ps                                      # 視窗程序：pid、名稱、標題
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 協議，每行一個回覆）。座標為遊戲視窗的用戶端區域。

• 滑鼠：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> 在單次呼叫中的步驟之間等待。每次 um win drive 呼叫都會啟動 PowerShell（1-2 秒），因此請將含時序的組合動作放在同一次呼叫中。
• 虛擬按鍵碼：Esc 0x1B、Enter 0x0D、Space 0x20、W/A/S/D 0x57/0x41/0x53/0x44、F1 0x70、Shift 0x10、Ctrl 0x11、方向鍵 0x25-0x28。

行車守則

• 絕不在使用者打字時聚焦含有線上模式的遊戲。 這在 GTA V 發生過：Agent 聚焦 GTA 以點擊「故事模式」，使用者的按鍵輸入卻打到了 GTA 的登入頁面，導致 GTA 發出「使用修改版存取 GTA 線上模式伺服器」的警告。ScriptHookV 封鎖了它；不要依賴這個。請檢查 idle，詢問使用者點擊，並在關閉反作弊的情況下啟動，使線上模式無法啟動。參閱 knowledge/techniques/driving-real-games-safely.md。
• 輸入只會傳送到遊戲。 當其他應用程式處於前景時，WinDrive 拒絕發送輸入。唯一的例外是當前景無視窗且游標位於遊戲上方時——這在視窗模式遊戲因點擊而失去前景時會發生。
• 使用者可能正在使用電腦。 如果 idle 少於一分鐘，請在驅動前先詢問，並保持操作時段簡短。使用者同意後，無人值守執行即可。
• 截圖會消耗 Token。 請檢視 --scale 0.33 的複本。將座標乘以 3 還原為點擊位置，並在 MODLOG.md 中維護一份選單點擊點對照表，僅測量一次。
• 為何使用 gfxcapture： 使用 GDI 擷取時，GPU 渲染的遊戲會呈現黑色畫面。gfxcapture（Windows.Graphics.Capture）能擷取單一視窗的真實幀，即使被遮蓋也無妨。它無法擷取最小化的視窗。
• HDR 顯示器： 當 Windows 自動 HDR 為 SDR 遊戲開啟時，擷取的畫面會變得泛白（亮度提升 2-3 倍，偏青色），因此無法判斷顏色。um win shot/record 會在開啟時發出警告；請在擷取期間為遊戲關閉自動 HDR（設定 > 系統 > 顯示器 > 圖形 > 該遊戲 > 自動 HDR），並在使用者需要時再重新開啟。

讓視窗可預測

• 固定用戶端尺寸的視窗模式。 每個遊戲都將此設定藏在某處：
  • 一個 ini 檔（UE 的 GameUserSettings.ini 中的 [/Script/Engine.GameUserSettings]、Unity 的 Screenmanager Fullscreen mode / Resolution 登錄值，位於 HKCU\Software\<公司>\<產品>）；
  • 一個啟動旗標（-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）。

比點擊更好：腳本化場景或橋接器

• 模組中的聊天或控制台指令可給予物品、生成敵人或傳送。這讓測試只需一行指令（/arsenal、/mothership）。
• 測試場景： 模組端的時間軸（在第 N 幀生成一波敵人、在第 N+30 幀開火）、帶觸發器的劇情（透過 AoE2ScenarioParser 的 AoE2）、一個帶有乾淨備份的專用測試世界。
• Agent 橋接器： 模組內在 127.0.0.1 上的 JSON 行 Socket（參閱 examples/terraria-tmodloader/reference/AgentBridge.cs）。
  • 指令如 observe（以文字回傳選單選項或世界狀態）、click <id>、controls、step。
  • 在遊戲主執行緒上處理每個請求，確保回覆一致。
  • 從 UI 樹中通用地讀取選單，讓 Agent 看到玩家會看到的內容。排除破壞性按鈕（如刪除）。
  • Agent 接著可以完全不用像素來進行遊戲。
• 進程外後端： 保持遊戲內部分輕量，將大腦放在外部（HTTP/檔案投放）。這種模式可擴展到 AI NPC 和跨遊戲混搭。

崩潰與清理

• 崩潰回報程式（BugSplat 的 BsSndRpt64.exe、CrashReportClient.exe、UnityCrashHandler64.exe）可能會殘留，導致 Steam 顯示「已在執行中」。使用 um win ps 找出它們，再用 um win kill <pid> 清除。
• 切勿使用 pkill -f 或萬用字元 taskkill /IM。此模式可能匹配到您自己的 Shell 或其他應用程式。
• 崩潰後，先讀取載入器或遊戲紀錄（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（透過 GetWindowID 或 AppleScript 取得視窗 ID）、osascript / cliclick 用於輸入。輸入與螢幕錄製需要為終端機授予輔助使用與螢幕錄製權限。