Every public type in io.blockdesigner.plugin and io.blockdesigner.plugin.ui (the plugin-api module, plugin-api/src/main/java/io/blockdesigner/plugin), with its members. The Javadoc in the sources has the details; PLUGINS.md is the guide with worked examples, and plugin-api-v2.md is the design record.
API is the "api" version a plugin must declare in blockdesigner-plugin.json to use the type. Types from core that the API uses (BlockState, BlockPos, Box, Structure, Layer, Scene, SceneEditor, WorldEdit.World, SchematicFormat, BlockFamily, McVersion) are in the core jar.
| Type | Kind | API | What it is |
|---|---|---|---|
PluginApi |
class | 1 | The API version (VERSION = 6) and the manifest file name |
BlockDesignerPlugin |
interface | 1 | A plugin's entry point |
PluginInfo |
record | 1 | What the manifest says about a plugin |
PluginContext |
interface | 1 (parts 2) | The plugin's handle on BlockDesigner: registration, the scene, edits, feedback |
PluginCommand |
record | 1 | A /command for the command bar |
PluginAction |
record | 1 | An entry in the Plugins menu |
PluginExporter |
interface | 1 (parts 2) | A card in the Export window for non-schematic output |
Options |
class | 2 | Declarative parameters BlockDesigner draws controls for |
OptionValues |
class | 2 | The values chosen for some Options |
BlockPattern |
record | 2 | A weighted mix of blocks (70%stone,30%andesite) |
Progress |
interface | 2 | Progress reporting for long jobs |
SceneEvent |
sealed interface | 2 | Changes in the open project, delivered to listeners |
Subscription |
interface | 2 | A listener handle; cancel to stop listening |
BlockCatalog |
interface | 2 | The block registry, families, variants, colours and names |
AssetAccess |
interface | 2 | Block models as quads, the texture atlas and raw asset files |
PluginTransform |
interface | 2 | An operation on existing blocks with a previewed dialog |
TransformContext |
interface | 2 | What a transform sees while it runs |
PluginPanel |
interface | 2 | A tab of the plugin's own in the right-hand panel (JavaFX) |
PanelContext |
interface | 2 | A panel's handle on its tab |
PluginTool |
interface | 2 | A tool in the tool dock over the viewport |
ToolHandler |
interface | 2 | Receives an active tool's mouse, wheel and key input |
ToolEvent |
record | 2 | Mouse input for a tool handler |
ToolContext |
interface | 2 | What an active tool can use: options, preview, strokes |
PluginImporter |
interface | 2 | Turns a non-schematic file into layers |
SceneObjectType |
interface | 3 | A kind of scene object (reference image, guide): makes them, from files too |
SceneObject |
interface | 3 | Something in the scene that isn't blocks: draws itself, has a right-click menu and its own state |
ObjectHandle |
interface | 3 | BlockDesigner's side of one object: name, pose, visibility, lock, undoable edits |
SceneObjects |
interface | 3 | The plugin's objects in the project, the view, and blobs |
Pose |
record | 3 | Position, rotation and scale of an object |
Drawing |
interface | 3 | What an object draws: images on patches, lines |
ImageData |
class | 3 | ARGB pixels for Drawing.image |
ViewInfo |
record | 3 | How the 3D view looks at the scene: ortho, axis view, eye, target |
UI kit (PanelScaffold, Section, Form, ActionBar, StatusBadge, Banner, EmptyState, ItemList, ItemRow, Segmented, Controls, Icon, Theme, Tone, PluginUi, OptionsForm) |
classes, interfaces | 6 | Pages and dialogs in BlockDesigner's look |
public final class PluginApi
| Member | Description |
|---|---|
static final int VERSION = 7 |
The API version this BlockDesigner provides. Plugins declaring a newer api are not loaded. |
static final String DESCRIPTOR = "blockdesigner-plugin.json" |
Name of the manifest at the root of a plugin jar. |
public interface BlockDesignerPlugin — the class named by "main" in the manifest; needs a public no-argument constructor.
| Member | Description |
|---|---|
void enable(PluginContext context) throws Exception |
Called once after loading (or re-enabling). Register everything here; don't build JavaFX nodes yet. |
default void disable() |
Called when the plugin is disabled or the app closes. Registrations are removed automatically; release anything else. |
public record PluginInfo(String id, String name, String version, String author, String description, String mainClass, int api) — the parsed manifest. name defaults to id; version, author and description default to "".
public interface PluginContext — passed to enable. Use from the JavaFX thread.
| Member | API | Description |
|---|---|---|
PluginInfo info() |
1 | This plugin's manifest. |
Path dataFolder() |
1 | A folder for the plugin's own files (created on first call). |
void log(String message) |
1 | Writes a line to the plugin log in the Plugins window. |
void registerFormat(SchematicFormat format) |
1 | Adds a schematic format to Import and Export (id unique across all formats). |
void registerExporter(PluginExporter exporter) |
1 | Adds a card to the Export window. |
void registerAction(PluginAction action) |
1 | Adds an entry to the Plugins menu. |
void registerCommand(PluginCommand command) |
1 | Adds a command to the command bar. |
void registerTransform(PluginTransform transform) |
2 | Adds a transform (Plugins › Transform, right-click menu, /transform <id>). |
void registerPanel(PluginPanel panel) |
2 | Adds a panel: a page of the plugin's tab on the right (from 0.4.17; before, a tab of its own). |
void registerImporter(PluginImporter importer) |
2 | Adds an importer (Import window, drag and drop). |
void registerTool(PluginTool tool) |
2 | Adds a tool to the tool dock. |
void registerObjectType(SceneObjectType type) |
3 | Adds a kind of scene object; objects of it in the open project appear. |
<E extends SceneEvent> Subscription on(Class<E> type, Consumer<? super E> listener) |
2 | Listens for scene events, at most once per frame per kind; SceneEvent.class hears every kind. |
Scene scene() |
1 | The layers being edited (read freely; edit through editor()). |
SceneEditor editor() |
1 | Undoable editing: block sessions, adding / removing / modifying layers. |
Optional<Layer> activeLayer() |
1 | The active layer. |
List<Layer> selectedLayers() |
1 | Layers selected in the layer list (the active one when nothing else is). |
McVersion targetVersion() |
1 | The Minecraft version exports target. |
BlockCatalog blocks() |
2 | Block registry, families, variants and colours. |
AssetAccess assets() |
2 | Block models, the texture atlas and texture files. |
Optional<Box> selection() |
2 | World-space box around the selected blocks, or the //pos1 //pos2 region; empty when neither. |
void editWorld(String label, Consumer<WorldEdit.World> edit) |
1 | Edits blocks in world coordinates across visible, unlocked layers as one undo step; new blocks go into the active layer. |
Layer addLayer(String name, Structure blocks) |
1 | Adds a layer (one undo step) and makes it active. |
SceneObjects objects() |
3 | The plugin's scene objects. |
void status(String message) |
1 | Sets the status bar text. |
void toast(String message) |
1 | Shows a short message over the 3D view. |
void runOnUiThread(Runnable task) |
1 | Runs on the JavaFX thread (immediately when already on it). |
List<BlockState> hotbar() |
5 | The hotbar's nine slots, left to right; air for an empty slot. |
void setHotbar(List<BlockState> blocks) |
5 | Fills the hotbar from the left with up to nine blocks (air leaves a slot empty), empties the rest and holds the first. |
Optional<Image> blockIcon(BlockState block) |
5 | The block's icon as the block list and hotbar draw it (JavaFX Image); empty while no assets are loaded. |
void pickTool(String toolId) |
5 | Picks one of this plugin's tools, as its key or button does. |
void setToolOptions(String toolId, UnaryOperator<OptionValues> change) |
5 | Changes one of this plugin's tools' remembered options; its options bar follows when it is active. |
void registerSettings(Options options, Consumer<OptionValues> onChange) |
4 | The plugin's settings: its page in the Settings window (from 0.4.24; the tab before). onChange runs once straight away and after every change. Once, from enable. |
OptionValues settings() |
4 | The current settings. |
List<Path> resourcePacks() |
6 | The resource packs on the Minecraft assets, lowest priority first. |
void useResourcePacks(List<Path> packs) |
6 | Reloads the assets with these packs, kept as the user's choice. |
PluginUi ui() |
6 | The app's options form, dialogs, owner window and dark mode, for the plugin's own pages. |
void showPanel(String panelId) |
6 | Opens the plugin's tab at one of its pages (reopening the tab if closed); an unknown id opens the tab. |
void setPanelStatus(String panelId, Tone tone, String text) |
6 | A status dot on a page's button, text as its tooltip; a null tone removes it. Works before the page is built. |
void openSettings() |
6 | Opens the Settings window at the plugin's page (the tab's Overview when it has no settings). |
void updateSettings(UnaryOperator<OptionValues> change) |
6 | Changes the settings as if the user had: saved, onChange called, an open Settings page redrawn. |
void openFile(Path file, Consumer<OpenResult> done) |
7 | Opens a file as the project, as File › Open does: a .bdproj, or a schematic (.schem, .litematic, .nbt…) as a new, unsaved project named after the file. Asks to save the open project's changes first. done runs once on the JavaFX thread. |
public record OpenResult(Status status, String message) (API 7) — how openFile went. Status is OPENED, CANCELLED (the user cancelled at the save-changes question) or FAILED (message says why, e.g. "Could not read Castle.litematic: …"). isOpened(); factories opened(), cancelled(), failed(message).
public record PluginCommand(String name, String usage, String description, Handler handler) — name without the slash, a-z 0-9 _ only (otherwise IllegalArgumentException); usage defaults to /name.
| Nested type | Description |
|---|---|
interface Handler { String run(Context context) throws Exception; } |
Runs the command and returns the message shown; throw IllegalArgumentException for a friendly error. Writes to context.world() are one undo step. |
record Context(List<String> args, List<String> flags, WorldEdit.World world, Optional<Box> region, Optional<BlockPos> aim, Optional<BlockState> hand, BlockResolver blocks) |
What a command sees: words after the name (flags removed), -x flags, the merged visible unlocked layers, the //pos region, the aimed block, the held block and a resolver. Box requireRegion() returns the region or throws "Select a region first". |
interface BlockResolver { BlockState resolve(String text); } |
Turns text like oak_stairs[facing=east] into a block state; throws IllegalArgumentException when unknown. |
public record PluginAction(String label, String description, Runnable action) — a Plugins-menu entry: menu text, tooltip, and the action run on the JavaFX thread. label and action are required.
public interface PluginExporter — an Export window card for output that isn't a schematic format.
| Member | API | Description |
|---|---|---|
String id() |
1 | Stable id, unique within the plugin. |
String displayName() |
1 | Card title. |
default String description() |
1 | One line under the name (default ""). |
String extension() |
1 | Extension written, without the dot; null when writesFolder(). |
default boolean writesFolder() |
1 | True to have the user pick a folder as the target. |
default Options options() |
2 | Parameters shown on the card and remembered. |
default String summary(Structure merged) |
2 | An extra summary line on the card, or null; runs on the JavaFX thread when the chosen layers change. |
void export(Request request) throws IOException |
1 | Writes the output on a background thread. |
record Request(String name, String author, McVersion version, Structure merged, List<Layer> layers, Path target, OptionValues options, Progress progress, AssetAccess assets) — the export name, author, target version, the chosen layers merged in world coordinates, the layers themselves (bottom first, read-only by convention), the target file or folder, and (API 2) the chosen options, a progress sink and asset access. A six-argument constructor (without the API 2 components) is kept for API 1.
public final class Options — immutable, ordered parameters.
| Member | Description |
|---|---|
static Options none() |
No parameters: the feature runs straight away. |
static Builder builder() |
Starts a builder. Keys must be unique and use A-Z a-z 0-9 _ . -. |
List<Option> all() |
Every option, in display order. |
Optional<Option> get(String key) |
One option by key. |
boolean isEmpty() |
Whether there are no options. |
OptionValues defaults() |
Values with every option at its default. |
List<Condition> conditions(String key) |
API 5: when the option shows (every condition must hold); empty for always. |
boolean shown(String key, OptionValues values) |
API 5: whether the option shows with these values. Hidden options keep their values. |
List<Group> groups() |
API 6: the headings, in order; options before the first group form an untitled group. record Group(String title, boolean advanced, List<String> keys). |
Optional<String> help(String key), Optional<String> unit(String key) |
API 6: the option's help line and unit. |
Optional<String> enabledWhen(String key), boolean enabled(String key, OptionValues values) |
API 6: the toggle an option depends on, and whether it is on. |
record Condition(String choiceKey, Set<String> values): holds while the choice option choiceKey is one of values.
Builder methods (each returns the builder; finish with Options build()):
| Method | Control |
|---|---|
integer(String key, String label, int defaultValue, int min, int max) |
Spinner |
decimal(String key, String label, double defaultValue, double min, double max) |
Slider (a 0..1 range shows as a percentage) |
toggle(String key, String label, boolean defaultValue) |
Check box |
block(String key, String label, BlockState defaultValue) |
Block field |
blockList(String key, String label, List<BlockState> defaultBlocks) / blockList(String key, String label, BlockPattern defaultValue) |
Weighted block pattern field |
choice(String key, String label, List<String> values, String defaultValue) |
Drop-down |
text(String key, String label, String defaultValue) |
Text field |
file(String key, String label, List<String> extensions) |
File field with Browse (extensions without the dot; empty for any) |
showWhen(String choiceKey, String... values) |
API 5: shows the option added just before only while an earlier choice option is one of values. Call it more than once and every condition must hold. Older BlockDesigners show the option always. |
group(String title), advanced(String title) |
API 6: a heading over the options that follow; advanced draws it folded. Empty groups are dropped. |
help(String text) |
API 6: a line of help under the option added last. |
unit(String unit) |
API 6: the unit after a number added last ("blocks", "px", "°"); "%" on a decimal in 0..1 shows it ×100. |
enabledWhen(String toggleKey) |
API 6: greys the option added last out while an earlier toggle is off. |
option(Option o) |
API 6: adds an option record as it is (copying from other Options). |
From 0.4.17, block and block-mix options show as small hotbar-style slots with the block's icon (click for the held block, drop a block on it, right-click removes one from a mix, the wheel changes its share); a pencil button edits the same value as text.
sealed interface Option { String key(); String label(); } with the records IntegerOption, DecimalOption, ToggleOption, BlockOption, BlockListOption, ChoiceOption, TextOption and FileOption, one per builder method.
public final class OptionValues — immutable values for some Options. Every option has a value (its default until changed), except a file nobody picked.
| Member | Description |
|---|---|
static OptionValues defaults(Options options) |
Every option at its default. |
Options options() |
The options these values are for. |
int integer(String key), double decimal(String key), boolean toggle(String key) |
Typed getters. |
BlockState block(String key), BlockPattern blockList(String key) |
Block getters. |
String choice(String key), String text(String key) |
Text getters. |
Optional<Path> file(String key) |
The picked file, if any. |
Object get(String key) |
The raw value. |
OptionValues with(String key, Object value) |
A changed copy; numbers are clamped, choices must be valid. |
Map<String, String> toStrings() / static OptionValues fromStrings(Options, Map<String, String>, PluginCommand.BlockResolver) |
Text form for saving, and reading it back (invalid values fall back to defaults). |
Typed getters throw IllegalArgumentException for an unknown key or the wrong type.
public record BlockPattern(List<Entry> entries) — a weighted mix of blocks, the value of a block-list option. record Entry(BlockState block, double weight) (weight must be positive).
| Member | Description |
|---|---|
static BlockPattern of(BlockState... blocks) / of(List<BlockState> blocks) |
Equal parts of each block. |
static BlockPattern parse(String text, PluginCommand.BlockResolver resolve) |
Parses 70%stone,30%andesite (a missing weight counts as 1). |
BlockState pick(RandomGenerator random) |
A block drawn by weight. |
List<BlockState> blocks() |
The blocks, in order. |
String toString() |
The text form; round-trips through parse. |
@FunctionalInterface public interface Progress — void update(double fraction, String message): fraction 0 to 1 (negative when unknown), message null keeps the last one. Safe from any thread. Progress.NONE ignores updates.
public sealed interface SceneEvent — delivered on the JavaFX thread, at most one of each kind per frame.
| Record | Description |
|---|---|
BlocksChanged(List<Layer> layers, Box dirty) |
Blocks changed (edits, undo, redo, imports); layers bottom first, dirty in world coordinates. |
LayersChanged() |
Layers were added, removed, reordered, renamed, moved, shown or hidden. |
ActiveLayerChanged(Optional<Layer> layer) |
Another layer became active (empty when there are none). |
SelectionChanged(Optional<Box> region) |
The block selection or //pos region changed; world-space box, or empty. |
ProjectOpened(Optional<Path> file) |
A project was opened, or a new one started (empty file). |
@FunctionalInterface public interface Subscription extends AutoCloseable — void cancel() stops the listener (safe to call twice); close() cancels. Listeners are removed automatically when the plugin is disabled.
public interface BlockCatalog extends PluginCommand.BlockResolver — the loaded registry (vanilla creative-menu blocks before assets load).
| Member | Description |
|---|---|
BlockState resolve(String text) |
Completes a block state from text; throws IllegalArgumentException when malformed or unknown. |
boolean exists(String blockId) |
Whether a block id exists in the registry. |
Optional<BlockFamily> family(BlockState block) |
The block's family (planks, stairs, slab, fence, door…), if it has several shapes. |
Optional<BlockState> sameShape(BlockState block, BlockFamily other) |
The same shape in another family, keeping properties. |
Optional<BlockState> variant(BlockState block, String modifier) |
A material variant (mossy, cracked, exposed…), keeping shape and properties. |
Optional<BlockState> withoutVariant(BlockState block, String modifier) |
The reverse of variant. |
BlockState withId(BlockState block, String newId) |
Another block, copying the properties it also has. |
int averageColor(BlockState block) |
Average texture colour, 0xAARRGGBB, opaque (top face when it has one). |
String displayName(BlockState block) |
The block's display name. |
public interface AssetAccess — plain-data access to the loaded game, mod and resource-pack assets; safe on background threads. AssetAccess.NONE returns nothing.
| Member | Description |
|---|---|
boolean available() |
Whether Minecraft's assets are loaded. |
List<Quad> quads(BlockState block, Predicate<BlockPlacement.Dir> culled) |
The block model as quads, leaving out faces whose cull side is covered (side -> false for all). |
Optional<Atlas> atlas() |
The block texture atlas. |
Optional<byte[]> texture(String resourceId) |
A raw resource file by id (minecraft:block/stone) or full path. |
record Quad(float[] positions, float[] uvs, BlockPlacement.Dir face, Optional<BlockPlacement.Dir> cull, int tint, String texture) — one face in block space: 4 × xyz, 4 × uv in the atlas, facing side, cull side, tint (0xFFFFFF for none), texture id.
record Atlas(int width, int height, int[] argb, byte[] png) — pixels row by row and the same image as PNG bytes.
public interface PluginTransform
| Member | Description |
|---|---|
String id() |
Stable id, unique within the plugin; also the word after /transform (a-z 0-9 _). |
String name() |
Menu and dialog title. |
default String description() |
One line under the title and as tooltip. |
default String icon() |
16×16 SVG path data, stroked like the tool icons; null for none. |
default Scope scope() |
SELECTION, LAYER or SELECTION_OR_LAYER (default). |
default Options options() |
Parameters shown in the dialog. |
default boolean randomized() |
True to show a seed and Reroll button. |
void apply(TransformContext context) throws Exception |
Changes the blocks; runs per preview and once on Apply. Throw IllegalArgumentException for a message in the dialog. |
public interface TransformContext
| Member | Description |
|---|---|
WorldEdit.World world() |
Blocks in world coordinates; reads see the scene plus this run's writes. |
Box bounds() |
World-space box around the blocks being transformed. |
Iterable<BlockPos> solidBlocks() / int blockCount() |
The non-air blocks being transformed and how many. |
OptionValues options() |
The values chosen in the dialog. |
Random random() |
Seeded from the dialog's seed, so preview and Apply match. |
BlockCatalog blocks() |
Block registry, families and variants. |
boolean preview() |
True while previewing, false when applying. |
public interface PluginPanel — uses JavaFX (javafx.scene.Node).
| Member | Description |
|---|---|
String id() |
Stable id, unique within the plugin (remembers whether the panel is open). |
String title() |
Tab title. |
default String icon() |
16×16 SVG path data; null for a puzzle-piece glyph. |
default Dock dock() |
RIGHT (default), LEFT or BOTTOM; only RIGHT is laid out today, the others fall back to it. |
Node create(PanelContext context) |
Builds the content once, the first time the panel is shown. |
default void dispose() |
The panel is being removed: stop timers and listeners. |
public interface PanelContext
| Member | Description |
|---|---|
PluginContext plugin() |
The plugin's context. |
boolean isShowing() |
Whether the panel is on screen: its page picked in the plugin's tab, and the tab open and selected. |
void onShown(Runnable action) |
Runs each time the panel comes into view. |
void setBadge(String text) |
Text next to the panel's page button; null or empty removes it. |
void reveal() |
Opens the plugin's tab if closed, selects it and shows the panel's page. |
public interface PluginTool
| Member | Description |
|---|---|
String id() |
Stable id, unique within the plugin. |
String name() |
Tooltip title and toast. |
default String description() |
One tooltip line: what the buttons do. |
default String icon() |
16×16 SVG path data; null for a default. |
default String defaultKey() |
JavaFX KeyCombination text ("Shift+K"), or null; ignored when the key is already bound. |
default Options options() |
Parameters shown in the tool's options bar (bottom left of the view). |
default boolean selects() |
API 5: true for a tool that works on the selection. The left button then selects blocks as in Select mode (click, drag a box, Shift adds, Ctrl removes) and the tool gets the right button, the wheel and keys. |
ToolHandler activate(ToolContext context) |
The tool was picked: return the handler for its input. |
public interface ToolHandler — every method runs on the JavaFX thread and has a do-nothing default.
| Member | Description |
|---|---|
void hover(ToolEvent e) |
Mouse moved with no button held. |
void press(ToolEvent e) / void drag(ToolEvent e) / void release(ToolEvent e) |
Left or right button down, moved while held, up. |
boolean scroll(ToolEvent e, double delta) |
Wheel turned (+1 / -1 per notch); return true when used, else the view zooms. |
boolean key(String key) |
A key outside text fields ("R", "Shift+R", "Esc", "Enter"); return true when used. |
void optionsChanged() |
API 5: the user (or the plugin, through setToolOptions) changed a value in the options bar. |
void deactivate() |
Another tool was picked or the plugin is being disabled. |
public record ToolEvent(Optional<Hit> hit, Button button, Set<Modifier> modifiers, Vec3 rayOrigin, Vec3 rayDir) — with shift(), ctrl() and alt().
| Nested type | Description |
|---|---|
enum Button { NONE, PRIMARY, SECONDARY, MIDDLE } |
The button pressed or released (NONE for hover, scroll and drag without one). |
enum Modifier { SHIFT, CTRL, ALT } |
Modifier keys held. |
record Vec3(double x, double y, double z) |
A point or direction in world space. |
record Hit(BlockPos block, BlockPlacement.Dir face, BlockPos adjacent, Optional<Layer> layer) |
The block hit (for the ground, the cell below the grid), the face, the empty cell in front of it, and its layer (empty for the ground). |
public interface ToolContext — valid until ToolHandler.deactivate().
| Member | Description |
|---|---|
PluginContext plugin() |
The plugin's context. |
OptionValues options() |
Current values of the options bar (read them each time). |
Optional<BlockState> hand() |
The block in the selected hotbar slot. |
BlockCatalog blocks() |
The block catalog. |
Preview preview() |
Ghost blocks and outlines. |
Stroke beginStroke(String label) |
Starts an edit that becomes one undo step when committed. |
Optional<Selection> selection() |
API 5: the selected blocks (Select mode, or the //pos1 //pos2 region) in world coordinates; empty when nothing is selected. Locked and hidden layers are left out. |
int previewTransform(PluginTransform t, OptionValues options, long seed) |
API 5: runs a transform on the selection with these options and seed and shows the result as ghosts (the selection outlined); nothing changes. Returns how many blocks would change. |
int applyTransform(PluginTransform t, OptionValues options, long seed) |
API 5: the same, for real, as one undo step; clears the preview. Returns how many blocks changed. |
record Selection(Box bounds, List<BlockPos> blocks): the box around the selected blocks, and the non-air ones.
interface Preview: void ghost(Map<BlockPos, BlockState> blocks) (air entries outlined in red; replaces earlier ghosts), void outline(Box box) (null removes it), void clear().
interface Stroke extends AutoCloseable: WorldEdit.World world() (world coordinates; reads see the stroke's own writes), void commit(), void cancel() (puts every changed block back), close() commits.
public interface PluginImporter
| Member | Description |
|---|---|
String id() |
Stable id, unique within the plugin. |
String displayName() |
Shown in the file filter. |
List<String> extensions() |
Extensions without the dot, lower case. |
default Options options() |
Asked for in a small dialog before importing, and remembered. |
List<ImportedLayer> importFile(Path file, OptionValues options, Progress progress, BlockCatalog blocks) throws IOException |
Reads the file on a background thread; an IOException message is shown to the user. |
record ImportedLayer(String name, Structure blocks, BlockPos offset) — a layer to add; name defaults to "Imported", offset (the layer's origin relative to the others of the same import) defaults to the origin.
public interface SceneObjectType — registered with PluginContext.registerObjectType.
| Member | Description |
|---|---|
String id() |
Stable id, unique within the plugin, saved in projects (a-z 0-9 _ . -). |
String name() |
What one is called ("Reference image"); also the choice when a file could be imported several ways. |
String badge() |
The tag on its rows in the Layers panel ("REFERENCE"). |
SceneObject create() |
A new, empty object (load follows when it comes from a project). |
default List<String> extensions() |
Files open turns into objects (Import, drag and drop). |
default void open(Path file, ViewInfo view) throws IOException |
Makes an object from such a file, usually with objects().add(...); an IOException message is shown. |
public interface SceneObject — a plugin's object. Every call runs on the JavaFX thread.
| Member | Description |
|---|---|
void draw(ViewInfo view, Drawing out) |
Draws the object in its own space, every frame it is visible; draw nothing to hide it in this view. |
default String description(ObjectHandle self) |
The line under its name in the Layers panel. |
default List<MenuItem> menu(ObjectHandle self) |
Its own right-click entries (JavaFX); BlockDesigner adds rename, focus, hide, lock and delete. |
byte[] save() |
Its own state (not the name, pose or flags), for projects and undo. |
void load(byte[] data) throws IOException |
Puts back a saved state. |
default Set<String> blobs() |
Keys of the blobs it uses, saved with the project. |
public interface ObjectHandle — BlockDesigner's side of one object. The setters are one undo step each.
| Member | Description |
|---|---|
String id(), String type(), SceneObject object() |
Its id in the project, its type id and the plugin's object. |
boolean exists() |
Still in the scene (false once deleted, or while its plugin is off). |
String name(), void setName(String) |
Its name in the Layers panel. |
Pose pose(), void setPose(Pose pose, String label) |
Where it is; the Move and Rotate tools change it too. |
boolean visible(), void setVisible(boolean) |
Shown or hidden. |
boolean locked(), void setLocked(boolean) |
A locked object is drawn but can't be picked or moved in the view. |
void edit(String label, Runnable change) |
Changes the plugin's own state as one undo step (undo loads what save() returned before). |
void refresh() |
Redraws without an undo step. |
boolean selected(), void select(), void remove() |
Selection (the gizmo tools work on the selected object) and deleting (one undo step). |
public interface SceneObjects — from PluginContext.objects().
| Member | Description |
|---|---|
List<ObjectHandle> list() |
The plugin's objects, top first. |
ObjectHandle add(String type, String name, Pose pose, SceneObject object) |
Adds one of the plugin's types, as one undo step, and selects it. |
Optional<ObjectHandle> selected() |
The selected object, if it is the plugin's. |
ViewInfo view() |
How the 3D view looks now. |
String storeBlob(byte[] data) |
Keeps data (an image file) with the project; the key is the same for the same bytes. |
Optional<byte[]> blob(String key) |
Data stored under a key. |
public record Pose(Vec3 position, Vec3 rotation, Vec3 scale) — Vec3 is ToolEvent.Vec3. Rotation is in degrees, XYZ Euler (R = Rz·Ry·Rx); a point goes to position + R·(scale∘local).
| Member | Description |
|---|---|
static Pose IDENTITY, static Pose at(x, y, z) |
At the origin (or a point), unturned, scale 1. |
withPosition, withRotation, withScale |
Copies with one part changed. |
Pose translated(dx, dy, dz) |
Moved. |
Pose rotatedAbout(int axis, double degrees, Vec3 pivot) |
Turned about world axis 0 / 1 / 2 through a pivot. |
Pose scaledBy(fx, fy, fz) |
Scaled along its own axes. |
Vec3 toWorld(...), Vec3 toLocal(Vec3) |
Points between its own space and the world. |
Vec3 axis(int), double[] rotationMatrix() |
Its turned axes; the rotation as a row-major 3×3 matrix. |
public interface Drawing — valid only during SceneObject.draw; coordinates are in the object's own space.
| Member | Description |
|---|---|
void image(ImageData image, Vec3[] corners, double[] uv, double opacity, Depth depth) |
A picture on four corners (bottom-left, bottom-right, top-right, top-left), seen from both sides; uv is u v per corner, v from the top, outside 0..1 see-through. |
void line(Vec3 from, Vec3 to, int argb) |
A line. |
enum Depth { BEHIND_BLOCKS, IN_SCENE, IN_FRONT } |
A backdrop blocks always cover; hidden by blocks in front; over everything. |
public final class ImageData(int width, int height, int[] argb) — ARGB pixels (not premultiplied), top row first, wrapped, not copied. Uploaded once per instance: keep one per picture and never change its pixels. width(), height(), argb(), aspect(); MAX_SIZE = 4096.
public record ViewInfo(boolean ortho, Optional<Side> side, Vec3 eye, Vec3 forward, Vec3 target) — side is the axis view the camera is at (empty for a free view); isOrthoSide(Side) checks for one orthographic axis view. enum Side { FRONT, BACK, RIGHT, LEFT, TOP, BOTTOM }, with facing(): the rotation that turns something drawn facing +Z towards that view, upright.
Plain JavaFX classes in the plugin API jar; at runtime they come from the installed BlockDesigner, so pages match the app.
Each attaches the kit's stylesheet (bd.css) itself. PLUGINS.md has
the guide and examples.
| Type | Kind | What it is |
|---|---|---|
PanelScaffold |
class | A page: top(...) (sticky), add(...) (scrolling content), grow(node) (takes the free height), footer(...) (sticky), empty(EmptyState) + showEmptyProperty(), narrowProperty() / isNarrow() (below 300 px). |
Section |
class | A heading and content: add, grow, actions(...), badge(StatusBadge), collapsible(expanded), expandedProperty(), titleLabel(). |
Form |
class | Label / control rows: row(label, control), row(fullWidth), rows(); Form.Row: help, unit, error, enabledWhen, shownWhen, label(), control(). |
ActionBar |
class | Up to three buttons; the accent one grows; stacked when narrow. |
StatusBadge |
class | Dot + text in a Tone: new StatusBadge(tone, text), set(tone, text), tone(). |
Banner |
class | A message with an optional action: show(tone, message), show(tone, message, actionText, action), hide(), message(). |
EmptyState |
class | Icon, sentence, hint(text), up to two action(button). |
ItemList<T> |
class | A ListView whose rows fit the width: new ItemList<>(item -> ItemRow) or own cells (wire(cell, item)), empty, visibleRows(min, max), onOpen, onDelete, menu. |
ItemRow |
class | of(title), meta(text[, tone]), image, swatch, leading, below, trailing(...) (≤ 3), tooltip, node(). |
Segmented<T> |
class | Mutually exclusive choices side by side: valueProperty(), getValue(), setValue(v). |
Controls |
class | primary, button, danger, iconButton, toggle, busy, hint, caption, pathCaption, link, search, blockIcon, spacer, show. |
Icon |
enum | Feather icons: node() (16 px), node(size), path(). |
Theme |
class | STYLESHEET, spacing XS SM MD LG XL, LABEL_MIN/PREF/MAX, NARROW, ROW; attach(node), root(node). |
Tone |
enum | NEUTRAL, ACCENT, SUCCESS, WARNING, DANGER; pseudoClass(), apply(node, tone). |
PluginUi |
interface | From ctx.ui(): optionsForm(options, rememberAs, onChange), darkProperty(), isDark(), owner(), style(dialog), confirm, askText, choose, copyText, open; API 7: toFront() brings the main window forward. |
OptionsForm |
interface | The app's form: node(), values(), setValues(values), reset(). |
Stable style classes: bd-root, bd-scaffold, bd-top, bd-content, bd-footer, bd-section, bd-section-header,
bd-section-title, bd-hint, bd-caption, bd-form, bd-form-label, bd-action-bar, bd-badge, bd-banner,
bd-empty, bd-list, bd-row, bd-row-title, bd-row-meta, bd-segmented, bd-segment, bd-block-slot, bd-icon,
bd-card, bd-frame, bd-mono, bd-search, bd-progress, bd-inline-field, bd-dialog; pseudo-classes :narrow,
:error, :accent, :success, :warning, :danger, :busy. Icons: Feather (MIT), licence in
io/blockdesigner/plugin/ui/FEATHER-LICENSE.txt.