Публичный API и внутренние объекты

window.editorAPI

window.editorAPI - стабильный, официально поддерживаемый интерфейс для плагинов. Он объединяет операции с интерфейсом, объектами, проектами, переводами, HeadPaint, окружением и отдельными параметрами анимации.

const api = window.editorAPI;
const selected = api.getSelectedObjects();
console.log('Selected objects:', selected.length);

Этот фрагмент выполняйте после готовности редактора. Существование editorAPI ещё не означает готовность GUI или сцены. Для установленного плагина точкой начала работы с ними служит событие bde:started.

Стабильность точки входа не превращает возвращаемые объекты в независимые копии. Например, getSelectedObjects() возвращает объекты самой сцены. Обращение к их внутренним полям требует знания модели объектов и может иметь отдельные ограничения.

window.editor

window.editor - экземпляр редактора с доступом к его внутренним подсистемам. Его можно изучать и использовать в своих плагинах, в том числе когда нужная возможность ещё не представлена в публичном API.

// Внутренняя зависимость: currentMode не является методом editorAPI.
console.log(window.editor.currentMode);

Методы, поля и связи внутри editor могут меняться без сохранения совместимости. Плагин, использующий их, нужно проверять при обновлениях BDEngine. Укажите такую зависимость в описании плагина и держите обращения к внутренней подсистеме в одном месте кода, чтобы её было проще адаптировать.

Поле editorAPI.editor тоже ведёт к внутреннему экземпляру редактора. Переход через него не меняет уровень гарантий: editorAPI.editor.gui остаётся внутренней зависимостью.

THREE, GLTFExporter, Selectable и gT

Редактор предоставляет несколько глобальных зависимостей:

Доступ	Назначение
window.THREE	Three.js из сборки редактора.
window.THREE.GLTFExporter	Экспортёр glTF, добавленный к THREE; отдельного глобального GLTFExporter загрузчик не создаёт.
window.Selectable	Базовый класс собственных объектов редактора.
window.gT	Получение переведённой строки через локаль редактора.
window.libs.JSZip	JSZip из сборки редактора.

Их наличие удобно для расширений, но не означает, что версии библиотек и вся внутренняя модель объектов зафиксированы навсегда. Особенно это важно для наследования от Selectable и работы с ресурсами Three.js. Контракты и ограничения разобраны в статье Собственные объекты и глобальные зависимости.

Публичное решение или эксперимент

Сначала найдите операцию в справочнике editorAPI. Например, встроенный дисплей создаётся через editorAPI.add(), а кнопка меню экспорта регистрируется через editorAPI.addButtonExportMenu().

Если готового метода нет, можно использовать editor или собственный объект. Сверяйте вызов с реализацией: нужны не только название и параметры, но и готовность подсистемы, возвращаемое значение, обновление интерфейса, история действий и освобождение ресурсов. Не заменяйте неизвестный вызов похожим названием наугад.

Проверка наличия возможностей

Перед регистрацией инструмента проверяйте конкретный метод, от которого он зависит:

const api = window.editorAPI;
if (typeof api?.addButtonExportMenu !== 'function') {
  console.warn('[my-useful-plugin] This BDEngine version lacks export menu actions.');
  // Не регистрируйте недоступный инструмент.
}

Такую проверку нужно делать в нужный момент жизненного цикла. Например, editorAPI.headPaint создаётся при инициализации GUI: его отсутствие до bde:started не доказывает несовместимость версии.

Номер версии редактора помогает воспроизвести проблему, а проверка метода позволяет понятно обработать недоступную возможность. Оба подхода дополняют друг друга. Полный порядок проверки: Совместимость и обновления.