A Windows editor for Minecraft builds: design in a Minecraft-style 3D view, arrange schematics as layers,
and export Litematica, WorldEdit and Create / structure files or a worldgen data pack.
BlockDesigner is a desktop app for planning Minecraft structures outside the game. You build block by block with the controls you know from creative mode (flight, a hotbar, place / break / pick block), use shapes, symmetry, sculpting brushes and BlockEdit commands, and keep every imported or new schematic as its own layer. The textures and models come from your own Minecraft install (modded instances too), and nothing from Minecraft is shipped with the app.
Contents: Download · Features · Controls · Plugins · Building from source · Project layout
Get the latest version from the releases page. There are two downloads:
| File | Use it if… |
|---|---|
The installer (.msi) |
You want a normal install. It installs to C:\Program Files\BlockDesigner, adds Start menu and desktop shortcuts, and makes .bdproj projects open in BlockDesigner. Installing a newer version upgrades in place. |
The portable zip (BlockDesigner-<version>-portable.zip) |
You don't want to install anything. Unzip it anywhere and run BlockDesigner.exe. Settings are kept in a data folder next to the exe. |
Both include their own Java runtime, so there is nothing else to install.
- Settings (theme, keybinds, recent files, plugins) live in
%APPDATA%\BlockDesignerfor the installed version, never in the install folder, so they survive updates and reinstalls. Each new version copies them into%APPDATA%\BlockDesigner\backupsthe first time it starts. Settings › General › Your settings can save a backup to a file, load one (for example on another PC) or reset everything to the defaults. - Updates: when it opens, BlockDesigner checks GitHub for a newer release and shows its notes. Install and restart downloads it, checks it against the release's checksum and installs it. You can skip a version, or turn the check off under Settings › General › Updates.
- Windows Smart App Control / SmartScreen: releases aren't code-signed yet. On PCs with Smart App Control switched on, Windows may block BlockDesigner from starting, even after a successful install or update, and SmartScreen may warn about it.
- First launch: pick the Minecraft version whose textures and models to use. You can also pick a modded instance (Prism, CurseForge, Modrinth or the official launcher) so modded blocks, such as Create's, render too.
- Creative flight, a hotbar, and break / place / pick-block controls with Minecraft's repeat timing.
- Placement works as in the game: stairs and slabs go top or bottom, logs follow the clicked face, torches and signs go on walls, and doors and beds place both halves. Fences, walls, panes, redstone dust and rails connect to their neighbours.
- Palette laid out like the creative menu (Building, Colored, Natural, Functional, Redstone, plus All and Recently used), with Minecraft's own block names from the game's and each mod's language files. Hover a block and press 1–9 to put it in that hotbar slot.
- Replace (swap the aimed block, keeping its facing) and Shuffle (random blocks from the hotbar) modes.
- Easy Build shapes (hold Alt in Build mode for the Easy Build wheel): line, wall, floor, box, room, walls, circle, ring, cylinder, sphere, dome and pyramid, drawn out with a preview and placed as one undo step. They grow from the face you start on.
- Symmetry (M): mirror across X, Y and / or Z, or radial copies around a vertical axis. Stairs, doors, slabs and logs turn to match in every copy.
- Mobs as stand-ins: place pigs, villagers, iron golems, armour stands, paintings and more, drawn with Minecraft's models where available. They are saved with the project and exported with the schematic.
- Sculpting brushes: draw, erase, smooth, erode, fill, pinch, raise, lower, flatten and slope, with size, strength and shape settings, plus an Eraser. Each stroke is one undo step.
- Select blocks by clicking, marquee-dragging or setting pos1 / pos2. Select or replace by type (Alt+T) finds blocks by kind and swaps them, keeping facing and other shared properties.
- Move and Rotate gizmos (Blender-style) move or turn whole layers or just the selected blocks.
- BlockEdit command line (T or /), like Minecraft's chat:
/set,/replace,/walls,/copy,/paste,/stack,/smooth,/sphereand more, with Tab completion and history. See the command table under Controls › Select mode and BlockEdit.
- Every schematic, imported or new, is a layer: show / hide, lock, ghost, rename, reorder, duplicate and merge.
- Move layers with the wheel, the arrow keys or the Move gizmo, and turn them in quarter turns.
- The slice view steps through Y levels.
Put pictures in the scene and build from them, like Blender's reference images. This was the Reference Planes plugin; it is built in now.
- Add one with the picture button at the top of the Layers panel, by dropping a PNG, JPEG, GIF or BMP on the window, or with Import. Add a reference image can be given a key in Settings › Keybinds. It goes at the point the camera orbits around, facing you. Added in an orthographic axis view (numpad 1 / 3 / 7, or a view cube face), it faces that view straight on and shows only there.
- How new pictures start out is on the Reference images page of Settings: height in blocks, opacity, how blocks cover them, and whether one added in an axis view shows only in that view.
- They are listed above the layers with a REFERENCE tag: click to select, double-click to rename, eye and lock to hide or lock. Select one and use G / R / S to move, turn and scale it (Ctrl snaps); Delete removes it. Every change can be undone.
- Right-click one (in the view or in Layers) for Properties… (position, rotation, scale, UV offset and scale, opacity, with resets), Opacity, Show in (all views, orthographic views, or one of the six), Draw (behind blocks, in the scene, in front of blocks), flips, aligning it to the view and Replace picture….
- Pictures are saved inside the
.bdproj, at full size, so a project opens with its references on another PC. Projects made with the Reference Planes plugin open with their pictures.
- Import and export Create / structure-block
.nbt, Litematica.litematic(multi-region) and WorldEdit.schem(Sponge v2 / v3). Directional blocks stay correct through rotation and mirroring. - Export window (Ctrl+E): a card per format showing what will be exported (layers, blocks, size, block types). It saves straight into a detected instance's
schematicsorconfig/worldedit/schematicsfolder and remembers your choices. - Worldgen data packs (Ctrl+Shift+E): make a build generate in new chunks, as a single structure (with random variants) or village-style with jigsaw pieces: mark layers as the centre, streets or buildings, and BlockDesigner adds the jigsaw blocks and can generate streets. Built-in and saved presets set placement, biomes and blending, and containers can get loot tables. Save the pack as a zip or install it straight into a world, then test with
/place structure <namespace>:<name>.
- Orbit and pan like Blender, a view cube, perspective or orthographic, numpad views, and creative flight with momentum.
- Themes: Claude, Blue, Green, Red, Orange and Zen, each dark or light or following Windows. A theme colours every window and the 3D view's sky and grid.
- Keybinds: every keyboard shortcut can be changed in Settings › Keybinds (Ctrl+,), with a second key per action and clash warnings. Key hints in the corner show the keys for what you're doing (Shift+F1).
- Place, break and paint sounds, break particles and quiet UI sounds, each of which can be turned off in the viewport settings (N).
- Undo and redo cover every action.
These are the default keys. Every keyboard shortcut can be rebound in Settings › Keybinds, and the app always shows your current keys: press F1 (or Alt+K), or click the ⌘ button in the viewport, for the list. Single-letter keys don't fire while you're typing in a text box, and while flying W A S D, Space, Shift and Ctrl belong to flight.
Modes and tools
| Key | Action |
|---|---|
| 1 | View mode: look around only |
| 2 | Select mode |
| 3 | Build mode on / off (also while flying) |
| G / R / S | Move / Rotate / Scale tool (gizmos for the selected layers, or the selected blocks) |
| 4 / 5 | Brush / Eraser |
| Esc | Leave Build mode (in Build mode the number keys pick hotbar slots) |
| Esc | Cancel a drag or placement, clear the selection, stop flying, then back to Select |
Camera
| Key | Action |
|---|---|
| Middle-drag | Orbit around the point under the mouse |
| Shift+middle-drag | Pan |
| Alt+middle-drag | Swing to the next orthographic view in that direction |
| Wheel | Zoom |
| F | Focus: frame the selected blocks, or else the active layer |
| Home | Frame everything |
| C | Creative flight on / off |
| P / O | Perspective / orthographic |
| Numpad 1 / 3 / 7 | Front / right / top (Ctrl: back / left / bottom) |
| Numpad 9 / 5 | Opposite side / toggle perspective and orthographic |
| Numpad 2 4 6 8 / . | Orbit 15° / frame the active layer |
| View cube | Click a face for that view (again for the opposite side), drag to orbit |
Flying
| Key | Action |
|---|---|
| W A S D | Move (W and S follow where you look) |
| Space / Shift | Up / down |
| Ctrl | Sprint |
| Wheel | Next / previous hotbar slot |
| C / Esc | Stop flying |
Build mode and hotbar
| Key | Action |
|---|---|
| Left-click | Break (hold to repeat) |
| Right-click | Place (hold to repeat), oriented like Minecraft |
| Middle-click | Pick the block into the hotbar |
| Hold Alt | Easy Build wheel: point at a shape and let go, then right-drag to draw it |
| M / Shift+M | Symmetry settings / put the symmetry centre on the aimed block |
| Shift+X | Replace mode: right-click swaps the aimed block and keeps its facing |
| Shift+Z | Shuffle mode: place random blocks from the hotbar |
| 1 – 9 (Build mode) | Hold a hotbar slot |
| 1 – 9 over a palette block | Put that block in that hotbar slot, like Minecraft's creative inventory |
| Delete | Empty the held hotbar slot |
| Shift+C | Clear the hotbar |
Brush and Eraser
| Key | Action |
|---|---|
| Drag | Paint with the brush mode (Eraser: remove blocks) |
| Right-drag | Smooth |
| Alt+1 … Alt+0 | Draw · Erase · Smooth · Erode · Fill · Pinch · Raise · Lower · Flatten · Slope |
| Shift+right-click | Brush settings: mode, size, strength, shape |
| [ / ] (or - / =) | Smaller / bigger brush (1–16) |
| , / . | Weaker / stronger brush (1–5) |
| Shift+drag / Ctrl+drag | Smooth / inverse mode (not while flying) |
Select mode and BlockEdit
| Key | Action |
|---|---|
| Left-click / right-click | Set pos1 / pos2; the box's blocks become the selection |
| Shift+click / Ctrl+click | Add a block to / remove it from the selection |
| Drag | Marquee select; pos1 and pos2 are set to the corners of the box around the selection |
| Shift+right-click or Menu key | Context menu |
| Alt+T | Select or replace by type |
| Ctrl+A / Alt+A | Select every block of the active layer / deselect |
| Ctrl+C / Ctrl+X | Copy / cut the selection (shares the clipboard with /copy and /paste) |
| Ctrl+V | Paste: the copy follows the mouse, click to put it in the active layer (it stays selected), right-click or Esc cancels |
| Ctrl+J / Ctrl+Shift+J | Copy / move the selection to a new layer |
| Ctrl+R | Fill the selection with the held block |
| Delete | Delete the selected blocks |
| Esc | Clear the region and selection |
| T or / | Command line, like Minecraft's chat (Tab completes, ↑ ↓ history) |
Commands take one slash and work on every visible, unlocked layer:
| Command | Action |
|---|---|
/pos1, /pos2 [x y z] |
Set a corner (default: the block you aim at) |
/set <pattern> |
Fill the region, e.g. stone, 70%stone,30%andesite, hand |
/replace [from] <to> |
Replace blocks |
/walls, /faces, /overlay, /center <pattern> |
Side walls, all faces, a layer on top, the middle |
/smooth [passes], /naturalize |
Smooth the terrain · grass, dirt and stone by depth |
/hollow [thickness] [pattern] |
Hollow out shapes, keeping a shell |
/copy, /cut, /paste [-a] [-s], /rotate, /flip |
Clipboard, relative to pos1 |
/move, /stack [n] [dir] [-a] |
Move or repeat the region's contents |
/expand, /contract, /shift <n> [dir], /outset, /inset |
Resize or move the region |
/line, /sphere, /cyl, /pyramid (/h… hollow) |
Shapes at pos1 |
/count, /distr, /size, /sel |
Region info, clear the region |
/undo, /redo, /help |
Undo, redo, list commands |
Move, Rotate and Scale tools
| Action | Result |
|---|---|
| Drag an arrow / square / the centre | Move along an axis / in a plane / freely |
| Drag a ring | Turn in 90° steps |
| Scale: drag a square handle / the centre | Stretch along that axis / scale evenly (whole blocks, nearest neighbour) |
| Click a layer | Select it (Shift adds) |
| Esc / right-click | Cancel the drag |
Layers
| Key | Action |
|---|---|
| Ctrl+wheel | Move along the axis of the layer's bounding-box side under the mouse |
| Ctrl+Shift+wheel | Up / down |
| Shift+wheel (outside Build mode) | Same as Ctrl+wheel |
| Arrow keys, hold Tab | Move, bigger steps |
| Alt+wheel (Shift+wheel in Build mode) | Turn by the bounding-box side under the mouse: spin (top or bottom) or flip (a side) |
| Alt+wheel in Build mode | Next / previous hotbar slot (the wheel still zooms) |
| [ / ] | Make the layer below / above active (with the brush or eraser: brush size) |
| Ctrl+Shift+N / Ctrl+D / Ctrl+M | New / duplicate / merge |
| F2 | Rename the active layer |
| H / Alt+H / Shift+H | Hide or show / show every layer / ghost |
| L | Lock or unlock |
| Shift+Delete | Delete the selected layers |
| PgUp / PgDn, Insert | Slice view: step through Y levels, single level |
| Click / Enter, R, Esc | Placing an import: place, rotate, cancel |
File, edit and view
| Key | Action |
|---|---|
| Ctrl+N / Ctrl+O / Ctrl+I | New / open / import |
| Ctrl+S / Ctrl+Shift+S | Save / save as |
| Ctrl+E / Ctrl+Shift+E | Export schematic / worldgen data pack |
| Ctrl+Z / Ctrl+Y (Ctrl+Shift+Z) | Undo / redo |
| Ctrl+F | Search blocks |
| Ctrl+, | Settings |
| N | Viewport settings |
| Alt+G | Ground grid on / off |
| F1 / Alt+K | Keyboard shortcuts |
| Shift+F1 | Key hints on / off |
| F11 | Full screen |
Plugins are .jar files that add schematic formats, exporters, importers, menu actions, /commands, transforms with a live preview, side panels and tools. Manage them under Plugins (puzzle icon) › Manage plugins…, where you can install, enable or disable, reload and uninstall them. Plugins run with the same access as BlockDesigner itself, so only install ones you trust.
Each running plugin has a tab on the right with its pages; the info button on the tab shows what it adds. A plugin's settings are on its page under Plugins in Settings, and its tools and Plugins-menu actions can be given keys in Settings › Keybinds. When two plugins can import the same kind of file, Import asks which one to use.
Each plugin lives in its own repository and is released there, separately from BlockDesigner:
| Plugin | What it does | Needs |
|---|---|---|
| BlockCompanion Plugin (formerly Resource Tracker; installed with BlockDesigner) | Links BlockDesigner to the BlockCompanion Minecraft mod: send projects into the game and edit builds from it. Also the materials a build needs as items (stacks and shulker boxes), what you have gathered and what is left, saved with each project | 0.4.24 |
| Palette Tools | Weathering, palette swap and gradient transforms, a Palette panel, a colour palette exporter, a pixel art importer and a Wall tool | 0.4.24 |
Install one from Plugins › Manage plugins…: pick it under Suggested to install, or download its .jar from its releases page and drop it on the drop box there.
Reference Planes is no longer a plugin: it is built in as reference images. If you have its
plugin, BlockDesigner no longer loads it (it renames the jar to end in .retired and tells you once), and keeps its
settings, its key and the pictures in your projects.
To write one, see PLUGINS.md (guide), docs/plugin-api-reference.md (every API type) and the plugin repositories above. The smallest template to copy is examples/hello-plugin; it and examples/palette-tools stay in this repository because BlockDesigner's own tests load them. The plugin developer wiki covers project setup, the manifest, loading, automatic updates, releasing and testing.
Requires JDK 25+ (the build uses a Java 26 toolchain; gradle.properties points Gradle at a local Temurin 26, so change org.gradle.java.home to your own JDK).
./gradlew :app:run
./gradlew :app:portablebuildsdist/BlockDesigner/BlockDesigner.exeanddist/BlockDesigner-<version>-portable.zip. The Java runtime is bundled, and settings are kept in adatafolder next to the exe../gradlew :app:installerbuildsdist/BlockDesigner-<version>.msi, which installs toC:\Program Files\BlockDesignerwith Start menu and desktop shortcuts, and makes.bdprojsaves show the BlockDesigner icon and open in the app. It needs the WiX Toolset: unzip the WiX 3.14 binaries intotools/wix3, or have WiX on PATH.- The version is
versionin the rootbuild.gradle.kts. The icon is described bypackaging/icon.pyand the official plugins' logos bypackaging/plugin_logos.py; thevoxel-iconsskill draws them (python <skill>/scripts/draw.py packaging/icon.py, needs Pillow). Rerun it after changing a design.
Windows Smart App Control blocks unsigned programs it doesn't recognise, and SmartScreen warns about them. Every release is a new, unknown file, so releases should be signed. When a certificate is set up, :app:portable and :app:installer sign:
BlockDesigner.exe;- the installer;
- the native DLLs that JavaFX, LWJGL and JNA unpack from their jars at runtime (they ship unsigned).
The Java runtime's own DLLs are already signed by Eclipse and Microsoft. Without a certificate, the build warns and leaves everything unsigned.
-
Run
./gradlew :app:fetchSigntoolonce. It downloadssigntool.exefrom Microsoft's SDK build tools on nuget.org intotools/signtool, which is git-ignored. An installed Windows SDK works too. -
Put the signtool options in
~/.gradle/gradle.propertiesasblockdesigner.sign.args, or in theBLOCKDESIGNER_SIGN_ARGSenvironment variable. Never put them in the repo. The value is everything betweensigntool signand the file names:- A certificate in the Windows store, such as a USB token or Certum SimplySign:
/sha1 <thumbprint> /fd SHA256 /tr http://time.certum.pl /td SHA256 - A
.pfxfile:/f C:\certs\blockdesigner.pfx /p <password> /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 - Azure Trusted Signing:
/fd SHA256 /tr http://timestamp.acs.microsoft.com /td SHA256 /dlib <path>\Azure.CodeSigning.Dlib.dll /dmdf <path>\metadata.json
In
gradle.properties, write a backslash as\\or use forward slashes (C:/certs/blockdesigner.pfx). A path with spaces goes in double quotes. - A certificate in the Windows store, such as a USB token or Certum SimplySign:
-
For releases, add
-Pblockdesigner.sign.required=true. The build then fails instead of quietly shipping unsigned files.
A self-signed certificate signs fine but doesn't satisfy Smart App Control or SmartScreen. The certificate has to come from a code-signing authority that Windows trusts.
./gradlew test
The integration tests in assets and render use your local Minecraft install and testdata/ when they exist, and are skipped otherwise. With UI_SNAPSHOTS=1, the *UiSnapshotsIT tests render the app's windows and panels to PNGs in app/build/ui-snapshots (the screenshots in this README come from there).
| Module | What it does |
|---|---|
core |
NBT, block states, sparse structures, layers and scenes, undo, transforms, schematic formats, .bdproj projects |
assets |
Finds installs; loads blockstates, models and textures from game, mod and resource-pack jars; bakes models; builds the texture atlas |
render |
LWJGL / OpenGL offscreen renderer (MSAA, smooth AO, sorted translucency), meshing on worker threads, picking |
worldgen |
Data pack exporter: single structures and village-style jigsaw layouts |
plugin-api |
The API third-party plugins compile against |
app |
JavaFX UI (AtlantaFX theme), reference images (refplanes), plugin manager, updater |
examples/hello-plugin |
Sample plugin for API 1, also used by the tests |
examples/palette-tools |
Sample plugin for API 2 (transforms, panel, tool, importer, exporter), also used by the tests |
packaging |
Icon and plugin logo designs (icon.py, plugin_logos.py) and Windows packaging resources |