Selection API

Read and change the player's selection, and capture part of the world as blueprint data.

The selection is the set of boxes the editor's Select and Magic select tools and the /buildprint select commands make. Each dimension has its own selection, and every call works on the one of the dimension the player is in. Changes show at once, in the editor and outside it. From BuildPrint 0.1.19.

A box is int[] {minX, minY, minZ, maxX, maxY, maxZ} in world blocks, inclusive. Several boxes are one int[] with 6 numbers per box.

Change the selection #

Java

BuildprintSelection.clear();
int index = BuildprintSelection.add(new int[]{0, 64, 0, 15, 80, 15});
int[] boxes = BuildprintSelection.regions();
BuildprintSelection.remove(index);

Capture part of the world #

A capture is what saving the selection would write, as blueprint data and without a file. It keeps block entities, entities and each box as a region.

Java

BuildprintSelection.capture("mymod", data -> {
    if (data == null) return; // the player left the world in between
    int[] origin = (int[]) data.get("origin"); // world block of the first cell
    boolean complete = (Boolean) data.get("complete");
});

// Or other boxes; the selection stays as it is.
BuildprintSelection.captureBoxes("mymod", new int[]{0, 64, 0, 7, 70, 7}, data -> { });

Good to know #

In single-player the capture comes from the world on the built-in server, so it has everything, container contents too.
On a server it has what the game sends players, and with Bobby the chunks Bobby remembers. Container contents are only there for containers the player opened this session. unseenContainers says how many were not. It does not wait for the world the way a save does.
complete is false when part of it was not loaded and came out as air. missingChunks says how many chunks.
The callback runs on the client thread, a moment later, or for a big selection a while later.
A server can turn off making schematics with VoxelSprout Policy. capture then returns false and does not call back.
Captures over 67,108,864 blocks call back with null.

A save that waits for the world #

On a server, a selection bigger than what the client has seen does not save right away: BuildPrint collects the chunks as the player walks and saves when none are left. The calls that start with savePending, isSavePending and dropPendingSave let your mod follow and end that. From BuildPrint 0.1.34.

Reference #

BuildprintSelection	What it does
`isAvailable()`	In a world.
`regions()` / `activeRegion()`	The boxes in order, and the index of the active one, or -1.
`add(int[] box)`	Add a box, corners in any order, and make it active. Returns its index.
`remove(int index)` / `clear()`	Remove one box, or all of them.
`capture(String owner, Consumer<Map<String, Object>> done)`	Capture the selection.
`captureBoxes(String owner, int[] boxes, Consumer<Map<String, Object>> done)`	Capture these boxes instead.
`isSavePending()`	A save is waiting for the world. There is one at most. Since 0.1.34.
`savePendingProgress()`	`{chunks still to see, chunks of the selection}`, empty with none waiting. Since 0.1.34.
`savePendingChunks()`	The chunks still to see, as x, z pairs in chunk coordinates. Since 0.1.34.
`savePendingNow()`	Writes it now with what it has, gaps included. False with none waiting. True too when a server rule refuses it, which BuildPrint tells the player; the save then stays. Since 0.1.34.
`dropPendingSave()`	Drops it without writing or telling the player. False with none waiting. Since 0.1.34.

Something missing or wrong on this page? Say so on Discord.