Python Developer API

在受支持的 Engine 版本上，Locus 直接在 unreal 下暴露共享请求基础。Python 使用这些请求，而不是 Blueprint 异步操作代理。

入口点是 unreal.LocusDeveloperRequestLibrary。工厂和属性名称使用 snake case，例如 create_document、on_succeeded、operation_status 和 request_id。枚举值使用大写 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")

该示例会创建一个真实文档。选择适合项目的路径，并通过类型化的失败回调处理已有身份。

检查已完成的请求

已完成的类型化请求会保留：

state 和 succeeded；
request_id；
类型化的 result；
类型化的 error；
operation_status。

它还暴露 has_started() 和 is_completed()。基于 tick 的检查是有效的，但忙碌的轮询循环无效：它会阻塞必须完成请求的 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 属性。

无人值守的 Editor 自动化

受支持的模型是启用了 PythonScriptPlugin 的 Unreal Editor 进程：

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

下面使用 UE 5.6 展示受支持的无人值守启动形式；UE 5.7 或 5.8 请使用匹配的 Editor 可执行文件：

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

异步无人值守脚本应：

调用 unreal.EditorPythonScripting.set_keep_python_script_alive(True)；
注册 unreal.register_slate_post_tick_callback(...)；
构造、保留、绑定并启动 Locus 请求；
让正常的 Editor tick 驱动 Locus 现有的执行器；
观察终端完成并移除委托绑定；
注销 tick 回调；
调用 set_keep_python_script_alive(False) 以便干净退出。

不要使用 sleep()、自旋等待、同步 future 等待或手动 Game Thread 泵送。

流水线限制

Python 需要 Unreal Editor 进程和 PythonScriptPlugin。
Locus 本身不依赖 PythonScriptPlugin，即使其禁用也能加载。
独立的 python.exe 无法导入 Locus。
标记点需要受支持的已保存项目所有世界。
-run=PythonScript commandlet 不是完整的受支持环境；验证得到的是临时未保存世界，而不是完整 API 所需的已保存世界。
无人值守自动化使用完整 Editor 应用程序的 -ExecutePythonScript 路径。
启动或索引协调可能产生可重试的 Unavailable；在之后的正常 Editor tick 中重新提交，不要阻塞。

有关身份、修订版本、错误、操作状态和能力矩阵，请参阅Developer API 概览。