Python Developer API

対応する Engine バージョンでは、Locus は共有リクエスト基盤を unreal の下に直接公開します。Python では Blueprint の非同期アクションプロキシではなく、これらのリクエストを使います。

エントリポイントは unreal.LocusDeveloperRequestLibrary です。ファクトリとプロパティの名前は create_document、on_succeeded、operation_status、request_id のような snake case です。列挙値は LocusDeveloperRequestState.NOT_STARTED と LocusDeveloperResultCode.STALE_REVISION のような大文字の snake case です。

構築、保持、バインド、開始

この順序は契約の一部です。

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

この例では実際のドキュメントを作成します。プロジェクトに適したパスを選び、型付きの失敗コールバックで既存 ID を処理してください。

完了したリクエストを調べる

完了した型付きリクエストは次を保持します。

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 で再送信してください。

ID、リビジョン、エラー、操作ステータス、機能マトリックスについては、Developer API の概要を参照してください。