This section is currently being written and will be updated frequently.

Important: only the API from window.editorAPI is considered stable and officially supported.
The window.editor object is available for exploration and experimentation, but its structure may change without notice and compatibility between versions is not guaranteed.

JS plugins allow you to extend the editor’s functionality without modifying its core code.
A plugin is a regular JavaScript file with a special header (metadata) and custom code.

Plugin Installation

1. Prepare a JS file with the plugin (see the “Structure of a JS Plugin” section).
2. Drag and drop the .js file into the editor window.
3. The editor will recognize the plugin header and install it.

Updating/Replacing a Plugin

Plugins are identified by the @namespace field.
If you install a plugin with the same @namespace, the existing plugin will be replaced/updated.

Managing Installed Plugins

Open: Editor Settings → Plugins

In this section you can:
- view the list of installed plugins;
- download plugins to review or modify their code;
- delete/update plugins.

A typical plugin consists of two parts:
1. A metadata header in the UserScript comment format.
2. Plugin code, usually wrapped in an IIFE (an immediately invoked function expression) to avoid polluting the global scope.

Plugin Header (Metadata)

Example:

// ==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==

Required fields:

@name - A human-readable name of the plugin. Displayed in the interface.
@namespace - A unique identifier of the plugin. Used to determine updates/replacements.

Optional fields:

@description - A brief description of what the plugin does.
@logo_url - The URL of the plugin’s logo/icon. An image or SVG.
@author - The name/nickname of the author.

Plugin Entry Point

Recommended template:

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

  // Your code here
})();

Recommended template:

window.editor (Internal Unstable Object)

window.editorAPI (Official Plugin API)

Launching the editor

Triggers after the editor has fully loaded and is about to remove the splash screen.

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

Editor mode change

Triggers when the editor mode changes (Editor/Animator/Sound) and returns the current mode via the variable e.detail.

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

Creating a window

Creates a custom window inside the editor where the plugin can display any custom HTML content. Deleted after closing.

Signature

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

Example of use:

// ==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!`;

})();

Creating a modal window

Creates a modal window inside the scene window, in which the plugin can display any user-defined HTML content.
Not deleted after closing (hiding).

Signature

createModalWindow(name = 'Window');

Example of use:

// ==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

})();

Project insertion

Inserts a JSON project in BDEngine format into the currently open project. Both base64+gzip encrypted and plain JSON.

Signature

async mergeContent(content, decode = false);