NBT format

From Minecraft Wiki
Jump to: navigation, search
This article is about the NBT file format. For using NBT in commands, see Tutorials/Command NBT tags.

The Named Binary Tag (NBT) format is used by Minecraft for the various files in which it saves data. The format is described by Notch in a brief specification.[1] The format is designed to store data in a tree structure made up of various tags. All tags have an ID and a name. 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.

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. 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.

TAG definition[edit]

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). The name of tags may contain spaces, although Minecraft itself never saves tags with spaces in the names. 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 SNBT Format‌[JE only] Description Storage Capacity
0 TAG_End None. - 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 <number>b or <number>B 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 <number>s or <number>S 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 <number> 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 <number>l or <number>L 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 <number>f or <number>F 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 <decimal number>, <number>d or <number>D 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. [B;<byte>,<byte>,...] 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 TAG_Short's payload length, then a UTF-8 string with size length. <a-zA-Z0-9 text>, "<text>" (" within needs to be escaped to \"), or '<text>' (' within needs to be escaped to \') A UTF-8 string. It has a size, rather than being null terminated. 32,767 bytes interpretable as UTF-8 (see 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. [<value>,<value>,...] 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. {<tag name>:<value>,<tag name>:<value>,...} 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. [I;<integer>,<integer>,...] 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. [L;<long>,<long>,...] 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.

File format[edit]

An NBT file is a zipped Compound tag, with the name and tag ID included. 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.

Usage[edit]

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, although the original specification by Notch allows for spaces in tag names, and even the example uses spaces in the tag names, Minecraft has no known files where any tags have spaces in their names. There is also inconsistent use of letter case, mostly either camelCase or PascalCase, but sometimes even in all lowercase.

Uses[edit]

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.

Official software[edit]

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[edit]

Java Edition
1.0.0September 28, 2011Notch works on "saving arbitrary data with item instances."
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 ".[4]

References[edit]

External links[edit]

  • NBT on wiki.vg
  • NBTExplorer, a tool for viewing and editing NBT files.
  • webNBT, an online tool for viewing and editing NBT files.