Раздел в процессе написания и будет часто обновляться.

Важно: стабильным и официально поддерживаемым считается только API из window.editorAPI.
Объект window.editor доступен для изучения и экспериментов, но его структура может меняться без предупреждения и не гарантируется совместимость между версиями.

JS-плагины позволяют расширять функциональность редактора без изменения его основного кода.
Плагин - это обычный JavaScript-файл со специальной шапкой (метаданными) и пользовательским кодом.

Установка плагина

1. Подготовьте JS-файл с плагином (см. раздел «Структура JS-плагина»).
2. Перетащите файл .js мышкой в окно редактора.
3. Редактор распознает шапку плагина и установит его.

Обновление/замена плагина

Плагины идентифицируются по полю @namespace.
Если установить плагин с тем же @namespace, существующий плагин будет заменён/обновлён.

Управление установленными плагинами

Открыть: Настройки редактора → Plugins

В этом разделе вы можете:
- просматривать список установленных плагинов;
- скачивать плагины, для просмотра кода или его изменения;
- удалять/обновлять плагины.

Типичный плагин состоит из двух частей:
1. Шапка с метаданными в формате комментариев UserScript.
2. Код плагина, как правило обёрнутый в IIFE (немедленно вызываемую функцию), чтобы не засорять глобальную область видимости.

Шапка плагина (Метаданные)

Пример:

// ==UserScript==
// @name         Test plugin
// @namespace    example-illystray
// @description  A test plugin that does nothing
// @logo_url     https://bdecdn.com/icon/icon-192x192.png
// @author       illystray
// ==/UserScript==

Обязательные поля:

@name - Человекочитаемое имя плагина. Отображается в интерфейсе.
@namespace - Уникальный идентификатор плагина. По нему определяется обновление/замена.

Необязательные поля:

@description - Краткое описание того, что делает плагин.
@logo_url - URL логотипа/иконки плагина. Изображение или SVG.
@author - Имя/ник автора.

Точка входа плагина

Рекомендуемый шаблон:

(() => {
  const log = (...args) => console.log('[Plugin name]', ...args);

  // Your code here
})();

- Использование IIFE помогает изолировать переменные плагина.
- Внутри функции вы можете использовать объекты window.editor и window.editorAPI.

window.editor (Внутренний нестабильный объект)

window.editorAPI (Официальный API для плагинов)

Запуск редактора

Срабатывает после того, как редактор полностью загрузился и собирается убрать экран запуска.

window.addEventListener('bde:started', (e) => {
  console.log('Started');
});

Смена режима редактора

Срабатывает при смене режима редактора (Editor/Animator/Sound) и возвращает текущий режим через переменную e.detail.

window.addEventListener('bde:change-mode', (e) => {
    let mode = e.detail;
    console.log(mode); // editor animator sound
});

Создание окна

Создаёт пользовательское окно внутри редактора, в котором плагин может отражать любой пользовательский HTML контент.
Удаляется после закрытия.

Сигнатура

editorAPI.createWindow(
    name = 'Window',
    name_id = 'default',
    icon = 'icon-layout-grid',
    width = 1100,
    height = 550,
    minWidth = 500,
    minHeight = 400,
    closeFunc = () => {}
);

Пример использования:

// ==UserScript==
// @name         Example window
// @namespace    example-window
// @description  Demonstration editorAPI.createWindow
// ==/UserScript==

(() => {
  const log = (...args) => console.log('[Example Window]', ...args);

  const win = editorAPI.createWindow(
    'My window',
    'my-window',
    'icon-anchor',
    800,
    500,
    400,
    300,
    () => log('The window is closed')
  );

  win.container.innerHTML = `Hello World!`;

})();

Создание модального окна

Создает модальное окно внутри окна сцены, в котором плагин может отражать любой пользовательский HTML контент.
Не удаляется после закрытия(скрытия).

Сигнатура

createModalWindow(name = 'Window');

Пример использования:

// ==UserScript==
// @name         Example modal window
// @namespace    example-modal-window
// @description  Demonstration editorAPI.createModalWindow
// ==/UserScript==

(() => {
    const log = (...args) => console.log('[Example Window]', ...args);

    const win = editorAPI.createModalWindow('My window');

    win.container.innerHTML = 'Hello World!';

    win.showModal();

    // win.hideModal(); - To hide the window

})();

Вставка проекта

Вставляет JSON-проект в формате BDEngine в текущий открытый проект. Как зашифрованный в base64+gzip, так и чистый JSON.

Сигнатура

async mergeContent(content, decode = false);