automação-de-jogos

Automação de jogos: as mãos e os olhos do agente

O jogo real é o oráculo. O ciclo é iniciar → navegar → configurar a cena → agir → capturar tela e ler logs → decidir. Construa uma vez por jogo, então cada alteração que você fizer pode ser verificada em um minuto.

Windows (nativo ou a partir do WSL): um win

um win setup                                   # uma vez: ferramentas PowerShell + um ffmpeg com gfxcapture, escolhe NVENC/AMF/QSV/x264
um win ps                                      # processos em janela: pid, nome, título
um win launch --steam 105600                   # ou: um win launch "C:\Games\Foo\Foo.exe" -- -windowed
um win shot --exe Terraria.exe shot.png --scale 0.33   # quadro completo + uma cópia 1/3 que é barata de olhar
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> pausa entre os passos
um win drive --proc Terraria idle              # segundos desde que o usuário tocou no mouse/teclado pela última vez (não espera)
um win kill <pid>                              # apenas PID exato
um win reg get "HKCU\Software\..."             # registro (reg set faz backup da chave primeiro)

A partir do Python (para scripts mais longos), from um.win import Drive, shot, Recorder, então d = Drive("AoE2DE_s"), d.focus(), d.click(x, y), d.key("0x0D").

Comandos WinDrive (um/ps1/WinDrive.ps1; protocolo stdin, uma resposta por linha). As coordenadas estão na área cliente da janela do jogo.

• Mouse: move x y, click x y [right], mdown/mup, drag x0 y0 x1 y1, rel dx dy (câmeras FPS / entrada bruta), wheel 120.
• Teclado: key <vk> [tap|down|up], hold <vk> <ms>, type <text>, scanmode on (DirectInput / jogos de entrada bruta que ignoram eventos de tecla virtual).
• Janela: focus, rect, size <w> <h> (define o tamanho da área cliente), title, fg, idle, untop.
• Temporização: sleep <ms> aguarda entre os passos em uma única chamada. Cada chamada um win drive inicia o PowerShell (1-2 s), então coloque combos temporizados em uma única chamada.
• Códigos de tecla virtual: Esc 0x1B, Enter 0x0D, Espaço 0x20, W/A/S/D 0x57/0x41/0x53/0x44, F1 0x70, Shift 0x10, Ctrl 0x11, setas 0x25-0x28.

Regras de conduta

• Nunca foque um jogo com modo online enquanto o humano está digitando. Aconteceu com GTA V: o agente focou GTA para clicar em Modo História, as teclas digitadas pelo humano atingiram a página inicial do GTA, e o GTA avisou sobre "acesso aos servidores do GTA Online com uma versão alterada". ScriptHookV bloqueou; não confie nisso. Verifique idle, peça ao humano para clicar e inicie com o anti-cheat desligado para que o online não possa iniciar. Veja knowledge/techniques/driving-real-games-safely.md.
• A entrada só vai para o jogo. O WinDrive se recusa a enviar enquanto outro aplicativo está em primeiro plano. A única exceção é quando nada está e o cursor está sobre o jogo, o que jogos em modo janela causam ao perder o primeiro plano em cliques.
• O usuário pode estar no PC. Se idle for menor que um minuto, pergunte antes de dirigir e mantenha as sessões curtas. Execuções não supervisionadas são aceitáveis uma vez que o usuário autorize.
• Capturas de tela custam tokens. Olhe para cópias --scale 0.33. Multiplique as coordenadas de volta ×3 para cliques e mantenha uma tabela de pontos de clique de menu no MODLOG.md, medidos uma vez.
• Por que gfxcapture: jogos renderizados por GPU saem pretos com captura GDI. gfxcapture (Windows.Graphics.Capture) captura quadros reais de uma janela, mesmo quando coberta. Não pode capturar janelas minimizadas.
• Telas HDR: com o Windows Auto HDR ativado para um jogo SDR, as capturas saem lavadas (2-3x mais brilhantes, deslocadas para ciano), então as cores não podem ser avaliadas. um win shot/record avisam quando está ativado; desligue para o jogo durante a captura (Configurações > Sistema > Vídeo > Gráficos > o jogo > Auto HDR), e religue depois se o usuário quiser.

Torne a janela previsível

• Modo janela com um tamanho fixo de área cliente. Cada jogo esconde essa configuração em algum lugar:
  • um ini ([/Script/Engine.GameUserSettings] no UE GameUserSettings.ini, valores de registro Screenmanager Fullscreen mode/Resolution do Unity sob HKCU\Software\<empresa>\<produto>);
  • um flag de inicialização (-windowed -w 1920 -h 1080, Unity -screen-fullscreen 0 -screen-width 1920 -screen-height 1080, Source -sw -w 1920 -h 1080);
  • ou o próprio registro do jogo (AoE2: Mode Display 0 + Windowed Width/Height).
  • um win drive --proc X "size 1920 1080" também redimensiona a maioria dos jogos em janela.
• Pule intros: flags de inicialização (-skipintro, -nosplash, Unity -popupwindow), ou exclua/renomeie vídeos de introdução em uma cópia do jogo.
• Vá direto ao ponto: flags de loader (tModLoader -skipselect Player:World), um save feito para teste, carregamento automático de cenário, um comando de console de desenvolvimento.
• Throttling em segundo plano: muitos jogos reduzem ou pausam quando não estão em foco. Encontre a configuração (Terraria: Main.instance.InactiveSleepTime = TimeSpan.Zero; Unity: Application.runInBackground = true; UE: t.IdleWhenNotForeground 0).

Melhor do que clicar: uma cena com script ou uma ponte

• Comandos de chat ou console no seu mod dão itens, spawnam inimigos e teleportam. Eles tornam os testes uma linha (/arsenal, /mothership).
• Cenas de teste: uma linha do tempo do lado do mod (spawnar ondas no quadro N, atirar no N+30), um cenário com gatilhos (AoE2 via AoE2ScenarioParser), um mundo de teste dedicado com um backup intacto.
• Ponte do agente: um socket JSON-lines dentro do mod em 127.0.0.1 (veja examples/terraria-tmodloader/reference/AgentBridge.cs).
  • Comandos como observe (opções de menu ou estado do mundo como texto), click <id>, controls, step.
  • Trate cada requisição na thread principal do jogo após uma atualização, para que as respostas sejam consistentes.
  • Leia menus genericamente da árvore de UI, para que o agente veja o que um jogador veria. Deixe botões destrutivos (excluir) de fora.
  • Um agente pode então jogar sem pixels.
• Backend fora do processo: mantenha a parte dentro do jogo enxuta e coloque o cérebro fora (HTTP/file-drop). Esse padrão escala para NPCs com IA e mashups entre jogos.

Falhas e limpeza

• Relatórios de crash (BugSplat BsSndRpt64.exe, CrashReportClient.exe, UnityCrashHandler64.exe) podem permanecer e fazer o Steam dizer "já em execução". um win ps para identificá-los, um win kill <pid> para limpá-los.
• Nunca pkill -f ou taskkill /IM com curinga. O padrão pode corresponder ao seu próprio shell ou outros aplicativos.
• Após uma falha, leia o log do loader ou do jogo primeiro (a habilidade mod-any-game os lista), depois o Visualizador de Eventos do Windows (log de Aplicativo) para falhas nativas.

Linux e macOS

• Linux (X11): xdotool search --name "Jogo" windowactivate --sync key Escape, xdotool mousemove --window $W 640 360 click 1. Capturas de tela: import -window $(xdotool search --name Jogo) shot.png, ou ffmpeg x11grab.
• Linux (Wayland): ydotool + grim. Jogos Proton são jogos Windows sob Wine: opções de inicialização (WINEDLLOVERRIDES, PROTON_LOG=1) vão no Steam.
• macOS: screencapture -l <windowid> shot.png (id da janela via GetWindowID ou AppleScript), osascript / cliclick para entrada. Entrada e captura de tela precisam de permissão de Acessibilidade e Captura de Tela para o terminal.