Registration

This page is under construction.

This page is incomplete, and needs more work. Feel free to edit and improve this page!

Registration is the process of making an object (such as an item or block) known to the game during runtime. If some objects are not registered, this could cause crashes even before the game is fully loaded or arbitrary behaviors such as bottlenecking mod compatibility for world generation.

Most objects that are known within the game are handled by a Registry. Each registry uniquely defines each object through a "registry name" via a ResourceLocation. This "registry name" can be accessed with its respective getter and setter: #getRegistryName and #setRegistryName. You can only set the "registry name" of a given object once; otherwise, an exception will be thrown.

In a global context, each object is universally unique through its ResourceKey: a concatenation of its registry's id and the object's registry name.

Due to the inconsistent ordering and registration process vanilla uses, Forge wraps most vanilla registries using IForgeRegistry. This guarantees that the loading order for these wrapped registries will be Block, Item, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the ForgeRegistries class. Since all registry names are unique to a specific registry, different registry objects within different registries can have the same name (e.g. a Block and an Item each hold a registry object named examplemod:object.

Warning

If two registry objects within the same registry have the same name, the second object will override the first. The only registry that will throw an IllegalArgumentException is the DataSerializerEntry registry.

Methods for Registering

Referencing Registered Objects

Each forge registered object should not be statically initialized nor reference another instance being registered. They must always be a new, singleton instance that is resolved during their respective RegistryEvent$Register event. This is to maintain a sane loading order for registries and their objects along with dynamic loading/unloading of mods.

Forge registered objects must always be referenced through a RegistryObject or a field with @ObjectHolder.

Using RegistryObjects

RegistryObjects can be used to retrieve references to registered objects once they become available. Their references are updated along with all @ObjectHolder annotations after the associated RegistryEvent$Register has been dispatched and frozen.

A RegistryObject can be retrieved as a result of using DeferredRegister or calling the static constructor RegistryObject::of. Each static constructor takes in the "registry name" of the object being referenced and either a IForgeRegistry or, if custom registries are used, a supplier of the object class implementing IForgeRegistryEntry. The RegistryObject can be stored within some field and retrieve the registered object using #get.

An example using RegistryObject:

JavaKotlinScala

public static final RegistryObject<Item> EXAMPLE_ITEM = RegistryObject.of(new ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS);

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
public static final RegistryObject<ExampleRegistry> EXAMPLE_OBJECT = RegistryObject.of(new ResourceLocation("examplemod", "example_object"), () -> ExampleRegistry.class);

val EXAMPLE_ITEM: RegistryObject<Item> = RegistryObject.of(ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS)

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
val EXAMPLE_OBJECT: RegistryObject<ExampleRegistry> = RegistryObject.of(ResourceLocation("examplemod", "example_object")) { ExampleRegistry.class }

final val EXAMPLE_ITEM = RegistryObject.of(new ResourceLocation("examplemod:example_item"), ForgeRegistries.ITEMS)

// Assume that 'ExampleRegistry' is a valid registry, and 'examplemod:example_object' is a valid object within that registry
final val EXAMPLE_OBJECT = RegistryObject.of(new ResourceLocation("examplemod", "example_object"), () => classOf[ExampleRegistry]);

Important

All vanilla objects are bootstrapped and registered before mods are loaded. As such, they can be referenced as is without any issues, assuming the entries are not replaced.

Using @ObjectHolder

Forge registry objects can also be injected into public static fields with either their class or that field annotated with @ObjectHolder. There must be enough information to construct a ResourceLocation to identify a single object within a specific registry.

The rules for @ObjectHolder are as follows:

If the class is annotated with @ObjectHolder, its value will be the default namespace for all fields within if not explicitly defined
If the class is annotated with @Mod, the modid will be the default namespace for all annotated fields within if not explicitly defined
A field is considered for injection if:
- it has at least the modifiers public static; and
- one of the following conditions are true:
  - the enclosing class has an @ObjectHolder annotation, and the field is final, and:
    - the name value is the field's name; and
    - the namespace value is the enclosing class's namespace
    - An exception is thrown if the namespace value cannot be found and inherited
  - the field is annotated with @ObjectHolder, and:
    - the name value is explicitly defined; and
    - the namespace value is either explicitly defined or the enclosing class's namespace
- the field type or one of its supertypes corresponds to a valid registry (e.g. Item or ArrowItem for the Item registry)
- An exception is thrown if a field does not have a corresponding registry.
An exception is thrown if the resulting ResourceLocation is incomplete or invalid (non-valid characters in path)
If no other errors or exceptions occur, the field will be injected
If all of the above rules do not apply, no action will be taken (and a message may be logged)

@ObjectHolder annotated fields are injected with their associated object values after their corresponding registry's RegistryEvent$Register event is fired, along with RegistryObjects.

Warning

If the object does not exist in the registry when it is to be injected, a debug message will be logged, and no value will be injected. If the object is found, but the field cannot be set, a warning message will be logged instead.

As these rules are rather complicated, here are some examples:

Example uses of @ObjectHolder

@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
class AnnotatedHolder {
    public static final Block diamond_block = null;   // No annotation. [public static final] is required.
                                                      // Block has a corresponding registry: [Block]
                                                      // Name path is the name of the field: "diamond_block"
                                                      // Namespace is not explicitly defined.
                                                      // So, namespace is inherited from class annotation: "minecraft"
                                                      // To inject: "minecraft:diamond_block" from the [Block] registry

    @ObjectHolder("ambient.cave")
    public static SoundEvent ambient_sound = null;    // Annotation present. [public static] is required.
                                                      // SoundEvent has a corresponding registry: [SoundEvent]
                                                      // Name path is the value of the annotation: "ambient.cave"
                                                      // Namespace is not explicitly defined.
                                                      // So, namespace is inherited from class annotation: "minecraft"
                                                      // To inject: "minecraft:ambient.cave" from the [SoundEvent] registry

    // Assume for the next entry that [ManaType] is a valid registry.          
    @ObjectHolder("neomagicae:coffeinum")
    public static final ManaType coffeinum = null;    // Annotation present. [public static] is required. [final] is optional.
                                                      // ManaType has a corresponding registry: [ManaType] (custom registry)
                                                      // Resource location is explicitly defined: "neomagicae:coffeinum"
                                                      // To inject: "neomagicae:coffeinum" from the [ManaType] registry

    public static final Item ENDER_PEARL = null;      // No annotation. [public static final] is required.
                                                      // Item has a corresponding registry: [Item].
                                                      // Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
                                                      // !! ^ Field name is valid, because they are
                                                      //      converted to lowercase automatically.
                                                      // Namespace is not explicitly defined.
                                                      // So, namespace is inherited from class annotation: "minecraft"
                                                      // To inject: "minecraft:ender_pearl" from the [Item] registry

    @ObjectHolder("minecraft:arrow")
    public static final ArrowItem arrow = null;       // Annotation present. [public static] is required. [final] is optional.
                                                      // ArrowItem does not have a corresponding registry.
                                                      // ArrowItem's supertype of Item has a corresponding registry: [Item]
                                                      // Resource location is explicitly defined: "minecraft:arrow"
                                                      // To inject: "minecraft:arrow" from the [Item] registry                                                    

    public static Block bedrock = null;               // No annotation, so [public static final] is required.
                                                      // Therefore, the field is ignored.
    
    public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
                                                      // CreativeModeTab does not have a corresponding registry.
                                                      // No supertypes of CreativeModeTab has a corresponding registry.
                                                      // Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
    @ObjectHolder("minecraft:flame")
    public static final Enchantment flame = null;     // Annotation present. [public static] is required. [final] is optional.
                                                      // Enchantment has corresponding registry: [Enchantment].
                                                      // Resource location is explicitly defined: "minecraft:flame"
                                                      // To inject: "minecraft:flame" from the [Enchantment] registry

    public static final Biome ice_flat = null;        // No annotation on the enclosing class.
                                                      // Therefore, the field is ignored.

    @ObjectHolder("minecraft:creeper")
    public static Entity creeper = null;              // Annotation present. [public static] is required.
                                                      // Entity does not have a corresponding registry.
                                                      // No supertypes of Entity has a corresponding registry.
                                                      // Therefore, THIS WILL PRODUCE AN EXCEPTION.

    @ObjectHolder("levitation")
    public static final Potion levitation = null;     // Annotation present. [public static] is required. [final] is optional.
                                                      // Potion has a corresponding registry: [Potion].
                                                      // Name path is the value of the annotation: "levitation"
                                                      // Namespace is not explicitly defined.
                                                      // No annotation in enclosing class.
                                                      // Therefore, THIS WILL PRODUCE AN EXCEPTION.
}

Creating Custom Registries

Creating custom registries for your mod might be useful if you want other mods to add new things to your system. For example, you might have magic spells and want to allow other mods to add new spells. For this you will want to make a registry (eg. "mymagicmod:spells"). This way, other mods will be able to register things to that list, and you won't have to do anything else.

Just like with registering a new item or block you have two ways of making a new registry. Each method takes in a RegistryBuilder which is used to build an IForgeRegistry for an object class that implements IForgeRegistryEntry. Each builder should have its name and type set via #setName and #setType respectively before being created.

For the class that implements IForgeRegistryEntry, it is recommended in most cases to extend the default implementation of ForgeRegistryEntry. For interfaces, it should extend IForgeRegistryEntry with its implementations extending ForgeRegistryEntry.

With DeferredRegister

The first method involves the second static constructor: DeferredRegister::create(Class, String). The class supplied must extend IForgeRegistryEntry. From there, we can construct the registry using #makeRegistry. This will already populate #setName and #setType for us. This method also returns a supplier of the registry which we can use after the RegistryEvent$NewRegistry event.

Here is an example:

JavaKotlinScala

public static final DeferredRegister<ExampleRegistry> EXAMPLE = DeferredRegister.create(ExampleRegistry.class, MODID);

public static final Supplier<IForgeRegistry<ExampleRegistry>> REGISTRY = EXAMPLE.makeRegistry("example_registry", RegistryBuilder::new);

val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ExampleRegistry::class.java, MODID)

val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
    EXAMPLE.makeRegistry("example_registry", ::RegistryBuilder).get()
}

final val EXAMPLE = DeferredRegister.create(classOf[ExampleRegistry], MODID)

final lazy val REGISTRY = EXAMPLE.makeRegistry("example_registry", () => new RegistryBuilder).get

Using RegistryEvent$NewRegistry

The second method can be done during the RegistryEvent$NewRegistry event. This will call a new instance of the builder directly. From there, the registry can be built and stored via RegistryBuilder#create. This will cause the registry to be registered to the RegistryManager and returned to the caller for additional processing.

Here is an example: (the event handler is registered on the mod event bus)

public static IForgeRegistry<ExampleRegistry> registry = null;

@SubscribeEvent
public void onNewRegistry(RegistryEvent.NewRegistry event){
    RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
    registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
    registryBuilder.setType(ExampleRegistry.class);
    registry = registryBuilder.create();
}

Handling Missing Entries

When loading a pre-existing world after removing mods or updating versions, there are cases where certain registry objects will cease to exist. In these cases, it is possible to specify actions to remove a mapping, prevent the world from loading, or remap the name as needed. This can be done through the third of the registry events: RegistryEvent$MissingMappings<T>, where the type parameter T is the object type being registered. Within the event, you can grab an immutable list of missing mappings associated with a mod id via #getMappings or a list of all mappings via #getAllMappings.

For each Mapping, you can either execute one of the following methods:

#ignore which abandons the entry when loading
#warn which warns the user about the missing entry but continues loading
#fail which prevents the world from loading
#remap which remaps the entry to the specified non-null object in the same registry

If none of the above are specified, then the default action of notifying the user about the missing mappings occur.

Here is an example: (the event handler is registered on the mod event bus)

JavaGroovy

// This will ignore any missing test items from the specified world
@SubscribeEvent
public void onMissingItems(final RegistryEvent.MissingMappings<Item> event) {
    event.getMappings(MODID).stream()
        .filter(mapping -> mapping.key.getPath().contains("test"))
            .forEach(Mapping::ignore);
}

// This will ignore any missing test items from the specified world
@SubscribeEvent
void onMissingItems(final RegistryEvent.MissingMappings<Item> event) {
    event.getMappings(MODID).stream()
        .filter(mapping -> mapping.key.path.contains("test"))
            .forEach(Mapping::ignore);
}

Registration

Contents

Methods for Registering

DeferredRegister

RegistryEvent.Register

Non-Forge Registries

Data Driven Entries