NBTs

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}