Placements API

Read the builds loaded in BuildPrint: where they are, what they want at a block, progress and materials.

BuildprintPlacements is read-only. It suits a minimap that draws the outlines of builds, a HUD that shows progress, or a storage mod that shows what a build still needs. From BuildPrint 0.1.17.

Each build has an int id that stays the same while it is loaded. A build loaded again after a restart gets a new one. Dimensions are ids like minecraft:overworld, and block states are strings like minecraft:oak_stairs[facing=east,half=bottom,shape=straight,waterlogged=false].

List the builds #

Java

for (int id : BuildprintPlacements.ids()) {
    if (!BuildprintPlacements.visible(id)) continue;
    String name = BuildprintPlacements.name(id);
    int[] box = BuildprintPlacements.bounds(id); // minX, minY, minZ, maxX, maxY, maxZ
    double done = BuildprintPlacements.completion(id); // 0 to 1
}

Ask about one block #

Java

String dim = level.dimension().identifier().toString();
String wants = BuildprintPlacements.expectedAt(dim, x, y, z); // null: no build here
String status = BuildprintPlacements.statusAt(dim, x, y, z);  // "MISSING", "CORRECT", ...

Where builds overlap, one that wants a block there wins over one that wants air, the same as BuildPrint's own look-at card. The expected state is turned the way the build is turned.

Status	Means
`CORRECT`	The right block in the right state.
`MISSING`	The build wants a block and there is air.
`WRONG_BLOCK`	A different block is there.
`WRONG_STATE`	The right block, turned or set differently.
`EXTRA`	The build wants air and there is a block.
`UNKNOWN`	Not checked yet, or its chunk was not loaded last time.

Be told about changes #

Java

BuildprintPlacements.listen("mymod", (event, id) -> {
    switch (event) {
        case "added" -> addMarker(id);      // loaded, or restored on joining a world
        case "removed" -> removeMarker(id);
        case "moved" -> moveMarker(id);     // moved, turned or flipped
    }
});

Events come on the client thread, at the end of the tick they happened in. One listener per owner: a second call replaces the first. unlisten(owner) stops it.

Reference #

BuildprintPlacements	What it does
`ids()`	The loaded builds, oldest first.
`exists(int id)`	Whether that build is loaded.
`name(int id)` / `owner(int id)`	Its name, and the mod that keeps it through `BuildprintBlueprints`. `owner` is null for a player's own build.
`dimension(int id)` / `visible(int id)`	Where it is, and whether it is drawn right now.
`origin(int id)`	`{x, y, z}` of the placement.
`rotation(int id)` / `flipped(int id)`	Clockwise degrees (0, 90, 180, 270), and whether it is mirrored.
`orientationFixed(int id)`	Whether the player cannot turn or flip it.
`size(int id)`	`{width, height, length}` before turning.
`bounds(int id)`	`{minX, minY, minZ, maxX, maxY, maxZ}` in the world, inclusive.
`version(int id)`	Changes when the build is moved, turned or flipped.
`placementAt(String dim, int x, int y, int z)`	The visible build covering a block, or -1.
`expectedAt(String dim, int x, int y, int z)`	The block state the build wants there, or null.
`statusAt(String dim, int x, int y, int z)`	How the block compares, or null.
`counts(int id)`	`{required, placed, missing, wrongBlock, wrongState, extra, unknown}`.
`completion(int id)` / `fullyChecked(int id)`	Progress from 0 to 1, and whether every block was checked once.
`materials(int id)`	Item id to `{required, placed, stillNeeded}`, in the order of the material list. Includes container contents and extras such as dyes for signs.
`listen(String owner, BiConsumer<String, Integer> listener)` / `unlisten(String owner)`	Get `added`, `removed` and `moved` events, or stop.

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