---
title: "Previews API - BuildPrint wiki"
description: "Show a changed copy of a build as a ghost, then throw it away or save it."
url: https://voxelsprout.com/buildprint/wiki/previews-api
---

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

# Previews API

Show a changed copy of a build as a ghost, then throw it away or save it.

For a mod that changes a build, for example to restyle or recolour it, and wants the player to see the result before anything is saved. From BuildPrint **0.1.19**.

## Show a copy in place of a build

```java
Map<String, Object> data = BuildprintPlacements.snapshot(id);
// Change data.get("palette") or data.get("blocks") here.

int[] o = BuildprintPlacements.origin(id);
int preview = BuildprintPreviews.create("mymod", data, o[0], o[1], o[2],
        BuildprintPlacements.rotation(id), BuildprintPlacements.flipped(id));
BuildprintPreviews.hide("mymod", id); // hide the original while the copy is up
```

The data is described under [blueprint data](https://voxelsprout.com/buildprint/wiki/placements-api#blueprint-data). Only `size`, `palette` and `blocks` are needed. `palette` can also be a `List<String>`.

## Change it, keep it or drop it

```java
BuildprintPreviews.update("mymod", preview, changed);   // same place, new blocks

BuildprintLibrary.save("mymod", preview, "Castle restyled", path -> {
    // path is inside the schematics folder, or null when writing failed
});

BuildprintPreviews.release("mymod"); // previews gone, hidden builds back
```

## Good to know

* A preview is a normal build while it is up. It is drawn, listed and checked against the world, and the editor tools and the printer work on it.
* It has no file. It is not saved with the world's placements, and it is gone when the player leaves the world. To keep it, save it with [BuildprintLibrary](https://voxelsprout.com/buildprint/wiki/library-api).
* The player can remove a preview in BuildPrint like any other build. `ids(owner)` lists the ones still up.
* `hide` is not the player's own show and hide, and it is not saved. `show`, `release` and leaving the world bring the build back.
* Everything is per owner, your mod id. One mod cannot change or discard another mod's previews.

## Reference

| BuildprintPreviews                                                                                 | What it does                                                                                                |
| -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| isAvailable()                                                                                      | In a world, with its placements restored.                                                                   |
| create(String owner, Map<String, Object> data, int x, int y, int z, int rotation, boolean flipped) | Show the data with its first block at x, y, z. Returns the build id, or -1\. Data it cannot read is logged. |
| update(String owner, int id, Map<String, Object> data)                                             | New blocks for your preview. A new name renames it.                                                         |
| discard(String owner, int id)                                                                      | Take your preview away. Nothing is written.                                                                 |
| ids(String owner) / owner(int id)                                                                  | Your previews that are still up, and the mod that made a preview. owner is null for a normal build.         |
| hide(String owner, int id) / show(String owner, int id)                                            | Hide any build while your preview stands in for it, or show it again.                                       |
| release(String owner)                                                                              | Discard all your previews and show everything you hid.                                                      |

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

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