Commands/data
Restrictions | |
---|---|
First introduced |
The /data
command allows the user to get, merge, modify, and remove NBT data of a block entity, entity, or Command NBT storage.
Syntax[edit]
There are four instructions for /data
(get
, merge
, modify
, remove
), and the targets/sources referenced by each instruction command may be either block <targetPos>
, entity <target>
, or storage <target>
.
/data ...
... get
... (block <targetPos>|entity <target>|storage <target>) [<path>] [<scale>]
- Read off the entire NBT data or the subsection of the NBT data from the targeted block position or entity to the executor with syntax highlighting, scaled by <scale> if specified.
... merge
... (block <targetPos>|entity <target>|storage <target>) <nbt>
- Merge the NBT data from the sourced block position or entity with the specified
<nbt>
data.
- Merge the NBT data from the sourced block position or entity with the specified
... modify (block <targetPos>|entity <target>|storage <target>) <targetPath> ...
... append from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... append value <value>
- Append the source data onto the end of the pointed-to list.
... insert <index> from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... insert <index> value <value>
- Insert the source data into the pointed-to list as element
<index>
, then shift higher elements one position upwards.
- Insert the source data into the pointed-to list as element
... merge from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... merge value <value>
- Merge the source data into the pointed-to object.
... prepend from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... prepend value <value>
- Prepend the source data onto the beginning of the pointed-to list.
... set from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
... set value <value>
- Set the tag specified by
<targetPath>
to the source data.
- Set the tag specified by
... remove
... (block <targetPos>|entity <target>|storage <target>) <path>
- Removes NBT data at
<path>
from the targeted block position or entity. Player NBT data cannot be removed.
- Removes NBT data at
Syntax displayed in various ways
Simplified tree: /data
- where substituted arguments are:
<TARGET>
=(block <targetPos> | entity <target> | storage <target>)
<MODIFICATION>
=(append|insert <index>|merge|prepend|set)
<SOURCE>
=(block <sourcePos> | entity <source> | storage <source>)
Squished tree: /data
… get (block <targetPos>|entity <target>|storage <target>) [<path>] [<scale>]
… merge (block <targetPos>|entity <target>|storage <target>) <nbt>
… modify (block <targetPos>|entity <target>|storage <target>) <targetPath> (append|insert <index>|merge|prepend|set)
… from (block <sourcePos>|entity <source>|storage <source>) [<sourcePath>]
… value <value>
… remove (block <targetPos>|entity <target>|storage <target>) <path>
Maximised: data get block <targetPos> [<path>] [<scale>]
data get entity <target> [<path>] [<scale>]
data get storage <target> [<path>] [<scale>]
data merge block <targetPos> <nbt>
data merge entity <target> <nbt>
data merge storage <target> <nbt>
data modify block <targetPos> <targetPath> append from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> append from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> append from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> append value <nbt>
data modify block <targetPos> <targetPath> insert index> from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> insert <index> from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> insert <index> from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> insert <index> value <nbt>
data modify block <targetPos> <targetPath> merge from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> merge from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> merge from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> merge value <nbt>
data modify block <targetPos> <targetPath> prepend from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> prepend from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> prepend from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> prepend value <nbt>
data modify block <targetPos> <targetPath> set from block <sourcePos> <sourcePath>
data modify block <targetPos> <targetPath> set from entity <source> <sourcePath>
data modify block <targetPos> <targetPath> set from storage <source> <sourcePath>
data modify block <targetPos> <targetPath> set value <nbt>
data modify entity <target> <targetPath> append from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> append from entity <source> <sourcePath>
data modify entity <target> <targetPath> append from storage <source> <sourcePath>
data modify entity <target> <targetPath> append value <value>
data modify entity <target> <targetPath> insert <index> from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> insert <index> from entity <source> <sourcePath>
data modify entity <target> <targetPath> insert <index> from storage <source> <sourcePath>
data modify entity <target> <targetPath> insert <index> value <value>
data modify entity <target> <targetPath> merge from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> merge from entity <source> <sourcePath>
data modify entity <target> <targetPath> merge from storage <source> <sourcePath>
data modify entity <target> <targetPath> merge value <value>
data modify entity <target> <targetPath> prepend from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> prepend from entity <source> <sourcePath>
data modify entity <target> <targetPath> prepend from storage <source> <sourcePath>
data modify entity <target> <targetPath> prepend value <value>
data modify entity <target> <targetPath> set from block <sourcePos> <sourcePath>
data modify entity <target> <targetPath> set from entity <source> <sourcePath>
data modify entity <target> <targetPath> set from storage <source> <sourcePath>
data modify entity <target> <targetPath> set value <value>
data modify storage <target> <targetPath> append from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> append from entity <source> <sourcePath>
data modify storage <target> <targetPath> append from storage <source> <sourcePath>
data modify storage <target> <targetPath> append value <value>
data modify storage <target> <targetPath> insert <index> from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> insert <index> from entity <source> <sourcePath>
data modify storage <target> <targetPath> insert <index> from storage <source> <sourcePath>
data modify storage <target> <targetPath> insert <index> value <value>
data modify storage <target> <targetPath> merge from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> merge from entity <source> <sourcePath>
data modify storage <target> <targetPath> merge from storage <source> <sourcePath>
data modify storage <target> <targetPath> merge value <value>
data modify storage <target> <targetPath> prepend from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> prepend from entity <source> <sourcePath>
data modify storage <target> <targetPath> prepend from storage <source> <sourcePath>
data modify storage <target> <targetPath> prepend value <value>
data modify storage <target> <targetPath> set from block <sourcePos> <sourcePath>
data modify storage <target> <targetPath> set from entity <source> <sourcePath>
data modify storage <target> <targetPath> set from storage <source> <sourcePath>
data modify storage <target> <targetPath> set value <value>
data remove block <targetPos> <path>
data remove entity <target> <path>
data remove storage <target> <path>
Arguments[edit]
<targetPos>
: block_pos
- It must be a block position composed of <x>, <y> and <z>, each of which must be an integer or tilde and caret notation.
- The position of the target block entity whose NBT is to be operated on.
<target>
: entity (in entity <target>
mode)
- Must be a player name, a target selector or a UUID. And the target selector must be of single type.
- Speciafies an entity whose NBT is to be operated on.
<target>
: resource_location (in storage <target>
mode)
- Must be a namespaced ID.
- Specifies a storage to be operated on.
<path>
: nbt_path
- Must be an NBT path.
- Specifies the NBT to retrieve or remove.
<scale>
: double
- Must be a Double-precision floating-point format number.
- Scalar for the command's return value.
<nbt>
: nbt_compound_tag
- Must be a Double-precision floating-point format number.
- Specifies a compound tag to be merged into somewhere.
<targetPath>
: nbt_path
- Must be an NBT path.
- Specifies target NBT to modify.
<index>
: integer
- Must be a 32-bit integer number. And it must be between -2147483648 and 2147483647 (inclusive).
- Specifies an item's index within a list.
<sourcePos>
: block_pos
- It must be a block position composed of <x>, <y> and <z>, each of which must be an integer or tilde and caret notation.
- The position of the target block entity whose NBT is to be used.
<sourceEntity>
: entity
- Must be a player name, a target selector or a UUID. And the target selector must be of single type.
- Speciafies an entity whose NBT is to be used by
modify
.
<sourceStorage>
: resource_location
- Must be a namespaced ID.
- Specifies a storage to be used by
modify
.
<sourcePath>
: nbt_path
- Must be an NBT path.
- Specifies the source NBT to be used by
modify
.
<value>
: nbt_tag
- Must be an NBT tag of any type in SNBT format.
- Value used in modifying the target NBT. Should match in data type.
Result[edit]
Command | Trigger | Java Edition |
---|---|---|
any | the arguments are not specified correctly | Unparseable |
if <targetPos> is unloaded or out of the world | Failed | |
if the block at <targetPos> is not a block entity | ||
if <target> (in entity <target> mode) fails to resolve to an entity (named player must be online) | ||
/data get ... | if more than one tag is got | |
/data get ... <path> | if <path> does not exist | |
/data get ... <path> <scale> | if the obtained tag is not a numeric tag | |
/data merge ... | if nothing is changed | |
try to edit player's data | ||
/data remove ... | if <path> is {} (the root tag) | |
/data modify ... from block ... | if <sourcePos> is unloaded or out of the world | |
if the block at <sourcePos> is not a block entity | ||
/data modify ... from entity ... | if <sourceEntity> fails to resolve to an entity (named player must be online) | |
/data modify ... from ... <sourcePath> | if <sourcePath> does not exist | |
/data modify ... append ... | if the target tag isn't a list or array | |
if source data isn't of an item type appropriate for the list | ||
/data modify ... insert <index> ... | if the index is invalid | |
/data modify ... merge ... | if the target path does not specify a compound tag | |
if the source data is not a compound tag | ||
any | On success | Get, merge, modify, and remove NBT data. |
Output[edit]
Command | Edition | Situation | Success Count | /execute store success ... | /execute store result ... |
---|---|---|---|---|---|
any | Java Edition | On fail | 0 | 0 | 0 |
/data get ... | On success | 1 | 1 | 1 | |
/data get ... <path> | if a numeric tag is got | 1 | 1 | the obtained value after rounding down[1] | |
if a list or array tag is got | 1 | 1 | The number of elements in this list or array | ||
if a string tag is got | 1 | 1 | The length of the string | ||
if a compound tag is got | 1 | 1 | The number of tags that are direct children of that compound | ||
/data get ... <path> <scale> | On success | 1 | 1 | the obtained value multiplied by <scale> , then rounded down[2] | |
/data merge ... | On success | 1 | 1 | 1 | |
/data remove ... | On success | 1 | 1 | 1 | |
/data modify ... append ... | On success | 1 | 1 | the number of lists or arrays to which new elements are added | |
/data modify ... set ... | On success | 1 | 1 | the number of target tags that was successfully modified | |
/data modify ... merge ... | On success | 1 | 1 | the number of target compound tags that was successfully modified |
Examples[edit]
- To make the nearest item within 10 blocks unable to be picked up by players:
/data modify entity @e[type=item,distance=..10,limit=1,sort=nearest] PickupDelay set value -1
- To get the Y-position of a random item:
/data get entity @e[type=item,limit=1,sort=random] Pos[1]
- To get the item ID of the item in the first hotbar slot of the nearest player:
/data get entity @p Inventory[{Slot:0b}].id
- To set the armor attribute of the dolphin closest to coordinates (0, 64, 0) to 20:
/data modify entity @e[x=0,y=64,z=0,type=dolphin,limit=1] Attributes[{Name:"generic.armor"}].Base set value 20
- To change the first item in a chest located at coordinates (1, 64, 1) into a diamond block, keeping all NBT data:
/data modify block 1 64 1 Items[0].id set value "minecraft:diamond_block"
Storage[edit]
The command storage of NBT data is an efficient way for commands to access or save NBT data without an overhead for block entities or entities reading from or writing to the NBT data.
Each command storage is a general purpose, key-value storage, identified by a namespaced ID to prevent unintentional conflicts.
/data get
and /data modify
can read from the storage, while /data merge
, /data modify
, /data remove
, and /execute store
can write to the storage.
The command storage is accessible with JSON text as well.
History[edit]
Java Edition | |||||
---|---|---|---|---|---|
1.13 | 17w45b | Added /data . | |||
17w47a | Commands /blockdata and /entitydata have been removed as their features are merged into /data . | ||||
18w03a | Using /data get with a path now works on non-numeric values. | ||||
1.14 | 18w43a | Added /data modify . | |||
1.15 | 19w38a | Added command storage. | |||
Added storage <namespaced ID> as a source or target. | |||||
19w39a | Added NBT storage chat component. |