用途
Game automation 是面向游戏模组开发者的自动化技能，目标是让 AI 智能体能够启动、观察并操作一个真实运行的游戏，从而测试自己编写的模组。其核心理念是“真实游戏就是验证基准”：建立“启动 → 导航 → 布置场景 → 操作 → 截图并读取日志 → 判断”的循环。每个游戏只需搭建一次，之后每次改动都能在一分钟内完成检查。
主要能力
该技能提供 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：通过 Steam 或 exe 启动游戏。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 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 案例：智能体聚焦 GTA 点击故事模式，人类按键落到 GTA 着陆页，GTA 警告“使用修改版本访问 GTA Online 服务器”。ScriptHookV 阻止了它，但不应依赖此保护。应检查 idle、请人类点击，并以关闭反作弊的方式启动，使在线模式无法开始。
- 输入只发送给游戏。WinDrive 在前台是其他应用时拒绝发送。唯一例外是没有前台应用且光标位于游戏上，这是窗口化游戏点击时丢失前台导致的。
- 用户可能正在电脑前。若 idle 少于一分钟，操作前先询问，并保持会话简短。用户同意后可无人值守运行。
- 截图消耗 token。查看
--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（设置 > 系统 > 显示 > 图形 > 该游戏 > 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）。
比点击更好的方式：脚本化场景或桥接
- 模组中的聊天或控制台命令可给予物品、生成敌人和传送，使测试只需一行（
/arsenal、/mothership）。 - 测试场景：模组侧时间线（第 N 帧生成波次，第 N+30 帧开火）、带触发器的场景（AoE2 通过 AoE2ScenarioParser）、带原始备份的专用测试世界。
- 智能体桥接：模组内 127.0.0.1 上的 JSON-lines socket（参见 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，模式可能匹配到自己的 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（窗口 id 通过 GetWindowID 或 AppleScript 获取），输入用 osascript / cliclick。输入和屏幕录制需要为终端授予辅助功能与屏幕录制权限。
适用场景与限制
适用于游戏模组开发与测试，尤其是需要验证模组在真实游戏中的行为。限制包括：主要面向 Windows，Linux/macOS 支持有限；截图消耗 token；HDR 与后台节流会影响捕获；gfxcapture 无法捕获最小化窗口；在线模式存在安全风险，需谨慎处理。