Werkzeuge

Diese Seite beschreibt, was ein KI-Agent mit Unreal MCP im Unreal Editor tun kann. Das Plugin bringt 27 Tools in 7 Familien mit. Du rufst ein Tool selten beim Namen auf: Frage in normaler Sprache, und der Agent wählt das passende Tool. Wenn du die Familien kennst, kannst du gezielter nach Dingen fragen, die der Agent tatsächlich tun kann.

Tool-Karten mit Parametern findest du im Unreal-Tool-Katalog.

RQL: eine Abfragesprache für Editor-Daten#

Unreal MCP hat nicht ein Tool pro Editor-Operation. Stattdessen laufen Editor-Daten über RQL, eine Abfragesprache, die Actors, Komponenten, Assets, Levels und Editor-Zustand in einem Aufruf liest und ändert.

Ein paar Beispiele, wie RQL aussieht (der Agent schreibt sie für dich):

actors | where $ is PointLight | select $ref Label Intensity
actors | where Label == "Door_01" | set Location = "(0, 0, 100)"
editor | call SpawnActor("PointLight")
console | where Verbosity == "Error"

Über Actors und Komponenten hinaus erreicht RQL:

• Assets und Levels: Assets erstellen, kopieren, verschieben, löschen und importieren, Ordner und Materialinstanzen anlegen, Levels öffnen, erstellen und speichern, Streaming-Sublevels hinzufügen.
• Editor-Zustand: Auswahl, Play-In-Editor-Status, Undo-Verlauf, das Editor-Log.
• DataTables: Zeilen lesen und bearbeiten (Rows["Sword"].Damage), Zeilen hinzufügen, entfernen, umbenennen und duplizieren.
• Gameplay-Tags: Tags auflisten, hinzufügen, entfernen und umbenennen.
• Project Settings und Editor Preferences: Konfigurationseigenschaften lesen und ändern, gespeichert in der richtigen .ini-Datei.
• Blueprint-Graphen: Funktionsaufrufe, Variablen, Events, Casts, Branches und Schleifen hinzufügen, Pins verbinden und dann call Compile().
• Widget Blueprints: den Widget-Baum durchlaufen und bearbeiten, Widgets hinzufügen und das Layout festlegen.
• Benutzerdefinierte Structs: Felder hinzufügen, entfernen und umbenennen.
• Level Sequences: Actors binden, Tracks und Keys hinzufügen.

Jede Änderung ist eine Editor-Transaktion, sodass Ctrl+Z sie rückgängig macht. Der Agent lernt die Sprache aus dem Skill unreal-rql, das auch auflistet, was installierte Erweiterungen hinzufügen.

Beispiel-Prompts:

• „Liste jedes Point Light im Level mit seiner Intensität auf und verdopple dann die Intensität der schwachen.“
• „Spawne 20 Würfel in einem 5-mal-4-Raster mit 200 Einheiten Abstand.“
• „Füge der DataTable DT_Weapons eine Zeile Bow mit Damage 7 hinzu.“
• „Setze die Standard-Map des Spiels auf /Game/Maps/Arena.“

Blueprint-Familie#

Das Erstellen von Blueprints ist Unreals wichtigste Skript-Oberfläche, und der Agent bekommt eine vollständige Rückmeldeschleife: erstellen, bearbeiten, kompilieren, Fehler lesen, beheben.

Beispiel: „Erstelle ein Actor-Blueprint BP_Door mit einer Static-Mesh-Komponente und einer Bool-Variable IsOpen, kompiliere es und platziere eine Instanz am Ursprung.“

Source-/C++-Familie#

Alle Dateioperationen sind auf <Project>/Source/ beschränkt. Beispiel: „Erstelle eine C++-Komponente UHealthComponent mit MaxHealth und einer TakeDamage-Funktion, kompiliere und behebe alle Fehler.“

Python-Familie#

Der letzte Ausdruck wird als Ergebnis zurückgegeben, die print-Ausgabe kommt als Logs zurück, und Fehler zeigen auf die fehlerhafte Zeile. include fügt Hilfsdateien oder -ordner aus <Project>/.ai-game-dev/snippets hinzu, und timeout (Standard 30 Sekunden) stoppt ein außer Kontrolle geratenes Skript. Das Plugin aktiviert Unreals Python Editor Script Plugin; Python ist nur im Editor verfügbar und wird nie in einem gepackten Spiel ausgeliefert. Die Verdrahtung von Blueprint-Graphen ist für Python nicht zugänglich; verwende dafür die Blueprint-Tools oder RQL.

Du kannst Python auch von einem Terminal aus mit unreal-mcp-cli exec ausführen, siehe die CLI-Referenz.

Screenshot-Familie#

Bilder kommen als PNG-Inhalt zurück, den sich das Modell ansehen kann, standardmäßig 1024 Pixel und maximal 2048 pro Seite. Sie benötigen einen GPU-gestützten Editor; unter -nullrhi geben sie einen Fehler zurück. Beispiel: „Mach einen Screenshot von CameraActor_Main und sag mir, ob die Beleuchtung zu dunkel aussieht.“

Konsole und Tool-Liste#

Das Auslesen des Logs, des Play-In-Editor-Status und der Auswahl erfolgt über RQL.

Tools, die der Agent nie sieht#

Einige Systemtools dienen der CLI und der App und werden KI-Agenten nicht angezeigt:

• ping: prüft die Kette aus Plugin, Bridge und Server.
• unreal-skill-generate: schreibt eine SKILL.md pro Tool in einen Skills-Ordner (Standard .claude/skills); die Schaltfläche Generate skill files verwendet es.
• unreal-skill-create: erzeugt eine neue C++-Tool-Datei im Editor-Modul des Plugins. Es erfordert eine Quellcode-Installation des Plugins und einen Editor-Neubuild, bevor das Tool funktioniert.
• editor-quit: speichert und schließt einen Editor, den eine CLI-Sitzung gestartet hat.

Prompts und Ressourcen#

Das Plugin liefert außerdem einen MCP-Prompt, level-design-brief (ein Level-Design-Briefing aus einem Thema), und zwei Ressourcen: unreal://project/levels (eine JSON-Momentaufnahme der aktiven Welt und ihrer Levels) und unreal://project/icon.

Steuere, was der Agent sieht#

Blende Tools, die du nicht brauchst, im Fenster MCP Tools aus oder stelle mit UNREAL_MCP_TOOLS nur einen festen Satz bereit. Siehe Konfiguration. Um Fähigkeiten hinzuzufügen, installiere Erweiterungen oder schreibe eigene Tools.

Nur im Editor#

Alle 27 Tools steuern den Editor. Einige davon sind mächtig (rql-mutate, console-run-command, python-execute), deshalb wird keines von ihnen in ein gepacktes Spiel kompiliert. Ein Spiel, das sich für eine Laufzeitverbindung entscheidet, stellt nur die Tools bereit, die es selbst registriert.

Tipps, wie du das Beste aus diesen Tools herausholst, findest du in den Unreal Best Practices.