game-automation (automatización de juegos)

Automatización de juegos: las manos y los ojos del agente

El juego real es el oráculo. El bucle es: lanzar → navegar → preparar la escena → actuar → capturar pantalla y leer registros → decidir. Constrúyelo una vez por juego, luego cada cambio que hagas podrá verificarse en un minuto.

Windows (nativo o desde WSL): um win

um win setup                                   # una vez: herramientas PowerShell + un ffmpeg con gfxcapture, elige NVENC/AMF/QSV/x264
um win ps                                      # procesos en ventana: pid, nombre, título
um win launch --steam 105600                   # o: um win launch "C:\Juegos\Foo\Foo.exe" -- -windowed
um win shot --exe Terraria.exe shot.png --scale 0.33   # fotograma completo + una copia a 1/3 que es barata de mirar
um win drive --proc Terraria "focus" "click 640 360" "key 0x1B" "type hola" "hold 0x44 1500"
um win drive --proc Terraria "hold 0x20 150" "sleep 200" "hold 0x20 150"   # sleep <ms> pausa entre pasos
um win drive --proc Terraria idle              # segundos desde que el usuario tocó el ratón/teclado (no espera)
um win kill <pid>                              # solo PID exacto
um win reg get "HKCU\Software\..."             # registro (reg set hace una copia de seguridad de la clave primero)

Desde Python (para scripts más largos): from um.win import Drive, shot, Recorder, luego d = Drive("AoE2DE_s"), d.focus(), d.click(x, y), d.key("0x0D").

Comandos de WinDrive (um/ps1/WinDrive.ps1; protocolo stdin, una respuesta por línea). Las coordenadas están en el área cliente de la ventana del juego.

• Ratón: move x y, click x y [right], mdown/mup, drag x0 y0 x1 y1, rel dx dy (cámaras FPS / entrada bruta), wheel 120.
• Teclado: key <vk> [tap|down|up], hold <vk> <ms>, type <texto>, scanmode on (DirectInput / juegos de entrada bruta que ignoran eventos de tecla virtual).
• Ventana: focus, rect, size <an> <al> (establece el tamaño del cliente), title, fg, idle, untop.
• Temporización: sleep <ms> espera entre pasos en una misma llamada. Cada llamada um win drive inicia PowerShell (1-2 s), así que pon las combinaciones temporizadas en una sola llamada.
• Códigos de tecla virtual: Esc 0x1B, Intro 0x0D, Espacio 0x20, W/A/S/D 0x57/0x41/0x53/0x44, F1 0x70, Mayús 0x10, Ctrl 0x11, flechas 0x25-0x28.

Reglas de circulación

• Nunca enfoques un juego con modo online mientras el humano está escribiendo. Sucedió con GTA V: el agente enfocó GTA para hacer clic en Modo Historia, las pulsaciones del humano llegaron a la página de inicio de GTA, y GTA advirtió sobre "acceder a los servidores de GTA Online con una versión alterada". ScriptHookV lo bloqueó; no confíes en eso. Comprueba idle, pide al humano que haga clic, y ejecuta con el anticheat desactivado para que online no pueda iniciarse. Consulta knowledge/techniques/driving-real-games-safely.md.
• La entrada solo va al juego. WinDrive se niega a enviar mientras otra aplicación está en primer plano. La única excepción es cuando no hay ninguna y el cursor está sobre el juego, lo que los juegos en ventana causan al perder el primer plano al hacer clic.
• El usuario puede estar en el PC. Si idle es inferior a un minuto, pregunta antes de manejar y mantén las sesiones cortas. Las ejecuciones desatendidas están bien una vez que el usuario lo autorice.
• Las capturas cuestan tokens. Mira las copias --scale 0.33. Multiplica las coordenadas de vuelta ×3 para los clics y mantén una tabla de puntos de clic de menú en MODLOG.md, medida una vez.
• Por qué gfxcapture: los juegos renderizados por GPU salen negros con captura GDI. gfxcapture (Windows.Graphics.Capture) captura los fotogramas reales de una ventana, incluso cuando está cubierta. No puede capturar ventanas minimizadas.
• Pantallas HDR: con Windows Auto HDR activado para un juego SDR, las capturas salen deslavadas (2-3 veces más brillantes, con desplazamiento cian), por lo que no se pueden juzgar los colores. um win shot/record advierten cuando está activado; desactívalo para el juego mientras se captura (Configuración > Sistema > Pantalla > Gráficos > el juego > Auto HDR), y vuelve a activarlo después si el usuario lo desea.

Haz la ventana predecible

• Modo ventana con un tamaño de cliente fijo. Cada juego esconde esta configuración en algún sitio:
  • un ini ([/Script/Engine.GameUserSettings] en UE GameUserSettings.ini, valores de registro Screenmanager Fullscreen mode / Resolution de Unity bajo HKCU\Software\<empresa>\<producto>);
  • un flag de lanzamiento (-windowed -w 1920 -h 1080, Unity -screen-fullscreen 0 -screen-width 1920 -screen-height 1080, Source -sw -w 1920 -h 1080);
  • o el propio registro del juego (AoE2: Mode Display 0 + Windowed Width/Height).
  • um win drive --proc X "size 1920 1080" también redimensiona la mayoría de juegos en ventana.
• Saltar intros: flags de lanzamiento (-skipintro, -nosplash, Unity -popupwindow), o borrar/renombrar videos de introducción en una copia del juego.
• Entrar directo: flags del cargador (tModLoader -skipselect Player:World), una partida guardada para pruebas, carga automática de escenario, un comando de consola de desarrollador.
• Limitación en segundo plano: muchos juegos limitan o pausan cuando no están enfocados. Encuentra la opción (Terraria: Main.instance.InactiveSleepTime = TimeSpan.Zero; Unity: Application.runInBackground = true; UE: t.IdleWhenNotForeground 0).

Mejor que hacer clic: una escena con script o un puente

• Comandos de chat o consola en tu mod que den objetos, generen enemigos y teletransporten. Hacen que las pruebas sean de una línea (/arsenal, /mothership).
• Escenas de prueba: una línea de tiempo en el mod (oleadas de apariciones en el fotograma N, disparo en N+30), un escenario con disparadores (AoE2 mediante AoE2ScenarioParser), un mundo de prueba dedicado con una copia de seguridad impecable.
• Puente del agente: un socket de líneas JSON dentro del mod en 127.0.0.1 (ver examples/terraria-tmodloader/reference/AgentBridge.cs).
  • Comandos como observe (opciones de menú o estado del mundo como texto), click <id>, controls, step.
  • Maneja cada solicitud en el hilo principal del juego después de una actualización, para que las respuestas sean consistentes.
  • Lee los menús genéricamente desde el árbol de la interfaz de usuario, para que el agente vea lo que vería un jugador. Deja fuera los botones destructivos (eliminar).
  • Un agente puede entonces jugar sin píxeles en absoluto.
• Backend fuera del proceso: mantén la parte dentro del juego ligera y pon la inteligencia fuera (HTTP/archivo). Ese patrón escala a NPCs IA y mashups entre juegos.

Fallos y limpieza

• Los informes de fallos (BugSplat BsSndRpt64.exe, CrashReportClient.exe, UnityCrashHandler64.exe) pueden quedarse y hacer que Steam diga "ya en ejecución". um win ps para detectarlos, um win kill <pid> para eliminarlos.
• Nunca uses pkill -f o el comodín taskkill /IM. El patrón podría coincidir con tu propio shell u otras aplicaciones.
• Después de un fallo, lee primero el registro del cargador o del juego (la habilidad mod-any-game los enumera), luego el Visor de eventos de Windows (registro de Aplicación) para fallos nativos.

Linux y macOS

• Linux (X11): xdotool search --name "Juego" windowactivate --sync key Escape, xdotool mousemove --window $W 640 360 click 1. Capturas: import -window $(xdotool search --name Juego) shot.png, o ffmpeg x11grab.
• Linux (Wayland): ydotool + grim. Los juegos Proton son juegos de Windows bajo Wine: las opciones de lanzamiento (WINEDLLOVERRIDES, PROTON_LOG=1) van en Steam.
• macOS: screencapture -l <idventana> shot.png (id de ventana mediante GetWindowID o AppleScript), osascript / cliclick para entrada. La entrada y la grabación de pantalla necesitan permiso de Accesibilidad y Grabación de Pantalla para la terminal.