Scripting im Unreal Editor mit Python

Diese Seite beschreibt, wie Sie mit der Verwendung von Python im Unreal Editor beginnen.

Warum Python?

In den letzten Jahren hat sich Python zur De-facto-Sprache für Produktionspipelines und die Interoperabilität zwischen 3D-Anwendungen entwickelt, insbesondere in der Medien- und Unterhaltungsindustrie. Dies liegt zum Teil an dem breiten Spektrum von Anwendungen, die ihn unterstützen. Da die Komplexität der Produktionspipelines immer weiter zunimmt und die Anzahl der beteiligten Anwendungen immer weiter zunimmt, macht es eine gemeinsame Skriptsprache einfacher, große Asset -Management-Systeme zu erstellen und zu warten.

Auch ohne diese externen Überlegungen oder die Notwendigkeit, mit anderen Anwendungen zu arbeiten, ist Python eine gute Wahl, wenn Sie Ihre Workflows im Unreal Editor automatisieren wollen. Der Einstieg für Programmier-Neueinsteiger ist relativ einfach. Die Fähigkeit, durch Module wie PySide komplexe und voll funktionsfähige Benutzeroberflächen zu erstellen, ist gegeben, und es gibt viele andere nützliche kostenlose Module, die der Community das Leben erleichtern.

Mit Python können Sie im Unreal Editor unter anderem folgende Dinge ausführen:

• Erstellen Sie Asset-Management-Pipelines oder Workflows größeren Maßstabs, die den Unreal Editor mit anderen 3D-Anwendungen verbinden, die Sie in Ihrer Organisation nutzen.

• Automatisieren Sie zeitaufwendige Asset-Management-Aufgaben im Unreal Editor, wie z. B. das Generieren von Detailebenen (LODs) für statische Meshes.

• Inhalt im Level prozedural anordnen.

• Den Unreal Editor über Benutzeroberflächen steuern, die Sie selbst in Python erstellen.

Einrichten Ihres Projekts für die Verwendung von Python

Python Unterstützung im Unreal Editor wird durch das Python-Editor-Script-Plugin bereitgestellt. Sie müssen dieses Plugin für Ihr aktuelles Projekt aktivieren, bevor Sie Python-Scripts im Editor ausführen können.

Um das Plugin einzuschalten:

1. Öffnen Sie Ihr Projekt und wählen Sie im Hauptmenü Bearbeiten > Plugins.

2. Gehen Sie im Plugins-Fenster zur Sektion Scripting.
   Suchen Sie das Python-Editor-Script-Plugin im rechten Panel und prüfen Sie die Box Aktiviert.

   

   Sie sollten außerdem das Plugin Editor Scripting Utilities aktivieren, das vereinfachte APIs für viele gewöhnliche Editor-Aufgaben bietet. Detaillierte Informationen dazu finden Sie auf der Seite Scripting and Automating the Editor.

3. Starten Sie den Editor neu.

Python 3.11.8

Das Python-Editor-Script-Plugin enthält eine eingebettete Version von Python 3.11.8.

Sie müssen Python also nicht separat auf Ihrem Computer installieren.

Möglichkeiten, Python -Code im Unreal Editor auszuführen

Es gibt verschiedene Möglichkeiten, wie Sie Python-Scripts im Unreal Editor ausführen können, die alle für leicht verschiedene Verwendungsszenarien entworfen wurden. Sie können wählen, was Ihre Bedürfnisse anpasst.

Die Python Konsole im Output-Log

Sie können die Konsole Input des Unreal Editors so einstellen, dass sie Python Code anstatt Unreal-Konsole akzeptiert.

Das können Sie wie oben gezeigt im Panel Output-Log tun oder in der Konsole durch Drücken der Taste ~, um den Balken Konsole-Input aufzurufen.

Wenn die Konsole im Python Modus ist:

• Sie können Python-Codezeilen in diese Konsole eingeben und den Editor jede einzelne sofort ausführen lassen – genau so, als würden Sie eine interaktive Python-Konsole in einem Befehlsfenster verwenden. Das ist die einzige Möglichkeit, Python-Code Zeile für Zeile auszuführen; Alle anderen unten aufgeführten Ansätze führen eine von Ihnen angegebene Script-Datei aus.

• Sie können mehrere Codezeilen Zeit ausführen, indem Sie Umschalt-Taste + Enter drücken, um die einzelnen Codezeilen zu trennen, oder indem Editor einen mehrzeiligen Block einfügen, den Sie aus dem Text kopieren.

• Sie können Python Script-Dateien ausführen, indem Sie einfach den Dateinamen in die Konsole eingeben. Sollte Ihr Python Script zusätzliche Befehlszeilen-Argumente erfordern, fügen Sie diese nach dem Namen Ihres Script ein.

Der py-Konsolenbefehl

Mit der Konsole im CMD-Modus können Sie mit dem Befehl py den Rest der Zeile als Python-Code ausführen, genau so, als hätten Sie ihn in die oben beschriebene Python-Konsole eingegeben.

Führt dieser Befehl Beispiel die angegebene Script Datei aus:

Kommandozeile

py "C:\MyScripts\my_script.py"

Das Datei-Menü

Das Datei-Menü im Hauptfenster des Unreal Editor bietet neue Optionen, mit denen Sie Python Script Dateien ausführen können.

• Nutzen Sie Execute Python Script, wenn Sie eine neue Script auf Ihrem Computer suchen wollen, die Sie noch nicht ausgeführt haben.

• Über die Liste der neuesten Python-Scripts können Sie ein zuvor ausgeführtes Script erneut ausführen. Die Datei wird erneut von der Festplatte gelesen, also haben Sie das Script zwischenzeitlich geändert, Ihre neue Version wird ausgeführt.

Die Befehlszeile

Wenn Sie den Unreal Editor über die Befehlszeile oder ein Script starten, können Sie in den Befehlszeilen-Argumenten eine Python Script Datei angeben. Sollte Ihr Python Script zusätzliche Befehlszeilen-Argumente erfordern, fügen Sie diese nach dem Namen Ihres Script ein.

Es gibt zwei verschiedene Möglichkeiten, ein Python Script über die Befehlszeile auszuführen. Bei beiden Ansätzen wird der Editor sofort nach der Ausführung Ihres Python-Scripts beendet.

Option 1: Vollständiger Editor Bei dieser Herangehensweise startet der vollständige Unreal Editor, öffnet Ihr spezifiziertes Projekt, lädt das Standard-Startlevel und führt anschließend Ihr Python-Script aus, sobald alles geladen und bereit ist. Diese Herangehensweise eignet sich, wenn Ihr Script mit Inhalt in Ihrem Projekt oder in einem Level interagieren soll, dessen Laden einige Zeit dauern kann.

Fügen Sie das Argument ExecutePythonScript in die Befehlszeile ein und legen Sie als Wert den Pfad und Dateinamen des Python Script fest, das Sie ausführen möchten. Zum Beispiel:

Kommandozeile

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

Option 2: Commandlet Dieser Ansatz ist sehr schnell ausführbar und kann Ihre Skripte sogar im Headless-Modus ausführen, ohne die Editor-Benutzeroberfläche öffnen zu müssen.

Hinzufügen Sie die folgenden Argumente zur Befehlszeile für UnrealEditor-Cmd.exe: -run=pythonscript -script=<script_file_or_code>. <script_file_or_code> nimmt einen der folgenden Werte an:

• Pfad und Dateiname eines Python Script, das Sie ausführen wollen.

• Python-Anweisungen und Befehle, die Sie ausführen wollen. Bei Bedarf können Sie \n im String verwenden, um Zeilenumbrüche zu umgehen.

Zum Beispiel:

Kommandozeile

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

or:

Kommandozeile

> UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="a=5 \nb=10 \nc=a+b \nf=open('D:\myfile.txt','w+') \nf.write(str(c)) \nf.close()"

Dieses Commandlet lädt Levels nicht automatisch. Wenn Sie also Ihr Script schreiben, fügen Sie als Erstes die folgende Zeile hinzu:

Kommandozeile

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

Die Datei init_unreal.py

Wenn der Editor eine Script-Datei namens init_unreal.py in einem der Pfade findet, für die er konfiguriert ist (siehe "Python-Pfade im Unreal Editor" unten), führt er das Script automatisch aus.

Dies ist ein guter Ansatz für Situationen, in denen Sie an einem Projekt oder Plugin arbeiten und wissen, dass alle, die mit diesem Inhalt arbeiten, bei jedem Start des Editors denselben Initialisierungscode ausführen müssen. Sie könnten Ihren Initialisierungscode in einem Script mit diesem Name ablegen und es im Inhalt/Python-Ordner dieses Projekt oder Plugins platzieren.

Startup Scripts

In Ihren Projekt-Einstellungen können Sie eine beliebige Anzahl von Python-Scripts festlegen, die jedes Mal ausgeführt werden sollen, wenn Sie das Projekt öffnen. Der Editor führt diese Scripts aus, nachdem das Standard Startlevel vollständig geladen wurde.

Wählen Sie Bearbeiten > Projekt-Einstellungen…. Wählen Sie in der Plugins-Liste Python aus. Fügen Sie dann Ihre Scripts zur Einstellung Start-Scripts hinzu:

Starten Sie den Unreal Editor nach Abschluss neu. Wenn der Editor das nächste Mal Ihr Projekt lädt, sollte er Ihre neuen Start-Scripts ausführen.

Von Editor-exklusiven Blueprints

Das Python-Script-Plugin stellt neue Knoten für Blueprint-Visual-Scripting bereit, mit denen Sie Python-Code-Auszüge oder -Dateien während der Auswertung eines Blueprint-Diagramms ausführen können.

Sie finden die folgenden Knoten im Sektion Python > Execution in der Blueprint-Palette.

	Python-Script ausführen	Führt den Literal-Python Code aus, den/die Sie an den Python-Befehl eingeben. Das ist der empfohlene Weg, um Python über Blueprints aufzurufen, und ersetzt die Erstellung eines neuen BlueprintFunctionLibrary(BPFL)-Typs in Python. Die bereits erwähnte BPFL Methode verursacht Probleme beim Speichern oder Laden eines Assets, da in Python generierte Typen vergänglich sind und wird nicht mehr offiziell unterstützt. Python Script ausführen kann benutzerdefinierte Input und Output-Pins haben, die als Variablen innerhalb des Python Script auf dem Knoten verfügbar sind und durch die Eigenschaften des Knotens hinzugefügt werden können. –Inputs werden vor der Ausführung des Python Script auf dem Knoten gesetzt und können im Script ausgelesen werden. –Outputs werden nach der Ausführung des Python Script auf dem Knoten gelesen und können im Script festgelegt werden. Ausführen von Python-Script kann mehrere Zeilen Python-Code enthalten, und Zeilenumbrüche können mit den Tasten Umschalten+Rückgabe eingegeben werden. Der Erfolg? ist "true", wenn der Python Code erfolgreich ausgeführt wurde, ansonsten "false". Ist er False, finden Sie die Fehler im Output-Log. Dieser Knoten kann keine Dateien ausführen. Sie kann nur Zeilen Python -Code ausführen.
	Ausführen des Python-Befehls	Führt den Literal-Python Code oder die Python-Datei aus, den/die Sie an den Python-Script eingeben. Der Knoten wird versuchen, basierend auf Ihrem Input zu bestimmen, ob es sich um Literal-Code oder einen Dateinamen handelt. -Der Rückgabewert-Output ist True, wenn der Python Code oder die -Datei erfolgreich ausgeführt wurde, ansonsten False. Ist er False, finden Sie die Fehler im Output-Log.
	Python-Befehl ausführen (erweitert)	Führt den Literal-Python Code oder die Python-Datei aus, den/die Sie an den Python-Script eingeben. Dieser Knoten ähnelt Python-Befehl ausführen, bietet aber einige zusätzliche Inputs und Outputs, die in einigen Szenarien nützlich sein können. Der Ausführungsmodus zeigt an, wie Sie den Python-Script-Input interpretieren wollen. Wählen Sie Execute Datei aus, um den Befehl zu zwingen, Ihren Input als Name einer Datei zu behandeln und zu versuchen, diese Datei zu finden und auszuführen. Alle von diesem Script zurückgegebenen Werte werden im Log abgelegt. Wählen Sie Script ausführen aus, um den Befehl zu erzwingen, Ihren Input als Literal-Python Code zu behandeln und ihn so auszuführen, wie er ist. Alle von diesem Script zurückgegebenen Werte werden im Log abgelegt. Wählen Sie Evaluate Script aus, um den Befehl zu erzwingen, Ihren Input als Python Code zu behandeln, ihn unverändert zu bewerten und alle vom Script produzierten Werte im Ergebnis Output zurückzugeben. Wenn Sie einen Dateinamen an den Python-Script-Input übergeben, bestimmt der Datei-Ausführungs-Bereich, ob diese Datei im globalen Bereich (öffentlich) oder in einem Sandbox-Bereich (privat) ausgeführt wird. Wenn Sie möchten, dass der Code in Ihrer Datei auf Variablen, Funktionen usw. zugreifen kann, die bereits in der Python-Umgebung definiert wurden, müssen Sie öffentlich auswählen. Allerdings erhält die Python-Datei dadurch auch die Fähigkeit, Variablen und Funktionen umzudefinieren. Dies kann versehentlich zu unerwartetem Verhalten führen. Daher kann es sicherer sein, den Bereich Privat zu verwenden. Das Befehl-Ergebnis hängt vom Ausführungsmodus ab. Wenn der Python-Script-Input ausgeführt oder erfolgreich ausgewertet wurde und der Ausführungsmodus Script auswerten ist, gibt dieser Output den Wert zurück, der vom Script produziert wurde. Wenn der Python-Script-Input erfolgreich ausgeführt oder ausgewertet wurde und der Ausführungsmodus entweder ausführen oder Script ausführen ist, gibt dieser Output None zurück. Wenn der Python-Script-Input nicht ausgeführt oder erfolgreich ausgewertet wird, enthält dieser Output die Fehlerinformationen. Der Log-Output bietet Zugang auf die vollständige Liste der Nachrichten, die während der Ausführung des Input Script oder der Datei ins Python Log geschrieben wurden. Sie können dieses Array iterieren, wenn Sie nach bestimmten, vom Script geschriebenen Nachrichten suchen müssen. Der Rückgabewert ist „True”, wenn der Python-Code erfolgreich ausgeführt wurde, andernfalls „False”. Ist er False, finden Sie die Fehler im Output-Log der Engine, im Log Output Output-Pin und im Befehl-Ergebnis.

Python Umgebung und Pfade im Unreal Editor

Wenn Sie einen relativen Python Pfad verwenden, um ein Python Script auszuführen oder ein anderes Script Modul mit dem importieren Befehl in einem Ihrer Scripte zu importieren, kann das Script, das Sie ausführen oder importieren, sich in einem beliebigen Pfad befinden, der in der sys.path Python Variable Ihrer Python Umgebung aufgeführt ist.

Der Unreal Editor fügt dieser sys.path-Liste automatisch mehrere Pfade hinzu:

• Der Content/Python-Unterordner in Ihrem Projektordner.

• Der Inhalt/Python-Unterordner in der Hauptinstallation der Unreal Engine.

• Der Inhalt/Python-Unterordner im Ordner jedes aktivierten Plugins.

• Der Ordner Documents/UnrealEngine/Python in Ihrem Nutzerverzeichnis. Auf Windows 10 entspricht das Beispiel C:/Users/Nutzername/Documents/UnrealEngine/Python

Sie können über einen der folgenden Ansätze auch eigene Pfade zu dieser Liste hinzufügen:

• In Ihren Projekteinstellungen. Wählen Sie Bearbeiten > Projekt-Einstellungen…. Wählen Sie in der Plugins-Liste Python aus. Fügen Sie dann die Pfade zur Einstellung Zusätzliche Pfade hinzu. Starten Sie den Unreal Editor nach Abschluss neu.

  

• Hinzufügen die Pfade zum Wert der Variable UE_PYTHONPATH (oder PYTHONPATH, wenn Sie die Option Editor isolierte Interpreter-Umgebung deaktiviert haben) in Ihrem System hinzu und starten Sie dann den Unreal Editor neu.

• Fügne Sie die Pfade direkt zur sys.path-Liste in einem Python-Script oder in der Python-Konsole hinzu.

Mehr Informationen finden Sie in der Python-Dokumentation sys.path

Standardmäßig wird der eingebettete Python Interpreter der Unreal Engine im isolierten Modus ausgeführt. Sie können den isolierten Modus deaktivieren, indem Sie Bearbeiten > Projekt-Einstellungen > Plugins > Python > Isolierte Interpreter-Umgebung auswählen.

Mehr Informationen finden Sie in der Dokumentation zu Python-Befehlszeilen-I-Option

Die Variable UE_PYTHONPATH wird immer von der Engine geparst und ihr Inhalt wird zu sys.path hinzugefügt, unabhängig von den gewählten Modus-Optionen. UE_PYTHONPATH dient demselben Zweck wie die PYTHONPATH-Variable, aber er sollte niemals durch Software von Dritten verändert werden.

Über die Python -API des Unreal Editor

Das Python Editor-Script-Plugin bietet eine breites Spektrum von Klassen und Funktionen, die Sie für die Interaktion mit dem Unreal Editor, den Assets in Ihrem Projekt und den Inhalt in Ihren Levels nutzen können. Diese API ist komplett im Unreal-Modul enthalten. Um darauf zuzugreifen, müssen Sie dieses Modul am Anfang eines beliebigen Python-Scripts importieren, das Sie in der Python-Umgebung des Editors ausführen:

import unreal

Das Unreal-Modul stellt fast alles, was durch C++ bereitgestellt wird, den Blueprints in Ihrer Editor-Umgebung zur Verfügung. Sie ist nicht vorgeneriert; spiegelt es automatisch alles wider, was an Blueprints in Ihrem Editor verfügbar ist. Wenn Sie neue Plugins im Unreal Editor aktivieren, wird alles, was diese Plugins in Blueprints bereitstellen, auch in Python verfügbar. Das Gleiche gilt für sämtlichen C++- Code, den Sie in Ihrem Projekt schreiben und in Blueprints bereitstellen.

Die Python API unternimmt alle Bemühungen, nativ Unreal-APIs auf eine Weise zur Verfügung zu stellen, die für Python-Entwickler so benutzerfreundlich wie möglich ist. Zum Beispiel:

• Einfache Datentypen werden bei Bedarf transparent zwischen Python und nativen Typen konvertiert.
  Wenn Sie eine Liste, ein Set oder ein Dikt in Python durchlaufen, wird diese automatisch in ein Unreal-Array, -Set oder eine Map umgewandelt. Wenn Sie eine Liste, ein Set oder ein Dictionary abrufen, das von einer API-Funktion zurückgegeben wurde, erhalten Sie eigentlich eine Instanz einer Unreal-Klasse, aber deren API ist vollständig konsistent mit dem Basis-Python-Listen-, Set- oder Dictionary-Typ.

• Python Klassen haben dieselbe Hierarchie wie die nativ Typen, die sie repräsentieren. Das bedeutet zum Beispiel, dass Sie die eingebauten Python Funktionen isinstance() und type() verwenden können, um zu testen, ob ein Objekt von einer bestimmten Klasse abgeleitet wird oder dieser entspricht.

• Die API versucht, ein gutes Balance zwischen den Benennungskonventionen, die in Unreal für C++ und Blueprints verwendet werden, und den Python-Benennungskonventionen zu schaffen. Klassen und Objekte in der Python API haben dieselben Namen wie in Blueprints. Das ist normalerweise das Gleiche wie bei ihren nativ Typen, wobei das Präfix weggelassen wird (z. B U oder T). Funktions- und Eigenschaft werden automatisch als kleine snake_case angezeigt. Beispiel: Man ruft Funktionen wie unreal.StaticMeshActor.get_actor_transform() auf. Namen von Enumeration-Wert werden automatisch als großgeschriebene SNAKE_CASE angezeigt.

• Alle exponierten Funktionen können entweder geordnete Parameter oder benannte Parameter in beliebiger Reihenfolge akzeptieren. Beispielsweise sind die folgenden beiden Funktionsaufrufe genau gleichwertig:

  C++

  unreal.get_editor_subsystem(unreal.StaticMeshEditorSubsystem).join_static_mesh_actors(list_of_actors, my_options)
      unreal.get_editor_subsystem(unreal.StaticMeshEditorSubsystem).join_static_mesh_actors(join_options=my_options, actors_to_join=list_of_actors)

  Copy full snippet(2 lines long)

API-Referenz

Für Details zu allen Klassen und Funktionen, die von der Unreal Python-API bereitgestellt werden, siehe die API-Referenzen hier:

Python-API-Referenz für den Unreal Editor

Bewährte Praktiken für die Verwendung der Python-API

Diese Sektion behandelt einige Dinge, die bei der Verwendung der Python-API zu beachten sind.

Arbeit mit Assets

Wenn Sie in Ihrem Projekt mit Assets arbeiten müssen, verwenden Sie dafür immer Funktionen aus der Unreal Python-API. Verwenden Sie niemals in Python eingebaute Dateimanagement-Module, um direkt mit Ihren Asset-Dateien auf der Festplatte zu arbeiten. Wenn Sie zum Beispiel ein Asset in einen anderen Ordner verschieben müssen, verwenden Sie keine Python Funktionen wie os.rename oder shutil.move. Unreal Projekte und Assets enthalten interne Referenzen, die Sie zerstören können, wenn Sie diese Regel nicht einhalten.

Stattdessen empfehlen wir, die Unreal.EditorAssetLibrary API zu nutzen, die vom Editor Scripting Utilities Plugin bereitgestellt wird, oder die in die Unreal Python API eingebaute unreal.AssetTools-Klasse.

Editor-Eigenschaften ändern

Sie können Python verwenden, um auf Objekte in Ihrem Projekt zuzugreifen und viele Konfiguration für diese Objekte programmatisch einzurichten. Als Beispiel könnte Ihr Python Script auf Statisches Mesh-Actors im aktuellen Level Zugang und Eigenschaften festlegen, ob die Actors beschädigt werden können oder ob sie im Spiel verborgen werden sollen. Oder Sie können ihre Statisches Mesh-Komponenten abrufen und Eigenschaften für diese Komponenten einrichten, zum Beispiel deren Lightmass Einstellungen oder sogar das Statisches Mesh-Asset, mit dem sie verknüpft sind.

Diese Eigenschaften können in Python auf zwei verschiedene Arten offengelegt werden:

• Items mit der Flag (das) BlueprintReadOnly oder BlueprintReadWrite werden als einfache Eigenschaften des Objekts angezeigt.
  Sie können diese Eigenschaften lesen und modifizieren, genau wie Sie auf Python Eigenschaft Zugang haben.

• Items mit der ViewAnywhere- oder EditAnywhere-Flag werden als "Editor Eigenschaften" angezeigt.
  Sie können diese Werte mit einem speziellen Paar von Funktionen lesen und schreiben, das von jedem Objekt bereitgestellt wird: set_editor_property() und get_editor_property().

In der API-Referenz für jede Klasse finden Sie eine Liste der Editor-Eigenschaften, die direkt auf die Klassenbeschreibung folgt. Das sind alle Werte, die Sie mit den Funktionen set_editor_property() und get_editor_property() setzen und holen können. Wann immer Sie eine Konfigurationseigenschaft für ein Objekt setzen oder holen müssen, prüfen Sie zuerst diese Liste, um zu sehen, ob die gewünschte Eigenschaft dort aufgeführt ist.

• Wenn Sie einen Wert lesen musst, der sowohl als Objekteigenschaft als auch als Editoreigenschaft bereitgestellt wird, ist das Ergebnis des direkten Zugangs auf die Eigenschaft in der Regel dasselbe wie beim Aufrufen der Funktion get_editor_property(). Allerdings hat die Funktion get_editor_property() oft Zugang auf Eigenschaften, die nicht direkt im Python Objekt offengelegt werden.

• Wenn Sie einen Wert festlegen müssen, der sowohl als Eigenschaft als auch als Editor Eigenschaft exponiert ist, sollten Sie in den meisten Fällen die Funktion set_editor_property() verwenden, um den Wert festzulegen, anstatt den Wert direkt auf dem Objekt festzulegen. Wenn Sie Eigenschaften in der Benutzeroberfläche anpassen, führt der Editor im Hintergrund oft zusätzliche Operationen durch: Änderungen vor und nach der Bearbeitung. Die Operationen reagieren in der Regel auf bestimmte Entscheidungen, die Sie treffen, und halten die Editor-Benutzeroberfläche mit dem Zustand des Objekts in der Spiel Synchronisation. Wenn Sie diese Eigenschaften direkt am Python Objekt ändern, wird der Editor-Code nicht automatisch ausgeführt. Auf der anderen Seite, wenn Sie set_editor_property() aufrufen, um den Zustand einer Eigenschaft festzulegen, löst du diesen Pre- und Post-Bearbeitungscode aus, genau so, als würden Sie die Einstellung im Details-Panel der Editor-Benutzeroberfläche ändern.

Media Player Objekte haben beispielsweise die Einstellung Abspielen beim Öffnen:

Dies wird in der Unreal.MediaPlayer-Klasse im play_on_open-Mitglied angezeigt:

import unreal
		obj = unreal.MediaPlayer()
		# Modifying a property directly can have different results
		# than changing settings in the Editor UI.
		# Generally you'll want to avoid setting these values directly, like this:
		obj.play_on_open = True
		# This way of accessing the property will have exactly the same
		# result as changing the setting in the Editor UI:
		obj.set_editor_property("play_on_open", True)
		# Both ways of reading the value are equivalent.

Use Unreal Types When Possible

Wann immer Sie Unreal Hilfsmittel benötigen, die in der Unreal Python API verfügbar sind, etwa Klassen für mathematische Operationen oder die Manipulation von 3D Koordinaten, empfehlen wir, die Unreal Hilfsmittel zu nutzen anstatt Ihre eigenen Implementierungen zu verwenden. Die Unreal-Versionen sind für beste Performance in der Engine-Umgebung optimiert.

Wenn Sie beispielsweise Koordinaten in einem 3D-Raum manipulieren müssen, verwenden Sie die Unreal.Vektor-Klasse:

import unreal
    v1 = unreal.Vector()
    v1.x = 10
    v2 = unreal.Vector(10, 20, 30)
    v3 = (v1 + v2) * 2
    print(v3)

Protokollierung und Feedback

Das Unreal Objekt exponiert Funktionen, die Sie in Ihrem Code verwenden können, um Log-, Warnungs- und Fehlermeldungen über dasselbe Messaging-System zu senden, das von allen Engine- und Editor-Subsystemen verwendet wird. Wir empfehlen die Nutzung dieses standardisierten Frameworks immer dann, wenn Ihr Script dem Nutzer eine Nachricht senden muss.

• Nutzen Sie Unreal.Log() für Informationsmeldungen. Beachten Sie, dass die Python Funktion print() ebenfalls implementiert wurde, um durch unreal.log() durchzulaufen. intern

• Verwende Unreal.log_warning(), um Nutzer vor potenziellen Problemen zu warnen.

• Benutzen Sie unreal.log_error() wegen gravierender Probleme, die verhindern, dass Ihr Script wie erwartet ausgeführt werden kann.

Ihre Nachrichten erscheinen zusammen mit den Nachrichten, die von anderen Subsystemen gesendet werden, im Output-Log Panel:

Unterstützung für "Rückgängig" und "Wiederholen".

Ihre Scripts können die Vorteile des im Unreal Editor eingebauten Rückgängig-/Wiederholen-Systems voll nutzen.

Jede von Ihnen definierte Transaktion kann eine beliebige Anzahl an Python-Operationen enthalten. Mit diesen Transaktionen können Sie große Operationen oder Operationen an vielen verschiedenen Objekten zu einem einzigen Eintrag im Rückgängig-/Wiederholen-Verlauf bündeln. Wenn Ihr Script bestimmte Änderungen an mehreren Objekten vornehmen soll, wollen Sie normalerweise nicht für jede Änderung einen eigenen Eintrag im Rückgängig-/Wiederholen-Verlauf, sondern einen Eintrag, der alle Änderungen an allen Objekten rückgängig macht.

Um eine Transaktion zu definieren, verwenden Sie den Bereich Unreal.ScopedEditorTransaction. Wenn Sie beispielsweise diesen Code ausführen:

import unreal
	obj = unreal.MediaPlayer()
	with unreal.ScopedEditorTransaction("My Transaction Test") as trans:
		obj.set_editor_property("play_on_open", False)
		obj.set_editor_property("vertical_field_of_view", 80)

Das Rückgängig machen-Verlauf-Panel Ihres Editors zeigt diese Transaktion nun nach Name an:

Als allgemeine Regel können Ihre Bereichs-Transaktionen alle Operationen enthalten, die auch in der Editor-Benutzeroberfläche rückgängig gemacht werden können. Allerdings kann nicht jede Operation im Editor rückgängig gemacht werden. Sie können den Import eines Modells in der Editor-Benutzeroberfläche nicht rückgängig machen, also wird der Import eines Modells aus einer unreal.ScopedEditorTransaction nicht wie erwartet funktionieren.

Fortschrittsdialoge für langsame Operationen

Wenn Ihre Scripts in derselben Operation an vielen Assets oder Actors Arbeit leisten müssen, kann deren Abschluss einige Zeit dauern. Allerdings, während der Unreal Editor ein Python Script ausführt, wird seine Benutzeroberfläche für andere Nutzerinteraktionen gesperrt. Um dem Benutzer Informationen über den Fortschritt einer großen Aufgabe zu geben und zu vermeiden, dass der Editor scheinbar einfriert oder hängen bleibt, können Sie den Bereich unreal.ScopedSlowTask verwenden.

Zum Beispiel:

import unreal
    total_frames = 100
    text_label = "Working!"
    with unreal.ScopedSlowTask(total_frames, text_label) as slow_task:
        slow_task.make_dialog(True)               # Makes the dialog visible, if it isn't already
        for i in range(total_frames):
            if slow_task.should_cancel():         # True if the user has pressed Cancel in the UI
                break
            slow_task.enter_progress_frame(1)     # Advance progress by one frame.
                                                # You can also update the dialog text in this call, if you want.