Skip to content

Enter a tool name, task, or method name.

Open BDE
On this page

First plugin: a button and a window

Build your first BDEngine plugin with a complete JS file, a Dock menu button, a custom window, and installation and reopening checks.

A complete minimal example

We will add My first plugin to the Dock menu. Clicking it opens a window with a message. Clicking it again focuses the existing window; after closing it, you can create a new one. The example does not change the scene and needs no project, npm packages, or build tool.

You need BDEngine, a text editor, and a basic understanding of JavaScript functions. You can download the complete first-plugin.js or save the code below as a UTF-8 file with that name.

The file starts with @name and @namespace. The first field is shown to the user; the second identifies the installed plugin. For your own plugin, replace bde-docs-first-plugin with your identifier and update the window ID prefix.

We will also specify a version, author, and description. See required metadata. The IIFE (() => { ... })() keeps the example’s variables in their own scope.

Add a button and create a window

The complete installable file:

first-plugin.js
// ==UserScript==
// @name         BDE Docs: First plugin
// @namespace    bde-docs-first-plugin
// @version      1.0.0
// @description  Adds a Dock menu button that opens one reusable window.
// @author       BDEngine
// ==/UserScript==


(() => {
  let win = null;


  function start() {
    const api = window.editorAPI;
    if (typeof api?.addButtonDockMenu !== 'function' ||
        typeof api?.createWindow !== 'function') {
      console.warn('[bde-docs-first-plugin] Required UI methods are unavailable.');
      return;
    }


    function openWindow() {
      if (win) {
        win.focus();
        return;
      }


      win = api.createWindow(
        'My first plugin',
        'bde-docs-first-plugin-window',
        'icon-smile',
        480, 300, 300, 200,
        () => { win = null; }
      );


      const message = document.createElement('p');
      message.textContent = 'Hello! This window was created by your plugin.';
      win.container.appendChild(message);
    }


    api.addButtonDockMenu('icon-smile', 'My first plugin', openWindow);
    console.log('[bde-docs-first-plugin] Ready. Open the Dock menu.');
  }


  window.addEventListener('bde:started', start, { once: true });
})();

start() runs when the interface is ready. It adds the button once per editor startup. addButtonDockMenu() creates an item in the Dock’s dropdown menu, rather than a separate button on the main bar.

The window is created only when the button is clicked. The arguments passed to

createWindow()

are the title, ID, icon, width and height, minimum dimensions, and the close-button callback. Content is added to win.container using standard DOM methods.

This file is intended for normal installation followed by a restart. If you paste it into the console of an already running editor, bde:started will not fire again and the button will not appear.

Install it and see the result

  1. Save your current project before restarting.
  2. Open BDEngine settings and select My plugins.
  3. Click the .js file selection area and choose first-plugin.js. You can also drag the file into the editor.
  4. Check that BDE Docs: First plugin appears in the installed plugins list.
  5. Click Restart in the message about modified plugins.
  6. After the editor loads, open the Dock menu using the horizontal-lines button and select My first plugin.

The editor first saves the file in local storage. Installing it does not execute the new version over the currently running one. After changing the code, install the .js file with the same namespace again and restart BDEngine.

User guide: installing and managing plugins.

Open, close, and reopen

Check these three actions:

  • Select the menu item again while the window is open. It should receive focus without creating a second window.
  • Minimize the window using the minus button, then select the item again. focus() restores a minimized window.
  • Close the window using its close button, then select the item again. The close-button callback clears win, and a new window is created.

A regular window’s DOM is removed after closing. You cannot fill the container of a closed instance again. This example creates a new instance instead. To remove the plugin itself, open My plugins, click Remove, and restart the editor.

If the menu item is missing, check the saved file and make sure you restarted. In the developer console, look for a message prefixed with [bde-docs-first-plugin] or an error from the plugin file. See Debugging and cleanup.

Choose your next improvement