Developer API

Developer API Locus позволяет локальным инструментам Unreal Editor работать с заметками, документами и метками Locus. Он предназначен для плагинов C++ редактора, Editor Utility Blueprint и Widget, скриптов Unreal Python и автоматизации конвейеров внутри редактора.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Операции разработчика используют те же проверки, ревизии, сохранение, защиту от конфликтов, правила путей документов, маршрутизацию системы контроля версий и время жизни приложения, что и интерфейс Locus. Используйте API вместо прямого редактирования файлов Locus.

Выберите API

Поверхность	Лучше всего подходит для	Начните здесь
Нативный C++	Плагины редактора, нативные инструменты, расширенные интеграции	C++ Developer API
Blueprint	Editor Utility Blueprint, Editor Utility Widget	Blueprint Developer API
Unreal Python	Скрипты редактора, проверки, пакетная и автономная автоматизация	Python Developer API

Интеграция MCP — отдельная поверхность внешнего клиента для AI и агентов. Инструменты C++, Blueprint и Python Developer API не используют MCP внутри процесса.

Совместимость с движком

Основные Locus, C++, Blueprint и MCP поддерживаются в Unreal Engine 5.4–5.8. Интерактивный и автономный Python Developer API требует Unreal Engine 5.6 или новее.

Поверхность	UE 5.4–5.5	UE 5.6–5.8
C++	Поддерживается	Поддерживается
Blueprint	Поддерживается	Поддерживается
Python	Не поддерживается	Поддерживается
MCP	Поддерживается	Поддерживается

Текущий набор операций

В поддерживаемых версиях Engine все 16 отобранных операций доступны из C++, Blueprint и Python:

Содержимое	Операции
Заметки	List, Get, Search, Create, Update, Archive
Документы	List, Get, Search, Create, Update
Метки	List, Get, Create, Update metadata, Add comment

API намеренно не предоставляет изменение папок заметок; переименование, перемещение или удаление документов; изменение положения метки или полную замену якоря; управление видом или поверхностью метки; согласование возможностей автоматизации или события изменений; а также сроки выполнения запросов.

Идентичность

Заметка: GUID и явно заданная область Общие или Личные.
Метка: GUID и явно заданная область Общие или Личные.
Документ: нормализованный путь Markdown относительно ProjectDocuments.

Корень представления документа, путь представления, контекст /Game/... и абсолютное расположение в файловой системе не являются альтернативными идентификаторами.

Корни представления документов

Запросы создания выбирают один конкретный корень. Переданный путь задаётся относительно этого видимого корня:

Корень представления	Переданный путь	Авторитетная идентичность
Документы Locus	`Design/Combat.md`	`Design/Combat.md`
Браузер контента	`Characters/Hero.md`	`Content/Characters/Hero.md`

При создании под Браузером контента не добавляйте Content/. Locus применяет это отображение один раз.

Ревизии

Чтение и успешные изменения возвращают непрозрачную ревизию. Обновление или архивирование должно передать текущее значение как ExpectedRevision:

Get → Snapshot + Revision → Update with ExpectedRevision

Не анализируйте и не создавайте ревизии. Если результат — StaleRevision, снова прочитайте авторитетный элемент и пересмотрите изменение. Locus не скрывает устаревшую запись автоматическим повторным чтением или повтором.

Ошибки

Обрабатывайте типизированный код ошибки, а не удобочитаемое сообщение:

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown и OperationFailed. None означает отсутствие ошибки.

Повторяемый запрос Unavailable можно отправить позднее, на следующем обычном тике редактора. Не блокируйте Game Thread во время ожидания.

Успех и состояние системы контроля версий разделены

Успешное локальное изменение может сообщить о локальном сохранении Committed, а о системе контроля версий — Pending, NotConfigured, Unknown или NotRequired. Это всё равно успешная операция Locus. Состояние операции — дополнительная информация, нейтральная к поставщику, для обычного процесса системы контроля версий пользователя.

Locus не отправляет изменения и не администрирует changelist.

Граница доверия

C++, Blueprint и Python — доверенные локальные инструменты редактора. Вызывающий, явно запросивший область Личные, намеренно получает доступ к локальному Личному содержимому текущего проекта. Настройки MCP Разрешить изменения и Разрешить личные заметки и метки управляют отдельной границей внешнего клиента MCP и не действуют на вызывающего Developer API внутри процесса.