Developer API

La Locus Developer API consente agli strumenti locali di Unreal Editor di lavorare con Note, Documenti e Pin Locus. È pensata per plugin C++ dell’Editor, Editor Utility Blueprint e Widget, script Unreal Python e automazione di pipeline ospitata nell’Editor.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Le operazioni Developer usano la stessa validazione, revisioni, persistenza, protezione dai conflitti, regole dei percorsi Documento, instradamento del controllo del codice sorgente e durata dell’applicazione della UI Locus. Usa l’API invece di modificare direttamente i file Locus.

Scegli un’API

Superficie	Ideale per	Inizia qui
C++ nativo	Plugin Editor, strumenti nativi, integrazioni avanzate	C++ Developer API
Blueprint	Editor Utility Blueprint, Editor Utility Widget	Blueprint Developer API
Unreal Python	Script Editor, validazione, automazione batch e non presidiata	Python Developer API

Integrazione MCP è la superficie separata per client esterni AI/agent. Gli strumenti Developer C++, Blueprint e Python non usano MCP internamente.

Compatibilità Engine

Locus core, C++, Blueprint e MCP sono supportati su Unreal Engine 5.4–5.8. La Python Developer API interattiva e non presidiata richiede Unreal Engine 5.6 o successivo.

Superficie	UE 5.4–5.5	UE 5.6–5.8
C++	Supportato	Supportato
Blueprint	Supportato	Supportato
Python	Non supportato	Supportato
MCP	Supportato	Supportato

Superficie operativa corrente

Nelle versioni Engine supportate, tutte le 16 operazioni selezionate sono disponibili da C++, Blueprint e Python:

Contenuto	Operazioni
Note	List, Get, Search, Create, Update, Archive
Documenti	List, Get, Search, Create, Update
Pin	List, Get, Create, Update metadata, Add comment

L’API non espone intenzionalmente modifica delle cartelle Note; rinomina, spostamento o eliminazione dei Documenti; modifica della posizione o sostituzione completa dell’ancora dei Pin; manipolazione di vista/superficie dei Pin; negoziazione delle capacità di automazione o eventi di modifica; né scadenze delle richieste.

Identità

• Nota: GUID più ambito esplicito Condiviso o Privato.
• Pin: GUID più ambito esplicito Condiviso o Privato.
• Documento: percorso Markdown normalizzato relativo a ProjectDocuments.

La radice di presentazione, il percorso di presentazione, il contesto /Game/... e il percorso assoluto del filesystem di un Documento non sono identità alternative.

Radici di presentazione dei Documenti

Le richieste di creazione scelgono una radice concreta. Il percorso fornito è relativo alla radice visibile:

Radice di presentazione	Percorso fornito	Identità canonica
Documenti Locus	Design/Combat.md	Design/Combat.md
Content Browser	Characters/Hero.md	Content/Characters/Hero.md

Non anteporre Content/ quando crei sotto Content Browser. Locus applica la mappatura una sola volta.

Revisioni

Letture e mutazioni riuscite restituiscono una revisione opaca. Un aggiornamento o un’archiviazione deve inviare il valore corrente come ExpectedRevision:

Get → Snapshot + Revision → Update with ExpectedRevision

Non analizzare o fabbricare revisioni. Se il risultato è StaleRevision, rileggi l’elemento corrente e rivaluta la modifica. Locus non nasconde una scrittura non aggiornata con rilettura o retry automatico.

Errori

Usa il codice di errore tipizzato, non il messaggio leggibile:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown e OperationFailed. None rappresenta nessun errore.

Una query Unavailable ritentabile può essere reinviata in un normale tick successivo dell’Editor. Non bloccare il Game Thread in attesa.

Successo e stato del controllo del codice sorgente sono separati

Una mutazione locale riuscita può riportare la persistenza locale come Committed mentre il controllo del codice sorgente è Pending, NotConfigured, Unknown o NotRequired. È comunque un’operazione Locus riuscita. Lo stato dell’operazione è informazione aggiuntiva neutrale rispetto al provider per il normale flusso del controllo del codice sorgente.

Locus non invia modifiche e non amministra changelist.

Confine di fiducia

C++, Blueprint e Python sono strumenti locali attendibili dell’Editor. Un chiamante che richiede esplicitamente l’ambito Privato accede intenzionalmente ai contenuti Privati locali del progetto corrente. Le impostazioni MCP Consenti modifiche e Consenti note e Pin Privati governano il confine MCP separato del client esterno e non quello di un chiamante Developer API in-process.