Registry docs (#423)

Initial set of docs for registry related API in paper 1.21.

Co-authored-by: Nassim Jahnke <[email protected]>
Co-authored-by: powercas_gamer <[email protected]>
Co-authored-by: Matouš Kučera <[email protected]>

config/sidebar.paper.ts

@@ -148,6 +148,7 @@ const paper: SidebarsConfig = {
             "dev/api/plugin-messaging",
             "dev/api/plugin-configs",
             "dev/api/lifecycle",
+            "dev/api/registries",
             "dev/api/recipes",
             "dev/api/folia-support",
             "dev/api/roadmap",

docs/paper/dev/api/registries.mdx

@@ -0,0 +1,165 @@
+---
+slug: /dev/registries
+description: A guide to registries and their modification on Paper.
+---
+
+# Registries
+
+:::danger[Experimental]
+The Registry API and anything that uses it is currently experimental and may change in the future.
+:::
+
+## What is a registry?
+
+In the context of Minecraft, a registry holds onto a set of values of the same type, identifying
+each by a key. An example of such a registry would be the <Javadoc name={"org.bukkit.Registry#ITEM"}>ItemType registry</Javadoc> which holds all known item types.
+Registries are available via the <Javadoc name={"io.papermc.paper.registry.RegistryAccess"}>RegistryAccess</Javadoc> class.
+
+While a large portion of registries are defined by the server and client independently, more and
+more are defined by the server and sent to the client while joining the server.
+This enables the server, and to that extent plugins, to define custom content for both itself and
+clients playing on it.
+Notable examples include **enchantments** and **biomes**.
+
+### Retrieving values from a registry
+
+To retrieve elements from a registry, their respective keys can be used.
+The API defines two types of keys.
+<ol>
+  <li>
+    `net.kyori.adventure.key.Key` represents a namespace and a key.
+  </li>
+  <li>
+    <Javadoc name={"io.papermc.paper.registry.TypedKey"}>TypedKey</Javadoc> wraps an Adventure key,
+    but also includes the <Javadoc name={"io.papermc.paper.registry.TypedKey#registryKey()"}>key of
+    the registry</Javadoc> the
+    <Javadoc name={"io.papermc.paper.registry.TypedKey"}>TypedKey</Javadoc> belongs to.
+  </li>
+</ol>
+An example of retrieving the `Sharpness` enchantment using
+<Javadoc name={"io.papermc.paper.registry.TypedKey"}>TypedKeys</Javadoc> looks as follows:
+
+```java
+// Fetch the enchantment registry from the registry access
+final Registry<Enchantment> enchantmentRegistry = RegistryAccess
+    .registryAccess()
+    .getRegistry(RegistryKey.ENCHANTMENT);
+
+// Get the sharpness enchantment using its key.
+// getOrThrow may be replaced with get if the registry may not contain said value
+final Enchantment enchantment = enchantmentRegistry.getOrThrow(TypedKey.create(
+    RegistryKey.ENCHANTMENT, Key.key("minecraft:sharpness"))
+);
+
+// Same as above, but using generated typed keys.
+// Only Vanilla entries have generated keys, for custom entries, the above method must be used.
+final Enchantment enchantment = enchantmentRegistry.getOrThrow(EnchantmentKeys.SHARPNESS);
+```
+
+### Referencing registry values
+
+Referencing entries in a registry is easier said then done.
+While for most cases a plain <Javadoc project={"java"} name={"java.util.Collection"}>Collection</Javadoc> of the values might suffice, alternative approaches are
+more often used by Minecraft and will hence be encountered.
+
+A <Javadoc name={"io.papermc.paper.registry.set.RegistrySet"}>`RegistrySet`</Javadoc> defines a
+collection of elements that *relate* to a registry.
+
+Its most common subtype is the
+<Javadoc name={"io.papermc.paper.registry.set.RegistryKeySet"}>`RegistryKeySet`</Javadoc> which
+simply holds onto <Javadoc name={"io.papermc.paper.registry.TypedKey"}>TypedKey</Javadoc> instances.
+An advantage of this data structure is its ability to remain valid even if the values of a
+registry change.
+
+A <Javadoc name={"io.papermc.paper.registry.set.RegistryKeySet"}>`RegistryKeySet`</Javadoc> can be
+created via the factory methods on <Javadoc name={"io.papermc.paper.registry.set.RegistrySet"}>`RegistrySet`</Javadoc> like this:
+```java
+// Create a new registry key set that holds a collection enchantments
+final RegistryKeySet<@NotNull Enchantment> bestEnchantments = RegistrySet.keySet(
+    RegistryKey.ENCHANTMENT,
+    // Arbitrary keys of enchantments to store in the key set.
+    EnchantmentKeys.CHANNELING,
+    TypedKey.create(RegistryKey.ENCHANTMENT, Key.key("papermc:softspoon"))
+);
+```
+
+A <Javadoc name={"io.papermc.paper.registry.tag.Tag"}>`Tag`</Javadoc> follows up the concept
+of a <Javadoc name={"io.papermc.paper.registry.set.RegistryKeySet"}>`RegistryKeySet`</Javadoc>
+but is itself named and can hence be referenced.
+A list of Vanilla tags can be found [on the Minecraft wiki](https://minecraft.wiki/w/Tag#Java_Edition_2).
+
+## Mutating registries
+
+Beyond plain reading access to registries, Paper also offers a way for plugins to modify registries.
+
+:::warning
+Mutating registries needs to be done during the server's bootstrap phase.
+As such, this section is only applicable to [Paper plugins](../getting-started/paper-plugins.mdx).
+
+**Exceptions** thrown by plugins during this phase will cause the server to shutdown before loading,
+as missing values or modifications to the registries would otherwise cause data loss.
+:::
+
+:::note
+Mutating registries is done via the
+<Javadoc
+  name={"io.papermc.paper.plugin.lifecycle.event.LifecycleEventManager"}>LifecycleEventManager</Javadoc>.
+See the [Lifecycle Events](./lifecycle.mdx) page for more information.
+:::
+
+The general entrypoint for mutating registries is
+the <Javadoc name={"io.papermc.paper.registry.event.RegistryEvents"}>RegistryEvents</Javadoc> type,
+which provides an entry point for each registry that can be modified.
+Modification of a registry can take two different forms.
+
+### Create new entries
+
+Creating new entries is done via the <Javadoc name={"io.papermc.paper.registry.event.RegistryEventProvider#freeze()"}>`freeze` lifecycle event</Javadoc>
+on the respective registries.
+The freeze event is called right before a registry's content is frozen in-place, meaning all Vanilla entries are registered.
+Plugins can hence register their own entries at this point.
+The following example shows how to create a new enchantment:
+
+```java
+public class TestPluginBootstrap implements PluginBootstrap {
+
+    @Override
+    public void bootstrap(@NotNull BootstrapContext context) {
+        // Register a new handled for the freeze lifecycle event on the enchantment registry
+        context.getLifecycleManager().registerEventHandler(RegistryEvents.ENCHANTMENT.freeze().newHandler(event -> {
+            event.registry().register(
+                // The key of the registry
+                // Plugins should use their own namespace instead of minecraft or papermc
+                TypedKey.create(RegistryKey.ENCHANTMENT, Key.key("papermc:pointy")),
+                b -> b.description(Component.text("Pointy"))
+                    .supportedItems(h.getOrCreateTag(ItemTypeTagKeys.SWORDS))
+                    .anvilCost(1)
+                    .maxLevel(25)
+                    .weight(10)
+                    .minimumCost(EnchantmentRegistryEntry.EnchantmentCost.of(1, 1))
+                    .maximumCost(EnchantmentRegistryEntry.EnchantmentCost.of(3, 1))
+                    .activeSlots(EquipmentSlotGroup.ANY)
+            );
+        }));
+    }
+}
+```
+
+### Modifying existing entries
+
+Modification of existing entries is useful for plugins that aim to change the way Vanilla entries
+behave. For this, use the <Javadoc name={"io.papermc.paper.registry.event.RegistryEventProvider#entryAdd()"}>`entryAdd` lifecycle event</Javadoc>.
+The event is called for _\*any\*_ entry added to a registry, however the API provides an easy way to target a specific entry for modification.
+The following example shows how to increase the maximum level of the `Sharpness` enchantment.
+
+```java
+@Override
+public void bootstrap(@NotNull BootstrapContext context) {
+    context.getLifecycleManager().registerEventHandler(RegistryEvents.ENCHANTMENT.entryAdd()
+        // Increase the max level to 20
+        .newHandler(event -> event.builder().maxLevel(20))
+        // Configure the handled to only be called for the Vanilla sharpness enchantment.
+        .filter(EnchantmentKeys.SHARPNESS)
+    );
+}
+```