Python Developer API

Requisito Unreal Engine

L’accesso interattivo alla Python Developer API e l’automazione Python non presidiata richiedono Unreal Engine 5.6 o successivo. Locus core, C++, Blueprint e MCP restano supportati in Unreal Engine 5.4 e 5.5. Python non è supportato su queste versioni a causa di una limitazione verificata del sistema di reflection di Unreal nel percorso di invocazione Python.

Nelle versioni Engine supportate, Locus espone direttamente sotto unreal la base condivisa delle richieste. Python usa queste richieste invece dei proxy async-action Blueprint.

Il punto di ingresso è unreal.LocusDeveloperRequestLibrary. I nomi di factory e proprietà sono in snake case, come create_document, on_succeeded, operation_status e request_id. I valori enum usano uppercase snake case, come LocusDeveloperRequestState.NOT_STARTED e LocusDeveloperResultCode.STALE_REVISION.

Costruisci, conserva, associa, avvia

Questo ordine fa parte del contratto:

Construct → Retain references → Bind → Start → Completion

La costruzione non invia lavoro. Conserva la richiesta, i wrapper delegate e i callable Python associati fino al completamento terminale. Associa successo e fallimento prima di start(), perché l’errore di ammissione può completare inline. Rimuovi le associazioni e rilascia i riferimenti dopo il completamento.

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’esempio crea un Documento reale. Scegli un percorso adatto al progetto e gestisci un’identità esistente tramite il callback di errore tipizzato.

Ispeziona una richiesta completata

Una richiesta tipizzata completata conserva:

• state e succeeded;
• request_id;
• result tipizzato;
• error tipizzato;
• operation_status.

Espone anche has_started() e is_completed(). L’ispezione guidata dai tick è valida. Un ciclo di polling impegnato non lo è: blocca il Game Thread che deve completare la richiesta.

cancel() richiede una cancellazione cooperativa. Può impedire lavoro accodato, ma non interrompere il lavoro del repository né trasformare il risultato di una mutazione già persistita in un risultato cancellato.

Aggiornamenti parziali

Usa i flag set_* esposti tramite il sistema di reflection per esprimere l’intento:

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

Non esiste una convenzione None specifica per Python. Le modifiche ai metadati Pin usano le stesse proprietà esplicite set_title, set_description, set_pin_type e set_tags.

Automazione Editor non presidiata

Il modello supportato è un processo Unreal Editor con PythonScriptPlugin abilitato:

External automation
        ↓
UnrealEditor-Cmd full Editor environment
        ↓
PythonScriptPlugin
        ↓
Richieste Locus esposte tramite il sistema di reflection

La forma di avvio non presidiato supportata è mostrata con UE 5.6; usa l’eseguibile Editor corrispondente per UE 5.7 o 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

Uno script asincrono non presidiato dovrebbe:

1. chiamare unreal.EditorPythonScripting.set_keep_python_script_alive(True);
2. registrare unreal.register_slate_post_tick_callback(...);
3. costruire, conservare, associare e avviare la richiesta Locus;
4. lasciare che i normali tick dell’Editor guidino l’executor Locus esistente;
5. osservare il completamento terminale e rimuovere le associazioni delegate;
6. annullare la registrazione del callback tick;
7. chiamare set_keep_python_script_alive(False) per un’uscita pulita.

Non usare sleep(), attesa in busy loop, attesa sincrona di future o pumping manuale del Game Thread.

Limiti della pipeline

• Python richiede un processo Unreal Editor e PythonScriptPlugin.
• Locus non dipende da PythonScriptPlugin e continua a caricarsi quando è disabilitato.
• python.exe standalone non può importare Locus.
• I Pin richiedono un mondo salvato supportato e di proprietà del progetto.
• Il commandlet -run=PythonScript non è l’ambiente completo supportato; la validazione ha ricevuto un mondo transitorio non salvato invece del mondo salvato richiesto dall’API completa.
• Usa il percorso -ExecutePythonScript dell’applicazione Editor completa per l’automazione non presidiata.
• L’avvio o la riconciliazione dell’indice può produrre Unavailable ritentabile; invia di nuovo la richiesta in un normale tick successivo dell’Editor invece di bloccare.

Vedi la panoramica Developer API per identità, revisioni, errori, stato dell’operazione e matrice delle capacità.