Registration - Revision history

SizableShrimp: Some improvements of changes in 1.19; skimmed

2022-09-08T17:06:38Z

Some improvements of changes in 1.19; skimmed

ChampionAsh5357: Fix lazy in multilingual examples

2022-06-27T21:32:22Z

Fix lazy in multilingual examples

ChampionAsh5357: Fix ObjectHolder

2022-06-14T11:29:37Z

Fix ObjectHolder

ChampionAsh5357: Fix ObjectHolder info

2022-06-13T19:50:17Z

Fix ObjectHolder info

SizableShrimp: Clarify non-vanilla registries tip

2022-06-13T00:50:13Z

Clarify non-vanilla registries tip

ChampionAsh5357: Add notice about non-vanilla registries for keys and names with DeferredRegister

2022-06-12T18:44:14Z

Add notice about non-vanilla registries for keys and names with DeferredRegister

SizableShrimp: /* Using `NewRegistryEvent` */ Fix header

2022-06-12T06:23:41Z

Using `NewRegistryEvent`: Fix header

SizableShrimp: I don't think this page is under construction anymore

2022-06-12T06:20:06Z

I don't think this page is under construction anymore

ChampionAsh5357: Missed something, whoops

2022-06-11T17:25:34Z

Missed something, whoops

ChampionAsh5357: Update to 1.19

2022-06-11T17:24:38Z

Update to 1.19

Show changes

@@ Line 1: / Line 1: @@
-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.
+Registration is the process of making an object (such as an item or block) known to the game during runtime with an attached <code>ResourceLocation</code> name. Unregistered objects are a likely cause of game loading crashes or bugs, so it is important to register objects correctly.
-Most objects that are known within the game are handled by a <code>Registry</code>. Each registry uniquely defines each object through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]].
+Most objects that are known within the game are handled by a Vanilla <code>Registry</code> or a Forge <code>IForgeRegistry</code>. Each registry uniquely defines each of its own objects through a "registry name" via a [[Using Resources#ResourceLocation|ResourceLocation]].
 {{Tip|In a global context, each object is universally unique through its <code>ResourceKey</code>: 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 <code>IForgeRegistry</code>. This guarantees that the loading order for these wrapped registries will be <code>Block</code>, <code>Item</code>, and then the rest of the wrapped registries in alphabetical order. All registries supported by Forge can be found within the <code>ForgeRegistries</code> 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 <code>Block</code> and an <code>Item</code> each hold a registry object named <code>examplemod:object</code>.
+Forge expands Vanilla's registries to add important features for modded environments, such as world saving of integer ids and network syncing of integer ids, to ensure consistency when different mods and entries are present.
-{{Tip/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 <code>IllegalArgumentException</code> is the <code>DataSerializerEntry</code> registry.}}
+Forge registries preserves the same loading order of Vanilla registries, with all modded registries fired after Vanilla in alphabetical order by string comparing namespace then path. This loading order determines what order registries have their entries registered. All registries wrapped by Forge can be found within the <code>ForgeRegistries</code> class.
 == Methods for Registering ==
-There are two proper ways to register objects within an associated wrapped Forge registry: the <code>DeferredRegister</code> class, and the <code>RegisterEvent</code> lifecycle event.
+There are two proper ways to register objects to a Forge registry or Vanilla registry: the <code>DeferredRegister</code> class, and the <code>RegisterEvent</code> lifecycle event.
 === DeferredRegister ===
@@ Line 158: / Line 164: @@
 === Using @ObjectHolder ===
-Forge registry objects can also be injected into <code>public static</code> fields with either their class or that field annotated with <code>@ObjectHolder</code>. There must be enough information to construct a <code>ResourceLocation</code> to identify a single object within a specific registry.
+Forge registry objects can also be injected into <code>public static final</code> fields by annotating each field with <code>@ObjectHolder</code>. Note that using <code>RegistryObject</code>s is the preferred strategy as ObjectHolders are verbose, clunky, and easy to mess up.
 The rules for <code>@ObjectHolder</code> are as follows:
 * If the class is annotated with <code>@Mod</code>, 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 <code>public static</code>; and
+** it has at least the modifiers <code>public static</code> and optionally <code>final</code>, and
 ** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
-*** the name value is explicitly defined; and
+*** the entry name value is explicitly defined, and
 *** the registry name value is explicitly defined
 * ''An exception is thrown if the resulting <code>ResourceLocation</code> 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)
-<code>@ObjectHolder</code> annotated fields are injected with their associated object values after <code>RegisterEvent</code> is fired for their registry, along with <code>RegistryObject</code>s.
+<code>@ObjectHolder</code> annotated fields are injected with their associated object values after <code>RegisterEvent</code> is fired for their registry, the same time that <code>RegistryObject</code>s are filled. ObjectHolders will remain empty if the associated registry does not exist.
 {{Tip/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.}}
@@ Line 184: / Line 197: @@
 <syntaxhighlight lang="java">
 class Holder {
-     @ObjectHolder(registryName = "enchantment", value = "minecraft:flame")
+     @ObjectHolder(registryName = "minecraft:enchantment", value = "minecraft:flame")
      public static final Enchantment flame = null;     // Annotation present. [public static] is required. [final] is optional.
                                                        // Registry name is explicitly defined: "minecraft:enchantment"
@@ Line 194: / Line 207: @@
      @ObjectHolder("minecraft:creeper")
-     public static Entity creeper = null;              // Annotation present. [public static] is required.
+     public static final Entity creeper = null;        // Annotation present. [public static] is required. [final] is optional.
-                                                       // The registry has not been specified on the field.
+                                                       // The registry name has not been specified on the field.
-                                                       // Therefore, THIS WILL PRODUCE AN EXCEPTION.
+                                                       // Therefore, this will not compile.
-     @ObjectHolder(registryName = "potion")
+     @ObjectHolder(registryName = "minecraft:potion")
      public static final Potion levitation = null;     // Annotation present. [public static] is required. [final] is optional.
                                                        // Registry name is explicitly defined: "minecraft:potion"
-                                                       // Resource location is not specified on the field
+                                                       // The entry's name value has not been specified on the field.
-                                                       // Therefore, THIS WILL PRODUCE AN EXCEPTION.
+                                                       // Therefore, this will not compile.
+}
 </syntaxhighlight>

@@ Line 226: / Line 226: @@
 |kotlin=val EXAMPLE: DeferredRegister<ExampleRegistry> = DeferredRegister.create(ResourceLocation(MODID, "example_registry"), MODID)
-val REGISTRY: IForgeRegistry<ExampleRegistry> by lazy {
+val REGISTRY: IForgeRegistry<ExampleRegistry> by EXAMPLE.makeRegistry(::RegistryBuilder).let {
-    EXAMPLE.makeRegistry(::RegistryBuilder).get()
+    lazy {
+}
 |scala=final val EXAMPLE = DeferredRegister.create(new ResourceLocation(MODID, "example_registry"), MODID)
-final lazy val REGISTRY = EXAMPLE.makeRegistry(() => new RegistryBuilder).get
+private final val PRIVATE_REGISTRY = EXAMPLE.makeRegistry(() => new RegistryBuilder)
 |}}

@@ Line 166: / Line 166: @@
 * A field is considered for injection if:
 ** it has at least the modifiers <code>public static</code>; and
-** one of the following conditions are true:
+** the '''field''' is annotated with <code>@ObjectHolder</code>, and:
-*** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, and:
+*** the name value is explicitly defined; and
-**** the name value is the field's name; and
+*** the registry name value is explicitly defined
 ** ''An exception is thrown if a field does not have a corresponding registry.''
 * ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
@@ Line 190: / Line 183: @@
 <div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
 <syntaxhighlight lang="java">
-@ObjectHolder(registryName = "block", value = "minecraft") // Registry: minecraft:block, Inheritable resource namespace: "minecraft"
+class Holder {
      @ObjectHolder(registryName = "enchantment", value = "minecraft:flame")
      public static final Enchantment flame = null;     // Annotation present. [public static] is required. [final] is optional.
@@ Line 250: / Line 190: @@
                                                        // To inject: "minecraft:flame" from the [Enchantment] registry
-     public static final Biome ice_flat = null;        // No annotation on the enclosing class.
+     public static final Biome ice_flat = null;        // No annotation on the field.
                                                        // 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.
+                                                       // The registry has not been specified on the field.
                                                        // Therefore, THIS WILL PRODUCE AN EXCEPTION.
-     @ObjectHolder(registryName = "potion", value = "levitation")
+     @ObjectHolder(registryName = "potion")
      public static final Potion levitation = null;     // Annotation present. [public static] is required. [final] is optional.
                                                        // Registry name is explicitly defined: "minecraft:potion"
-                                                       // Name path is the value of the annotation: "levitation"
+                                                       // Resource location is not specified on the field
                                                        // Therefore, THIS WILL PRODUCE AN EXCEPTION.
+}

@@ Line 169: / Line 169: @@
 *** the '''enclosing class''' has an <code>@ObjectHolder</code> annotation, and the field is <code>final</code>, 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 <code>@ObjectHolder</code>, and:
 **** the name value is explicitly defined; and
 **** the namespace value is either explicitly defined or the enclosing class's namespace
 ** ''An exception is thrown if a field does not have a corresponding registry.''
 * ''An exception is thrown if the resulting <code>ResourceLocation</code> is incomplete or invalid (non-valid characters in path)''
@@ Line 189: / Line 190: @@
 <div class="mw-collapsible-content" style="overflow: auto; white-space: nowrap;">
 <syntaxhighlight lang="java">
-@ObjectHolder("minecraft") // Inheritable resource namespace: "minecraft"
+@ObjectHolder(registryName = "block", value = "minecraft") // Registry: minecraft:block, 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]
+                                                       // Registry name is not explicitly defined.
                                                        // Name path is the name of the field: "diamond_block"
                                                        // Namespace is not explicitly defined.
@@ Line 198: / Line 200: @@
                                                        // To inject: "minecraft:diamond_block" from the [Block] registry
-     @ObjectHolder("ambient.cave")
+     @ObjectHolder(registry = "sound_event", value = "ambient.cave")
      public static SoundEvent ambient_sound = null;    // Annotation present. [public static] is required.
-                                                       // SoundEvent has a corresponding registry: [SoundEvent]
+                                                       // Registry name is explicitly defined: "minecraft:sound_event"
                                                        // Name path is the value of the annotation: "ambient.cave"
                                                        // Namespace is not explicitly defined.
@@ Line 207: / Line 209: @@
      // Assume for the next entry that [ManaType] is a valid registry.
-     @ObjectHolder("neomagicae:coffeinum")
+     @ObjectHolder(registryName = "neomagicae:mana_type", value = "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)
+                                                       // Registry name is explicitly defined: "neomagicae:mana_type" (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].
+                                                       // Registry name is not explicitly defined.
                                                        // Name path is the name of the field: "ENDER_PEARL" -> "ender_pearl"
                                                        // !! ^ Field name is valid, because they are
@@ Line 220: / Line 223: @@
                                                        // Namespace is not explicitly defined.
                                                        // So, namespace is inherited from class annotation: "minecraft"
-                                                       // To inject: "minecraft:ender_pearl" from the [Item] registry
+                                                       // When registering, this will attempt to force into a Block type, which is not a type or supertype of this object.
-     @ObjectHolder("minecraft:arrow")
+     @ObjectHolder(registryName = "item", value = "minecraft:arrow")
      public static final ArrowItem arrow = null;       // Annotation present. [public static] is required. [final] is optional.
-                                                       // ArrowItem does not have a corresponding registry.
+                                                       // Registry name is explicitly defined: "minecraft:item"
                                                        // ArrowItem's supertype of Item has a corresponding registry: [Item]
                                                        // Resource location is explicitly defined: "minecraft:arrow"
@@ Line 233: / Line 237: @@
      public static final CreativeModeTab group = null; // No annotation. [public static final] is required.
-                                                       // CreativeModeTab does not have a corresponding registry.
+                                                       // Registry name is not explicitly defined.
-                                                       // No supertypes of CreativeModeTab has a corresponding registry.
+                                                      // So, registry name is inherited from class annotation: "minecraft:block"
                                                        // Therefore, THIS WILL PRODUCE AN EXCEPTION.
+}
 class UnannotatedHolder { // Note the lack of an @ObjectHolder annotation on this class.
-     @ObjectHolder("minecraft:flame")
+     @ObjectHolder(registryName = "enchantment", value = "minecraft:flame")
      public static final Enchantment flame = null;     // Annotation present. [public static] is required. [final] is optional.
-                                                       // Enchantment has corresponding registry: [Enchantment].
+                                                       // Registry name is explicitly defined: "minecraft:enchantment"
                                                        // Resource location is explicitly defined: "minecraft:flame"
                                                        // To inject: "minecraft:flame" from the [Enchantment] registry
@@ Line 251: / Line 256: @@
      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.
+                                                       // The registry has not been specified on the class.
                                                        // Therefore, THIS WILL PRODUCE AN EXCEPTION.
-     @ObjectHolder("levitation")
+     @ObjectHolder(registryName = "potion", value = "levitation")
      public static final Potion levitation = null;     // Annotation present. [public static] is required. [final] is optional.
-                                                       // Potion has a corresponding registry: [Potion].
+                                                       // Registry name is explicitly defined: "minecraft:potion"
                                                        // Name path is the value of the annotation: "levitation"
                                                        // Namespace is not explicitly defined.

@@ Line 17: / Line 17: @@
 <code>DeferredRegister</code> is an abstraction layer over the registry event used to register objects. It maintains a map of "registry name" to their associated suppliers and resolves those suppliers during <code>RegisterEvent</code> for the associated registry. This method is the currently recommended, and documented, way to handle these objects as it provides convenience and safety for those who want to statically initialize objects while avoiding some issues associated with it.
-{{Tip/Important|When using <code>DeferredRegister</code>s with non-vanilla registries, the registry key or the registry name should be supplied instead. These include registries for entity data serializers, global loot modifier serializers, world presets, and biome modifier serializers.}}
+{{Tip/Important|When using <code>DeferredRegister</code>s with non-vanilla registries, the registry key or the registry name should be supplied to the <code>create</code> method. These include the custom Forge registries for entity data serializers, global loot modifier serializers, world presets, and biome modifier serializers. Calling <code>Supplier#get</code> on a <code>Supplier<IForgeRegistry<?>></code> when making a DeferredRegister will return null because the registry does not exist yet.}}
 An example of a mod registering a custom block:

@@ Line 290: / Line 290: @@
 |}}
-=== Using `NewRegistryEvent` ===
+=== Using <code>NewRegistryEvent</code> ===
 The second method can be done during the <code>NewRegistryEvent</code> event. Using <code>NewRegistryEvent#create</code>, you can pass in a <code>RegistryBuilder</code> directly. This method will return a <code>Supplier<IForgeRegistry<V>></code> that can be stored and queried after the event is fired to gain access to your <code>IForgeRegistry</code> instance.

← Older revision		Revision as of 06:20, 12 June 2022
Line 1:		Line 1:
−	~~{{Under construction}}~~
−
	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.		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.

@@ Line 305: / Line 305: @@
      RegistryBuilder<ExampleRegistry> registryBuilder = new RegistryBuilder<>();
      registryBuilder.setName(new ResourceLocation(MODID, "example_registry");
      registrySupplier = event.create(registryBuilder);
+}