Python Developer API

Auf unterstützten Engine-Versionen stellt Locus seine gemeinsame Anfragegrundlage direkt unter unreal bereit. Python verwendet diese Anfragen statt der asynchronen Blueprint-Action-Proxys.

Der Einstiegspunkt ist unreal.LocusDeveloperRequestLibrary. Fabrik- und Eigenschaftsnamen verwenden snake case, etwa create_document, on_succeeded, operation_status und request_id. Enum-Werte verwenden uppercase snake case, etwa LocusDeveloperRequestState.NOT_STARTED und LocusDeveloperResultCode.STALE_REVISION.

Erstellen, behalten, binden, starten

Diese Reihenfolge ist Teil des Vertrags:

Construct → Retain references → Bind → Start → Completion

Die Konstruktion übermittelt noch keine Arbeit. Behalten Sie Anfrage, Delegate-Wrapper und gebundene Python-Aufrufe bis zum terminalen Abschluss. Binden Sie Erfolg und Fehler vor start(), da ein Zulassungsfehler inline abgeschlossen werden kann. Entfernen Sie Bindings und geben Sie Referenzen nach dem Abschluss frei.

import unreal

input_value = unreal.LocusDeveloperDocumentCreateInput(
    path="DeveloperExamples/PythonGettingStarted.md",
    markdown="# Created from Unreal Python\n",
    presentation_root=unreal.LocusDeveloperDocumentRoot.LOCUS_DOCUMENTS,
)
request = unreal.LocusDeveloperRequestLibrary.create_document(input_value)

def on_succeeded(result):
    unreal.log(f"Created {result.identity.relative_path}")
    release_bindings()

def on_failed(error):
    unreal.log_error(f"Locus failed: {error.code.name}: {error.message}")
    release_bindings()

success_delegate = request.on_succeeded
failure_delegate = request.on_failed

def release_bindings():
    success_delegate.remove_callable(on_succeeded)
    failure_delegate.remove_callable(on_failed)

success_delegate.add_callable(on_succeeded)
failure_delegate.add_callable(on_failed)

if not request.start():
    unreal.log_error("The request had already been started")

Das Beispiel erstellt ein echtes Dokument. Wählen Sie einen für das Projekt geeigneten Pfad und behandeln Sie eine vorhandene Identität über den typisierten Fehler-Callback.

Eine abgeschlossene Anfrage prüfen

Eine abgeschlossene typisierte Anfrage behält:

state und succeeded;
request_id;
typisiertes result;
typisierten error;
operation_status.

Sie stellt außerdem has_started() und is_completed() bereit. Eine tickgesteuerte Prüfung ist gültig. Eine aktive Polling-Schleife ist es nicht, denn sie blockiert den Game Thread, der die Anfrage abschließen muss.

cancel() fordert kooperativen Abbruch an. Dadurch kann wartende Arbeit verhindert werden, Repository-Arbeit wird aber nicht unterbrochen und ein bereits lokal gespeichertes Ergebnis nicht in ein abgebrochenes umgewandelt.

Teilaktualisierungen

Verwenden Sie die reflektierten set_*-Flags, um die Absicht auszudrücken:

changes = unreal.LocusDeveloperNoteChanges()

changes.set_title = False       # Leave unchanged; title is ignored.
changes.title = "ignored"

changes.set_body = True         # Set a non-empty value.
changes.body = "Updated body"

changes.set_tags = True         # Explicitly clear tags.
changes.tags = []

request = unreal.LocusDeveloperRequestLibrary.update_note(
    note_identity,
    current_revision,
    changes,
)

Es gibt keine Python-spezifische None-Konvention. Metadatenänderungen von Pins verwenden dieselben ausdrücklichen Eigenschaften set_title, set_description, set_pin_type und set_tags.

Unbeaufsichtigte Editor-Automatisierung

Das unterstützte Modell ist ein Unreal-Editor-Prozess mit aktiviertem PythonScriptPlugin:

External automation
        ↓
UnrealEditor-Cmd full Editor environment
        ↓
PythonScriptPlugin
        ↓
Locus reflected requests

Die unterstützte Form für den unbeaufsichtigten Start ist unten mit UE 5.6 gezeigt; verwenden Sie für UE 5.7 oder 5.8 die passende Editor-Anwendung:

& "C:\Program Files\Epic Games\UE_5.6\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "C:\Path\To\Project.uproject" `
  "-ExecutePythonScript=C:\Path\To\Script.py" `
  -ScriptErrorsAreFatal -unattended -NullRHI -nosplash

Ein asynchrones unbeaufsichtigtes Skript sollte:

unreal.EditorPythonScripting.set_keep_python_script_alive(True) aufrufen;
unreal.register_slate_post_tick_callback(...) registrieren;
seine Locus-Anfrage erstellen, behalten, binden und starten;
normale Editor-Ticks den vorhandenen Locus-Executor antreiben lassen;
den terminalen Abschluss beobachten und Delegate-Bindings entfernen;
den Tick-Callback abmelden;
für ein sauberes Beenden set_keep_python_script_alive(False) aufrufen.

Verwenden Sie kein sleep(), kein Warten durch Schleifen, kein synchrones Warten auf ein Future und kein manuelles Pumpen des Game Threads.

Grenzen der Pipeline

Python erfordert einen Unreal-Editor-Prozess und PythonScriptPlugin.
Locus selbst hängt nicht von PythonScriptPlugin ab und wird auch geladen, wenn es deaktiviert ist.
Standalone-python.exe kann Locus nicht importieren.
Pins erfordern eine unterstützte gespeicherte, projekt-eigene Welt.
Das Commandlet -run=PythonScript ist nicht die vollständige unterstützte Umgebung; bei der Validierung wurde eine transiente ungespeicherte Welt statt der für die vollständige API erforderlichen gespeicherten Welt empfangen.
Verwenden Sie für unbeaufsichtigte Automatisierung den Pfad -ExecutePythonScript der vollständigen Editor-Anwendung.
Start- oder Indexabgleich kann ein wiederholbares Unavailable erzeugen; übermitteln Sie die Anfrage bei einem späteren normalen Editor-Tick erneut, statt zu blockieren.

Siehe die Developer-API-Übersicht zu Identitäten, Revisionen, Fehlern, Operationsstatus und der Fähigkeitsmatrix.