Developer API

Locus Developer API pozwala lokalnym narzędziom Unreal Editor pracować z Notatkami, Dokumentami i Pinezkami Locus. Jest przeznaczone do wtyczek C++ edytora, Editor Utility Blueprintów i Widgetów, skryptów Unreal Python oraz automatyzacji potoków działającej w edytorze.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Operacje deweloperskie używają tej samej walidacji, rewizji, trwałości, ochrony przed konfliktami, zasad ścieżek Dokumentów, routingu Kontroli wersji i cyklu życia aplikacji co interfejs Locus. Używaj API zamiast bezpośrednio edytować pliki Locus.

Wybierz API

Powierzchnia	Najlepsze zastosowanie	Zacznij tutaj
Natywne C++	Wtyczki edytora, narzędzia natywne, zaawansowane integracje	C++ Developer API
Blueprint	Editor Utility Blueprinty, Editor Utility Widgety	Blueprint Developer API
Unreal Python	Skrypty edytora, walidacja, automatyzacja wsadowa i bezobsługowa	Python Developer API

Integracja MCP jest osobną powierzchnią zewnętrznego klienta przeznaczoną dla AI/agentów. Narzędzia C++, Blueprint i Python Developer API nie używają wewnętrznie MCP.

Zgodność z silnikiem

Rdzeń Locus, C++, Blueprint i MCP są obsługiwane w Unreal Engine 5.4–5.8. Interaktywne i bezobsługowe Python Developer API wymaga Unreal Engine 5.6 lub nowszego.

Powierzchnia	UE 5.4–5.5	UE 5.6–5.8
C++	Obsługiwane	Obsługiwane
Blueprint	Obsługiwane	Obsługiwane
Python	Nieobsługiwane	Obsługiwane
MCP	Obsługiwane	Obsługiwane

Bieżąca powierzchnia operacji

W obsługiwanych wersjach Engine wszystkie 16 wybranych operacji jest dostępnych w C++, Blueprint i Python:

Zawartość	Operacje
Notatki	List, Get, Search, Create, Update, Archive
Dokumenty	List, Get, Search, Create, Update
Pinezki	List, Get, Create, Update metadata, Add comment

API celowo nie udostępnia modyfikowania folderów Notatek; zmiany nazwy, przenoszenia ani usuwania Dokumentów; zmiany położenia Pinezki ani pełnej wymiany kotwicy; manipulowania widokiem/powierzchnią Pinezki; negocjowania możliwości automatyzacji ani zdarzeń zmian; ani terminów żądań.

Tożsamości

Notatka: GUID oraz jawny zakres Współdzielone lub Prywatne.
Pinezka: GUID oraz jawny zakres Współdzielone lub Prywatne.
Dokument: znormalizowana ścieżka Markdown względem ProjectDocuments.

Korzeń prezentacji Dokumentu, ścieżka prezentacji, kontekst /Game/... i bezwzględna lokalizacja systemu plików nie są alternatywnymi tożsamościami.

Korzenie prezentacji Dokumentów

Żądania tworzenia wybierają jeden konkretny korzeń. Podana ścieżka jest względna względem tego widocznego korzenia:

Korzeń prezentacji	Podana ścieżka	Autorytatywna tożsamość
Dokumenty Locus	`Design/Combat.md`	`Design/Combat.md`
Przeglądarka zawartości	`Characters/Hero.md`	`Content/Characters/Hero.md`

Nie dodawaj Content/ podczas tworzenia pod Przeglądarką zawartości. Locus stosuje to odwzorowanie raz.

Rewizje

Odczyty i udane mutacje zwracają nieprzejrzystą rewizję. Aktualizacja lub archiwizacja musi przekazać bieżącą wartość jako ExpectedRevision:

Get → Snapshot + Revision → Update with ExpectedRevision

Nie analizuj ani nie twórz rewizji. Jeśli wynikiem jest StaleRevision, odczytaj ponownie autorytatywny element i ponownie rozważ zmianę. Locus nie ukrywa nieaktualnego zapisu przez automatyczny ponowny odczyt lub ponowienie.

Błędy

Rozgałęziaj logikę według typowanego kodu błędu, a nie komunikatu czytelnego dla człowieka:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown i OperationFailed. None oznacza brak błędu.

Możliwe do ponowienia zapytanie Unavailable można wysłać ponownie przy następnym zwykłym tyknięciu edytora. Nie blokuj Game Thread podczas oczekiwania.

Sukces i stan Kontroli wersji są odrębne

Udana lokalna mutacja może zgłosić lokalną trwałość jako Committed, a Kontrolę wersji jako Pending, NotConfigured, Unknown lub NotRequired. Nadal jest to udana operacja Locus. Stan operacji jest dodatkową, neutralną względem dostawcy informacją do zwykłego procesu Kontroli wersji użytkownika.

Locus nie przesyła zmian ani nie administruje changelistami.

Granica zaufania

C++, Blueprint i Python to zaufane lokalne narzędzia edytora. Wywołujący, który jawnie żąda zakresu Prywatne, celowo uzyskuje dostęp do lokalnej Prywatnej zawartości bieżącego projektu. Ustawienia MCP Zezwalaj na zmiany i Zezwalaj na Prywatne notatki i Pinezki regulują osobną granicę zewnętrznego klienta MCP i nie dotyczą wywołującego Developer API działającego w procesie.