From e1e8ab69aa0ac91005fdfe1404712d5ab6504e7a Mon Sep 17 00:00:00 2001 From: apple502j <33279053+apple502j@users.noreply.github.com> Date: Wed, 19 Oct 2022 03:31:24 +0900 Subject: [PATCH] Document registry (#3304) * Document registry * More registry javadoc * Map more registry * More registry javadoc * Apply suggestions from code review Co-authored-by: enbrain <69905075+enbrain@users.noreply.github.com> * Update mappings/net/minecraft/util/registry/RegistryEntry.mapping Co-authored-by: enbrain <69905075+enbrain@users.noreply.github.com> --- .../util/registry/BuiltinRegistries.mapping | 8 +- .../util/registry/DefaultedRegistry.mapping | 2 + .../registry/DynamicRegistryManager.mapping | 13 ++ .../util/registry/MutableRegistry.mapping | 5 + .../minecraft/util/registry/Registry.mapping | 193 +++++++++++++++++- .../util/registry/RegistryCodecs.mapping | 1 + .../util/registry/RegistryEntry.mapping | 114 +++++++++++ .../util/registry/RegistryEntryList.mapping | 31 +++ .../util/registry/SimpleRegistry.mapping | 4 + .../minecraft/util/registry/package-info.java | 10 + 10 files changed, 376 insertions(+), 5 deletions(-) create mode 100644 src/packageDocs/java/net/minecraft/util/registry/package-info.java diff --git a/mappings/net/minecraft/util/registry/BuiltinRegistries.mapping b/mappings/net/minecraft/util/registry/BuiltinRegistries.mapping index cf773011da..f1b05308c0 100644 --- a/mappings/net/minecraft/util/registry/BuiltinRegistries.mapping +++ b/mappings/net/minecraft/util/registry/BuiltinRegistries.mapping @@ -1,9 +1,11 @@ CLASS net/minecraft/class_5458 net/minecraft/util/registry/BuiltinRegistries - COMMENT Stores a few hardcoded registries with builtin values for datapack-loadable registries, - COMMENT from which a registry tracker can create a new dynamic registry. + COMMENT Stores a few hardcoded registries with builtin values for data pack-loadable registries, + COMMENT which are copied when starting a server. Register values here to make them available for + COMMENT every server run. COMMENT COMMENT

Note that these registries do not contain the actual entries that the server has, - COMMENT for that you will need to access it from {@link net.minecraft.util.registry.DynamicRegistryManager}. + COMMENT for that you will need to access it from {@link + COMMENT net.minecraft.util.registry.DynamicRegistryManager}. COMMENT COMMENT @see net.minecraft.server.MinecraftServer#getRegistryManager() COMMENT @see net.minecraft.client.network.ClientPlayNetworkHandler#getRegistryManager() diff --git a/mappings/net/minecraft/util/registry/DefaultedRegistry.mapping b/mappings/net/minecraft/util/registry/DefaultedRegistry.mapping index 141fec6bc9..f5a70d6e3d 100644 --- a/mappings/net/minecraft/util/registry/DefaultedRegistry.mapping +++ b/mappings/net/minecraft/util/registry/DefaultedRegistry.mapping @@ -1,4 +1,5 @@ CLASS net/minecraft/class_2348 net/minecraft/util/registry/DefaultedRegistry + COMMENT An implementation of {@link Registry} with a default ID and value for unknown lookups. FIELD field_11014 defaultId Lnet/minecraft/class_2960; FIELD field_11015 defaultEntry Lnet/minecraft/class_6880; METHOD (Ljava/lang/String;Lnet/minecraft/class_5321;Lcom/mojang/serialization/Lifecycle;Ljava/util/function/Function;)V @@ -7,3 +8,4 @@ CLASS net/minecraft/class_2348 net/minecraft/util/registry/DefaultedRegistry ARG 3 lifecycle ARG 4 valueToEntryFunction METHOD method_10137 getDefaultId ()Lnet/minecraft/class_2960; + COMMENT {@return the ID of the default value} diff --git a/mappings/net/minecraft/util/registry/DynamicRegistryManager.mapping b/mappings/net/minecraft/util/registry/DynamicRegistryManager.mapping index 3ce86aab2e..cfde4ce2d6 100644 --- a/mappings/net/minecraft/util/registry/DynamicRegistryManager.mapping +++ b/mappings/net/minecraft/util/registry/DynamicRegistryManager.mapping @@ -9,6 +9,14 @@ CLASS net/minecraft/class_5455 net/minecraft/util/registry/DynamicRegistryManage COMMENT

The {@link DynamicRegistryManager.ImmutableImpl} COMMENT class serves as an immutable implementation of any particular collection COMMENT or configuration of dynamic registries. + COMMENT + COMMENT

To create a new instance, call {@link #createAndLoad}, then (optionally) + COMMENT load the data pack-defined values via {@link + COMMENT net.minecraft.util.dynamic.RegistryOps#ofLoaded(DynamicOps, DynamicRegistryManager.Mutable, net.minecraft.resource.ResourceManager)}. + COMMENT Values registered in {@link BuiltinRegistries} are always available. + COMMENT + COMMENT @see net.minecraft.server.MinecraftServer#getRegistryManager() + COMMENT @see net.minecraft.client.network.ClientPlayNetworkHandler#getRegistryManager() FIELD field_25918 LOGGER Lorg/slf4j/Logger; FIELD field_25919 INFOS Ljava/util/Map; FIELD field_26733 BUILTIN Ljava/util/function/Supplier; @@ -86,6 +94,11 @@ CLASS net/minecraft/class_5455 net/minecraft/util/registry/DynamicRegistryManage ARG 0 entry METHOD method_40313 streamSyncedRegistries ()Ljava/util/stream/Stream; METHOD method_40314 createAndLoad ()Lnet/minecraft/class_5455$class_6893; + COMMENT {@return a new dynamic registry manager instance with all built-in registries loaded} + COMMENT + COMMENT

The registries do not contain values from data packs. + COMMENT Call {@link net.minecraft.util.dynamic.RegistryOps#ofLoaded(DynamicOps, DynamicRegistryManager.Mutable, net.minecraft.resource.ResourceManager)} + COMMENT to load those values. METHOD method_40316 toImmutable ()Lnet/minecraft/class_5455$class_6890; METHOD method_40317 createSimpleRegistry (Lnet/minecraft/class_5321;)Lnet/minecraft/class_2385; ARG 0 registryRef diff --git a/mappings/net/minecraft/util/registry/MutableRegistry.mapping b/mappings/net/minecraft/util/registry/MutableRegistry.mapping index dd4577b391..bd3b090080 100644 --- a/mappings/net/minecraft/util/registry/MutableRegistry.mapping +++ b/mappings/net/minecraft/util/registry/MutableRegistry.mapping @@ -1,4 +1,8 @@ CLASS net/minecraft/class_2385 net/minecraft/util/registry/MutableRegistry + COMMENT A registry that allows adding or modifying values. + COMMENT Note that in vanilla, all registries are instances of this. + COMMENT + COMMENT @see Registry METHOD method_10272 add (Lnet/minecraft/class_5321;Ljava/lang/Object;Lcom/mojang/serialization/Lifecycle;)Lnet/minecraft/class_6880; ARG 1 key ARG 2 entry @@ -21,3 +25,4 @@ CLASS net/minecraft/class_2385 net/minecraft/util/registry/MutableRegistry ARG 3 newEntry ARG 4 lifecycle METHOD method_35863 isEmpty ()Z + COMMENT {@return whether the registry is empty} diff --git a/mappings/net/minecraft/util/registry/Registry.mapping b/mappings/net/minecraft/util/registry/Registry.mapping index 13724cdc67..87823142a0 100644 --- a/mappings/net/minecraft/util/registry/Registry.mapping +++ b/mappings/net/minecraft/util/registry/Registry.mapping @@ -1,4 +1,147 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry + COMMENT A registry is used to register various in-game components. Almost all parts of the + COMMENT game - from blocks, items, and entity types, to cat types, goat horn instruments, + COMMENT and structure pools - are registered in registries. Registry system allows the game + COMMENT to enumerate all known types of something, and to assign a unique identifier to each + COMMENT of those. Therefore, registering an object in the registry plays a very important + COMMENT role, and failure to register new instances of registerable object usually results + COMMENT in a bug or even a crash. + COMMENT + COMMENT

Terminologies

+ COMMENT

A registry is an object that holds the mapping between three things: + COMMENT the string ID, the numeric ID, and the registered value. There are many registries + COMMENT for different types of registerable objects, and a registry's type parameter indicates + COMMENT the accepted type. For example, you register your {@link Block} to {@code + COMMENT Registry}. It's important to note that registries themselves are registered + COMMENT in a "registry of registries", {@link #ROOT}. + COMMENT + COMMENT

The string ID, usually just called "ID", is a human-readable + COMMENT {@link Identifier} that uniquely identifies the registered value in a registry. + COMMENT This should stay the same between two game versions, and is usually used for disk + COMMENT storage. + COMMENT + COMMENT

The numeric ID or raw ID is an integer + COMMENT assigned automatically by the registry to each registered value. This is not + COMMENT guaranteed to stay the same between two game versions, and is usually used for + COMMENT networking purposes. + COMMENT + COMMENT

The registered value, often just called "value" in the code, + COMMENT is the value added to the registry. The registry's type parameter determines + COMMENT the type of the registered value. + COMMENT + COMMENT

Each registered value can also be identified with a {@linkplain RegistryKey + COMMENT registry key}. A registry key is a combination of the registry's ID and + COMMENT the registered value's ID. Using a registry key makes the type of the ID's + COMMENT associated value clear, as the type parameter contains the type. + COMMENT + COMMENT

A {@linkplain RegistryEntry registry entry} is an object + COMMENT holding a value that can be registered in a registry. In most cases, the + COMMENT value is already registered in a registry ("reference entry"), hence the name; + COMMENT however, it is possible to create a registry entry by direct reference + COMMENT ("direct entry"). This is useful for data packs, as they can define + COMMENT one-time use values directly without having to register them every time. + COMMENT + COMMENT

A {@link RegistryEntryList registry entry list} is a list + COMMENT of registry entries. This, is either a direct reference to each item, or + COMMENT a reference to a tag. A tag is a way to dynamically + COMMENT define a list of registered values. Anything registered in a registry + COMMENT can be tagged, and each registry holds a list of tags it recognizes. + COMMENT + COMMENT

Static and dynamic registries

+ COMMENT

There are two kinds of registries: static and dynamic. + COMMENT + COMMENT

+ COMMENT + COMMENT

Using Registry

+ COMMENT

Reading Registry

+ COMMENT

A registry is also an {@link IndexedIterable}. Therefore, registries can be + COMMENT iterated using, e.g. {@code for (Block block : Registry.BLOCK)}. + COMMENT + COMMENT

There are several other methods used for reading the contents of the registry: + COMMENT

+ COMMENT + COMMENT

Registering something to Registry

+ COMMENT

The steps for registration are different, depending on whether the registry is static + COMMENT or dynamic. For dynamic registries, data packs can usually be used to register a new + COMMENT value or replace one. For static registries, the game's code must be modified. + COMMENT + COMMENT

Static registries are defined in this class, and unlike the dynamic registries, it + COMMENT cannot be changed after the game initialization. The game enforces this by "freezing" + COMMENT the registry. Attempting to register a value after freezing causes a crash, such as + COMMENT "Registry is already frozen". Modding APIs usually provide a way to bypass this restriction. + COMMENT + COMMENT

To register a value to a dynamic registry, register to a registry found in {@link + COMMENT BuiltinRegistries}. Values registered in those registries are available in all worlds. + COMMENT + COMMENT

In both cases, use {@link #register(Registry, Identifier, Object)} for registering + COMMENT a value to a registry. + COMMENT + COMMENT

Intrusive holders

+ COMMENT

For historical reasons, there are two types of reference registry entries. + COMMENT (This is different from the "direct" and "reference" registry entry types.) + COMMENT + COMMENT

+ COMMENT + COMMENT

When a class whose instances are registered as intrusive holders, such as + COMMENT {@link Block} or {@link Item}, are instantiated without registering, the game + COMMENT crashes with "Some intrusive holders were not added to registry" error message. + COMMENT This includes conditional registration. For example, the code + COMMENT below can cause a crash: + COMMENT + COMMENT 

{@code
+	COMMENT Item myItem = new Item(new Item.Settings());
+	COMMENT if (condition) {
+	COMMENT     Registry.register(Registry.ITEM, new Identifier("example", "bad"), myItem);
+	COMMENT }
+	COMMENT }
+ COMMENT + COMMENT

The correct way is to make the instantiation conditional as well: + COMMENT + COMMENT 

{@code
+	COMMENT if (condition) {
+	COMMENT     Item myItem = new Item(new Item.Settings());
+	COMMENT     Registry.register(Registry.ITEM, new Identifier("example", "bad"), myItem);
+	COMMENT }
+	COMMENT }
FIELD field_11137 BLOCK_ENTITY_TYPE Lnet/minecraft/class_2378; FIELD field_11138 FEATURE Lnet/minecraft/class_2378; FIELD field_11139 LOGGER Lorg/slf4j/Logger; @@ -174,11 +317,14 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_10219 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_1291; ARG 0 registry METHOD method_10220 stream ()Ljava/util/stream/Stream; + COMMENT {@return a stream of all values of this registry} METHOD method_10221 getId (Ljava/lang/Object;)Lnet/minecraft/class_2960; + COMMENT {@return the ID assigned to {@code value}, or {@code null} if it is not registered} ARG 1 value METHOD method_10222 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_6018; ARG 0 registry METHOD method_10223 get (Lnet/minecraft/class_2960;)Ljava/lang/Object; + COMMENT {@return the value that is assigned {@code id}, or {@code null} if there is none} ARG 1 id METHOD method_10224 create (Lnet/minecraft/class_5321;Ljava/lang/String;Lnet/minecraft/class_2378$class_6889;)Lnet/minecraft/class_2348; ARG 0 key @@ -198,6 +344,9 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_10229 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_5864; ARG 0 registry METHOD method_10230 register (Lnet/minecraft/class_2378;Lnet/minecraft/class_2960;Ljava/lang/Object;)Ljava/lang/Object; + COMMENT Registers {@code entry} to {@code registry} under {@code id}. + COMMENT + COMMENT @return the passed {@code entry} ARG 0 registry ARG 1 id ARG 2 entry @@ -211,11 +360,14 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_10234 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_1792; ARG 0 registry METHOD method_10235 getIds ()Ljava/util/Set; + COMMENT {@return the set of all IDs registered in a registry} METHOD method_10236 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_2960; ARG 0 registry METHOD method_10237 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_2248; ARG 0 registry METHOD method_10240 getRandom (Lnet/minecraft/class_5819;)Ljava/util/Optional; + COMMENT {@return a random registry entry from this registry, or an empty optional if the + COMMENT registry is empty} ARG 1 random METHOD method_10243 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_1887; ARG 0 registry @@ -227,6 +379,7 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_10248 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_3611; ARG 0 registry METHOD method_10250 containsId (Lnet/minecraft/class_2960;)Z + COMMENT {@return whether {@code id} is registered in this registry} ARG 1 id METHOD method_10252 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_1299; ARG 0 registry @@ -245,6 +398,7 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_17798 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_3956; ARG 0 registry METHOD method_17966 getOrEmpty (Lnet/minecraft/class_2960;)Ljava/util/Optional; + COMMENT {@return the value that is assigned {@code id}, or an empty optional if there is none} ARG 1 id METHOD method_19449 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_4168; ARG 0 registry @@ -265,6 +419,7 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_29106 createRegistryKey (Ljava/lang/String;)Lnet/minecraft/class_5321; ARG 0 registryId METHOD method_29107 get (Lnet/minecraft/class_5321;)Ljava/lang/Object; + COMMENT {@return the value that is assigned {@code key}, or {@code null} if there is none} ARG 1 key METHOD method_29108 create (Lnet/minecraft/class_5321;Lcom/mojang/serialization/Lifecycle;Lnet/minecraft/class_2378$class_6889;)Lnet/minecraft/class_2378; ARG 0 key @@ -276,6 +431,7 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry ARG 2 lifecycle ARG 3 defaultEntryGetter METHOD method_29113 getKey (Ljava/lang/Object;)Ljava/util/Optional; + COMMENT {@return the registry key of {@code value}, or an empty optional if it is not registered} ARG 1 entry METHOD method_29396 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_5342; ARG 0 registry @@ -284,17 +440,21 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_29398 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_5338; ARG 0 registry METHOD method_29722 getEntrySet ()Ljava/util/Set; + COMMENT {@return the set containing {@link Map.Entry} of the registry keys and values registered + COMMENT in this registry} METHOD method_30517 getKey ()Lnet/minecraft/class_5321; + COMMENT {@return the registry key that identifies this registry} METHOD method_31138 getLifecycle ()Lcom/mojang/serialization/Lifecycle; METHOD method_31139 getEntryLifecycle (Ljava/lang/Object;)Lcom/mojang/serialization/Lifecycle; COMMENT Gets the lifecycle of a registry entry. ARG 1 entry METHOD method_31140 getOrThrow (Lnet/minecraft/class_5321;)Ljava/lang/Object; - COMMENT Gets an entry from the registry. + COMMENT {@return the value that is assigned {@code key}} COMMENT - COMMENT @throws IllegalStateException if the entry was not present in the registry + COMMENT @throws IllegalStateException if there is no value with {@code key} in the registry ARG 1 key METHOD method_31189 getOrEmpty (Lnet/minecraft/class_5321;)Ljava/util/Optional; + COMMENT {@return the value that is assigned {@code key}, or an empty optional if there is none} ARG 1 key METHOD method_32693 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_5669; ARG 0 registry @@ -340,10 +500,14 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_34044 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_2939; ARG 0 registry METHOD method_35842 contains (Lnet/minecraft/class_5321;)Z + COMMENT {@return whether {@code key} is registered in this registry} ARG 1 key METHOD method_35844 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_6123; ARG 0 registry METHOD method_39197 register (Lnet/minecraft/class_2378;Lnet/minecraft/class_5321;Ljava/lang/Object;)Ljava/lang/Object; + COMMENT Registers {@code entry} to {@code registry} under {@code key}. + COMMENT + COMMENT @return the passed {@code entry} ARG 0 registry ARG 1 key ARG 2 entry @@ -356,25 +520,39 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_39671 (Ljava/lang/Object;)Lcom/mojang/serialization/DataResult; ARG 1 value METHOD method_39673 getCodec ()Lcom/mojang/serialization/Codec; + COMMENT {@return the codec for serializing {@code T}} + COMMENT + COMMENT @implNote This serializes a value using the ID or (if compressed) the raw ID. METHOD method_40252 containsTag (Lnet/minecraft/class_6862;)Z + COMMENT {@return whether {@code tag} is known to this registry} ARG 1 tag METHOD method_40257 populateTags (Ljava/util/Map;)V ARG 1 tagEntries METHOD method_40260 getOrCreateEntryList (Lnet/minecraft/class_6862;)Lnet/minecraft/class_6885$class_6888; ARG 1 tag METHOD method_40264 getEntry (Lnet/minecraft/class_5321;)Ljava/util/Optional; + COMMENT {@return the reference registry entry for the value assigned {@code key}, or an + COMMENT empty optional if there is no such value} + COMMENT + COMMENT @see #entryOf ARG 1 key METHOD method_40265 getEntry (I)Ljava/util/Optional; + COMMENT {@return the reference registry entry for the value assigned {@code rawId}, or an + COMMENT empty optional if there is no such value} ARG 1 rawId METHOD method_40266 getEntryList (Lnet/minecraft/class_6862;)Ljava/util/Optional; + COMMENT {@return the registry entry list of values that are assigned {@code tag}, or an empty + COMMENT optional if the tag is not known to the registry} ARG 1 tag METHOD method_40268 getOrCreateEntryDataResult (Lnet/minecraft/class_5321;)Lcom/mojang/serialization/DataResult; ARG 1 key METHOD method_40269 createEntry (Ljava/lang/Object;)Lnet/minecraft/class_6880$class_6883; ARG 1 value METHOD method_40270 streamEntries ()Ljava/util/stream/Stream; + COMMENT {@return a stream of reference registry entries of this registry} METHOD method_40272 streamTagsAndEntries ()Ljava/util/stream/Stream; METHOD method_40273 streamTags ()Ljava/util/stream/Stream; + COMMENT {@return a stream of all tag keys known to this registry} METHOD method_40276 freeze ()Lnet/minecraft/class_2378; METHOD method_40278 clearTags ()V METHOD method_40279 (Lnet/minecraft/class_6880;)Lcom/mojang/serialization/Lifecycle; @@ -400,17 +578,28 @@ CLASS net/minecraft/class_2378 net/minecraft/util/registry/Registry METHOD method_40285 (Lnet/minecraft/class_6880;)Lcom/mojang/serialization/DataResult; ARG 1 entry METHOD method_40286 iterateEntries (Lnet/minecraft/class_6862;)Ljava/lang/Iterable; + COMMENT {@return an iterable of values that are assigned {@code tag}, or an empty iterable + COMMENT if the tag is not known to the registry} ARG 1 tag METHOD method_40288 (Lnet/minecraft/class_2960;)Lcom/mojang/serialization/DataResult; ARG 1 id METHOD method_40290 entryOf (Lnet/minecraft/class_5321;)Lnet/minecraft/class_6880; + COMMENT {@return the reference registry entry for the value assigned {@code key}} + COMMENT + COMMENT @throws IllegalStateException if there is no value that is assigned {@code key} + COMMENT + COMMENT @see #getEntry(RegistryKey) ARG 1 key METHOD method_40292 freezeRegistries ()V METHOD method_40293 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_6875; ARG 0 registry METHOD method_40294 createEntryCodec ()Lcom/mojang/serialization/Codec; + COMMENT {@return the codec for serializing the registry entry of {@code T}} + COMMENT + COMMENT @implNote This serializes a registry entry using the ID. METHOD method_40295 getIndexedEntries ()Lnet/minecraft/class_2359; METHOD method_42021 getKeys ()Ljava/util/Set; + COMMENT {@return the set of all registry keys registered in a registry} METHOD method_43223 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_7106; ARG 0 registry METHOD method_43224 (Lnet/minecraft/class_2378;)Lnet/minecraft/class_7375; diff --git a/mappings/net/minecraft/util/registry/RegistryCodecs.mapping b/mappings/net/minecraft/util/registry/RegistryCodecs.mapping index 035e570cf8..15fc4f5d59 100644 --- a/mappings/net/minecraft/util/registry/RegistryCodecs.mapping +++ b/mappings/net/minecraft/util/registry/RegistryCodecs.mapping @@ -1,4 +1,5 @@ CLASS net/minecraft/class_6895 net/minecraft/util/registry/RegistryCodecs + COMMENT A utility class for serialization of registries using codecs. METHOD method_40338 (Lnet/minecraft/class_2378;)Ljava/util/Map; ARG 0 registry METHOD method_40339 (Lnet/minecraft/class_2385;Lcom/mojang/serialization/Lifecycle;Lnet/minecraft/class_5321;Ljava/lang/Object;)V diff --git a/mappings/net/minecraft/util/registry/RegistryEntry.mapping b/mappings/net/minecraft/util/registry/RegistryEntry.mapping index ef7c8e1380..1bc0b8dd35 100644 --- a/mappings/net/minecraft/util/registry/RegistryEntry.mapping +++ b/mappings/net/minecraft/util/registry/RegistryEntry.mapping @@ -1,26 +1,113 @@ CLASS net/minecraft/class_6880 net/minecraft/util/registry/RegistryEntry + COMMENT An object holding a value that can be registered in a registry. In most cases, the + COMMENT value is already registered in a registry ("reference entry"), hence the name; + COMMENT however, it is possible to create a registry entry by direct reference + COMMENT ("direct entry"). This is useful for data packs, as they can define + COMMENT one-time use values directly without having to register them every time. + COMMENT + COMMENT

Registry entries do not define {@code equals} method. Instead, compare the result + COMMENT of {@link #getKeyOrValue}. + COMMENT + COMMENT

Reference registry entries also hold their {@linkplain TagKey tags}. For more + COMMENT information on type-specific behaviors, including "intrusive" and "stand-alone" + COMMENT reference registry entries, see the respective class documentations. + COMMENT + COMMENT

A registry entry is sometimes referred to as a "holder" in error messages. + COMMENT + COMMENT @see RegistryEntry.Direct + COMMENT @see RegistryEntry.Reference + COMMENT @see Registry#entryOf + COMMENT @see Registry#getEntry METHOD method_40220 isIn (Lnet/minecraft/class_6862;)Z + COMMENT {@return whether this entry is in {@code tag}} + COMMENT + COMMENT

This always returns {@code false} for direct entries, since tags are managed by + COMMENT a registry. ARG 1 tag METHOD method_40221 upcast (Lnet/minecraft/class_6880;)Lnet/minecraft/class_6880; + COMMENT Casts {@code RegistryEntry} to {@code RegistryEntry}. + COMMENT + COMMENT @return the cast value ARG 0 entry METHOD method_40222 matchesRegistry (Lnet/minecraft/class_2378;)Z + COMMENT {@return whether the registry for the entry is {@code registry}} + COMMENT + COMMENT

This always returns {@code true} for direct entries. ARG 1 registry METHOD method_40223 of (Ljava/lang/Object;)Lnet/minecraft/class_6880; + COMMENT {@return a new direct registry entry of {@code value}} ARG 0 value METHOD method_40224 matches (Ljava/util/function/Predicate;)Z + COMMENT {@return whether this entry's key matches {@code predicate}} + COMMENT + COMMENT

This always returns {@code false} for direct entries. ARG 1 predicate METHOD method_40225 matchesKey (Lnet/minecraft/class_5321;)Z + COMMENT {@return whether the registry key of this entry is {@code key}} + COMMENT + COMMENT

This always returns {@code false} for direct entries. ARG 1 key METHOD method_40226 matchesId (Lnet/minecraft/class_2960;)Z + COMMENT {@return whether the ID of this entry is {@code id}} + COMMENT + COMMENT

This always returns {@code false} for direct entries. ARG 1 id METHOD method_40227 hasKeyAndValue ()Z METHOD method_40228 streamTags ()Ljava/util/stream/Stream; + COMMENT {@return a stream of the tags of this entry, or an empty stream if this is a direct entry} METHOD method_40229 getKeyOrValue ()Lcom/mojang/datafixers/util/Either; + COMMENT {@return the object that identifies this registry key} + COMMENT + COMMENT

For direct entries, this is the held value, and for reference entries, this is the + COMMENT key of the entry. METHOD method_40230 getKey ()Ljava/util/Optional; + COMMENT {@return the registry key of this entry, or an empty optional if this is a direct entry} METHOD method_40231 getType ()Lnet/minecraft/class_6880$class_6882; + COMMENT {@return the type (direct or reference) of this registry entry} + COMMENT + COMMENT

This is different from the types of reference registry entries, i.e. + COMMENT stand-alone or intrusive. CLASS class_6881 Direct + COMMENT A direct registry entry holds the value directly. The value does not have to be + COMMENT registered in a registry. Therefore, they receive no ID or registry key, and they + COMMENT cannot be tagged. + COMMENT + COMMENT

This is most often used in data packs to inline one-time use values directly. CLASS class_6882 Type + COMMENT The types of registry entries. + COMMENT + COMMENT @see RegistryEntry CLASS class_6883 Reference + COMMENT A reference registry entry holds the value by reference. The value is previously + COMMENT registered in a registry, so they can be referred to by their registry keys. + COMMENT This object also holds the entry's tags. + COMMENT + COMMENT

There are two types of reference registry entries. + COMMENT + COMMENT

+ COMMENT + COMMENT

Therefore, it is very important to construct any intrusive-entry type object + COMMENT and register at the same time. For example, a mod that conditionally registers an + COMMENT {@link Item} has to create an instance only if the condition is met. (See {@link Registry} + COMMENT for a code example.) + COMMENT + COMMENT

When a reference registry entry is first instantiated, it only has either the key + COMMENT or the value (depending on the type). They are later filled when registering the + COMMENT entry at {@link #setKeyAndValue}. Attempting to call methods before those fields are filled + COMMENT can cause a crash. Note that if you are just getting the entry from a registry, this + COMMENT should not be a problem. + COMMENT + COMMENT @see Registry#entryOf + COMMENT @see Registry#getEntry FIELD field_36449 registry Lnet/minecraft/class_2378; FIELD field_36450 tags Ljava/util/Set; FIELD field_36451 referenceType Lnet/minecraft/class_6880$class_6883$class_6884; @@ -32,15 +119,42 @@ CLASS net/minecraft/class_6880 net/minecraft/util/registry/RegistryEntry ARG 3 registryKey ARG 4 value METHOD method_40233 intrusive (Lnet/minecraft/class_2378;Ljava/lang/Object;)Lnet/minecraft/class_6880$class_6883; + COMMENT {@return a new intrusive registry entry} + COMMENT + COMMENT

This should not be called manually. Call {@link Registry#entryOf} or + COMMENT {@link Registry#getEntry} instead. + COMMENT + COMMENT

Callers are responsible for filling the key later by calling {@link + COMMENT #setKeyAndValue}. + COMMENT + COMMENT @deprecated Intrusive holders exist for legacy reasons only. ARG 0 registry ARG 1 value METHOD method_40234 standAlone (Lnet/minecraft/class_2378;Lnet/minecraft/class_5321;)Lnet/minecraft/class_6880$class_6883; + COMMENT {@return a new stand-alone registry entry} + COMMENT + COMMENT

This should not be called manually. Call {@link Registry#entryOf} or + COMMENT {@link Registry#getEntry} instead. + COMMENT + COMMENT

Callers are responsible for filling the value later by calling {@link + COMMENT #setKeyAndValue}. ARG 0 registry ARG 1 registryKey METHOD method_40235 setTags (Ljava/util/Collection;)V ARG 1 tags METHOD method_40236 setKeyAndValue (Lnet/minecraft/class_5321;Ljava/lang/Object;)V + COMMENT Sets the key and the value of this registry entry. When instantiated, an entry has + COMMENT only one of them, and this is called to fill the other value. Pass the current value + COMMENT for the parameter corresponding to the already filled field. + COMMENT + COMMENT @throws IllegalStateException when trying to change already filled fields ARG 1 key ARG 2 value METHOD method_40237 registryKey ()Lnet/minecraft/class_5321; + COMMENT {@return the registry key of this entry} + COMMENT + COMMENT @throws IllegalStateException if this is an intrusive entry and it is not initialized yet CLASS class_6884 Type + COMMENT The types of reference registry entries. + COMMENT + COMMENT @see RegistryEntry.Reference diff --git a/mappings/net/minecraft/util/registry/RegistryEntryList.mapping b/mappings/net/minecraft/util/registry/RegistryEntryList.mapping index 576d192f78..aa82ee5fbc 100644 --- a/mappings/net/minecraft/util/registry/RegistryEntryList.mapping +++ b/mappings/net/minecraft/util/registry/RegistryEntryList.mapping @@ -1,33 +1,63 @@ CLASS net/minecraft/class_6885 net/minecraft/util/registry/RegistryEntryList + COMMENT A registry entry list is an immutable list of registry entries. This, is either a direct + COMMENT reference to each item, or a reference to a tag. A tag is a way + COMMENT to dynamically define a list of registered values. Anything registered in a registry + COMMENT can be tagged, and each registry holds a list of tags it recognizes. + COMMENT + COMMENT

This can be iterated directly (i.e. {@code for (RegistryEntry entry : entries)}. + COMMENT Note that this does not implement {@link java.util.Collection}. + COMMENT + COMMENT @see Registry + COMMENT @see RegistryEntry METHOD method_40239 stream ()Ljava/util/stream/Stream; + COMMENT {@return a stream of registry entries in this list} METHOD method_40240 get (I)Lnet/minecraft/class_6880; + COMMENT {@return the registry entry at {@code index}} + COMMENT + COMMENT @throws IndexOutOfBoundsException if the index is out of bounds ARG 1 index METHOD method_40241 contains (Lnet/minecraft/class_6880;)Z + COMMENT {@return whether {@code entry} is in this list} ARG 1 entry METHOD method_40242 of (Ljava/util/List;)Lnet/minecraft/class_6885$class_6886; + COMMENT {@return a new direct list of {@code entries}} ARG 0 entries METHOD method_40243 getRandom (Lnet/minecraft/class_5819;)Ljava/util/Optional; + COMMENT {@return a random entry of the list, or an empty optional if this list is empty} ARG 1 random METHOD method_40244 of (Ljava/util/function/Function;Ljava/util/List;)Lnet/minecraft/class_6885$class_6886; + COMMENT {@return a new direct list of {@code values} converted to a registry entry with {@code mapper}} ARG 0 mapper ARG 1 values METHOD method_40245 of (Ljava/util/function/Function;[Ljava/lang/Object;)Lnet/minecraft/class_6885$class_6886; + COMMENT {@return a new direct list of {@code values} converted to a registry entry with {@code mapper}} ARG 0 mapper ARG 1 values METHOD method_40246 of ([Lnet/minecraft/class_6880;)Lnet/minecraft/class_6885$class_6886; + COMMENT {@return a new direct list of {@code entries}} ARG 0 entries METHOD method_40247 size ()I + COMMENT {@return the number of entries in this list} METHOD method_40248 getStorage ()Lcom/mojang/datafixers/util/Either; + COMMENT {@return the object that identifies this registry entry list} + COMMENT + COMMENT

This is the tag key for a reference list, and the backing list for a direct list. METHOD method_40560 isOf (Lnet/minecraft/class_2378;)Z + COMMENT {@return whether the list is of entries from {@code registry}} + COMMENT + COMMENT

This always returns {@code true} for direct lists. ARG 1 registry CLASS class_6886 Direct + COMMENT A direct registry entry list that holds the values directly, instead of using tags. FIELD field_36457 entries Ljava/util/List; FIELD field_36458 entrySet Ljava/util/Set; METHOD (Ljava/util/List;)V ARG 1 entries CLASS class_6887 ListBacked + COMMENT An internal implementation of {@link RegistryEntryList}. METHOD method_40249 getEntries ()Ljava/util/List; CLASS class_6888 Named + COMMENT A registry entry list that references a tag from the registry. FIELD field_36459 tag Lnet/minecraft/class_6862; FIELD field_36460 entries Ljava/util/List; FIELD field_36633 registry Lnet/minecraft/class_2378; @@ -37,3 +67,4 @@ CLASS net/minecraft/class_6885 net/minecraft/util/registry/RegistryEntryList METHOD method_40250 copyOf (Ljava/util/List;)V ARG 1 entries METHOD method_40251 getTag ()Lnet/minecraft/class_6862; + COMMENT {@return the tag key that this list references} diff --git a/mappings/net/minecraft/util/registry/SimpleRegistry.mapping b/mappings/net/minecraft/util/registry/SimpleRegistry.mapping index 1ca147bdfc..631ced4562 100644 --- a/mappings/net/minecraft/util/registry/SimpleRegistry.mapping +++ b/mappings/net/minecraft/util/registry/SimpleRegistry.mapping @@ -1,4 +1,8 @@ CLASS net/minecraft/class_2370 net/minecraft/util/registry/SimpleRegistry + COMMENT An implementation of a mutable registry. All vanilla registries use this (or its + COMMENT subclass, {@link DefaultedRegistry}). + COMMENT + COMMENT @see Registry FIELD field_11107 idToEntry Ljava/util/Map; FIELD field_11109 nextId I FIELD field_25067 keyToEntry Ljava/util/Map; diff --git a/src/packageDocs/java/net/minecraft/util/registry/package-info.java b/src/packageDocs/java/net/minecraft/util/registry/package-info.java new file mode 100644 index 0000000000..9404653de9 --- /dev/null +++ b/src/packageDocs/java/net/minecraft/util/registry/package-info.java @@ -0,0 +1,10 @@ +/* + * This file is free for everyone to use under the Creative Commons Zero license. + */ + +/** + * Contains the registry, used to register various in-game components, and related classes. + * + * @see Registry + */ +package net.minecraft.util.registry;