Python Developer API

En las versiones compatibles de Engine, Locus expone directamente bajo unreal su base de solicitudes compartida. Python usa estas solicitudes en lugar de los proxies de acciones asíncronas de Blueprint.

El punto de entrada es unreal.LocusDeveloperRequestLibrary. Los nombres de fábricas y propiedades están en snake case, como create_document, on_succeeded, operation_status y request_id. Los valores de enum usan snake case en mayúsculas, como LocusDeveloperRequestState.NOT_STARTED y LocusDeveloperResultCode.STALE_REVISION.

Construir, conservar, vincular, iniciar

Este orden forma parte del contrato:

Construct → Retain references → Bind → Start → Completion

La construcción no envía trabajo. Conserva la solicitud, los wrappers de delegate y los callables de Python vinculados hasta la finalización terminal. Vincula éxito y fallo antes de start() porque un fallo de admisión puede completarse en línea. Elimina las vinculaciones y libera las referencias después de completar.

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

El ejemplo crea un Documento real. Elige una ruta adecuada al proyecto y gestiona una identidad existente mediante el callback de error tipado.

Inspeccionar una solicitud completada

Una solicitud tipada completada conserva:

state y succeeded;
request_id;
result tipado;
error tipado;
operation_status.

También expone has_started() e is_completed(). La inspección controlada por ticks es válida. Un bucle de sondeo ocupado no lo es: bloquea el Game Thread que debe completar la solicitud.

cancel() solicita una cancelación cooperativa. Puede impedir trabajo en cola, pero no interrumpir el trabajo del repositorio ni convertir el resultado de una mutación ya persistida en un resultado cancelado.

Actualizaciones parciales

Usa las marcas reflejadas set_* para expresar la intención:

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

No existe una convención None específica de Python. Los cambios de metadatos de Pines usan las mismas propiedades explícitas set_title, set_description, set_pin_type y set_tags.

Automatización desatendida del Editor

El modelo compatible es un proceso de Unreal Editor con PythonScriptPlugin habilitado:

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

La forma de lanzamiento desatendido compatible se muestra con UE 5.6; usa el ejecutable de Editor correspondiente para 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

Un script desatendido asíncrono debe:

llamar a unreal.EditorPythonScripting.set_keep_python_script_alive(True);
registrar unreal.register_slate_post_tick_callback(...);
construir, conservar, vincular e iniciar su solicitud de Locus;
dejar que los ticks normales del Editor impulsen el ejecutor existente de Locus;
observar la finalización terminal y quitar las vinculaciones de delegate;
cancelar el registro del callback de tick;
llamar a set_keep_python_script_alive(False) para salir limpiamente.

No uses sleep(), espera en bucle, espera síncrona de future ni bombeo manual del Game Thread.

Límites de la canalización

Python requiere un proceso Unreal Editor y PythonScriptPlugin.
Locus no depende de PythonScriptPlugin y sigue cargándose cuando está deshabilitado.
python.exe independiente no puede importar Locus.
Los Pines requieren un mundo guardado y propiedad del proyecto compatible.
El commandlet -run=PythonScript no es el entorno completo compatible; la validación recibió un mundo transitorio no guardado en lugar del mundo guardado requerido por la API completa.
Usa la ruta -ExecutePythonScript de la aplicación completa del Editor para la automatización desatendida.
El arranque o la reconciliación del índice puede producir Unavailable reintentable; vuelve a enviar en un tick normal posterior del Editor en lugar de bloquear.

Consulta la descripción general de Developer API para identidades, revisiones, errores, estado de operación y la matriz de capacidades.