Home

BlockDesigner user guide

BlockDesigner is a Windows editor for Minecraft builds. These pages show how to use it.

Start here

• Getting started: install, first launch, settings and updates.
• Building like in Minecraft: movement, hotbar, place, break and pick, shapes, symmetry.
• Controls and keybinds: every default key.

Editing

• Brushes, selections and BlockEdit
• Layers
• Reference images

Files and look

• Import and export: Litematica, WorldEdit, Create and worldgen data packs.
• Camera, look and feel

Plugins and help

• Using plugins
• User FAQ

---

BlockDesigner plugin developer wiki

BlockDesigner is a Windows editor for Minecraft builds. A plugin is a .jar that BlockDesigner loads at startup and that adds features to it: schematic formats, exporters and importers, menu actions, BlockEdit commands, tools, transforms with a live preview, panels, objects in the scene and settings. This wiki is for people writing plugins.

It sits beside the existing plugin documents in the repository and links to them rather than repeating them:

• PLUGINS.md: the guide, with a worked example for every extension point.
• docs/plugin-api-reference.md: every type in the API with its members.
• docs/plugin-api-v2.md: the design record for API 2.

Where those and this wiki disagree, the code wins: plugin-api/src/main/java/io/blockdesigner/plugin (the API) and app/src/main/java/io/blockdesigner/app/plugins (the loader and updater).

Pages

Start here

• What plugins can do: the extension points and where each shows up in the app.
• API levels: API 1 to 5, what each added and the first BlockDesigner version with it.
• Setting up a plugin project: the template, JDK 26, the vendored API jars, compileOnly.
• The manifest: blockdesigner-plugin.json, field by field.

How it works

• How plugins are loaded: the plugins folder, class loading, on and off, errors, logs and the Console.
• Plugin lifecycle and context: enable, disable, PluginContext, threads.
• Registering features: formats, exporters, importers, actions, tools, transforms, panels, scene objects, settings.
• BlockEdit commands: /commands, and why the Java class is still called WorldEdit.
• Storing data and settings: the data folder, settings in the plugin's tab, remembered options, data saved in the project.
• Project file format: the .bdproj project file, the format shared with the game.

Shipping

• Automatic updates: exactly what a release needs for BlockDesigner to update the plugin by itself.
• Releasing on GitHub: version, notes, tag, release and jar.
• Testing plugins: unit tests against the API jars, and loading through PluginManager.
• Troubleshooting and FAQ

Official plugins

Each lives in its own repository and is a good reference for the features it uses:

Plugin	API	Shows how to
BlockCompanion Plugin (formerly Resource Tracker)	5	a panel, a menu action, scene events, data kept per project in the data folder
Palette Tools	5	a tool on the selection, transforms, an exporter, an importer, a panel
Terrain Generator	3	a panel, a command, a tool, a scene object that holds its state in the project, a two-module build
Pixel Art Generator	5	a large panel, a placing tool, an importer

Reference Planes, once a plugin here too, is built into BlockDesigner now as its reference images; its code (app/.../refplanes) still uses the scene object interfaces, so it remains a scene object example. BlockDesigner no longer loads a plugin with the id reference-planes.

The two example plugins in the main repository, examples/hello-plugin (API 1) and examples/palette-tools (API 2), are built inside BlockDesigner's own build because its tests load them. Start a real plugin from the template on Setting up a plugin project instead.