Blueprint Specification - Coder Documentation

cogg - 429 days ago - Edited 424 days agoLink


Blueprints are stored in a base64 textual wrapper. The wrapper may be prefixed with the string "DSA:" in order to make blueprints easy to identify, but this is not required.

We do NOT use "url safe" base64, since it is less safe in Discord and likely to be mangled.

The binary data contained within is DEFLATE compressed.


Some items are blacklisted from being built with blueprints, usually due to incompatibility. They include:

Serialization Format

The serialization is similar to messagepack. The following source excerpt outlines serializer tags:

// all types are stored in little endian byte order

// 00 - 7F single-byte signed integers
//      00 - 3F positive (0 to 63)
//      40 - 7F negative (-64 to -1)

// all other types consist of a 1-byte tag and some data

// unsigned integers
const TAG_U8:   u8 = 0x80;
const TAG_U16:  u8 = 0x81;
const TAG_U32:  u8 = 0x82;
const TAG_U64:  u8 = 0x83;

// signed integers (most significant bit is extended)
const TAG_I8:   u8 = 0x84;
const TAG_I16:  u8 = 0x85;
const TAG_I32:  u8 = 0x86;
const TAG_I64:  u8 = 0x87;

// float types
const TAG_F32:  u8 = 0x88;
const TAG_F64:  u8 = 0x89;

// utf8 strings, prefixed by an unsigned byte length of 1-4 bytes
const TAG_STR_L1: u8 = 0x8A;
const TAG_STR_L2: u8 = 0x8B;
const TAG_STR_L4: u8 = 0x8C;

// primitive types (true, false, and null)
const TAG_TRUE:  u8 = 0x8D;
const TAG_FALSE: u8 = 0x8E;
const TAG_NULL:  u8 = 0x8F;

// array begin and end delimiters
const TAG_ARRAY_BEGIN: u8 = 0x90;
const TAG_ARRAY_END:   u8 = 0x91;

// map begin and end delimiters, should contain an even number of elements to construct (key, value) pairs
const TAG_MAP_BEGIN:   u8 = 0x92;
const TAG_MAP_END:     u8 = 0x93;

// byte arrays, prefixed by an unsigned byte length of 1-4 bytes
const TAG_BYTES_L1: u8  = 0x94;
const TAG_BYTES_L2: u8  = 0x95;
const TAG_BYTES_L4: u8  = 0x96;

Top-Level Schema

[ V W H CMDS ]

V       = -1 or 0
        The blueprint format version. Both -1 and 0 are considered the same.

W H     Integers between 1 and 100 inclusive
        The width and height of the blueprint, in blocks. Validation will fail if any objects are place outside of these bounds.

CMDS    An array of one or more commands.
        Each command is an array. The first field of each command is an integer which specifies the kind of command.
        It is an error for there to be zero Build (0) commands.

Build (0) Command

Builds one or more objects using the configurations specified by other commands.


X Y     Finite integers or floats.
        Specify the base position to build the object.

ITEM    Integer.
        The item id to build. Invalid, non-build-able, and blacklisted items are not errors, but will be skipped.

BITS    Optional integer, up to 64 bits wide. Non-zero. Defaults to 1.
        Used to specify repeated item placements along the X+ axis. The least significant bit represents an offset of 0. 
        For instance, a value of 0b101 would place 2 objects with a 1 block gap between.

SHAPE   Optional integer, a valid shape index. Defaults to 0.
        Used to specify the shape when placing a shaped block. Ignored when not placing a shaped block.

It is an error for a build command to place an object outside the bounds specified in the header.
NOTE: The origin of the coordinate system is the CENTER of the lower/left-most block.
Therefore, it is valid to place an objects in these ranges:

    -0.5 <= X <= W - 0.5
    -0.5 <= Y <= H - 0.5

Configuration (1) Command

Sets the active configuration used to build subsequent objects.

[ 1 DATA ]

D       Either a byte array or null.
        A value to use for subsequent object configurations.

If present, the byte array is a wrapper around a configuration message.
Some issues parsing may result in an error, although in many cases the parser will often just fail silently.
The configuration message schema is outside the scope of this document.
The builder stores the active configuration in a variable, which is initially set to null.
The builder will fail silently if it is not able to apply a configuration to an object.
dani - 405 days ago Link

Configuration message schema?

AbestTeaLady - 396 days ago Link

This is a really cool thing to post on, Cogg.

El Capitano Del Marr - 176 days ago - Edited 176 days agoLink

thanks, this helps a lot :)

SkySea - 55 days ago Link

JavaScript implementation:

InterStellar - 55 days ago Link

thank you skysea


Sorry, anonymous users can not post in threads.