Python Developer API

Requisito do Unreal Engine

O acesso interativo à Python Developer API e a automação Python não assistida exigem Unreal Engine 5.6 ou posterior. Locus core, C++, Blueprint e MCP continuam compatíveis com Unreal Engine 5.4 e 5.5. Python não é compatível nessas versões devido a uma limitação verificada do sistema de reflection do Unreal no caminho de invocação do Python.

Nas versões compatíveis da Engine, o Locus expõe sua base compartilhada de requisições diretamente em unreal. O Python usa essas requisições em vez dos proxies de ação assíncrona do Blueprint.

O ponto de entrada é unreal.LocusDeveloperRequestLibrary. Nomes de fábrica e propriedades usam snake case, como create_document, on_succeeded, operation_status e request_id. Valores de enum usam snake case em maiúsculas, como LocusDeveloperRequestState.NOT_STARTED e LocusDeveloperResultCode.STALE_REVISION.

Construir, manter, associar, iniciar

Esta ordem faz parte do contrato:

Construct → Retain references → Bind → Start → Completion

A construção não envia trabalho. Mantenha a requisição, wrappers de delegate e callables Python associados até a conclusão terminal. Associe sucesso e falha antes de start(), pois a falha de admissão pode ser concluída inline. Remova as associações e libere as referências após a conclusão.

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

O exemplo cria um Documento real. Escolha um caminho adequado ao projeto e trate uma identidade existente pelo callback de falha tipado.

Inspecionar uma requisição concluída

Uma requisição tipada concluída mantém:

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

Ela também expõe has_started() e is_completed(). A inspeção orientada por ticks é válida. Um loop de polling ocupado não é: ele bloqueia o Game Thread que precisa concluir a requisição.

cancel() solicita cancelamento cooperativo. Pode impedir trabalho enfileirado, mas não interrompe o trabalho do repositório nem transforma um resultado de mutação confirmado em um resultado cancelado.

Atualizações parciais

Use as flags refletidas set_* para expressar a intenção:

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

Não existe uma convenção None específica do Python. Alterações de metadados de Pins usam as mesmas propriedades explícitas set_title, set_description, set_pin_type e set_tags.

Automação não assistida do Editor

O modelo compatível é um processo do Unreal Editor com PythonScriptPlugin habilitado:

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

A forma compatível de inicialização não assistida é mostrada abaixo com UE 5.6; use o executável correspondente do Editor para 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

Um script assíncrono não assistido deve:

1. chamar unreal.EditorPythonScripting.set_keep_python_script_alive(True);
2. registrar unreal.register_slate_post_tick_callback(...);
3. construir, manter, associar e iniciar sua requisição do Locus;
4. permitir que os ticks normais do Editor conduzam o executor existente do Locus;
5. observar a conclusão terminal e remover as associações de delegate;
6. cancelar o registro do callback de tick;
7. chamar set_keep_python_script_alive(False) para uma saída limpa.

Não use sleep(), espera em loop, espera síncrona de future ou bombeamento manual do Game Thread.

Limites do pipeline

• Python requer um processo Unreal Editor e PythonScriptPlugin.
• O Locus não depende do PythonScriptPlugin e continua carregando quando ele está desabilitado.
• python.exe standalone não pode importar o Locus.
• Pins exigem um mundo salvo compatível e de propriedade do projeto.
• O commandlet -run=PythonScript não é o ambiente completo compatível; a validação recebeu um mundo transitório não salvo em vez do mundo salvo exigido pela API completa.
• Use o caminho -ExecutePythonScript do aplicativo completo do Editor para automação não assistida.
• A inicialização ou reconciliação do índice pode produzir Unavailable que permite nova tentativa; reenvie em um tick normal posterior do Editor em vez de bloquear.

Consulte a visão geral da Developer API para identidades, revisões, erros, status da operação e matriz de capacidades.