Skip to main content


General Syntax#

In Sandstone, NBTs are regular JavaScript objects. JavaScript objects are very close to NBTs: they have arrays, objects, keys and values, numbers and strings.

For example, to summon an invisible armor stand with the "hello" tag and a pumpkin on his head, you would do the following command:

summon('minecraft:armor_stand', rel(0, 0, 0), {
Invisible: 1,
Tags: ["hello"],
ArmorItems: [
{}, {}, {}, { id: "minecraft:carved_pumpkin", Count: 1 },



Despite JavaScript objects and NBTs being close, there is one thing missing from JavaScript objects that is required in NBTs: specifying units.

For example, to summon an armor stand with a given rotation, you need to specify that the values are floats.

With this command, you get the expected result:

/summon minecraft:armor_stand ~ ~ ~ {Rotation: [90.0f, 0.0f]}

Result 90°

Omit the unit, and the armor stand rotation will be wrong:

/summon minecraft:armor_stand ~ ~ ~ {Rotation: [90.0, 0.0]}

Result 90°

Here, specifying that the values are floats is mandatory. However, this isn't possible to do it with a normal JavaScript object.

Unit Syntax#

To specify a unit, you must call the corresponding method under the NBT object. For all units, there are 2 possible calls:

  • With a single number. It will add the given unit to the number.
  • With an array of numbers. It will add the given unit to all numbers in the array.

For example, to summon an armor stand with Invisible: 1b and Rotation: [90f, 0f], you must write:

import { NBT } from 'sandstone'
summon('minecraft:armor_stand', rel(0, 0, 0), {
Invisible: NBT.byte(1), // => Invisible: 1b
Rotation: NBT.float([90, 0]), // => Rotation: [90f, 0f]

All units#

Here is a summary of all units and their corresponding methods.

int array'I;'NBT.integerArray
long array'L;'NBT.longArray

Integer array and Long array are different from arrays of integers and arrays of longs. These types were added recently, and are use in a few specific places. They are represented this way:

{ Test: [I; 0, 1, 2 ] } # Integer array
{ Test: [L; 0, 1, 2 ] } # Long array

Integer arrays are used in custom player heads IDs, and in several Villager NBTs storing locations.

Long arrays are used to store chunk data.

Unit-free Syntax#

Another syntax exists. It's more compact, easier to read, but has absolutely no type safety and no validation. It uses the template string syntax:

import { NBT } from 'sandstone'
summon('minecraft:armor_stand', rel(0, 0, 0), {
Invisible: NBT`1b`, // => Invisible: 1b
Rotation: NBT`[90f, 0f]`, // => Rotation: [90f, 0f]
// => /summon minecraft:armor_stand ~ ~ ~ {Invisible:1b, Rotation:[90f, 0f]}

Please note than no validation is performed. For example, missing a bracket will result in an invalid command.

summon('minecraft:armor_stand', rel(0, 0, 0), {
Rotation: NBT`[90f, 0f`, // Notice the missing square bracket

The above snippet results in the following invalid command:

summon minecraft:armor_stand ~ ~ ~ {Rotation:[90f, 0f}