C++ Developer API

Verwenden Sie die native Developer API aus einem Editor-only-C++-Plugin oder -Tool. Fügen Sie das Modul Locus zu den Abhängigkeiten des konsumierenden Editor-Moduls hinzu, schließen Sie für die Beschaffung Locus.h und für Anfragen und Ergebnisse Developer/LocusDeveloperApi.h ein.

Lebensdauer- und Async-Vertrag

GetLocusDeveloperApi() liefert die aktive FLocusDeveloperApi oder außerhalb der initialisierten Locus-Editor-Lebensdauer nullptr zurück.

• Beschaffen und übermitteln Sie auf dem Game Thread.
• Behalten Sie den API-Zeiger nicht über das Herunterfahren eines Subsystems oder Moduls hinaus.
• Jeder Abschluss läuft genau einmal auf dem Game Thread.
• Akzeptierte Arbeit wird in einem späteren Tick des vorhandenen Locus-Executors abgeschlossen.
• Ein Zulassungsfehler kann inline abgeschlossen werden, bevor die Übermittlung zurückkehrt.
• Bereiten Sie callback-eigenen Zustand vor der Übermittlung vor.
• Abbruch ist kooperativ. Er kann wartende Arbeit verhindern, aber Repository-Arbeit nicht unterbrechen und eine bereits lokal gespeicherte Änderung nicht nachträglich abbrechen.
• Fügen Sie keine blockierenden Wartezeiten, Sleeps, Game-Thread-Pumpen oder Future.Get() hinzu.

Der zurückgegebene FLocusDeveloperRequestHandle stellt Anfrageidentität und thread-sicheres kooperatives Cancel() bereit.

Ein Dokument erstellen

#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.
}

Der Eingabepfad ist relativ zur ausgewählten konkreten Präsentationswurzel. Die zurückgegebene Identität bleibt der maßgebliche, zu ProjectDocuments relative Pfad.

Abrufen, dann aktualisieren

Verbergen Sie die Revisionsbehandlung nicht. Verwenden Sie die Revision aus dem Leseergebnis als Vorbedingung für die Änderung:

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.
        }
      });
  });

Ausdrücklicher Notizbereich

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
    }
  });

Bereichsfilter sind ebenso ausdrücklich. All schließt private Inhalte ein; fordern Sie Shared an, wenn ein Tool sie nicht einbeziehen darf.

Grundlegendes Erstellen eines Pins

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));
    }
  });

Das Erstellen eines Pins erfordert eine unterstützte gespeicherte, projekt-eigene Welt. Metadatenänderungen bewahren Position, Welt, Anker, Ansicht und Bereich.

Siehe die Developer-API-Übersicht zur Operationsmatrix, zum Identitätsvertrag, zur Fehlerklassifikation, zu Revisionen und zum Operationsstatus.