Namespaced ID

From Minecraft Wiki
Jump to: navigation, search
Java Edition.pngMclogo.svg
Grass Block.svg
This page contains content on features that may be included in the next update to Bedrock Edition.
These features have appeared in Bedrock Edition development versions, but the full update containing these features has not been released to Bedrock Edition yet.
This article's name is conjectural.
An official name is yet to be given to the subject matter and may change at any time.

Namespaced identifiers are a way to declare and identify built-in and user-defined game objects in Minecraft without potential ambiguity or conflicts.

Usage[edit]

Namespaced identifiers are used as plain string to reference blocks, items, entity types, recipes, functions, advancements, tags, and various other objects in vanilla Minecraft.

A few examples (including, but not limited to):

A valid namespaced identifier has a format of namespace:name, where only certain characters can be used.

Legal characters[edit]

The namespace and the name of an ID should only contain the following symbols:

  • 0123456789 Numbers
  • abcdefghijklmnopqrstuvwxyz Lowercase letters
  • _ Underscore
  • - Hyphen/minus
  • / Forward slash
    • Directory separator; cannot be used in namespace.
  • . Dot
    • File suffix separator; cannot be used in namespace.

The preferred naming convention for either namespace or name is lower_case_with_underscores.

Conversion to string[edit]

A namespaced ID would be converted to a string by appending its namespace with a : (colon) and its name.

Examples:

Namespace Name String representation
minecraft diamond minecraft:diamond
foo bar.baz foo:bar.baz
minecraftwiki commands/minecraft_wiki minecraftwiki:commands/minecraft_wiki

For tags, in addition, an extra # would be prepended before the namespace.

Examples:

Namespace Name String representation
minecraft coal #minecraft:coal
bar baz #bar:baz
minecraftwiki listener/revert_vandalism #minecraftwiki:listener/revert_vandalism

Conversion from string[edit]

Unlike that namespaced IDs can always be converted to strings, some strings cannot convert to namespaced IDs.

A few restrictions:

  • The string can have at most one : (colon) character
  • When a tag is accepted, the string can optionally have a # in front
  • The rest of the string must fulfill the requirement of legal characters
  • If the : is present, the part of string before the : must not contain / or .

When the : is present, the part of string before the : (excluding the # in front for tags) becomes the namespace and that after the : becomes the name.

When the : is absent, minecraft becomes the namespace and the whole string (excluding the # in front for tags) becomes the name.

It is recommended to always include a : in the string format of namespaced IDs.

Reasons include:

  • This is the only way to specify a namespace other than minecraft
  • It is less confusing: it would be identical when the game converts the ID to a string again, compared ones without a specific namespace having a minecraft namespace added
  • It could help debugging when a wrong format is accidentally used, such as minecraft/villager (resolves to minecraft:minecraft/villager) versus minecraft:villager
  • Though the game would automatically convert prototype strings to namespaced IDs when using /give, /summon, /setblock, etc., the game cannot convert for the nbt target testing, as the NBT test has to match exactly how it’s saved.

A few of the examples below demonstrate the advantage of always including a :.

Examples
String Result Resolved namespace Resolved name What the game converts it back to
bar:code Object bar code bar:code
minecraft:zombie Object minecraft zombie minecraft:zombie
#my_datapack:player-updaters Tag my_datapack player-updaters #my_datapack:player-updaters
#minecraft:load Tag minecraft load #minecraft:load
diamond Object minecraft diamond minecraft:diamond
#tick Tag minecraft tick #minecraft:tick
foo/bar:coal Fail Invalid character /
minecraft/villager Object minecraft minecraft/villager minecraft:minecraft/villager
mypack_recipe Object minecraft mypack_recipe minecraft:mypack_recipe
mymap:schrödingers_var Fail Invalid character ö
#my_pack:Capital Fail Invalid character C

Locating contents in packs[edit]

Given objects from resource packs and data packs are files, the namespaced ID can also be used to find corresponding files that declared objects of the ID.

Though the locations varies by object type and the pack type the object type belongs to, there is a pattern to follow. In general, The location is in a fashion of pack_type/namespace/object_type/name.suffix, where all the / (forward slash) symbol (may be part of object_type or name) is replaced by operating system-dependent directory separator.

Note: Certain elements in the resource pack is not necessarily backed by an object with namespace ID, such as GUI textures.

Given the type of content we want to locate, we can find out the corresponding pack_type, object_type, and suffix. Then, we can substitute in and find out the final file location of the content.

Namespace[edit]

Dinnerbone-twitter.png

This isn't a new concept, but I thought I should reiterate what a "namespace" is. Most things in the game has a namespace, so that if we add something and a mod (or map, or whatever) adds something, they're both different somethings. Whenever you're asked to name something, for example a loot table, you're expected to also provide what namespace that thing comes from. If you don't specify the namespace, we default to minecraft. This means that something and minecraft:something are the same thing.

Dinnerbone on namespace[1]

A namespace is a domain for contents. It is to prevent potential content conflicts or unintentional overrides of object of a same name.

For example, two data packs add two minigame mechanisms to Minecraft; both have a function named start. Without namespaces, these two functions would clash and the minigames would be broken. When they have different namespaces of minigame_one and minigame_two, the functions would become minigame_one:start and minigame_two:start, which no longer conflict.

Custom namespace[edit]

The namespace should be distinct for different projects or content creations (e.g. a data pack, a resource pack, a mod, backing data/resource packs for a custom map, etc.)

To prevent potential clashes, the namespace should be as particular as possible.

  • Avoid alphabet soups. For example, a project named "nuclear craft" should not use the namespace nc, as this is too ambiguous.
  • Avoid words that are too vague. battle_royale would not be informative to look up as well, but player_name_battle_royale would be much better.

In either case, these poorly chosen namespaces reduces the exposure of a project and brings difficulties for debugging when there is multiple content creations applied to the game.

minecraft namespace[edit]

Minecraft reserves the minecraft namespace; when a namespace is not specified, a namespaced ID will fall-back to minecraft. As a result, the minecraft namespace should only be used by content creators when the content needs to overwrite or modify existing Minecraft data, such as adding a function to the #minecraft:load function tag.

History[edit]

Java Edition
??Added namespaced IDs alongside the minecraft prefix.
1.7.2?Commands now accept name IDs aside from numerical IDs.
1.1116w32aNamespaced IDs now have a character restriction.
Disallowed uppercase characters in namespaced IDs.
1.1317w47aAfter the flattening, nominal IDs are the only accepted form of ID.
Numerical IDs are removed.
Upcoming Bedrock Edition
1.12.0beta 1.12.0.2Added namespaced IDs alongside the minecraft prefix to support custom items being added through add-ons.

See also[edit]

References[edit]

  1. "Minecraft Snapshot 17w43a" – Minecraft.net

External links[edit]