Developer API

Locus Developer API, yerel Unreal Editor araçlarının Locus Notları, Belgeleri ve Pinleriyle çalışmasını sağlar. C++ editor eklentileri, Editor Utility Blueprint’leri ve Widget’ları, Unreal Python betikleri ve Editor tarafından barındırılan işlem hattı otomasyonu için tasarlanmıştır.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Geliştirici işlemleri Locus kullanıcı arayüzüyle aynı doğrulamayı, revizyonları, kalıcılığı, çakışma korumasını, Belge yolu kurallarını, Kaynak Denetimi yönlendirmesini ve uygulama ömrünü kullanır. Locus dosyalarını doğrudan düzenlemek yerine API’yi kullanın.

API seçme

Yüzey	En uygun kullanım	Başlangıç
Yerel C++	Editor eklentileri, yerel araçlar, gelişmiş entegrasyonlar	C++ Developer API
Blueprint	Editor Utility Blueprint’leri, Editor Utility Widget’ları	Blueprint Developer API
Unreal Python	Editor betikleri, doğrulama, toplu işlemler ve kullanıcı etkileşimi gerektirmeyen otomasyon	Python Developer API

MCP Entegrasyonu, yapay zekâ/agent odaklı harici istemciler için ayrı yüzeydir. C++, Blueprint ve Python geliştirici araçları dahili olarak MCP kullanmaz.

Engine uyumluluğu

Temel Locus özellikleri, C++, Blueprint ve MCP; Unreal Engine 5.4–5.8’de desteklenir. Etkileşimli Python Developer API erişimi ve kullanıcı etkileşimi gerektirmeyen Python otomasyonu, Unreal Engine 5.6 veya daha yeni bir sürüm gerektirir.

Yüzey	UE 5.4–5.5	UE 5.6–5.8
C++	Desteklenir	Desteklenir
Blueprint	Desteklenir	Desteklenir
Python	Desteklenmez	Desteklenir
MCP	Desteklenir	Desteklenir

Geçerli işlem yüzeyi

Desteklenen Engine sürümlerinde seçilmiş 16 işlemin tamamına C++, Blueprint ve Python üzerinden erişilebilir:

İçerik	İşlemler
Notlar	Listele, Getir, Ara, Oluştur, Güncelle, Arşivle
Belgeler	Listele, Getir, Ara, Oluştur, Güncelle
Pinler	Listele, Getir, Oluştur, Meta verileri güncelle, Yorum ekle

API bilerek şu işlemleri sunmaz: Not klasörü değişikliği; Belge yeniden adlandırma, taşıma veya silme; Pin konumu değişikliği veya tam çapa değiştirme; Pin görünümü/yüzey işlemleri; Otomasyon yetenek anlaşması veya değişiklik olayları; istek son tarihleri.

Kimlikler

• Not: GUID ve açık Paylaşılan veya Özel kapsam.
• Pin: GUID ve açık Paylaşılan veya Özel kapsam.
• Belge: ProjectDocuments köküne göre normalleştirilmiş Markdown yolu.

Belgenin sunum kökü, sunum yolu, /Game/... bağlamı ve mutlak dosya sistemi konumu alternatif kimlikler değildir.

Belge sunum kökleri

Oluşturma istekleri somut bir kök seçer. Verilen yol, görünen bu köke göredir:

Sunum kökü	Verilen yol	Belge kimliği
Locus Belgeleri	Design/Combat.md	Design/Combat.md
Content Browser	Characters/Hero.md	Content/Characters/Hero.md

Content Browser altında oluştururken yolun başına Content/ eklemeyin. Locus bu eşlemeyi bir kez uygular.

Revizyonlar

Okumalar ve başarılı değişiklikler opak bir revizyon döndürür. Güncelleme veya arşivleme, geçerli değeri ExpectedRevision olarak göndermelidir:

Get → Snapshot + Revision → Update with ExpectedRevision

Revizyonları ayrıştırmayın veya üretmeyin. Sonuç StaleRevision ise öğenin güncel halini yeniden okuyup değişikliği tekrar değerlendirin. Locus, güncel olmayan yazmayı otomatik yeniden okuma veya yeniden denemeyle gizlemez.

Hatalar

İnsan tarafından okunabilen mesaj yerine türü belirlenmiş hata koduna göre dallanın:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown ve OperationFailed. None, hata olmadığını gösterir.

Yeniden denenebilir bir Unavailable sorgusu sonraki normal Editor tick’inde tekrar gönderilebilir. Beklerken Game Thread’i engellemeyin.

Başarı ve Kaynak Denetimi durumu ayrıdır

Başarılı bir yerel değişiklik, Kaynak Denetimi Pending, NotConfigured, Unknown veya NotRequired durumundayken yerel kalıcılığı Committed olarak bildirebilir. Bu yine başarılı bir Locus işlemidir. İşlem durumu, kullanıcının normal Kaynak Denetimi iş akışı için sağlayıcıdan bağımsız ek bilgidir.

Locus değişiklikleri göndermez veya değişiklik listelerini yönetmez.

Güven sınırı

C++, Blueprint ve Python güvenilen yerel Editor araçlarıdır. Açıkça Özel kapsam isteyen bir araç, geçerli projenin yerel Özel içeriğine bilerek erişir. MCP’nin Değişikliklere İzin Ver ve Özel Notlara ve Pinlere İzin Ver ayarları ayrı harici istemci MCP sınırını yönetir; işlem içindeki Developer API araçlarını yönetmez.