Developer API

A Developer API do Locus permite que ferramentas locais do Unreal Editor trabalhem com Notas, Documentos e Pins do Locus. Ela se destina a plugins C++ de Editor, Editor Utility Blueprints e Widgets, scripts Python do Unreal e automação de pipeline hospedada no Editor.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

As operações Developer usam a mesma validação, revisões, persistência, proteção contra conflitos, regras de caminho de Documentos, roteamento do Controle de Código-Fonte e ciclo de vida da aplicação usados pela UI do Locus. Use a API em vez de editar diretamente os arquivos do Locus.

Escolher uma API

Superfície	Melhor para	Comece aqui
C++ nativo	Plugins do Editor, ferramentas nativas, integrações avançadas	C++ Developer API
Blueprint	Editor Utility Blueprints, Editor Utility Widgets	Blueprint Developer API
Unreal Python	Scripts do Editor, validação, automação em lote e não assistida	Python Developer API

Integração MCP é a superfície externa separada voltada a IA/agentes. As ferramentas Developer de C++, Blueprint e Python não usam MCP internamente.

Compatibilidade da Engine

Locus core, C++, Blueprint e MCP são compatíveis com Unreal Engine 5.4–5.8. A Python Developer API interativa e não assistida requer Unreal Engine 5.6 ou posterior.

Superfície	UE 5.4–5.5	UE 5.6–5.8
C++	Compatível	Compatível
Blueprint	Compatível	Compatível
Python	Não compatível	Compatível
MCP	Compatível	Compatível

Superfície de operações atual

Nas versões compatíveis da Engine, todas as 16 operações selecionadas estão disponíveis em C++, Blueprint e Python:

Conteúdo	Operações
Notas	List, Get, Search, Create, Update, Archive
Documentos	List, Get, Search, Create, Update
Pins	List, Get, Create, Update metadata, Add comment

A API intencionalmente não expõe alteração de pastas de Notas; renomeação, movimentação ou exclusão de Documentos; alteração de posição ou substituição completa de âncora de Pins; manipulação de visualização/superfície de Pins; negociação de capacidade de automação ou eventos de alteração; nem prazos de solicitação.

Identidades

Nota: GUID mais escopo explícito Compartilhado ou Privado.
Pin: GUID mais escopo explícito Compartilhado ou Privado.
Documento: caminho Markdown normalizado relativo a ProjectDocuments.

A raiz de apresentação, o caminho de apresentação, o contexto /Game/... e o local absoluto no sistema de arquivos de um Documento não são identidades alternativas.

Raízes de apresentação de Documentos

Solicitações de criação selecionam uma raiz concreta. O caminho fornecido é relativo a essa raiz visível:

Raiz de apresentação	Caminho fornecido	Identidade autoritativa
Documentos do Locus	`Design/Combat.md`	`Design/Combat.md`
Content Browser	`Characters/Hero.md`	`Content/Characters/Hero.md`

Não adicione Content/ ao criar em Content Browser. O Locus aplica esse mapeamento uma vez.

Revisões

Leituras e mutações bem-sucedidas retornam uma revisão opaca. Uma atualização ou arquivamento deve enviar o valor atual como ExpectedRevision:

Get → Snapshot + Revision → Update with ExpectedRevision

Não faça parsing nem fabrique revisões. Se o resultado for StaleRevision, leia novamente o item autoritativo e reconsidere a alteração. O Locus não esconde uma gravação desatualizada com releitura ou nova tentativa automática.

Erros

Use o código de erro tipado, não a mensagem legível:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown e OperationFailed. None representa ausência de erro.

Uma consulta Unavailable que pode ser repetida pode ser reenviada em um tick normal posterior do Editor. Não bloqueie o Game Thread enquanto aguarda.

Sucesso e status do Controle de Código-Fonte são separados

Uma mutação local bem-sucedida pode informar a persistência local como Committed enquanto o Controle de Código-Fonte está Pending, NotConfigured, Unknown ou NotRequired. Ainda é uma operação bem-sucedida do Locus. O status da operação é informação adicional neutra em relação ao provedor para o fluxo normal de Controle de Código-Fonte.

O Locus não envia alterações nem administra changelists.

Limite de confiança

C++, Blueprint e Python são ferramentas locais confiáveis do Editor. Um chamador que solicita explicitamente o escopo Privado acessa intencionalmente o conteúdo Privado local do projeto atual. As configurações MCP Permitir Alterações e Permitir Notas e Pins Privados regem o limite separado de cliente externo MCP e não regem um chamador da Developer API dentro do processo.