Python Developer API

Sur les versions d’Engine prises en charge, Locus expose directement sa base de requêtes partagée sous unreal. Python utilise ces requêtes plutôt que les proxies d’action asynchrone de Blueprint.

Le point d’entrée est unreal.LocusDeveloperRequestLibrary. Les noms de fabrique et de propriété utilisent le snake case, comme create_document, on_succeeded, operation_status et request_id. Les valeurs d’enum utilisent le snake case majuscule, comme LocusDeveloperRequestState.NOT_STARTED et LocusDeveloperResultCode.STALE_REVISION.

Construire, conserver, lier, démarrer

Cet ordre fait partie du contrat :

Construct → Retain references → Bind → Start → Completion

La construction ne soumet pas le travail. Conservez la requête, les wrappers de delegate et les fonctions Python liées jusqu’à la fin terminale. Liez le succès et l’échec avant start(), car une erreur d’admission peut se terminer inline. Supprimez les liaisons et libérez ces références après l’achèvement.

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")

L’exemple crée un véritable Document. Choisissez un chemin adapté au projet et gérez une identité existante via le callback d’échec typé.

Inspecter une requête terminée

Une requête typée terminée conserve :

state et succeeded ;
request_id ;
result typé ;
error typé ;
operation_status.

Elle expose aussi has_started() et is_completed(). Une inspection pilotée par les ticks est valide. Une boucle de polling active ne l’est pas : elle bloque le Game Thread qui doit terminer la requête.

cancel() demande une annulation coopérative. Elle peut empêcher le travail en file, mais ne peut pas interrompre le travail du dépôt ni transformer le résultat d’une mutation déjà persistée en résultat annulé.

Mises à jour partielles

Utilisez les indicateurs set_* exposés par le système de reflection pour exprimer l’intention :

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,
)

Il n’existe pas de convention None propre à Python. Les modifications de métadonnées des Repères utilisent les mêmes propriétés explicites set_title, set_description, set_pin_type et set_tags.

Automatisation Editor sans surveillance

Le modèle pris en charge est un processus Unreal Editor avec PythonScriptPlugin activé :

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

La forme de lancement sans surveillance prise en charge est montrée ci-dessous avec UE 5.6 ; utilisez l’exécutable Editor correspondant pour UE 5.7 ou 5.8 :

& "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

Un script asynchrone sans surveillance doit :

appeler unreal.EditorPythonScripting.set_keep_python_script_alive(True) ;
enregistrer unreal.register_slate_post_tick_callback(...) ;
construire, conserver, lier et démarrer sa requête Locus ;
laisser les ticks normaux de l’Editor piloter l’exécuteur Locus existant ;
observer la fin terminale et supprimer les liaisons de delegate ;
désenregistrer le callback de tick ;
appeler set_keep_python_script_alive(False) pour quitter proprement.

N’utilisez ni sleep(), ni attente en boucle, ni attente synchrone d’un future, ni pompage manuel du Game Thread.

Limites du pipeline

Python nécessite un processus Unreal Editor et PythonScriptPlugin.
Locus lui-même ne dépend pas de PythonScriptPlugin et continue de se charger lorsqu’il est désactivé.
python.exe autonome ne peut pas importer Locus.
Les Repères nécessitent un monde enregistré pris en charge et appartenant au projet.
Le commandlet -run=PythonScript n’est pas l’environnement complet pris en charge ; la validation a reçu un monde transitoire non enregistré plutôt que le monde enregistré requis par l’API complète.
Utilisez le chemin -ExecutePythonScript de l’application Editor complète pour l’automatisation sans surveillance.
Le démarrage ou la réconciliation de l’index peut produire un Unavailable réessayable ; resoumettez lors d’un tick normal ultérieur de l’Editor au lieu de bloquer.

Voir la vue d’ensemble de la Developer API pour les identités, révisions, erreurs, l’état de l’opération et la matrice de capacités.