---
title: "Placements API - BuildPrint wiki"
description: "Read the builds loaded in BuildPrint: where they are, what they want at a block, progress and materials."
url: https://voxelsprout.com/buildprint/wiki/placements-api
---

[BuildPrint](https://voxelsprout.com/buildprint) [Wiki](https://voxelsprout.com/buildprint/wiki)Placements API

# 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.                                                                                                 |

[Previous Blueprint API](https://voxelsprout.com/buildprint/wiki/blueprints-api) [Next HUD API](https://voxelsprout.com/buildprint/wiki/hud-api)

Something missing or wrong on this page? Say so on [Discord](https://discord.gg/CvdkGbEW4y).