Minecraft Wiki
Advertisement
Minecraft Wiki

Resource locations (also known as namespaced IDs, namespaced identifiers, resource identifiers,[1] or namespaced strings[2]) are a way to declare and identify built-in and user-defined game objects in Minecraft without potential ambiguity or conflicts.

Usage[]

Resource locations are used as plain string to reference blocks, items, entity types, recipes, functions, advancements, tags, and various other objects in vanilla Minecraft. Interestingly, block states are not using resource locations.

A valid resource location has a format of namespace:path, where only certain characters can be used.

This is a list of all places that use resource locations:

Built-in registries
Data pack contents‌[Java Edition only]
  • Advancements
  • Loot tables
  • Functions
  • Structure files
  • Recipes
  • Block/Fluid/Item/Entity type/Function Tags
Add on contents‌[Bedrock Edition only]
  • Loot tables
  • Functions
Resource pack contents‌[Java Edition only]
  • Block state files
  • Models
  • Textures
  • Sounds
Other customizable contents‌[Java Edition only]
  • Boss bars
  • Command storage
Other non-customizable (without mods) contents
  • Loot functions
  • Loot conditions
  • Loot types
  • Command argument types

Legal characters[]

Java Edition[]

The namespace and the path of a resource location should only contain the following symbols:

  • 0123456789 Numbers
  • abcdefghijklmnopqrstuvwxyz Lowercase letters
  • _ Underscore
  • - Hyphen/minus
  • . Dot

The following characters are illegal in the namespace, but acceptable in the path:

  • / Forward slash (directory separator)

The preferred naming convention for either namespace or path is snake_case.

Bedrock Edition[]

The namespace and the path of an ID can contain all symbols with the exception of slashes and colons.

The following characters are illegal in the namespace, but acceptable in the path of loot tables and functions.

  • / Forward slash (directory separator)

The preferred naming convention for either namespace or path is snake_case.

Conversion to string[]

A resource location would be converted to a string by appending its namespace with a : (colon) and its path.

Examples:

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

Conversion from string[]

Unlike that resource locations can always be converted to strings, some strings cannot convert to resource locations.

A few restrictions:

  • The string can have at most one : (colon) character
  • The rest of the string must fulfill the requirement of legal characters
  • If the : is present, the part of string before the : (the namespace) must not contain / or .

When the : is present, the part of string before the : becomes the namespace and that after the : becomes the path.

When the : is absent, minecraft becomes the namespace and the whole string becomes the path.‌[Java Edition only]

It is recommended to always include a : in the string format of resource locations.

Examples
String Resolved namespace Resolved path What the game converts it back to
bar:code bar code bar:code
minecraft:zombie minecraft zombie minecraft:zombie
diamond minecraft[Java Edition only]
None‌[Bedrock Edition only]
diamond minecraft:diamond[Java Edition only]
diamond[Bedrock Edition only]
foo/bar:coal Invalid character /
minecraft/villager minecraft[Java Edition only]
None‌[Bedrock Edition only]
minecraft/villager minecraft:minecraft/villager[Java Edition only]
minecraft/villager[Bedrock Edition only]
mypack_recipe minecraft[Java Edition only]
None‌[Bedrock Edition only]
mypack_recipe minecraft:mypack_recipe[Java Edition only]
mypack_recipe[Bedrock Edition only]
mymap:schrödingers_var mymap Invalid character ö[Java Edition only]
schrödingers_var[Bedrock Edition only]
mymap:schrödingers_var[Bedrock Edition only]
custom_pack:Capital custom_pack Invalid character C[Java Edition only]
Capital[Bedrock Edition only]
custom_pack:Capital[Bedrock Edition only]

Locating contents in packs[]

Information icon.svg
This feature is exclusive to Java Edition. 

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

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 resource location, 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.

Namespaces[]

Nathan Adams Mojang avatar.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 namespaces[3]

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.

minecraft namespace[]

Minecraft reserves the minecraft namespace; when a namespace is not specified, a resource location falls back to minecraft[Java Edition only]. 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.

Custom namespace[]

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.

Other built-in namespaces[]

The default resource pack of Minecraft declares Realms-oriented language files in the realms namespace (located at assets/realms/lang/<language-code>.json) and game-related language files in the minecraft namespace, even though translation keys are not resource locations. The realms jar itself also declares its en_us.json language file and its various textures in the realms namespace.

In the IDs of command argument types, a brigadier namespace also appears for command argument types that are native to Brigadier.[4]

History[]

Java Edition
1.6.113w21aAdded resource locations alongside the minecraft prefix for identifying assets.
1.7.213w37aCommands now accept name IDs aside from numerical IDs.
1.1116w32aResource locations now have a character restriction.
Disallowed uppercase characters in resource locations.
1.1317w47aAfter the flattening, resource locations are the only accepted form of identifiers.
pre4Resource locations are now used to identify plugin message channels.[5]
1.14.4pre1The realms namespace is added to the client jar's builtin resource pack.
1.1620w14aAttributes are now resource locations.
Pocket Edition Alpha
0.16.0build 1Added commands, which supported string IDs. However, these identifiers were not namespaced yet.
Bedrock Edition
1.12.0beta 1.12.0.2IDs are now namespaced using the minecraft prefix, to support custom items being added through add-ons.

See also[]

References[]

External links[]

Advertisement