NBTs

General Syntax

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

For example, summoning an invisible armor stand with the "hello" tag and a pumpkin on his head simply is:

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

Units

Despite JavaScript objects and NBTs being close, there is one thing missing from JavaScript objects: NBT units. For example, the Rotation tag needs explicit units.

Sandstone provides two ways of specifying units:

The Unit Syntax is type-safe, but verbose

The Unit-free Syntax is more readable, but not type-safe

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', '~ ~ ~', {
  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', '~ ~ ~', {
  Invisible: NBT`1b`,       // => Invisible: 1b
  Rotation: NBT`[90f, 0f]`, // => Rotation: [90f, 0f]
})
// => /summon minecraft:armor_stand ~ ~ ~ {Invisible:1b, Rotation:[90f, 0f]}

⚠️

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

summon('minecraft:armor_stand', '~ ~ ~', {
  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}