---
title: "Format API - BuildPrint wiki"
description: "Teach BuildPrint another schematic file format, so those files load like any other."
url: https://voxelsprout.com/buildprint/wiki/format-api
---

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

# Format API

Teach BuildPrint another schematic file format, so those files load like any other.

Implement `BlueprintFormat` and register it. Files with your extensions then show up in the **Local** tab and the file picker, and load like any other schematic. From BuildPrint **0.1.17**.

## Register a format

From your client initializer

```java
BuildprintFormats.register(new MyFormat());
```

```java
public class MyFormat implements BlueprintFormat {
    @Override public String id() { return "mymod:blocks"; }
    @Override public String label() { return "My Blocks"; }
    @Override public String[] extensions() { return new String[]{"myblocks"}; }

    @Override
    public BlueprintData read(InputStream in) throws IOException {
        // Parse the file, then hand BuildPrint plain data.
        return new BlueprintData(name, author, width, height, length, palette, blocks, Map.of());
    }
}
```

## The data

* `palette` holds block state strings, such as `minecraft:oak_stairs[facing=east,half=bottom]`. `minecraft:air` is air.
* `blocks` holds one palette index per block, `width * height * length` of them. `index(x, y, z)` says where a block sits: X fastest, then Z, then Y. An index outside the palette counts as air.
* `blockEntities` maps a block index to its block entity data as SNBT: chest contents, sign text. It may be empty.
* `name` and `author` may be empty.

## Writing

Writing is optional: return true from `canWrite()` and implement `write(data, out)`. BuildPrint saves its own schematics as `.litematic`, so it does not call `write` yet.

## Good to know

* BuildPrint's own formats are asked first, so a new format can add extensions but not take one over.
* Entities, such as item frames and armour stands, are not carried.

## Reference

| BlueprintFormat                                          | What it does                                                                    |
| -------------------------------------------------------- | ------------------------------------------------------------------------------- |
| id()                                                     | A namespaced id.                                                                |
| label()                                                  | The name shown for files of this format and in the file picker.                 |
| extensions()                                             | File extensions, lower case, without the dot.                                   |
| read(InputStream in)                                     | Read a file into BlueprintData. Throw an IOException for a file it cannot read. |
| canWrite() / write(BlueprintData data, OutputStream out) | Optional: write it back.                                                        |

[Previous Editor API](https://voxelsprout.com/buildprint/wiki/editor-api)

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