Unreal Engine mit Python automatisieren: Schritt-für-Schritt-Einstieg

Was Sie in diesem Leitfaden lernen

Die Python-Unterstützung in Unreal Editor eignet sich dazu, wiederkehrende Produktionsaufgaben per Skript auszuführen und Pipelines zwischen verschiedenen 3D-Anwendungen zu unterstützen. Zu den in Epics Dokumentation gezeigten Anwendungsfällen zählen die Automatisierung der Asset-Verwaltung, das Erstellen von LODs für Static Meshes und die prozedurale Platzierung von Inhalten in einem Level. Außerdem kann Python verwendet werden, um benutzerdefinierte Oberflächen für den Editor zu erstellen.

Zunächst richten wir das Projekt ein, führen anschließend einen kurzen Python-Befehl aus und vergleichen dann die Möglichkeiten zur Automatisierung mit Skriptdateien. Die hier beschriebenen Methoden sind auf die Editor-Automatisierung ausgerichtet: Python steht bei geöffnetem Unreal Editor zur Verfügung, nicht jedoch während das Spiel in Play In Editor, Standalone Game oder als gepackte ausführbare Datei läuft.

Voraussetzungen

Sie benötigen ein Unreal-Engine-Projekt, in dem sich das Python Editor Script Plugin aktivieren lässt, sowie Unreal Editor. Laut Epics Leitfaden wird das Plugin für jedes Projekt einzeln aktiviert. Wenn Sie Python in einem anderen Projekt verwenden möchten, müssen Sie es dort ebenfalls einschalten. Empfehlenswert ist außerdem das Plugin Editor Scripting Utilities, das vereinfachte APIs für häufige Editor-Aufgaben bereitstellt.

Das Python Editor Script Plugin bringt Python 3.11.8 mit und bettet es in Unreal Editor ein. Für die in diesem Leitfaden beschriebene Verwendung müssen Sie Python daher nicht separat auf Ihrem Computer installieren. Eine andere Python-Version erfordert, dass Sie die Umgebungsvariable UE_PYTHON_DIR im Betriebssystem setzen und Unreal Engine aus dem Quellcode neu kompilieren.

Epic kennzeichnet die Unreal-Python-API-Dokumentation für Unreal Python 5.8 als „Experimental“. Auch der zentrale Benutzerleitfaden weist darauf hin, dass die Funktion experimentell ist. Daher empfiehlt es sich, Skripte zunächst in einer Kopie des Produktionsprojekts oder in einem kontrollierten Testprojekt zu überprüfen.

Schritt für Schritt: Plugin aktivieren und den ersten Befehl ausführen

1. Öffnen Sie das Projekt, mit dem Sie in Unreal Editor arbeiten möchten. Wählen Sie im oberen Menü Edit > Plugins.

2. Suchen Sie im Bereich Scripting des Plugin-Fensters nach Python Editor Script Plugin und aktivieren Sie das Kontrollkästchen Enabled.

3. Aktivieren Sie im selben Fenster auch das Plugin Editor Scripting Utilities. Starten Sie den Editor anschließend neu.

4. Öffnen Sie das Output Log-Panel und wechseln Sie die Konsoleneingabe in den Python-Modus. Alternativ können Sie mit der Taste ~ die Konsolen-Eingabezeile öffnen. Im Python-Modus werden eingegebene Codezeilen sofort im Editor ausgeführt.

5. Geben Sie zum ersten Test mit Pythons Funktion print eine Nachricht im Output Log aus:

print("Python etkin")

Die Ausgabe von print erscheint im Output-Log-Panel. Um mehrere Zeilen in der Konsole auszuführen, können Sie die Zeilen mit Shift+Enter trennen oder mehrzeiligen Code einfügen. Diese Methode eignet sich, um einzelne Zeilen auszuprobieren und einfache Prüfungen vorzunehmen.

Optionen zum Ausführen einer Skriptdatei

Bei wiederkehrenden Aufgaben sorgt es für einen übersichtlicheren Arbeitsablauf, den Code in einer Python-Datei abzulegen. Sie können die Skriptdatei über die Konsole des Editors mit folgendem Befehl ausführen:

py "C:\MyScripts\my_script.py"

Der Pfad stammt aus Epics Dokumentationsbeispiel. Ersetzen Sie ihn durch den Speicherort Ihres Skripts. Alternativ können Sie im Hauptfenster File > Execute Python Script wählen und eine Skriptdatei auf Ihrem Computer auswählen. Bereits ausgeführte Dateien lassen sich auch über die Liste Recent Python scripts erneut starten. Da der Editor die Datei erneut von der Festplatte einliest, werden auch die zuletzt vorgenommenen Änderungen ausgeführt.

Die Ausführung über die Befehlszeile ist eine weitere Option für Teams, die Skripte in eine Automatisierungspipeline integrieren möchten. Sie können das Skript starten, nachdem der vollständige Editor geöffnet sowie das Projekt und das standardmäßige Startlevel geladen wurden:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -ExecutePythonScript="c:\my_script.py"

Für diesen Ansatz müssen Python Scripting Plugin und Editor Scripting Utilities im Projekt aktiviert sein. Nach Abschluss des Skripts wird der Editor geschlossen.

Für eine schnellere Ausführung ohne Benutzeroberfläche können Sie das pythonscript-Commandlet verwenden:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="c:\\my_script.py"

Bei dieser Methode werden Levels nicht automatisch geladen. Muss das Skript auf den Inhalt eines bestimmten Levels zugreifen, kann der in Epics Dokumentation als erste Zeile angegebene Ladeaufruf verwendet werden. Der darin enthaltene Pfad bezieht sich auf ein Beispielprojekt und muss an den Level-Pfad des tatsächlichen Projekts angepasst werden:

unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/UVlayoutTest.UVlayoutTest")

Häufige Fehler und Einschränkungen

Am häufigsten wird übersehen, dass das Plugin für jedes Projekt separat aktiviert werden muss. Gehen Sie nicht davon aus, dass ein Skript, das in einem Projekt funktioniert, automatisch auch in einem anderen läuft. Prüfen Sie zunächst den Plugin-Status im jeweiligen Projekt. Vergessen Sie bei der Ausführung über die Befehlszeile mit dem vollständigen Editor auch nicht die Voraussetzung Editor Scripting Utilities.

Das Commandlet und der Start des vollständigen Editors verhalten sich unterschiedlich. Da das Commandlet ein Level nicht automatisch lädt, muss der Ladeschritt bei Skripten, die auf Level-Inhalte angewiesen sind, ausdrücklich berücksichtigt werden. Bei der Methode mit dem vollständigen Editor wird das Skript hingegen ausgeführt, nachdem das Projekt geöffnet und das standardmäßige Startlevel geladen wurde.

Auch für Gameplay-Logik ist Python nicht geeignet. Epics Dokumentation zufolge ist die Python-Umgebung in Unreal Editor verfügbar, nicht jedoch in Laufzeitmodi. Knoten zum Ausführen von Python aus Blueprints können außerdem nur in editororientierten Blueprint-Klassen wie Editor Utility Widget und Editor Utility Blueprint verwendet werden, nicht in normalen Laufzeitklassen.

Auswirkungen auf Architektur-, Innenarchitektur- und Archviz-Workflows

Der unmittelbarste Vorteil für Architekturbüros und Visualisierungsteams liegt darin, wiederkehrende Asset-Aufgaben im Editor mit Skripten zu verwalten. Zu den ausdrücklich dokumentierten Anwendungsfällen zählen etwa die Organisation der Asset-Verwaltung im Projekt, die Automatisierung der LOD-Erstellung und das Platzieren von Inhalten in einem Level. Python als gemeinsame Skriptsprache in Pipelines mit mehreren 3D-Anwendungen einzusetzen, kann ebenfalls dazu beitragen, Prozesse miteinander zu verbinden.

Dieser Leitfaden bietet jedoch keine Garantie für die Kompatibilität mit einem bestimmten Archviz-Plugin oder Projekt und enthält keine Angaben zu Hardwareanforderungen oder Lizenzmodellen. Insbesondere bei APIs, die als experimentell gekennzeichnet sind, sollte geprüft werden, ob die benötigten Funktionen mit der Unreal-Version des Projekts arbeiten. Überführen Sie die Automatisierung erst dann in den Produktionsprozess, wenn Sie getestet haben, wie sie sich auf das Laden von Levels, die Editor-Plugins und die Projekteinstellungen für andere Teammitglieder auswirkt.

Nächste Schritte

Wählen Sie nach dem Ausführen des ersten Skripts eine kleine, rückgängig zu machende Aufgabe aus: Prüfen Sie beispielsweise einen Befehl direkt im Editor oder automatisieren Sie kontrolliert einen bestehenden Produktionsschritt. Speichern Sie den Vorgang anschließend als Datei und probieren Sie Execute Python Script oder eine geeignete Methode über die Befehlszeile aus. Für Projekte, die von mehreren Personen genutzt werden, können auch Startskripte sinnvoll sein: init_unreal.py lässt sich im Ordner Content/Python des Projekts oder Plugins ablegen und wird dann automatisch vom Editor ausgeführt. In den Projekteinstellungen können ebenfalls Skripte festgelegt werden, die beim Start laufen.

Wenn der Workflow wächst, sollten Sie die Unreal-Python-API-Dokumentation für die verwendete Version heranziehen. Sie dient als Referenz für Module, Typen und API-Header. Erweitern Sie den Umfang schrittweise und behalten Sie dabei im Blick, dass die Funktion als experimentell gilt und die Skripte nur im Editor ausgeführt werden.

Quelle und Lizenz

Dieser Leitfaden wurde anhand von Epics „Scripting the Unreal Editor Using Python“ und der Seite „Unreal Python API Documentation“ ins Türkische übertragen und angepasst. Die Quellen sind als frei nutzbar gekennzeichnet; Text und Beispielerläuterungen wurden neu bearbeitet.