Dieses How‑To Guide zeigt praxisnah, wie das unity ml agents Toolkit genutzt wird, um NPCs zu trainieren, zu evaluieren und im Spiel auszuführen.
Das Open‑Source‑Toolkit basiert auf PyTorch und unterstützt 2D/3D/VR/AR‑Szenarien. Es bietet Reinforcement Learning, Imitation Learning und Multi‑Agent‑Training als Kernmethoden.
Leser erhalten eine klare Roadmap: Installation, Projekt‑Setup, Training, Evaluation und Integration der Modelle in Projekte. Der Fokus liegt auf praktischen Schritten für Game‑Entwickler und Forschende.
Wir grenzen Rollen ab: Aus Sicht der Spielentwicklung stehen NPC‑Balancing, Tests und Inference im Vordergrund. Forschende nutzen reichhaltige Umgebungen für Experimente.
Typische Stolpersteine wie Versionskonflikte, Python‑Abhängigkeiten und Branch‑Wahl werden angesprochen. Erwartungsmanagement: Training braucht Iteration, aber keine Doktorarbeit — das Toolkit liefert viele Bausteine.
Wichtigste Erkenntnisse
- Schritt‑für‑Schritt: Von Installation bis Inference.
- Unterstützt viele Lernansätze für moderne Spiele.
- Praktisch nutzbar ohne tiefe Forschungsexpertise.
- Beachte Versionen und Python‑Dependencies.
- Training erfordert Iteration bei Reward‑Design.
Was ist das ML-Agents Toolkit und wofür lohnt es sich in Games?
Das Toolkit verwandelt Unity‑Szenen in realistische Trainingsumgebungen, in denen lernfähige agents Verhaltensstrategien entwickeln können.
Unity als Trainings-Environment für intelligente Agents in 2D, 3D und VR/AR
Die Engine bietet Physik, Animation und Rendering, die reale Situationen nachbilden. Das macht sie attraktiv als environment für Lernaufgaben in 2D, 3D und VR/AR.
Im Kern liefert die Szene Beobachtungen und empfängt Aktionen. Ein Python‑Trainer optimiert Policies basierend auf dieser Rückkopplung.
Typische Anwendungsfälle: NPC-Verhalten, Balancing, Autotesting und Simulationen
Praxisbeispiele reichen von Patrouillen und Team‑KI bis zu adversarial Multi‑agenten‑Szenarien. Entwickler nutzen die Umgebungen auch fürs Balancing: Parameterkombinationen werden automatisiert durchgespielt.
Autotesting hilft, Builds automatisch zu prüfen — etwa Level‑Completeness oder Softlocks — und reduziert manuelle QA‑Last.
Außerhalb von Spielen dienen die Szenen als kontrollierte simulations‑Umgebungen für autonome Fahrzeuge, Robotik oder industrielle Trainingsfälle.
- Wichtigste features: Randomization, Curriculum, Multi‑Environment für robustere Policies.
- Über 17 Beispiel‑environments erleichtern den Einstieg.
Voraussetzungen für ein stabiles Setup unter Windows, macOS und Linux
Ein stabiler Entwicklungs‑Stack ist die Grundlage für reproduzierbare Trainingsläufe auf allen Plattformen. Legen Sie früh Editor‑, Python‑ und Paketversionen fest, um späteren Migrationsstress zu vermeiden.
Die Installation über Unity Hub wird empfohlen. Das Kern‑Modul com.unity.ml-agents ist als unity package verfügbar. Manche aktuellen Funktionen liegen als Preview Packages vor und sind für neuere releases relevant.
Package‑Status, Release‑Zyklus und Kompatibilität
Package‑Stände unterscheiden sich: verified bedeutet getestete Stabilität, preview liefert neue Features, aber weniger Garantien.
Achten Sie darauf, dass die unity package‑Version mit der Python‑Bibliothek zusammenpasst. Fehlende Kompatibilität verursacht schwer zu debuggende API‑Fehler.
- Checkliste pro OS: Unity Hub + passende Editor‑Version; Python 3.10.12 empfohlen; Paketmanager (pip/conda).
- Verwenden Sie virtuelle Environments (conda/mamba oder venv) für reproduzierbare installs.
- Versionen früh festnageln und dokumentation der gewählten Kombinationen speichern.
Python‑Anforderungen und virtuelle Environments
Unterstützte Python‑Range: >= 3.10.1 bis
Nutzen Sie virtuelle Environments, um Konflikte mit Projekten aus früheren years zu verhindern.
Installation: Unity Package, Python-Pakete und Repository richtig kombinieren
Für eine zuverlässige Installation trennen Sie klar die C#‑SDK‑Komponenten vom Python‑Stack. Die drei Kern‑components sind das Unity Package com.unity.ml‑agents, das Python‑Paket mlagents und mlagents_envs. Das C#‑Paket liefert Behaviors, Sensors und das Laufzeit‑API; Python übernimmt Training, Optimizer und Logging.
Repository klonen vs. Package‑Installation
Ein einfacher package‑Install reicht, wenn Sie nur Beispiele nutzen oder eine stabile release brauchen. Klonen Sie das repository, wenn Sie neueste Fixes, Trainingsconfigs oder Beispiele benötigen. Use-case: Produktivbetrieb → release‑branch; Entwicklung → develop (unstable) für bleeding‑edge‑Fixes.
Praktische Schrittfolge
In Unity: Package Manager öffnen, Advanced → Enable Preview Packages, dann com.unity.ml‑agents installieren und Samples importieren.
Für Python: Erstellen Sie ein conda/mamba‑Env:
conda create -n mlagents python=3.10.12conda activate mlagents- Installieren Sie zuerst mlagents_envs, dann mlagents oder pinnen Sie auf die PyPI‑Version.
Verifikation: Führen Sie mlagents-learn --help als schnellen Smoke‑Test aus, um CLI, Abhängigkeiten und Pfade zu prüfen.
Windows‑Spezialfall
On windows make sure, dass PyTorch mit CUDA vorinstalliert ist, sonst läuft Training nur auf CPU. Beispiel: pip3 install torch~=2.2.1 --index-url https://download.pytorch.org/whl/cu121. Installieren Sie bei Bedarf das Visual C++ Redistributable, um DLL‑Fehler zu vermeiden.
Typische Stolpersteine
- Version‑Mismatch zwischen unity package und Python‑releases.
- Fehlende Preview‑Anzeige im Package Manager (Advanced aktivieren).
- Falscher branch nach dem Klonen führt zu unerwarteten Abhängigkeiten.
Projekt-Setup in Unity: Scenes, Environments und wichtige Komponenten
Beginnen Sie mit einer minimalen Trainings‑Scene, die klar definierte Reset‑Punkte, Zielobjekte und einfache Physik enthält. So schaffen Sie eine saubere Basis, auf der schrittweise Beobachtungen, Aktionen und Rewards erweitert werden können.
Agent in der Szene platzieren: Observations, Actions und Reward‑Design
Platzieren Sie einen Agent‑GameObject mit Behavior‑Komponente, Collider und einer Reset‑Routine. Ergänzen Sie Zielobjekte und einfache Sensing‑Komponenten.
- Minimal: Agent/Behavior, Collider, Ziel, Reset‑Logik.
- Observations: Positionen, Distanzen, Raycasts, Geschwindigkeiten.
- Actions: Diskret oder kontinuierlich an Movement/Animation binden.
Observations und Actions sinnvoll planen
Geben Sie nur die Informationen, die für das Lernen nötig sind. Zu perfekte Beobachtungen führen schnell zu Overfitting.
Wählen Sie Actions so, dass Movement stabil bleibt: langsame Schritte, klare Grenzen und sinnvolle Skalierung helfen dem Training.
Environment‑Properties: Trainingsbedingungen reproduzierbar machen
Seed, deterministische Physik und kontrollierte Randomisierung sind zentral. Versionieren Sie die Scene und dokumentieren Sie Property‑Werte.
- Feste Reset‑Positionen vs. kontrollierte Randomisierung.
- Physik‑Settings, Seeds und Reset‑Bedingungen.
- Saubere Done/Reset‑Signale für stabilen Datenfluss.
„Ein reproduzierbares Environment reduziert Überraschungen und beschleunigt echtes learning.“
unity ml agents in der Praxis: den ersten Agenten trainieren
Im praktischen Ablauf beginnt das erste Training, wenn die Szene Beobachtungen an den externen Trainer sendet und Aktionen zurückliefert. Dieser Abschnitt zeigt den minimalen Workflow vom Start bis zur Inference im Spiel.
Verbindung aufbauen und Training starten
Führen Sie die Scene im Play Mode oder als Build aus und starten den Python‑Trainer (mlagents). Ein kurzer Handshake über Port und Protokoll stellt sicher, dass Beobachtungen gesendet und Aktionen empfangen werden.
Konfiguration und erste Stellschrauben
Trainingsparameter liegen in Config‑YAMLs: Batch Size, Buffer, Learning Rate und Reward‑Signale. Optimieren Sie anfangs nur grobe Werte, statt alle hyperparameter gleichzeitig zu ändern.
Ergebnisse bewerten und typische Signale
Wichtige Metriken sind episodischer Reward, Success Rate, Loss und Entropy. Gute Signale: steigende Erfolgsrate, kürzere Time‑to‑Goal und stabilere Aktionen.
- Warnsignale: Plateau, hohe Varianz, Reward‑Exploits.
- Export: Modell als .onnx oder .nn speichern und im Package referenzieren.
- Example‑Loop: Build ↔ Trainer → Evaluierung → Export → Inference.
„Ein klarer Trainingsloop macht den Sprung von Beispiel‑Setup zu produktionsreifem Modell planbar.“
Reinforcement Learning verstehen: Algorithmen und passende Einsatzszenarien
Reinforcement learning ordnet Verhaltensanpassung über Rewards statt manueller Regeln ein. Ein Agent interagiert mit dem Environment und optimiert seine Policy über Episoden. So entstehen adaptive, nicht‑deterministische Verhaltensweisen für Spiele und Simulationen.
PPO vs. SAC: Stabilität und Einsatzfelder
PPO ist robust und stabil. Es eignet sich gut für diskrete Entscheidungen und schnelle Iterationen. PPO skaliert zuverlässig für viele Trainings‑years und einfache Steuerungsaufgaben.
SAC bietet bessere Sample‑Effizienz bei kontinuierlicher Kontrolle. Für flüssige Bewegung, präzise Steuerung oder energieeffiziente Policies bringt SAC oft Vorteile.
MA‑POCA und Self‑Play für Multi‑Agent‑Settings
MA‑POCA zielt auf kooperatives Multi‑Agent‑Training. Es fördert gemeinsame Belohnungen und koordiniertes Verhalten. Design‑Konsequenz: Rewards und Beobachtungen müssen Teamziele klar widerspiegeln.
Self‑Play ist ideal für adversariale Szenarien wie Fighting oder Strategy. Durch wechselnde Gegner entsteht Robustheit gegen Overfitting an statische Gegnertypen.
- Wann welches wählen: PPO für Stabilität, SAC für feine Kontrolle.
- Multi‑Agent: MA‑POCA für Kooperation, Self‑Play für Wettbewerb.
- Game‑Mapping: Movement, Ausweichen → SAC; taktische Entscheidungen → PPO oder Self‑Play.
„Die richtige Algorithmuswahl spart Trainingszeit und liefert spielbare NPCs schneller.“
Imitation Learning: NPCs aus Demonstrationen lernen lassen
Imitation Learning ermöglicht, gewünschte NPC‑Stile direkt aus Designer‑ oder Spielerdaten zu übernehmen. Dieser Ansatz hilft, wenn ein Reward schwer zu formulieren ist oder ein menschliches Verhalten gewünscht wird.
Behavioral Cloning (BC) als schnelle Baseline
BC trainiert eine Policy, indem es Observations und Actions aus geloggten Daten nachahmt. Das eignet sich hervorragend für schnelles Prototyping und erste Tests im game-Kontext.
Grenzen: Verteilungsshift und Fehleransammlung treten auf, wenn der Agent in unbekannte Zustände gerät. BC ist deshalb oft der Startpunkt vor weiterem RL‑training.
GAIL für realistischere Bewegungs- und Entscheidungsstile
GAIL optimiert Verhaltensähnlichkeit via adversarieller Lernstruktur. Das erzeugt natürlicher wirkende Animationen und Timing‑Entscheidungen, verlangt aber mehr Rechenzeit und bessere Datenqualität.
- Datenerhebung: Zeichnen Sie Observations + Actions + Kontext auf.
- Qualität: Variabilität und saubere Labels steigern Generalisierung.
- Praxis‑example: Gegner lernt Patrouille + Investigation aus Designer‑Demos, dann feinjustiert durch RL.
„Lernen aus Demos liefert oft die beste Grundlage, wenn Stil wichtiger ist als ein punktgenau definierter Reward.“
Curriculum Learning: komplexe Aufgaben schrittweise trainierbar machen
Curriculum Learning teilt komplexe Aufgaben in kleine, gut handhabbare Schritte auf. Das reduziert Frustration beim Training und beschleunigt stabile Policy‑Entwicklung.
Die Grundidee: Ein Agent soll erst Basisfähigkeiten erlernen, bevor er Störungen und Variationen meistern muss. Das erhöht die Chance, dass spätere Ziele nicht in Reward‑Hacks oder Instabilität enden.
Schwierigkeitsstufen definieren und automatisch steigern
Typische properties je Stufe sind Zielabstand, Gegnerstärke, Sensor‑Rauschen, Zeitlimit und Reward‑Sparsity. Automatische Progression nutzt Metriken wie Success Rate, durchschnittlichen Reward oder Episodenlänge.
- Erfolgskriterium: z.B. 80 % Success Rate über N Episoden.
- Fallback: nur eine Stufe zurückgehen, statt vollständig zu resetten.
- Variationen: zufällige Seeds und minimale Randomisierung pro Stufe einbauen.
Fehler vermeiden: Overfitting und Reward‑Hacks
Häufige Fallen: Curriculum zu schnell (Agent kollabiert), zu langsam (Zeitverlust) oder zu „leaky“ (Agent findet Stufen‑Shortcuts). Ein klassisches Reward‑Hacking ist, dass der Agent in einer sicheren Ecke campiert und shaping‑Rewards sammelt.
Testen Sie Curricula systematisch und versionieren Sie sie.
Praxis‑Tipp: Wenn ein Setup months ago noch funktionierte, make sure Sie Curricula nach Updates überprüfen. Änderungen an environment oder algorithms können sonst unerwartete Effekte bringen.
Robuste Agenten durch Environment Randomization und Simulationen
Gezielte Randomisierung macht aus spezialisierter Spiel‑KI eine belastbare, übertragbare Policy. Das Toolkit erlaubt es, vielfältige environments und simulations zu nutzen, um Overfitting zu vermeiden und reale Variationen abzubilden.
Randomisierung von Physik, Spawn‑Parametern und Sensor‑Rauschen
Varieren Sie Physikparameter wie Reibung oder Masse, Spawn‑Positionen, Zielpunkte und Hindernis‑Layouts. Ergänzen Sie Licht, Sichtbarkeit und gezieltes Sensor‑Rauschen.
Wichtig: Beginnen Sie moderat und erhöhen Sie die Variation schrittweise. Das verbindet Randomization mit Curriculum‑Ideen und erhält Lernsignale.
Generalisation testen: Holdouts und „unseen“ Situationen
Definieren Sie klare Holdout‑Szenen als unseen‑Varianten. Nutzen diese Szenen strikt nur für Evaluation. So messen Sie echten Fortschritt statt Level‑Memorization.
- Warum: Ohne Varianz lernt ein Agent oft das Layout statt eine Strategie.
- Simulationen nutzen: Erzeugen Sie viele Episoden schnell und bauen Sie gezielt Edge‑Cases ein.
- Data‑Logging: Tracken Erfolgsraten pro Randomization‑Bucket und wichtige Failure‑Modes.
Robuste Trainingspipelines zahlen sich über years aus: sie sind wartbarer als manuelle Skripte und liefern stabilere Verhaltensmodelle.
Multi-Environment Training: schneller lernen mit parallelen Instanzen
Paralleles Training nutzt mehrere Spiel‑Instanzen, um die Lernkurve stark zu beschleunigen. Mehrere environments liefern mehr Experience pro Zeiteinheit und verkürzen das training deutlich.
Mehrere Instanzen orchestrieren und Hardware sinnvoll auslasten
Konzept: Mehrere Builds oder Editor‑Instanzen verbinden sich mit einem zentralen Trainer. So erhöht sich der data-Durchsatz ohne komplexes verteiltes System.
Hardware‑Heuristik: Wenn die GPU die Trainingsschritte limitiert, reduzieren Sie Instanzen; wenn die CPU/Physik limitiert, erhöhen Sie Headless‑Instanzen auf mehreren Kernen.
- Startprobe: 4–8 Instanzen pro CPU‑Socket als grobe Faustregel.
- Headless Builds reduzieren Render‑Kosten und sparen RAM.
- Nutzen Sie sample‑basierte Profiling‑Runs, um Flaschenhälse zu finden.
Stolpersteine: Determinismus, Performance‑Bottlenecks und Datenfluss
Determinismus ist bei paralleler Physik schwierig. Setzen Sie Seeds, pinnen Sie packages und Versionen im repository, um Reproduzierbarkeit zu verbessern.
Parallelisierung erhöht Logs und I/O; TensorBoard, Checkpoints und Logging können zum Engpass werden. Reduzieren Sie unnötige Sensoren und erhöhen Sie Buffer‑Sizes für I/O.
„Parallele Environments liefern Tempo, verlangen aber sorgfältige Profilierung und Versionierung.“
Fortgeschrittene Features für produktionsnahe NPC-Integration
Produktionsreife NPC‑Integration verlangt gezielte Features, die Laufzeitkosten senken und das Verhalten natürlicher machen.
On‑Demand Decision Making
Statt konstante Entscheidungen zu fordern, ruft die Engine Entscheidungen nur bei Bedarf ab — etwa an Wegpunkten oder bei Sichtkontakt.
Das reduziert Rechenlast und macht Aktionen realistischer. Ein Agent kann so zwischen aktiven und passiven Zuständen wechseln.
Custom Sensors und Input‑System‑Integration
Custom Sensors ermöglichen Raycasts, Grid‑ oder Buffer‑Inputs und visuelle Daten, die zum Spielgefühl passen.
Die Integration ins Input System stellt sicher, dass der KI‑Controller dieselben Constraints wie Spieler hat. So vermeiden Sie unfaire Vorteile.
Inference Engine für native Auslieferung
Für Release‑Builds ist eine native Inference Engine wichtig, damit kein Python im Spiel läuft. Das erlaubt plattformübergreifende Deployments und stabile Laufzeit.
- Modell exportieren und einbinden (z. B. .onnx/.nn).
- Behavior auf Inference umstellen und Ressourcenprofiling durchführen.
- Release‑Build testen auf Ziel‑Hardware und optional GPU/TPU‑Support aktivieren.
Unity‑Environment als Gym‑/PettingZoo‑Wrapper
Das Wrappen als Gym oder PettingZoo macht die scene für Research und externe Tools nutzbar.
Game‑Teams profitieren durch standardisierte Schnittstellen: Evaluation, Benchmarking und automatisierte Tests über remote environments.
„Kombinieren Sie Custom Sensors, On‑Demand Decisions und kontrollierte Randomization schrittweise — so bleibt Debugging handhabbar.“
Debugging, Dokumentation und Versionsmanagement im Team
Eine strukturierte Debugging‑Praxis spart Teams viel Zeit bei der Fehlersuche. Beginnen Sie damit, Probleme systematisch einzugrenzen: Engine‑Seite vs. Python‑Stack vs. Versionsmismatch. So vermeiden Sie langes Trial‑and‑Error.
Dokumentations-Stand heute
Die primäre documentation liegt now im Package‑Dokumentationssystem. Die alte Web‑Doku ist deprecated. Legen Sie teamweit fest, dass die Package Docs die autoritative Quelle sind.
Release‑Überblick und Migration
Lesen Sie Release‑Notes genau und prüfen Sie Abhängigkeiten im repository. Release 23 (28.08.2025) dient als Referenzpunkt für größere API‑Änderungen.
Planen Sie Upgrades in definierten Fenstern: alle X months, mit einem kurzen days‑basierten Smoke‑Test (CI) bevor Sie in production mergen.
Wenn es klemmt: Issue‑Qualität
Gute Issues enthalten präzise information: OS, Editor‑Version, com.unity.ml‑agents‑Version, Python‑Version, Install‑Pfad, Branch, relevante Log‑Auszüge und Repro‑Schritte.
- Debugging‑Strategie: zuerst Isolation, dann Reproduktion.
- Dokumentations‑Workflow: Package Docs als Single Source.
- Release‑Management: Notes lesen, Migrationsschritte testen, Backout‑Plan parat halten.
- Teamprozess: Versionen pinnen, Upgrade‑Fenster planen und minimale CI‑Regression über ein paar Smoke‑Trainingsläufe laufen lassen.
„Klare Versionierung und reproduzierbare Environments sind über Jahre entscheidend, wenn Modelle in Produktion laufen.“
Fazit
Am Ende zählt: ein stabiler Workflow von Installation bis Inference sichert langlebige Modelle.
Das ml‑agents Toolkit verbindet Reinforcement‑Learning, Imitation Learning, Curriculum und Randomization, um praxisnahe NPC‑Verhalten in der unity-Scene zu erzeugen.
Kurzcheck für den Start: saubere installation, Version‑Match zwischen Editor und Python, bewusste Branch‑Wahl im repository und ein kleines, messbares example‑Environment.
Produktionspfad: Training → Evaluierung → Export/Inference im Build. Testen Sie Robustheit mit Holdout‑environments und gezielter Randomization.
Teamhinweis: Dokumentation, Release‑Notes und reproduzierbare Trainingsläufe sind entscheidend, damit das System über Jahre wartbar bleibt. Auf Windows prüfen Sie CUDA/VC++‑Schritte.
Praktische next steps: Scene bauen, Reward/Observations definieren, Baseline‑training starten, Multi‑Env ausrollen und Definition of Done festlegen. Öffnen Sie dazu Package Manager, Samples und den Inspector/Behavior‑Tab im Editor.
