game-automation

Spielautomatisierung: die Hände und Augen des Agenten

Das echte Spiel ist der Orakel. Der Kreislauf ist: Starten → Navigieren → Szene aufbauen → Handeln → Screenshot machen und Logs lesen → entscheiden. Baue es einmal pro Spiel auf, dann kann jede Änderung, die du machst, in einer Minute überprüft werden.

Windows (nativ oder aus WSL): um win

um win setup                                   # einmalig: PowerShell-Tools + ffmpeg mit gfxcapture, wählt NVENC/AMF/QSV/x264
um win ps                                      # fensterprozesse: PID, Name, Titel
um win launch --steam 105600                   # oder: um win launch "C:\Games\Foo\Foo.exe" -- -windowed
um win shot --exe Terraria.exe shot.png --scale 0.33   # Vollbild + eine 1/3-Kopie, die billig anzusehen ist
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> pausiert zwischen Schritten
um win drive --proc Terraria idle              # Sekunden seit der letzte Benutzer Maus/Tastatur berührt hat (wartet nicht)
um win kill <pid>                              # nur genaue PID
um win reg get "HKCU\Software\..."             # Registry (reg set sichert den Schlüssel zuerst)

Aus Python (für längere Skripte): from um.win import Drive, shot, Recorder, dann d = Drive("AoE2DE_s"), d.focus(), d.click(x, y), d.key("0x0D").

WinDrive-Kommandos (um/ps1/WinDrive.ps1; stdin-Protokoll, eine Antwort pro Zeile). Koordinaten beziehen sich auf den Clientbereich des Spielfensters.

• Maus: move x y, click x y [right], mdown/mup, drag x0 y0 x1 y1, rel dx dy (FPS-Kameras / Raw Input), wheel 120.
• Tastatur: key <vk> [tap|down|up], hold <vk> <ms>, type <text>, scanmode on (DirectInput / Raw-Input-Spiele, die virtuelle Tastencodes ignorieren).
• Fenster: focus, rect, size <w> <h> (setzt die Client-Größe), title, fg, idle, untop.
• Timing: sleep <ms> wartet zwischen Schritten in einem Aufruf. Jeder um win drive-Aufruf startet PowerShell (1-2 s), also setze zeitgesteuerte Kombos in einen Aufruf.
• Virtuelle Tastencodes: Esc 0x1B, Enter 0x0D, Leerzeichen 0x20, W/A/S/D 0x57/0x41/0x53/0x44, F1 0x70, Shift 0x10, Strg 0x11, Pfeile 0x25-0x28.

Verhaltensregeln

• Setze niemals ein Spiel mit Online-Modus in den Fokus, während der Mensch tippt. Das passierte mit GTA V: Der Agent fokussierte GTA, um den Story-Modus zu klicken, die Tastatureingaben des Menschen trafen GTA's Startseite und GTA warnte vor "Zugriff auf GTA Online-Server mit einer geänderten Version". ScriptHookV blockierte es; verlass dich nicht darauf. Überprüfe idle, bitte den Menschen zu klicken und starte ohne Anti-Cheat, damit Online nicht starten kann. Siehe knowledge/techniques/driving-real-games-safely.md.
• Eingaben gehen nur an das Spiel. WinDrive verweigert die Ausgabe, während eine andere Anwendung im Vordergrund ist. Einzige Ausnahme: Wenn keine Anwendung im Vordergrund ist und der Cursor über dem Spiel liegt – was bei Fensterspielen passieren kann, wenn sie den Vordergrund beim Klicken verlieren.
• Der Benutzer könnte am PC sein. Wenn idle unter einer Minute liegt, frage vor dem Steuern und halte Sitzungen kurz. Unbeaufsichtigte Läufe sind in Ordnung, sobald der Benutzer zustimmt.
• Screenshots kosten Tokens. Verwende --scale 0.33-Kopien. Multipliziere Koordinaten für Klicks mit ×3 und führe eine Tabelle der Klickpunkte in MODLOG.md, einmalig gemessen.
• Warum gfxcapture: GPU-gerenderte Spiele erscheinen bei GDI-Erfassung schwarz. gfxcapture (Windows.Graphics.Capture) erfasst echte Frames eines Fensters, sogar wenn es verdeckt ist. Kann jedoch keine minimierten Fenster erfassen.
• HDR-Displays: Bei aktiviertem Windows Auto HDR für ein SDR-Spiel erscheinen Aufnahmen verwaschen (2-3x heller, cyan-verschoben), sodass Farben nicht beurteilt werden können. um win shot/record warnen, wenn es an ist; schalte es für das Spiel während der Aufnahme aus (Einstellungen > System > Bildschirm > Grafik > das Spiel > Auto HDR) und danach wieder an, wenn der Benutzer es möchte.

Mache das Fenster vorhersagbar

• Fenstermodus mit fester Client-Größe. Jedes Spiel versteckt diese Einstellung irgendwo:
  • einer ini ([/Script/Engine.GameUserSettings] in UEs GameUserSettings.ini, Unitys Screenmanager Fullscreen mode / Resolution-Registry-Werte unter HKCU\Software\<Firma>\<Produkt>);
  • einem Startflag (-windowed -w 1920 -h 1080, Unity -screen-fullscreen 0 -screen-width 1920 -screen-height 1080, Source -sw -w 1920 -h 1080);
  • oder der eigenen Registry des Spiels (AoE2: Mode Display 0 + Windowed Width/Height).
  • um win drive --proc X "size 1920 1080" passt auch die Größe der meisten Fensterspiele an.
• Intros überspringen: Startflags (-skipintro, -nosplash, Unity -popupwindow) oder lösche/benenne Intro-Videos in einer Kopie des Spiels um.
• Direkt einsteigen: Loader-Flags (tModLoader -skipselect Player:World), ein für Tests erstellter Spielstand, Szenario-Autoload, ein Dev-Console-Befehl.
• Hintergrund-Drosselung: Viele Spiele drosseln oder pausieren, wenn sie nicht im Fokus sind. Finde die Einstellung (Terraria: Main.instance.InactiveSleepTime = TimeSpan.Zero; Unity: Application.runInBackground = true; UE: t.IdleWhenNotForeground 0).

Besser als Klicken: eine skriptgesteuerte Szene oder eine Brücke

• Chat- oder Konsolenbefehle in deinem Mod geben Gegenstände, spawnen Feinde und teleportieren. Sie machen Tests zu einer Zeile (/arsenal, /mothership).
• Testszenen: eine modseitige Zeitleiste (Wellen bei Frame N spawnen, bei N+30 feuern), ein Szenario mit Triggern (AoE2 via AoE2ScenarioParser), eine dedizierte Testwelt mit einem unberührten Backup.
• Agent-Brücke: ein JSON-Lines-Socket im Mod auf 127.0.0.1 (siehe examples/terraria-tmodloader/reference/AgentBridge.cs).
  • Befehle wie observe (Menüoptionen oder Weltzustand als Text), click <id>, controls, step.
  • Bearbeite jede Anfrage im Hauptthread des Spiels nach einem Update, damit die Antworten konsistent sind.
  • Lese Menüs generisch aus dem UI-Baum, sodass der Agent sieht, was ein Spieler sehen würde. Lasse zerstörerische Schaltflächen (Löschen) weg.
  • Ein Agent kann dann ganz ohne Pixel spielen.
• Außerprozess-Backend: Halte den spielinternen Teil dünn und platziere das Gehirn außerhalb (HTTP/Dateiablage). Dieses Muster skaliert auf KI-NPCs und spielübergreifende Mashups.

Abstürze und Aufräumen

• Crash-Reporter (BugSplat BsSndRpt64.exe, CrashReportClient.exe, UnityCrashHandler64.exe) können hängen bleiben und Steam sagen lassen "Läuft bereits". um win ps zum Finden, um win kill <pid> zum Entfernen.
• Verwende niemals pkill -f oder wildcard taskkill /IM. Das Muster kann deine eigene Shell oder andere Anwendungen treffen.
• Nach einem Absturz lies zuerst das Loader- oder Spiel-Log (das mod-any-game-Skill listet sie), dann das Windows-Ereignisprotokoll (Anwendungsprotokoll) für native Abstürze.

Linux und macOS

• Linux (X11): xdotool search --name "Spiel" windowactivate --sync key Escape, xdotool mousemove --window $W 640 360 click 1. Screenshots: import -window $(xdotool search --name Spiel) shot.png, oder ffmpeg x11grab.
• Linux (Wayland): ydotool + grim. Proton-Spiele sind Windows-Spiele unter Wine: Startoptionen (WINEDLLOVERRIDES, PROTON_LOG=1) in Steam setzen.
• macOS: screencapture -l <windowid> shot.png (Fenster-ID via GetWindowID oder AppleScript), osascript / cliclick für Eingaben. Für Eingaben und Bildschirmaufnahme sind Berechtigungen für Barrierefreiheit und Bildschirmaufnahme für das Terminal erforderlich.