game-automation

游戏自动化：Agent 的双手和双眼

真正的游戏就是预言机。循环流程为：启动 → 导航 → 设置场景 → 执行操作 → 截图并读取日志 → 作出决策。每款游戏只需构建一次，之后每次更改都能在一分钟内检查。

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；标准输入协议，每行返回一条回复）。坐标相对于 游戏窗口的客户区。

• 鼠标：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 以点击 Story Mode，人类的按键却输入到了 GTA 的着陆页，GTA 随即警告称正在“使用修改版访问 GTA Online 服务器”。ScriptHookV 阻止了这一行为；不要依赖它。 检查 idle，请人类点击，并在关闭反作弊的情况下启动游戏，以防进入在线模式。参见 knowledge/techniques/driving-real-games-safely.md。
• 输入只会发送到游戏。 当另一个应用处于前台时，WinDrive 会拒绝发送输入。唯一例外是没有应用处于前台且光标位于游戏上方的情况；窗口化游戏在点击时会导致这种情况。
• 用户可能就在电脑旁。 如果 idle 不到一分钟，请先征求同意再操作，并缩短操作时长。用户同意后即可无人值守运行。
• 截图会消耗令牌。 查看 --scale 0.33 生成的副本。点击时将坐标乘以 3，并在 MODLOG.md 中记录菜单点击位置表，只需测量一次。
• 为什么使用 gfxcapture： 使用 GDI 捕获时，GPU 渲染的游戏画面会变黑。gfxcapture（Windows.Graphics.Capture）可以捕获单个窗口的实际帧，即使窗口被遮挡也行。但无法捕获最小化的窗口。
• HDR 显示器： 对 SDR 游戏开启 Windows Auto HDR 时，捕获的画面会褪色（亮度高出 2-3 倍，且偏青），因此无法判断颜色。um win shot/record 会在检测到此情况时发出警告；捕获画面时请为游戏关闭此功能（Settings > System > Display > Graphics > the game > 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）。

比点击更好：脚本化场景或桥接

• 模组中的聊天或控制台命令可给予物品、生成敌人和传送。这样只需一行命令即可测试 （/arsenal、/mothership）。
• 测试场景： 模组端时间线（在第 N 帧生成一波敌人，在 N+30 帧开火）、带触发器的场景 （通过 AoE2ScenarioParser 实现 AoE2），或带有完好备份的专用测试世界。
• Agent 桥接： 在模组中通过 127.0.0.1 上的 JSON 行套接字实现（参见 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 skill 中列出了日志位置），然后查看 Windows 事件查看器中的 Application 日志，排查原生崩溃。

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 处理输入。终端需要获得辅助功能和屏幕录制权限，才能输入和录屏。