Minecraft uses the registry system to handle almost everything in the game. For mod developers, you will need to register most content you add to the game. This helps with:

• Letting the game know your content exists
• Verifying game content between client & server
• Handling invalid content in a save
• Preventing conflicts between different mods
• Compression for client ↔ server communication and data saving
• Abstracting or hiding numerical IDs

When registering any type of content, you pass in an Identifier object, which speciied what things should be named for the game. Identifiers, often abbreviated as IDs, have a namespace and path. In most cases, the namespace is the ID of your mod (see terms), and the path is the name of the content you’re registering. The namespace and path cannot contain uppercases or characters in other languages. For example, the ID of vanilla dirt block has the ID of minecraft:dirt.

Using custom content without registering it can lead to buggy behavior, such as missing textures, world save issues, and crashes. The game will usually let you know if you forget to register something.

When registering content, you need to specify which registry you are adding content to. The base game provides registries for all vanilla content, which can be found in Registries (for 1.19.3 and above) or Registry (for below 1.19.3).

Two examples of registries you may use include Registries.ITEM (for 1.19.3 above)/Registry.ITEM (for 1.19.2 below) for items and Registries.BLOCK (for 1.19.3 above)/Registry.BLOCK (for 1.19.2 below) for blocks.

For a deeper overview and description of all available registries, read the registry types page.

Use Registry.register to register your contents into registries. Remember, each content cannot be registered once. The basic syntax is:

    Registry.register(registry, id, content);

• registry - an instance of the registry you want to add content to.
• id - the identifier for your content inside the registry.
• content - an instance of the content you want to register.

For example:

    Registry.register(Registries.ITEM, Identifier.of("tutorial", "example_item", EXAMPLE_ITEM));

Remember: registration should happen in mod initializers. Otherwise, you cannot register as they may have been frozen.

get returns the content associated with an ID inside a registry. If the conten doesn’t exist, SimpleDefaultedRegistry returns the default registry value, and SimpleRegistry returns null. You can use containsId or getOrEmpty method to test whether the id exists. For example:

    Registries.ITEM.containsId(Identifier.ofVanilla("diamond")); // returns true
 
    Registries.ITEM.containsId(Identifier.ofVanilla("invalid_name")); // returns false
 
    Registries.ITEM.get(Identifier.ofVanilla("diamond")); // returns Items.DIAMOND
 
    Registries.ITEM.get(Identifier.ofVanilla("invalid_name")); // returns Items.AIR
 
    Registries.ITEM.getOrEmpty(Identifier.ofVanilla("diamond")); // returns Optiona.of(Items.DIAMOND)
 
    Registries.ITEM.getOrEmpty(Identifier.ofVanilla("invalid_name")); // returns Optional.of()

getId returns the Identifier associated with an entry inside a registry. If the entry doesn’t exist, SimpleDefaultedRegistry returns the default registry ID, and SimpleRegistry returns null. For example:

    Registries.BLOCK.getId(Blocks.STONE);  // returns Identifier.ofVanilla("stone"))