Resource location

Resource locations (also known as namespaced strings, namespaced identifiers, or resource identifiers ) 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, where only certain characters can be used.

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


 * Built-in registries
 * Attributes
 * Blocks
 * Block entities
 * Fluids
 * Items
 * Entities
 * Mob memories
 * Painting motives
 * Villager professions
 * Villager types
 * Status effects
 * Potion types
 * Enchantments
 * Particles
 * Dimensions
 * Biomes
 * Statistics
 * Recipe types
 * Recipe serializers
 * Sound events


 * Data pack contents
 * Advancements
 * Loot tables
 * Functions
 * Structure files
 * Recipes
 * Block/Fluid/Item/Entity type/Function Tags


 * Add on contents
 * Loot tables
 * Functions


 * Resource pack contents
 * Block state files
 * Models
 * Textures
 * Sounds


 * Other customizable contents
 * Boss bars
 * Command storage


 * Other non-customizable (without mods) contents
 * Loot functions
 * Loot conditions
 * Loot types
 * Command argument types

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


 * Numbers
 * 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.

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.

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

Examples:

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,   becomes the namespace and the whole string becomes the path.

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


 * Examples

Locating contents in packs
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, where all the   (forward slash) symbol (may be part of  or ) is replaced by operating system-dependent directory separator.

Mappings from object type to,  , and   variables

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, , and. Then, we can substitute in and find out the final file location of the content.

Examples

Namespaces
"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 and a mod (or map, or whatever) adds, they're both different s. 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 . This means that and  are the same thing."

- Dinnerbone

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. Without namespaces, these two functions would clash and the minigames would be broken. When they have different namespaces of  and , the functions would become   and  , which no longer conflict.

namespace
Minecraft reserves the  namespace; when a namespace is not specified, a resource location falls back to. As a result, the  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   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. 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.
 * Avoid alphabet soups. For example, a project named "nuclear craft" should not use the namespace, as this is too ambiguous.
 * Avoid words that are too vague.  would not be informative to look up as well, but   would be much better.

Other built-in namespaces
The default resource pack of Minecraft declares Realms-oriented language files in the namespace (located at ) and game-related language files in the  namespace, even though translation keys are not resource locations. The realms jar itself also declares its language file and its various textures in the  namespace.

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