Developer API

La Developer API de Locus permite que las herramientas locales de Unreal Editor trabajen con Notas, Documentos y Pines de Locus. Está pensada para plugins C++ del Editor, Editor Utility Blueprints y Widgets, scripts de Unreal Python y automatización de pipelines alojada en el Editor.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Las operaciones Developer usan la misma validación, revisiones, persistencia, protección contra conflictos, reglas de rutas de Documentos, enrutamiento del control de código fuente y ciclo de vida de la aplicación que la interfaz de Locus. Usa la API en lugar de editar directamente los archivos de Locus.

Elegir una API

Superficie	Mejor para	Empieza aquí
C++ nativo	Plugins del Editor, herramientas nativas, integraciones avanzadas	C++ Developer API
Blueprint	Editor Utility Blueprints, Editor Utility Widgets	Blueprint Developer API
Unreal Python	Scripts del Editor, validación, automatización por lotes y desatendida	Python Developer API

Integración de MCP es la superficie externa separada orientada a IA/agentes. Las herramientas Developer de C++, Blueprint y Python no usan MCP internamente.

Compatibilidad de Engine

Locus principal, C++, Blueprint y MCP son compatibles con Unreal Engine 5.4–5.8. La Developer API de Python interactiva y desatendida requiere Unreal Engine 5.6 o posterior.

Superficie	UE 5.4–5.5	UE 5.6–5.8
C++	Compatible	Compatible
Blueprint	Compatible	Compatible
Python	No compatible	Compatible
MCP	Compatible	Compatible

Superficie de operaciones actual

En las versiones compatibles de Engine, las 16 operaciones seleccionadas están disponibles desde C++, Blueprint y Python:

Contenido	Operaciones
Notas	List, Get, Search, Create, Update, Archive
Documentos	List, Get, Search, Create, Update
Pines	List, Get, Create, Update metadata, Add comment

La API no expone intencionadamente la modificación de carpetas de Notas; cambiar nombre, mover o eliminar Documentos; cambiar la posición o sustituir por completo el anclaje de Pines; manipular vistas/superficies de Pines; negociar capacidades de automatización o eventos de cambio; ni plazos de solicitudes.

Identidades

Nota: GUID más ámbito explícito Compartido o Privado.
Pin: GUID más ámbito explícito Compartido o Privado.
Documento: ruta Markdown normalizada relativa a ProjectDocuments.

La raíz de presentación, la ruta de presentación, el contexto /Game/... y la ubicación absoluta en el sistema de archivos de un Documento no son identidades alternativas.

Raíces de presentación de Documentos

Las solicitudes de creación seleccionan una raíz concreta. La ruta proporcionada es relativa a esa raíz visible:

Raíz de presentación	Ruta proporcionada	Identidad autoritativa
Documentos de Locus	`Design/Combat.md`	`Design/Combat.md`
Content Browser	`Characters/Hero.md`	`Content/Characters/Hero.md`

No antepongas Content/ al crear bajo Content Browser. Locus aplica esa asignación una vez.

Revisiones

Las lecturas y mutaciones correctas devuelven una revisión opaca. Una actualización o archivado debe enviar el valor actual como ExpectedRevision:

Get → Snapshot + Revision → Update with ExpectedRevision

No analices ni fabriques revisiones. Si el resultado es StaleRevision, vuelve a leer el elemento autoritativo y reconsidera el cambio. Locus no oculta una escritura desactualizada mediante una relectura o reintento automáticos.

Errores

Usa el código de error tipado, no el mensaje legible:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown y OperationFailed. None representa ningún error.

Una consulta Unavailable reintentable se puede volver a enviar en un tick normal posterior del Editor. No bloquees el Game Thread mientras esperas.

El éxito y el estado del control de código fuente son independientes

Una mutación local correcta puede informar de persistencia local Committed mientras el control de código fuente está en Pending, NotConfigured, Unknown o NotRequired. Sigue siendo una operación correcta de Locus. El estado de la operación es información adicional neutral para el proveedor para el flujo normal de control de código fuente.

Locus no envía cambios ni administra changelists.

Límite de confianza

C++, Blueprint y Python son herramientas locales de confianza del Editor. Un llamador que solicita explícitamente el ámbito Privado accede intencionadamente al contenido Privado local del proyecto actual. Los ajustes MCP Permitir cambios y Permitir notas y pines privados rigen el límite separado de clientes externos MCP y no el de un llamador de Developer API dentro del proceso.