Developer API

Locus Developer API を使うと、ローカルの Unreal Editor ツールで Locus のノート、ドキュメント、ピンを操作できます。C++ のエディタプラグイン、Editor Utility Blueprint と Widget、Unreal Python スクリプト、エディタで動作するパイプライン自動化を対象にしています。

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Developer 操作には、Locus UI と同じ検証、リビジョン、永続化、競合保護、ドキュメントパスのルール、ソースコントロールのルーティング、アプリケーションのライフタイムが適用されます。Locus ファイルを直接編集せず、API を使ってください。

API を選ぶ

サーフェス	適した用途	ここから開始
Native C++	エディタプラグイン、ネイティブツール、高度な連携	C++ Developer API
Blueprint	Editor Utility Blueprint、Editor Utility Widget	Blueprint Developer API
Unreal Python	エディタスクリプト、検証、一括および非対話型自動化	Python Developer API

MCP 連携は、AI/エージェント向けの外部クライアントサーフェスです。C++、Blueprint、Python の Developer ツールは内部で MCP を使いません。

Engine の互換性

コア Locus、C++、Blueprint、MCP は Unreal Engine 5.4～5.8 でサポートされます。対話型および非対話型の Python Developer API には Unreal Engine 5.6 以降が必要です。

サーフェス	UE 5.4～5.5	UE 5.6～5.8
C++	サポート	サポート
Blueprint	サポート	サポート
Python	サポート対象外	サポート
MCP	サポート	サポート

現在の操作サーフェス

対応する Engine バージョンでは、16 個のすべてのキュレーション済み操作を C++、Blueprint、Python から利用できます。

コンテンツ	操作
ノート	List、Get、Search、Create、Update、Archive
ドキュメント	List、Get、Search、Create、Update
ピン	List、Get、Create、メタデータの Update、コメントの Add

API では、ノートフォルダーの変更、ドキュメントの名前変更・移動・削除、ピン位置の変更やアンカー全体の置換、ピンのビュー/サーフェス操作、自動化機能のネゴシエーションや変更イベント、リクエストの期限を意図的に公開していません。

ID

ノート: GUID と明示的な共有またはプライベートのスコープ。
ピン: GUID と明示的な共有またはプライベートのスコープ。
ドキュメント: ProjectDocuments を基準にした正規化済み Markdown パス。

ドキュメントの表示ルート、表示パス、/Game/... コンテキスト、絶対ファイルシステムパスは別の ID ではありません。

ドキュメントの表示ルート

作成リクエストでは具体的なルートを 1 つ選びます。指定するパスは、その表示ルートからの相対パスです。

表示ルート	指定するパス	権威のある ID
Locus ドキュメント	`Design/Combat.md`	`Design/Combat.md`
コンテンツブラウザ	`Characters/Hero.md`	`Content/Characters/Hero.md`

コンテンツブラウザの下に作成するときは Content/ を先頭に付けないでください。Locus がマッピングを一度適用します。

リビジョン

読み取りと成功した変更は不透明なリビジョンを返します。更新またはアーカイブでは、現在の値を ExpectedRevision として送信する必要があります。

Get → Snapshot + Revision → Update with ExpectedRevision

リビジョンを解析または生成しないでください。結果が StaleRevision の場合は、権威のある項目をもう一度読み取り、変更を再検討します。Locus は自動的な再読み取りや再試行で古い書き込みを隠しません。

エラー

人間向けのメッセージではなく、型付きエラーコードで分岐します。

InvalidInput、NotFound、AlreadyExists、Conflict、StaleRevision、AccessDenied、Unsupported、Busy、Cancelled、Unavailable、ShuttingDown、OperationFailed。None はエラーがないことを示します。

再試行可能な Unavailable クエリは、通常の後続の Editor tick で再送信できます。待機中に Game Thread をブロックしないでください。

成功とソースコントロールの状態は別です

ローカルの変更が成功すると、ローカル永続化が Committed と報告される一方で、ソースコントロールが Pending、NotConfigured、Unknown、NotRequired になることがあります。これは Locus 操作として成功しています。操作ステータスは、ユーザーが通常のソースコントロールワークフローを進めるための、プロバイダーに依存しない追加情報です。

Locus は変更を送信したり、チェンジリストを管理したりしません。

信頼境界

C++、Blueprint、Python は信頼されたローカル Editor ツールです。Private スコープを明示的に要求する呼び出し元は、現在のプロジェクトのローカルな Private コンテンツに意図的にアクセスします。MCP の 変更を許可と プライベートノートとピンを許可の設定は、別の外部クライアント MCP 境界を管理するもので、プロセス内の Developer API 呼び出し元には適用されません。