Developer API

Die Locus Developer API ermöglicht lokalen Werkzeugen im Unreal Editor, mit Locus-Notizen, Dokumenten und Pins zu arbeiten. Sie richtet sich an C++-Editor-Plugins, Editor Utility Blueprints und Widgets, Unreal-Python-Skripte sowie pipelinebezogene Automatisierung im Editor.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Developer-Operationen verwenden dieselbe Validierung, Revisionen, Persistenz, Konfliktsicherung, Regeln für Dokumentpfade, Weiterleitung an die Quellcodeverwaltung und Lebensdauer der Anwendung wie die Locus-UI. Verwenden Sie die API, statt Locus-Dateien direkt zu bearbeiten.

Eine API auswählen

Oberfläche	Geeignet für	Einstieg
Native C++	Editor-Plugins, native Tools, fortgeschrittene Integrationen	C++ Developer API
Blueprint	Editor Utility Blueprints, Editor Utility Widgets	Blueprint Developer API
Unreal Python	Editor-Skripte, Validierung, Batch- und unbeaufsichtigte Automatisierung	Python Developer API

MCP-Integration ist die separate externe Client-Oberfläche für KI und Agents. C++, Blueprint und Python Developer Tools verwenden MCP intern nicht.

Engine-Kompatibilität

Core Locus, C++, Blueprint und MCP werden unter Unreal Engine 5.4–5.8 unterstützt. Die interaktive und unbeaufsichtigte Python Developer API erfordert Unreal Engine 5.6 oder neuer.

Oberfläche	UE 5.4–5.5	UE 5.6–5.8
C++	Unterstützt	Unterstützt
Blueprint	Unterstützt	Unterstützt
Python	Nicht unterstützt	Unterstützt
MCP	Unterstützt	Unterstützt

Aktuelle Operationsoberfläche

In den unterstützten Engine-Versionen stehen alle 16 kuratierten Operationen in C++, Blueprint und Python zur Verfügung:

Inhalt	Operationen
Notizen	List, Get, Search, Create, Update, Archive
Dokumente	List, Get, Search, Create, Update
Pins	List, Get, Create, Update metadata, Add comment

Die API stellt absichtlich keine Änderung von Notizordnern, Umbenennen/Verschieben/Löschen von Dokumenten, Positionsänderung oder vollständigen Ankerersatz von Pins, View-/Oberflächenänderungen von Pins, Aushandlung von Automatisierungsfähigkeiten oder Änderungsereignisse und keine Anfragefristen bereit.

Identitäten

Notiz: GUID plus ausdrücklicher gemeinsamer oder privater Bereich.
Pin: GUID plus ausdrücklicher gemeinsamer oder privater Bereich.
Dokument: normalisierter Markdown-Pfad relativ zu ProjectDocuments.

Die Präsentationswurzel eines Dokuments, der Präsentationspfad, der /Game/...-Kontext und der absolute Dateisystemort sind keine alternativen Identitäten.

Präsentationswurzeln von Dokumenten

Erstellungsanfragen wählen eine konkrete Wurzel. Der angegebene Pfad ist relativ zu dieser sichtbaren Wurzel:

Präsentationswurzel	Angegebener Pfad	Maßgebliche Identität
Locus-Dokumente	`Design/Combat.md`	`Design/Combat.md`
Content Browser	`Characters/Hero.md`	`Content/Characters/Hero.md`

Fügen Sie beim Erstellen unter Content Browser nicht Content/ voran. Locus wendet diese Zuordnung einmal an.

Revisionen

Lesen und erfolgreiche Änderungen liefern eine undurchsichtige Revision zurück. Eine Aktualisierung oder Archivierung muss den aktuellen Wert als ExpectedRevision übermitteln:

Get → Snapshot + Revision → Update with ExpectedRevision

Parsen oder erzeugen Sie Revisionen nicht selbst. Wenn das Ergebnis StaleRevision lautet, lesen Sie das maßgebliche Element erneut und prüfen Sie die Änderung neu. Locus verbirgt einen veralteten Schreibvorgang nicht durch automatisches erneutes Lesen oder Wiederholen.

Fehler

Verzweigen Sie nach dem typisierten Fehlercode und nicht nach der menschenlesbaren Meldung:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown und OperationFailed. None bedeutet, dass kein Fehler vorliegt.

Eine wiederholbare Unavailable-Abfrage kann in einem späteren normalen Editor-Tick erneut übermittelt werden. Blockieren Sie den Game Thread nicht während des Wartens.

Erfolg und Status der Quellcodeverwaltung sind getrennt

Eine erfolgreiche lokale Änderung kann lokale Persistenz als Committed melden, während die Quellcodeverwaltung Pending, NotConfigured, Unknown oder NotRequired ist. Das ist weiterhin eine erfolgreiche Locus-Operation. Der Operationsstatus ist zusätzliche anbieterneutrale Information für den normalen Workflow der Quellcodeverwaltung.

Locus übermittelt keine Änderungen und verwaltet keine Changelists.

Vertrauensgrenze

C++, Blueprint und Python sind vertrauenswürdige lokale Editor-Werkzeuge. Ein Aufrufer, der ausdrücklich einen privaten Bereich anfordert, greift absichtlich auf private Inhalte des lokalen aktuellen Projekts zu. Die MCP-Einstellungen Änderungen zulassen und Private Notizen und Pins zulassen regeln die separate MCP-Grenze für externe Clients und gelten nicht für einen In-Process-Aufrufer der Developer API.