Minecraft Wiki
Advertisement
Minecraft Wiki

The Named Binary Tag (NBT) format is used by Minecraft for the various files in which it saves data. The format is designed to store data in a tree structure made up of various tags. All tags have an ID and a name.

Another more user-friendly format of NBT is in plain string, as used in commands. This format is referred to as SNBT, short for stringified NBT.

SNBT format[]

Information icon.svg
This feature is exclusive to Java Edition. 

SNBT, also known as data tag, is often used in command in Java Edition. It can be described starting with attribute-value pairs enclosed in curly braces. One common usage of data tags in Java Edition is in commands, used to specify complex data for any entity.

A data tag consists of zero or more attribute-value pairs delimited by commas and enclosed in curly braces. Each attribute-value pair consists of an tag name and the tag's value, separated by a colon. Some values, however, may be a compound tag and themselves contain attribute-value pairs, allowing a data tag to describe a hierarchical data structure.

Example: {name1:123,name2:"sometext1",name3:{subname1:456,subname2:"sometext2"}}

Tag's name can be enclosed with double quotes if necessary.

It is different from the JSON format; hence, any JSON used in NBT, such as raw JSON text, must be enclosed within a string tag.

Format of each type[]

The defined data structures also expect the values to be of the correct type.

Data Tags Value Types
Type Description Format Example
 Byte A signed 8-bit integer, ranging from -128 to 127 (inclusive). <number>b or <number>B 34B, -20b
 Short A signed 16-bit integer, ranging from -32,768 to 32,767 (inclusive). <number>s or <number>S 31415s, -27183s
 Int A signed 32-bit integer, ranging from -2,147,483,648 and 2,147,483,647 (inclusive). <integer_number> 31415926
 Long A signed 64-bit integer, ranging from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807 (inclusive). <number>l or <number>L 31415926l
 Float A 32-bit, single-precision floating-point number, ranging from -3.4E+38 to +3.4E+38.

See IEEE floating point for details.

<number>f or <number>F 3.1415926f
 Double A 64-bit, double-precision floating-point, ranging from -1.7E+308 to +1.7E+308.

See IEEE floating point for details.

<decimal_number>, <number>d or <number>D 3.1415926
 String A sequence of characters, enclosed in quotes. For strings without commas, brackets, braces or spaces, quote enclosure is optional. Quotes can be either single quote ' or double ". Nested quotes can be included within a string by escaping the character with a \ escape. <a-zA-Z0-9 text>, "<text>" (" within needs to be escaped to \"), or '<text>' (' within needs to be escaped to \')

"Call me \"Ishmael\""

'Call me "Ishmael"'

'Call me \'Ishmael\''

"Call me 'Ishmael'"

 List An ordered list of tags, enclosed in square brackets and delimited by commas. The tags must be of the same type, determined by the first tag in the list. [<value>,<value>,...] [3.2,64.5,129.5]
 Compound An ordered list of attribute-value pairs, enclosed in curly braces and delimited by commas.

Each tag can be of any type.

{<tag name>:<value>,<tag name>:<value>,...} {X:3,Y:64,Z:129}
 Byte Array B; followed by an ordered list of 8-bit integers, delimited by commas. Tag is enclosed in square brackets. [B;<byte>b,<byte>B,...] [B;1b,2b,3b]
 Int Array I; followed by an ordered list of 32-bit integers, delimited by commas. Tag is enclosed in square brackets. [I;<integer>,<integer>,...] [I;1,2,3]
 Long Array L; followed by an ordered list of 64-bit integers, delimited by commas. Tag is enclosed in square brackets. [L;<long>l,<long>L,...] [L;1l,2l,3l]
 Boolean A value, expressed as true, false. It is resolved by the game into a  Byte tag as 0b (for false) and 1b (for true). true, false or 0b, 1b {doFoo:true}

NBT object[]

When the game is running, entities and block entities in loading chunks are stored in the memory. They are not stored with NBT, instead, they are just programmatic objects.

When processing NBT operations, the game needs to generate programmatic NBT object from entities/block entities, parse SNBT into NBT object, modify entities/blocks based on provided NBT object, or convert NBT object into SNBT.

Generating NBT object[]

When generating NBT from an entity/block, the entity/block's properties are added into programmatic NBT object.

Note that not all properties are added. For example, the value of whether a player is opening a chest won't be added into NBT object.

A value is added with certain data type. For example, a resource location will be converted to a string value.

These NBT objects will also be stored into game's save files as NBT files when the game quits or automatically saves. So the data structures that NBT tags describe and the data type for each tag are basically the same ones used in game's save files. These data structures are described in other articles and commands expect data tags to use the same attribute names (which are case-sensitive):

Data Structure Specification Links
Objects Examples
Block entities chests, furnaces, command blocks, mob spawners, signs, etc.
Items items in inventories (includes specifications for enchantments, lore, custom names, etc.)
Item entities items on the ground
Mobs creepers, cows, villagers, etc.
Projectiles arrows, fireballs, thrown potions, etc.
Vehicles boats, minecarts, etc.
Dynamic tiles primed TNT, falling sand/gravel/concrete powder/anvils
Other entities firework rockets, paintings, and item frames

Conversion to SNBT[]

Information icon.svg
This feature is exclusive to Java Edition. 

A programmatic NBT object would be converted to a SNBT when trying to get it with /data get etc.

After converted, a number is always followed by a letter (lowercase for b, s, f, d, and uppercase for L) except  Integer. For example, 3s for a short, 3.2f for a float, etc.

And a string is always enclosed by double or single quotes.

Other data types are expressed as the #Format of each type table above.

Conversion from SNBT[]

Information icon.svg
This feature is exclusive to Java Edition. 

An SNBT will be converted to a programmatic NBT object when parsed by the game.

A number that followed by a letter (B, S, L, F, D, or their lowercase) is resolved to corresponding data type. For example, 3s for a short, 3.2f for a float, etc. The letter can be uppercase or lowercase. When no letter is used, it assumes double if there's a decimal point, int if there's no decimal point and the size fits within 32 bits, or string if neither is true.

A square-bracketed literal is assumed to be a list unless an identifier is used: [I;1,2,3] for an int array and [L;1L,2L,3L] for a long array.

true and false are converted as 1b and 0b respectively.

Modifying entity/block based on NBT object[]

Information icon.svg
This feature is exclusive to Java Edition. 

Modifying entity/block based on a programmatic NBT object is not a simple progress. All certain tags need to be resolved before changing properties of a block/entity. Note that only certain properties can be changed. For example, when using /data command to modify a block entity, its coordinates cannot be changed.

If a property needs a value of resource location and gets a  string tag, the string will be converted to a resource location.

If a property needs a value of JSON text and gets a  string tag, the string will be parsed into JSON text object.

If a property needs a numeric value of certain type and gets a numeric tag of wrong type, the number will get some rounding operation and converts to the required type.

If a property needs a numeric value and gets a non-numeric tag, the number will become 0.

If a property needs a string value and gets a non-string tag, the string will become an empty string.

If a property needs a list or array of certain type and gets a wrong-type tag, a empty list/array will be got.

If a property needs a compount tag and gets a non-compount tag, a empty compount tag will be got.

Testing NBT tags[]

Information icon.svg
This feature is exclusive to Java Edition. 

When commands such as /clear, /execute if data are used to match data tags, or nbt argument in target selector tries to target entity, the game converts SNBT into programmatic NBT object and gets programmatic NBT object from block/entity/storage, then compares the two NBT objects.

They check only for the presence of the provided tags in the target entity/block/storage. This means that the entity/block/storage can have additional tags and still match. This is true even for lists: the order and number of elements in an list a list is not considered, and as long as every requested element is in the list, it matches even if there are additional elements. For example, an entity with data {Pos:[1d,2d,3d],Tags:["a","b"]} can be targeted by @e[nbt={Pos:[3d,2d,1d]}] or even just @e[nbt={Pos:[2d]}] even though the former represents a totally different position and the latter is not a valid position at all. Note that @e[nbt={Tags:[]}] can't match it, because an empty list can only match empty list.

However, the order and number of elements in an byte/long/int array is acknowledged.

The requested data tags in the target entity/block/storage must match exactly for the provided tags to pass, including the data type (e.g. 1, an int, will not match 1d, a double). Namespaces also can't omitted because in NBT object it is just a plain string that won't be resolved into a resource location (e.g. @e[nbt={Item:{id:"stone"}}] will not match a stone item entity, it must be @e[nbt={Item:{id:"minecraft:stone"}}]). The same is true for string of JSON text, which must be exactly the same to match the provided tag (e.g. @e[nbt={CustomName:'"a"'}] will not match any entity, it must be @e[nbt={CustomName:"{\"text\":\"a\"}"}] or @e[nbt={CustomName:'{"text":"a"}'}]).

NBT file[]

An NBT file is a zipped Compound tag, with the name and tag ID included. The file in the zip must contain the Compound tag that it is as the first bytes. Some of the files utilized by Minecraft may be uncompressed, but in most cases, the files follow Notch's original specification and are compressed with GZip.

TAG definition[]

A tag is an individual part of the data tree. The first byte in a tag is the tag type (ID), followed by a two byte big-endian unsigned integer for the length of the name, then the name as a string in UTF-8 format (Note TAG_End is not named and does not contain the extra 2 bytes; the name is assumed to be empty). Finally, depending on the type of the tag, the bytes that follow are part of that tag's payload. This table describes each of the 13 known tags in version 19133 of the NBT format:

ID Icon Tag Type Payload Description Storage Capacity
0 TAG_End - Used to mark the end of compound tags. This tag does not have a name, so it is only ever a single byte 0. It may also be the type of empty List tags. N/A
1 TAG_Byte 1 byte / 8 bits, signed A signed integral type. Sometimes used for booleans. Full range of -(27) to (27 - 1)
(-128 to 127)
2 TAG_Short 2 bytes / 16 bits, signed, big endian A signed integral type. Full range of -(215) to (215 - 1)
(-32,768 to 32,767)
3 TAG_Int 4 bytes / 32 bits, signed, big endian A signed integral type. Full range of -(231) to (231 - 1)
(-2,147,483,648 to 2,147,483,647)
4 TAG_Long 8 bytes / 64 bits, signed, big endian A signed integral type. Full range of -(263) to (263 - 1)
(-9,223,372,036,854,775,808 to 9,223,372,036,854,775,807)
5 TAG_Float 4 bytes / 32 bits, signed, big endian, IEEE 754-2008, binary32 A signed floating point type. Precision varies throughout number line;
See Single-precision floating-point format. Maximum value about 3.4*1038
6 TAG_Double 8 bytes / 64 bits, signed, big endian, IEEE 754-2008, binary64 A signed floating point type. Precision varies throughout number line;
See Double-precision floating-point format. Maximum value about 1.8*10308
7 TAG_Byte_Array TAG_Int's payload size, then size TAG_Byte's payloads. An array of bytes. Maximum number of elements ranges between (231 - 9) and (231 - 1) (2,147,483,639 and 2,147,483,647), depending on the specific JVM.
8 TAG_String A TAG_Short-like, but instead unsigned[1] payload length, then a UTF-8 string resembled by length bytes. A UTF-8 string. It has a size, rather than being null terminated. 65,535 bytes interpretable as UTF-8 (see modified UTF-8 format; most commonly-used characters are a single byte).
9 TAG_List TAG_Byte's payload tagId, then TAG_Int's payload size, then size tags' payloads, all of type tagId. A list of tag payloads, without repeated tag IDs or any tag names. Due to JVM limitations and the implementation of ArrayList, the maximum number of list elements is (231 - 9), or 2,147,483,639. Also note that List and Compound tags may not be nested beyond a depth of 512.
10 TAG_Compound Fully formed tags, followed by a TAG_End. A list of fully formed tags, including their IDs, names, and payloads. No two tags may have the same name. Unlike lists, there is no hard limit to the number of tags within a Compound (of course, there is always the implicit limit of virtual memory). Note, however, that Compound and List tags may not be nested beyond a depth of 512.
11 TAG_Int_Array TAG_Int's payload size, then size TAG_Int's payloads. An array of TAG_Int's payloads. Maximum number of elements ranges between (231 - 9) and (231 - 1) (2,147,483,639 and 2,147,483,647), depending on the specific JVM.
12 TAG_Long_Array TAG_Int's payload size, then size TAG_Long's payloads. An array of TAG_Long's payloads. Maximum number of elements ranges between (231 - 9) and (231 - 1) (2,147,483,639 and 2,147,483,647), depending on the specific JVM.

The List and Compound tags can be and often are recursively nested. It should also be noted that, in a list of lists, each of the sub-lists can list a different kind of tag.

Usage[]

Minecraft sometimes uses the NBT format inconsistently; in some instances, empty lists may be represented as a list of Byte tags rather than a list of the correct type, or as a list of End tags in newer versions of Minecraft, which can break some older NBT tools. Additionally, almost every root tag has an empty name string and encapsulates only one Compound tag with the actual data and a name. For instance:

  • The root tag for most Minecraft NBT structures.
    •  SomeName: The only tag contained within the root tag - it has a name and contains all the actual data.

Additionally, there is also inconsistent use of letter case, mostly either camelCase or PascalCase, but sometimes even in all lowercase.

Uses[]

This section is missing information about Bedrock Edition NBTs. 
Please expand the section to include this information. Further details may exist on the talk page.
  • level.dat is stored in compressed NBT format.
  • <player>.dat files are stored in compressed NBT format.
  • idcounts.dat is stored in compressed NBT format.
  • villages.dat is stored in compressed NBT format.
  • raids.dat is stored in compressed NBT format.
  • map_<#>.dat files are stored in compressed NBT format.
  • servers.dat, which is used to store the list of saved multiplayer servers as uncompressed NBT.
  • hotbar.nbt, which is used to save hotbars as uncompressed NBT format.
  • Chunks are stored in compressed NBT format within Region files.
  • scoreboard.dat is stored in compressed NBT format.
  • Generated structures are stored in compressed NBT format.
  • Saved structures are stored in compressed NBT format.

Official software[]

Mojang has provided sample Java NBT classes for developers to use and reference as part of the source code for the MCRegion to Anvil file format converter.[2] Since Java Edition 1.13, Minecraft includes a built-in converter between the SNBT format and compressed NBT format, which comes with both the client and official server.[3]

The data generator from Minecraft is able to convert uncompressed Stringified NBT files with .snbt extension in an input folder to GZip compressed NBT format files with .nbt extension in an output folder, and vice versa.

The vanilla data generator can convert any GZip compressed NBT format to SNBT format. The file extension of a file can simply be changed, such as level.dat to level.nbt and put in the input folder, and the generator then decodes the GZip compressed NBT data.

History[]

The NBT file format was described by Notch in a brief specification.[4]

The original known version was 19132 as introduced in Beta 1.3, and since then has been updated to 19133 with the Anvil file format, which adds the Int Array tag. The NBT format dates all the way back to Indev with tags 0 to 10 in use.

Java Edition
1.0.0September 28, 2011Notch works on "saving arbitrary data with item instances."
1.814w03aNBT data now supports using string IDs rather than numerical IDs.
1.12?Added long array tags.
1.1318w01aAdded a data generator to both the Minecraft client and the default multiplayer software.
1.1419w08a String tags in SNBT can now be within single quotes ' in addition to double quotes ".[5]

References[]

External links[]

  • nbt, a Java library for working with the NBT format.
  • NBT on wiki.vg
  • NBTExplorer, a tool for viewing and editing NBT files.
  • NBT Studio, successor to NBTExplorer that includes additional features like Bedrock support and SNBT.
  • webNBT, an online tool for viewing and editing NBT files.
Advertisement