Структура файла и метаданные

UserScript-шапка и код

Файл состоит из комментариев с метаданными и исполняемого JavaScript. Сохраните его как .js в UTF-8. Плагин загружается как обычный скрипт, а не как JavaScript-модуль: верхнеуровневые import и export в таком файле не подходят.

// ==UserScript==
// @name         My useful plugin
// @namespace    my-useful-plugin
// @version      1.0.0
// @description  Adds a useful tool to BDEngine.
// @author       Your name
// @logo_url     https://editor.bdecdn.com/icon/icon-192x192.png
// ==/UserScript==

(() => {
  console.log('[my-useful-plugin] Script loaded');
})();

Маркеры ==UserScript== помогают читать файл. Сам загрузчик ищет строки с тегами в комментариях; это не поддержка всех возможностей менеджеров UserScript. Например, @require, @grant или @match не подключают зависимости и не настраивают права плагина в BDEngine.

Пишите каждый тег отдельной строкой без отступа перед //. Загрузчик также умеет читать теги из блочного комментария. Не дублируйте один тег в нескольких местах: оставьте одну понятную шапку в начале файла.

Обязательные name и namespace

Поле	Назначение
@name	Человекочитаемое имя для списка установленных плагинов.
@namespace	Постоянный идентификатор установленного плагина. По нему хранится код и определяется замена.

При локальной установке пустое или отсутствующее поле не позволит установить файл. Имя файла не заменяет @namespace: tool.js и new-tool.js с одинаковым namespace считаются одним плагином. При установке через «Мои плагины» сохранённая запись с этим идентификатором заменяется. Изменения вступают в силу после перезапуска редактора.

Выберите namespace, который не совпадает с чужим плагином, и сохраняйте его при обновлениях. Для будущей публикации удобно сразу использовать планируемый slug каталога, например my-useful-plugin. Это рекомендация для согласованности, а не дополнительная проверка формата namespace в локальном загрузчике.

description, logo_url, author, version

Поле	Назначение	Если не указано
@description	Краткое описание в менеджере плагинов.	-
@logo_url	Адрес изображения иконки.	Стандартная иконка BDEngine.
@author	Имя или ник автора.	Author
@version	Версия, отображаемая у установленного плагина.	1.0.0

Для иконки используется именно @logo_url. Поле @icon_url загрузчик не использует. Версию в шапке следует обновлять вместе с кодом. Локальный загрузчик читает её как строку; требование трёх числовых частей относится к форме публикации в каталоге.

Точка входа и глобальная область

Код файла выполняется при запуске редактора, до готовности его GUI. На этом этапе уже создан window.editorAPI, но окно или кнопку Dock нужно добавлять после bde:started:

(() => {
  const log = (...args) => console.log('[my-useful-plugin]', ...args);

  window.addEventListener('bde:started', () => {
    log('Editor UI is ready');
    // Здесь можно создавать интерфейс через window.editorAPI.
  }, { once: true });
})();

IIFE создаёт собственную область для переменных и функций. Это удобный способ избежать конфликтов с другими плагинами, а не обязательный формат запуска. Никакая функция с именем init или unload автоматически загрузчиком не вызывается.

Обычная установка сохраняет файл и предлагает перезапуск. При ручном выполнении кода в уже открытом редакторе событие bde:started могло пройти: такая подписка не вызовется задним числом. Для отладки запускайте свою функцию инициализации явно после готовности редактора. Подробнее: события и жизненный цикл.

Обновления и публикация

Namespace плагина, slug страницы каталога, ID проекта и теги Minecraft имеют разные назначения. При локальной установке источником метаданных служит JS-шапка. При установке из каталога редактор получает метаданные от каталога и использует его slug как namespace, а также имя, описание, автора, версию и иконку из ответа.

Если локальная копия имеет другой namespace, установка из каталога создаст отдельную запись. Обе копии могут запуститься после перезапуска. Перед проверкой опубликованной версии удалите старую тестовую копию либо заранее согласуйте namespace со slug.

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