Developer API

La Locus Developer API permet aux outils locaux d’Unreal Editor de travailler avec les Notes, Documents et Repères Locus. Elle est destinée aux plugins C++ d’Editor, aux Editor Utility Blueprints et Widgets, aux scripts Unreal Python et à l’automatisation de pipeline hébergée dans l’Editor.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Les opérations Developer utilisent la même validation, les mêmes révisions, la même persistance, la protection contre les conflits, les règles de chemin des Documents, le routage du contrôle de source et la durée de vie de l’application que l’UI Locus. Utilisez l’API au lieu de modifier directement les fichiers Locus.

Choisir une API

Surface	Pour	Commencer ici
C++ natif	Plugins Editor, outils natifs, intégrations avancées	C++ Developer API
Blueprint	Editor Utility Blueprints, Editor Utility Widgets	Blueprint Developer API
Unreal Python	Scripts Editor, validation, automatisation par lot et sans surveillance	Python Developer API

Intégration MCP est la surface externe distincte destinée aux IA/agents. Les outils Developer C++, Blueprint et Python n’utilisent pas MCP en interne.

Compatibilité Engine

Locus, C++, Blueprint et MCP sont pris en charge sous Unreal Engine 5.4 à 5.8. La Python Developer API interactive et sans surveillance nécessite Unreal Engine 5.6 ou une version ultérieure.

Surface	UE 5.4–5.5	UE 5.6–5.8
C++	Pris en charge	Pris en charge
Blueprint	Pris en charge	Pris en charge
Python	Non pris en charge	Pris en charge
MCP	Pris en charge	Pris en charge

Surface d’opérations actuelle

Sur les versions d’Engine prises en charge, les 16 opérations organisées sont disponibles depuis C++, Blueprint et Python :

Contenu	Opérations
Notes	List, Get, Search, Create, Update, Archive
Documents	List, Get, Search, Create, Update
Repères	List, Get, Create, Update metadata, Add comment

L’API n’expose volontairement pas la modification des dossiers de Notes ; le renommage, déplacement ou suppression de Documents ; la modification de position ou le remplacement complet d’ancre des Repères ; la manipulation de vue/surface des Repères ; la négociation de capacités d’automatisation ou les événements de changement ; ni les délais d’expiration des requêtes.

Identités

Note : GUID plus scope explicite Partagé ou Privé.
Repère : GUID plus scope explicite Partagé ou Privé.
Document : chemin Markdown normalisé relatif à ProjectDocuments.

La racine de présentation d’un Document, son chemin de présentation, le contexte /Game/... et son emplacement absolu dans le système de fichiers ne sont pas des identités alternatives.

Racines de présentation des Documents

Les requêtes de création sélectionnent une racine concrète. Le chemin fourni est relatif à cette racine visible :

Racine de présentation	Chemin fourni	Identité faisant autorité
Documents Locus	`Design/Combat.md`	`Design/Combat.md`
Content Browser	`Characters/Hero.md`	`Content/Characters/Hero.md`

N’ajoutez pas Content/ lorsque vous créez sous Content Browser. Locus applique ce mapping une seule fois.

Révisions

Les lectures et mutations réussies renvoient une révision opaque. Une mise à jour ou un archivage doit envoyer la valeur actuelle comme ExpectedRevision :

Get → Snapshot + Revision → Update with ExpectedRevision

Ne parsez ni ne fabriquez les révisions. Si le résultat est StaleRevision, relisez l’élément faisant autorité et reconsidérez la modification. Locus ne masque pas une écriture désynchronisée par une relecture ou une nouvelle tentative automatique.

Erreurs

Branchez-vous sur le code d’erreur typé et non sur le message lisible :

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown et OperationFailed. None représente l’absence d’erreur.

Une requête Unavailable réessayable peut être soumise lors d’un tick normal ultérieur de l’Editor. Ne bloquez pas le Game Thread en attendant.

Le succès et l’état du contrôle de source sont séparés

Une mutation locale réussie peut signaler une persistance locale Committed tandis que le contrôle de source est Pending, NotConfigured, Unknown, NotRequired. Il s’agit toujours d’une opération Locus réussie. L’état de l’opération est une information supplémentaire neutre vis-à-vis du fournisseur pour le workflow normal de contrôle de source.

Locus ne soumet pas les changements et n’administre pas les changelists.

Limite de confiance

C++, Blueprint et Python sont des outils locaux de l’Editor de confiance. Un appelant qui demande explicitement le scope Privé accède intentionnellement au contenu Privé local du projet actuel. Les paramètres MCP Autoriser les modifications et Autoriser les Notes et Repères Privés régissent la limite MCP distincte du client externe et ne régissent pas un appelant Developer API in-process.