NBT Intro

What is NBT?

NBT actually stands for Named Binary Tag, it's the standard Notch developed for the game long ago. The main use of NBT is to store information on blocks, entities and items, for example; entities use NBT to store their equipment, blocks use it to store the items in their inventory and items use it to store things like name and lore.

For more background information on NBT check out the NBT Format page on McWiki

What Does NBT Look Like?

NBT is known as a key-value system, which means the way it stores things is as a key-value pair, you access information via its key and you get the value in return.

The way you read NBT is very simple, a basic example is:

{MyKey:5}

Now, this is referred to as a compound, in the example it only has one key which is MyKey and the value of that is 5. Now of course you can add as many other keys and values as you want:

{MyKey:5,MyOtherKey:"Hello World!"}

The neat part about nbt is that you can put compounds within compounds, literally adding another layer onto what you have already:

{MyKey:5,MyOtherKey:"Hello World!",AnotherKey:{WowLook:"I'm inside a tag!"}}

Datatypes in NBT

Now that you know how to recognize and read nbt, I think we should get into the types of data NBT can use and show some examples of each. Most values are suffixed with a letter that tells you the datatype, such as 1b.

Byte

Likely the most common datatype seen by players, it can only be a whole number and can range from -128 to 127, the game mainly uses this type for boolean states (true/false).

Vanilla example:

{NoGravity:1b}

Float

Less common datatype both seen or used, it ranges from 1.40239846x10^-45 to 3.40282347x10^38.

Vanilla example:

{Health:20.0f}

Double

Less common datatype, ranges from 4.9406564584124654x10^-324 to 1.7976931348623157x10^308.

Vanilla example:

{Motion:[0.0d,0.0d,0.0d]}

Integer

Uncommon datatype, ranges from -2,147,483,648 to 2,147,483,647.

Vanilla example:

{UUID:[I;1514381575,-829078129,-1576973377,-636724600]}

Long

Uncommon datatype, ranges from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

Vanilla example:

{UUIDMost:6504219341755860367L}

Short

Sorta common datatype, ranges from -32,768 to 32,767.

Vanilla example:

{SleepTimer:0s}

String

Very common datatype, used for anything involving items or just text in general.

Vanilla example:

{id:"minecraft:stone"}

Compound

Common datatype, describes an entire compound with any tags inside, common use is for a compound within a compound.

Vanilla example:

{tags:{Damage:0}}

Array

Array can be thought of as just a list of things, in NBT an array can only have 1 datatype inside, meaning you cannot mix datatypes within the same array. Arrays use square brackets [ ] to enclose the data separated with commas.

Vanilla examples:

{Rotation:[0.0f,0.0f]}

Example of an array of floats

{Items:[{id:"minecraft:stone",Count:1b,Slot:0b},{id:"minecraft:dirt",Count:5b,Slot:3b}]}

Example of an array of compounds