C++ Developer API

在仅限 Editor 的 C++ 插件或工具中使用原生 Developer API。将 Locus 模块添加到使用方 Editor 模块的依赖项中；获取 API 时包含 Locus.h，使用请求和结果时包含 Developer/LocusDeveloperApi.h。

生命周期和异步契约

GetLocusDeveloperApi() 返回活动的 FLocusDeveloperApi；在初始化的 Locus Editor 生命周期之外返回 nullptr。

在 Game Thread 上获取并提交。
不要跨越子系统或模块关闭保留 API 指针。
每个完成回调都恰好在 Game Thread 上运行一次。
接受的工作会在 Locus 现有执行器的后续 tick 中完成。
接纳失败可能在提交返回前以内联方式完成。
提交前准备好回调拥有的状态。
取消是协作式的。它可以阻止排队的工作，但不能中断存储库工作，也不能将已完成持久化的变更追溯地取消。
不要添加阻塞等待、休眠、Game Thread 泵送或 Future.Get()。

返回的 FLocusDeveloperRequestHandle 暴露请求身份和线程安全的协作式 Cancel()。

创建文档

#include "Locus.h"
#include "Developer/LocusDeveloperApi.h"

void CreateCombatDocument()
{
  FLocusDeveloperApi* Locus = GetLocusDeveloperApi();
  if (Locus == nullptr)
  {
    return;
  }

  FLocusDeveloperCreateDocumentRequest Request;
  Request.Path = TEXT("Design/Combat.md");
  Request.Markdown = TEXT("# Combat\n");
  Request.PresentationRoot =
    ELocusDeveloperDocumentPresentationRoot::LocusDocuments;

  FLocusDeveloperRequestHandle Handle = Locus->CreateDocument(
    MoveTemp(Request),
    [](TLocusDeveloperResult<FLocusDeveloperDocumentSnapshot> Result)
    {
      if (!Result.IsSuccess())
      {
        UE_LOG(LogTemp, Error, TEXT("Locus: %s"), *Result.Error.Message);
        return;
      }

      const FLocusDeveloperDocumentSnapshot& Document = Result.Value.GetValue();
      UE_LOG(LogTemp, Display, TEXT("Created %s"),
        *Document.Identity.RelativePath);
    });

  // Retain Handle only if this tool needs to offer cancellation.
}

输入路径相对于所选的具体呈现根。返回的身份仍然是相对于 ProjectDocuments 的权威路径。

先获取，再更新

不要隐藏修订版本处理。使用读取结果中的修订版本作为变更前置条件：

FLocusDeveloperGetDocumentRequest GetRequest;
GetRequest.Identity.RelativePath = TEXT("Design/Combat.md");

Locus->GetDocument(
  MoveTemp(GetRequest),
  [Locus](TLocusDeveloperResult<FLocusDeveloperDocumentSnapshot> GetResult)
  {
    if (!GetResult.IsSuccess())
    {
      return;
    }

    const FLocusDeveloperDocumentSnapshot& Current = GetResult.Value.GetValue();
    FLocusDeveloperUpdateDocumentRequest UpdateRequest;
    UpdateRequest.Identity = Current.Identity;
    UpdateRequest.ExpectedRevision = Current.Revision;
    UpdateRequest.Markdown = Current.Markdown + TEXT("\n## Abilities\n");

    Locus->UpdateDocument(
      MoveTemp(UpdateRequest),
      [](TLocusDeveloperResult<FLocusDeveloperDocumentSnapshot> Result)
      {
        if (Result.Error.Code ==
          ELocusDeveloperErrorCode::StaleRevision)
        {
          // Reread before reconsidering the mutation.
        }
      });
  });

明确指定笔记范围

FLocusDeveloperCreateNoteRequest Request;
Request.Scope = ELocusDeveloperScope::Private;
Request.Title = TEXT("Local investigation");
Request.Body = TEXT("Not shared with the project repository.");
Request.Tags = {TEXT("investigation")};

FLocusDeveloperRequestHandle Handle = Locus->CreateNote(
  MoveTemp(Request),
  [](TLocusDeveloperResult<FLocusDeveloperNoteSnapshot> Result)
  {
    if (Result.IsSuccess())
    {
      const FLocusDeveloperNoteIdentifier Identity =
        Result.Value->Identity; // GUID + Private scope
    }
  });

范围过滤同样是明确的。All 包含私有内容；如果工具不能包含私有内容，请请求 Shared。

创建基本标记点

FLocusDeveloperCreatePinRequest Request;
Request.Scope = ELocusDeveloperScope::Shared;
Request.WorldAssetPath = TEXT("/Game/Maps/Main.Main");
Request.WorldLabel = TEXT("Main");
Request.Location = FVector(120.0, 40.0, 180.0);
Request.Title = TEXT("Check encounter cover");
Request.PinType = ELocusDeveloperPinType::Issue;

FLocusDeveloperRequestHandle Handle = Locus->CreatePin(
  MoveTemp(Request),
  [](TLocusDeveloperResult<FLocusDeveloperPinSnapshot> Result)
  {
    if (!Result.IsSuccess())
    {
      UE_LOG(LogTemp, Warning, TEXT("Pin create failed: %s"),
        LexToString(Result.Error.Code));
    }
  });

创建标记点需要受支持的已保存项目所有世界。元数据更新会保留位置、世界、锚点、视图和范围。

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