Compatibility and updates

Record the tested build

Test your plugin in BDEngine Release. If it uses a feature available only in Beta, tell users explicitly; availability in Beta does not prove compatibility with Release. This section of the manual targets the main version.

In your test notes, record:

• The plugin version and the exact .js file tested.
• The BDEngine version and Release channel.
• The environment: the web editor and browser, or BDEngine App and its version.
• The required API methods and the editor mode in which the tool is available.
• Project requirements, such as a selected group or an open HeadPaint panel.

The Minecraft version chosen for export is not the BDEngine version. For diagnostics, you can inspect the editor build number in window.editorVersion in the console. This is a global diagnostic variable on the page, not an editorAPI method.

Check the specific feature

Check required functions after the editor is ready and before adding a tool that depends on them. This snippet belongs inside your initialization function:

const api = window.editorAPI;
const required = ['getSelectedObjects', 'addButtonDockMenu'];
const missing = required.filter(name => typeof api?.[name] !== 'function');

if (missing.length) {
  console.warn('[my-useful-plugin] Missing editorAPI methods:', missing);
  return;
}

// You can register the tool here.

The existence of window.editor does not replace this check. Conversely, a missing GUI-dependent API before bde:started may simply mean the editor is still loading. For example, editorAPI.headPaint appears only when the interface is prepared.

Also check the action’s input requirements. An empty selection, an unsupported object type, or a closed tool should produce a clear message before any partial project changes are made.

Risks of internal dependencies

You are allowed to use editor. However, internal subsystems and global classes can change independently of stable editorAPI methods. Keep a short list of those dependencies: specific editor fields, scene object methods, classes such as Selectable, and the Three.js details your plugin uses.

Keep access to them in small functions, check the expected data shape, and repeat the relevant scenarios after updating the editor. If a required contract changes, temporarily disable the affected action with an explanation instead of attempting an incompatible call.

The boundary is described in Public API and internal objects. An .editor property inside editorAPI does not make subsequent access to internals stable.

Updates and replacement

Local installations are identified by @namespace. Reinstalling a file with the same namespace replaces its saved code and metadata. A different namespace creates a separate entry, even if the name stays the same. Catalog installations use the listing slug as the identifier and receive metadata from the catalog.

Installing, replacing, or removing a plugin does not unload code that has already run on the open page. My plugins displays a message about the changes and a Restart button. After restarting, the editor loads the current list and new code.

To verify an update:

1. Install the previous version, restart BDEngine, and complete its main workflow.
2. Save the project, then install the new file with the same namespace or select the new version in the catalog.
3. Restart the editor, check the version number, and make sure no second copy of the plugin is installed.
4. Repeat the actions on both a new and an existing project, including reading previously saved plugin settings if it uses them.
5. Remove the plugin through My plugins, restart BDEngine, and check that its interface is gone.

User instructions: installing and updating plugins. Removing a plugin should not be used to undo changes already saved to a model.

Test scenarios

This is a list for testing your tool, not an automated test system built into BDEngine. Choose the scenarios that apply to its features.

Scenario	What to check
Clean installation	The code runs after restarting, and the button appears once.
Repeated action	No extra windows, timers, or handlers are created.
Closing and reopening	A regular window is recreated; resources from the closed session are released.
Invalid input	Empty selections, other object types, and invalid parameters are handled before changing the scene.
Asynchronous operation	Repeated clicks do not start competing jobs; an error is shown and the action can be retried.
Changing projects or modes	No stale references to objects from the previous scene are used.
History	Undo/Redo works for operations the plugin claims are undoable.
Updating	New code replaces the previous version after restarting; old settings are read correctly.
Removing	The plugin no longer runs after restarting, and the project remains usable.
Different environments	Window size, input, file selection, and external requests work in the browsers and app versions you support.

If you claim phone or tablet support, test it separately: API availability does not guarantee that a custom interface is usable on a small screen.