NBTs

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 },
    ]
})

Units#

Usefulness#

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.

type	unit	method
float	`'f'`	`NBT.float`
double	`'d'`	`NBT.double`
byte	`'b'`	`NBT.byte`
short	`'s'`	`NBT.short`
long	`'l'`	`NBT.long`
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]}

caution

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}