Python Developer API

Требование Unreal Engine

Интерактивный доступ к Python Developer API и автономная автоматизация Python требуют Unreal Engine 5.6 или новее. Основные Locus, C++, Blueprint и MCP поддерживаются в Unreal Engine 5.4 и 5.5. Python не поддерживается в этих версиях из-за подтверждённого ограничения рефлексии Unreal Engine в пути вызова Python.

В поддерживаемых версиях Engine Locus напрямую предоставляет общую основу запросов под unreal. Python использует эти запросы, а не прокси асинхронных действий Blueprint.

Точкой входа является unreal.LocusDeveloperRequestLibrary. Имена фабрик и свойств используют snake case, например create_document, on_succeeded, operation_status и request_id. Значения enum используют верхний snake case, например LocusDeveloperRequestState.NOT_STARTED и LocusDeveloperResultCode.STALE_REVISION.

Создать, сохранить, связать, запустить

Эта последовательность является частью контракта:

Construct → Retain references → Bind → Start → Completion

Конструирование не отправляет работу. Сохраняйте запрос, обёртки делегатов и связанные вызываемые объекты Python до терминального завершения. Свяжите обработчики успеха и ошибки до start(), поскольку ошибка допуска может завершиться сразу. После завершения удалите связи и освободите эти ссылки.

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

Пример создаёт настоящий документ. Выберите подходящий для проекта путь и обработайте существующую идентичность в типизированном callback ошибки.

Проверка завершённого запроса

Завершённый типизированный запрос сохраняет:

• state и succeeded;
• request_id;
• типизированный result;
• типизированную error;
• operation_status.

Он также предоставляет has_started() и is_completed(). Проверка по тикам допустима. Цикл частого опроса недопустим: он блокирует Game Thread, который должен завершить запрос.

cancel() запрашивает кооперативную отмену. Она может предотвратить ожидающую работу, но не прерывает работу репозитория и не превращает уже зафиксированное изменение в отменённый результат.

Частичные обновления

Используйте отражённые флаги set_*, чтобы выразить намерение:

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

Специального соглашения Python с None нет. Изменения метаданных метки используют те же явные свойства set_title, set_description, set_pin_type и set_tags.

Автономная автоматизация редактора

Поддерживаемая модель — процесс Unreal Editor с включённым PythonScriptPlugin:

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

Ниже показан поддерживаемый вид автономного запуска с UE 5.6; для UE 5.7 или 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

Асинхронный автономный скрипт должен:

1. вызвать unreal.EditorPythonScripting.set_keep_python_script_alive(True);
2. зарегистрировать unreal.register_slate_post_tick_callback(...);
3. создать, сохранить, связать и запустить запрос Locus;
4. позволить обычным тикам редактора выполнять существующий исполнитель Locus;
5. дождаться терминального завершения и удалить связи делегатов;
6. отменить регистрацию callback тика;
7. вызвать set_keep_python_script_alive(False) для корректного выхода.

Не используйте sleep(), активное ожидание, синхронное ожидание future или ручную прокачку Game Thread.

Ограничения конвейера

• Python требует процесса Unreal Editor и PythonScriptPlugin.
• Сам Locus не зависит от PythonScriptPlugin и продолжает загружаться, когда он отключён.
• Отдельный python.exe не может импортировать Locus.
• Для меток требуется поддерживаемый сохранённый принадлежащий проекту мир.
• Commandlet -run=PythonScript не является полной поддерживаемой средой; проверка получила временный несохранённый мир вместо сохранённого мира, необходимого полному API.
• Для автономной автоматизации используйте путь -ExecutePythonScript полного приложения редактора.
• Запуск или согласование индекса может привести к повторяемой ошибке Unavailable; отправьте запрос на следующем обычном тике редактора, не блокируя поток.

См. Обзор Developer API с идентичностями, ревизиями, ошибками, состоянием операции и матрицей возможностей.