An NBT path is a descriptive label used to specify a collection of particular elements from an NBT data tree. A path has the general form node.….node, where each node declares what types of sub-elements can be chosen from a previous tag.
Node
These are all seven types of nodes available.
The tags collection start with only one element (i.e. the root tag) and changes along the nodes on the path. NBT path consumers operate on the final collection of the tags.
| Name | Format | Description | Selection Result | Example | Example Description |
|---|---|---|---|---|---|
| Root Compound Tag | {tag}, where tag is the compound NBT content and can be empty.
|
Selects the starting tag only if it matches the compound NBT content tag (if given). Only applicable as the first element in the path. |
The starting tag, or nothing if matching fails. | {Invisible:1b}
|
Selects the root tag if it has a subtag Invisible with value 1.
|
{}
|
Selects the root tag. | ||||
| Named Tag | name, where name can be a plain or an escaped string
|
Selects the subtags named name in the previous tags. | A collection of tags; no more elements than the previous tag collection. May be nothing. | VillagerData
|
Selects the VillagerData subtag. |
"A cool name[]"
|
Selects the A cool name[] subtag. | ||||
| Named Compound Tag | name{tag}, where name can be a plain or an escaped string, and tag is the compound NBT content which can be empty.
|
Selects the sub compound tags matching the compound NBT content tag (if given) that are named name in the previous tags. | A collection of compound tags; no more elements than the previous tag collection. May be nothing. | VillagerData{profession:"minecraft:nitwit"}
|
Select the VillagerData tag only if it has a subtag profession with value minecraft:nitwit.
|
VillagerData{}
|
Selects the VillagerData tag if it is a compound tag. | ||||
| Element of Named List or Array Tag | name[index], where name can be a plain or an escaped string and index is an integer.
|
Selects elements at index (or listLength + index if index is negative) of the lists (or array) named name in the previous tags.
|
A collection of tags; no more elements than the previous tag collection. May be nothing. | Pos[0]
|
Selects the first child tag in the "Pos" sublist (or array). |
Inventory[-1]
|
Selects the last child tag in the "Inventory" sublist (or array). | ||||
| All Elements of Named List or Array Tag | name[]
|
Selects all elements of the sub-lists (or array) named name in the previous tags. | A collection of tags; may have more elements than the previous tag collection. May be nothing. | ActiveEffects[]
|
Select all the elements in the "ActiveEffects" subtag of the last tag. |
| Compound Elements of Named List Tag | name[{tag}], where name can be a plain or an escaped string and tag is the compound NBT content which can be empty.
|
Selects the compound elements matching the compound NBT content tag (if given) within the lists named name in the previous tags. | A collection of compound tags; may have more elements than the previous tag collection. May be nothing. | Inventory[{Count:25b}]
|
Select the elements of Inventory tag that have a subtag Count with value 25.
|
Foo[{}]
|
Selects the elements of Foo tag. | ||||
| Elements of Sub-List (or Array) of Named List Tag | name[index or blank][index or blank][index or blank]......[index or tag], where name can be a plain or an escaped string, index is an integer, and tag is the compound NBT content which can be empty.
|
Selects the child elements of the child elements in the lists named name in the previous tags. | A collection of tags; may have more elements than the previous tag collection. May be nothing. | foo[][{}]
|
Select the elements of the sub-lists in foo tag. |
foo.bar[0][0].baz
|
Select the baz tag in the first element of the first element of the bar list in the foo tag. |
In the path, . (dot/period) characters separate the nodes. The nodes can be mixed and matched, except the root node with object must be the first in the path when it is present.
Name escaping
The valid character set (without quote) for a path seems to be all non-whitespace characters, as long as any opening brackets and braces ([ and {) are closed and at the end of each term (that is, followed by nothing but a period or the end of the path—. or ). That being said, the "reasonable character set" for defining a data tag includes all ASCII lowercase and uppercase letters, digits, underscore, period, and square and curly brackets (Regular expression: [a-zA-Z0-9_\.[\]{}]*)
Quoted strings, such as "Lorem ipsum", may be used if a name of a key needs to be escaped.
Examples
Mixed path
{}—Specifies the root tag{foo:4.0f}—Specifies the root tag if the "foo" subtag is set to4.0ffoo—Specifies the tag named "foo" under the root tagfoo.barorfoo{}.bar—Specifies foo's subtag named "bar".foo.bar[0]—Specifies the first element of the list (or array) "bar"foo.bar[-1]—Specifies the last element of the list (or array) "bar"foo.bar[0]."A [crazy name]!"—Specifies the subtag named "A [crazy name]!" under that first elementfoo.bar[0]."A [crazy name]!".baz—Specifies the subtag named "baz" under that crazily named tagfoo.bar[]—Specifies all elements of the list (or array) "bar"foo.bar[].baz—Specifies the subtags named "baz" under all elements of the list "bar"foo.bar[{baz:5b}]—Specifies all elements of the list "bar", in which the "baz" tag is set to5bfoo{bar:"baz"}—Specifies the "foo" tag if its subtag "bar" has the value"baz"foo{bar:"baz"}.bar—Specifies the "bar" tag if it matches the value"baz"
Example 1
/data get entity @p foo.bar[0]."A [crazy name]!".baz
These names have been arbitrarily picked, for demonstrative purposes.
foo—Specifies the subtag named "foo" under the root tag.foo.bar—Specifies foo's child named "bar".foo.bar[0]—Specifies the first element of the list "bar"foo.bar[0]."A [crazy name]!"—Specifies the child named "A [crazy name]!" under that first elementfoo.bar[0]."A [crazy name]!".baz—Specifies the child named "baz" under that crazily named element
The tree structure
- The root entity data
- foo: The "foo" element
- bar: The "bar" element
- The first element of list "bar"
- A [crazy name]!: The "A [crazy name]!" element
- baz: The "baz" element; the target element of this example.
- A [crazy name]!: The "A [crazy name]!" element
- Another unrelated element in list "bar"
- The first element of list "bar"
- bar: The "bar" element
- foo: The "foo" element
Example 2
/data get block ~ ~ ~ Items[1].tag.pages[3]
A player has written a book and placed it inside a chest at their feet, and are going to work up to the above command in stages. Observe the following imaginary chat log:
Chat log * Alex jumps on top of a chest. * Alex runs the command: /data get block ~ ~ ~ 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex only wants to look at the chest's inventory. They could search the Official Minecraft Wiki for what the name of that tag is, but because they understand how to read NBT format they decide to figure it out from that last command's output. * Alex runs the command: /data get block ~ ~ ~ Items 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants to narrow this down to the second item in the chest. Counting from 0, the second item would be element 1. * Alex runs the command: /data get block ~ ~ ~ Items[1] 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the "tag" tag. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the "pages" tag. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag.pages 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex wants just the fourth element from this list. * Alex runs the command: /data get block ~ ~ ~ Items[1].tag.pages[3] 0 55 0 has the following block data: {x: 0, y: 55, z: 0, Items: [{Slot: 0b, id: "minecraft:clock", Count: 1b}, {Slot: 9b, id: "minecraft:written_book", Count: 1b, tag: {pages: ['{"text":"\'twas brillig and the slithy toves"}', '{"text":"Did gyre and gimble in the wabe."}', '{"text":"All mimsy were the borogoves,"}', '{"text":"And the mome raths outgrabe."}'], author: "LewisCarroll", title: "Jabberwocky"}}], id: "minecraft:chest"} * Alex has what they need now, and uses the paths they have gathered to edit the book from outside the chest. * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.pages[3] set value '{"text":"And this pig here\'s named Babe."}' Modified block data of 0 55 0 * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.pages prepend value '{"text":"Call me Ishmael."}' Modified block data of 0 55 0 * Alex runs the command: /data modify block ~ ~ ~ Items[1].tag.author set value "Cthulhu the Sleeper"