Editing MinecraftCommands (section)

=== Data tags ===

A '''data tag''' is a sequence of text which describes a data structure using [[wikipedia:attribute-value pair|attribute-value pair]]s. Data tags are used in commands to specify complex data for players, entities, and some blocks.

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

:''Example:'' <code>{name1:123,name2:"sometext",name3:{subname1:456,subname2:789}}</code>

The data structures that data tags describe are the same ones used in ''Minecraft'''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):

{| class="wikitable"
|+ Data Structure Specification Links
! Objects
! Examples
|-
| [[Chunk format#Block entity format|Block entities]]
| chests, furnaces, command blocks, mob spawners, signs, etc.
|-
| [[Player.dat#Item structure|Items]]
| items in inventories (includes specifications for enchantments, lore, custom names, etc.)
|-
| [[Chunk format#Items and XPOrbs|Item entities]]
| items on the ground
|-
| [[Chunk format#Mobs|Mobs]]
| creepers, cows, villagers, etc.
|-
| [[Chunk format#Projectiles|Projectiles]]
| arrows, fireballs, thrown potions, etc.
|-
| [[Chunk format#Vehicles|Vehicles]]
| boats, minecarts, etc.
|-
| [[Chunk format#Dynamic Tiles|Dynamic tiles]]
|primed TNT, falling sand/gravel/anvils
|-
| [[Chunk format#Other|Other entities]]
| firework rockets, paintings, and item frames
|}

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

{| class="wikitable"
|+ Data Tags Value Types
! Type
! Description
|-
| {{nbt|byte|Byte}}
| An integer between -128 and 127 (inclusive).
|-
| {{nbt|short|Short}}
| An integer between -32,768 and 32,767 (inclusive).
|-
| {{nbt|int|Int}}
| An integer between -2,147,483,648 and 2,147,483,647 (inclusive).
|-
| {{nbt|long|Long}}
| An integer between -9,223,372,036,854,775,808 and 9,223,372,036,854,775,807 (inclusive).
|-
| {{nbt|float|Float}}<br>{{nbt|double|Double}}
| Numbers which can have a decimal portion (for example, <code>3.14159</code>).
|-
| {{nbt|string|String}}
| A sequence of text, optionally delineated with double quotes.

Double quotes ''must'' be used if the String contains commas, curly brackets, or square brackets. To include a double quote ''inside'' a String, add a backslash before the double quote.

:''Example:'' <code>"Call me \"Ishmael\""</code>
|-
| {{nbt|list|List}}
| A sequence of values, separated by commas and delineated with square brackets. The values must be of the same type, which is dictated by the first value in the sequence.

:''Example:'' <code>[3.2,64.5,129.5]</code>
|-
| {{nbt|int-array|Int Array}}
| A sequence of integers between -2,147,483,648 and 2,147,483,647 (inclusive), separated by commas and delineated with square brackets.
|-
| style="white-space:nowrap" | {{nbt|compound|Compound}}
| A sequence of attribute-value pairs, separated by commas and delineated with curly brackets.

:''Example:'' <code>{X:3,Y:64,Z:129}</code>

Every data tag argument is itself a Compound.
|}

The {{nbt|byte-array|Byte Array}} type is unavailable to commands.<!-- see net/minecraft/server/MojangsonPrimitiveParser in mc-dev -->

Some commands may require that a number's type be specified by adding a letter (B, S, L, F, D) to the end of the value. For example, <code>3s</code> for a short, <code>3.2f</code> for a float, etc. (This doesn't work with I for int.) The letter can be uppercase or lowercase. When no letter is used and Minecraft can't tell the type from context, it assumes double (if there's a decimal point), int (if there's no decimal point and the number is small enough to store as an int), or string (if neither is true). A square-bracketed literal is assumed to be an int array if every element that's between commas is an int; otherwise, it is assumed to be a list. An exception applies: <code>[]</code> is an empty list, but <code>[,]</code> is an empty int array.

When commands such as {{cmd|testfor}}, {{cmd|testforblock}}, and {{cmd|clear}} are used to match data tags, they only check for the presence of the provided tags in the target entity/block/item. This means that the entity/block/item may have additional tags and will still match. This is true even for lists and arrays: the order of a list is not acknowledged, and as long as every requested element is in the list, it will match even if there are additional elements.

The format used for data tags is a [https://google-gson.googlecode.com/svn/trunk/gson/docs/javadocs/com/google/gson/stream/JsonReader.html#setLenient%28boolean%29 lenient] form of [[wikipedia:JSON|JSON]].