From 12c76e95f9f2b9f1e07f1da46fa639e189e2a92f Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:42:27 +0200 Subject: [PATCH 01/25] Registry docs --- config/sidebar.paper.ts | 1 + docs/paper/dev/api/registries.mdx | 161 ++++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 docs/paper/dev/api/registries.mdx diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts index e3d3c727f..4fe862f95 100644 --- a/config/sidebar.paper.ts +++ b/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", diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx new file mode 100644 index 000000000..dd296b2ca --- /dev/null +++ b/docs/paper/dev/api/registries.mdx @@ -0,0 +1,161 @@ +--- +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 ItemType registry which holds all known item types. +Registries are available via the RegistryAccess. + +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 extend 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. +
    +
  1. + `net.kyori.adventure.key.Key` represent a namespace and a key. +
    2. +
  2. + TypedKey wrap an adventure key + but also including the key of + the registry the + TypedKey belongs to. +
    3. +
+An example of retrieving the sharpness enchantment using +TypedKeys looks as follows: + +```java +// Fetch the enchantment registry from the registry access +final Registry 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 Collection of the values might suffice, alternative approaches are +more often used by Minecraft and will hence be encountered. + +A `RegistrySet` defines a +collection of elements that *relate* to a registry. + +Its most common subtype is the +`RegistryKeySet` which +simply holds onto TypedKey instances. +An advantage of this data structure is its ability to remain valid even if the values of a +registry change. + +A `RegistryKeySet` can be +created via the factory methods on `RegistrySet` 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 `Tag` follows up the concept +of a `RegistryKeySet` +but is itself named and can hence be referenced. +A list of vanilla tags can be found on the minecraft wiki. + +## 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 servers bootstrap phase. +As such, this section is only applicable to [Paper plugins](./../getting-started/paper-plugins). +::: + +:::note +Mutating registries is done via the +LifecycleEventManager. +See the [Lifecycle Events](./lifecycle.mdx) page for more information. +::: + +The general entrypoint for mutating registries is +the RegistryEvents type, +which provides an entry point for each registry that can be modified. +Modification of a registries can take two different forms. + +### Create new entries + +Creating new entries is done via the `freeze` lifecycle event +on the respective registries. +The freeze event is called right before a registries 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 + TypedKey.create(RegistryKey.ENCHANTMENT, Key.key("papermc:pointy")), // Plugins should use their own namespace instead of minecraft or papermc + 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 the `entryAdd` lifecycle event. +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) + ); +} +``` From 3a4f74aeb73f499123855bf86f5845423fbfe99f Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:45:45 +0200 Subject: [PATCH 02/25] Fix build --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index dd296b2ca..f25d37c4a 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -94,7 +94,7 @@ Beyond plain reading access to registries, paper also offers a way for plugins t :::warning Mutating registries needs to be done during the servers bootstrap phase. -As such, this section is only applicable to [Paper plugins](./../getting-started/paper-plugins). +As such, this section is only applicable to [Paper plugins](../getting-started/paper-plugins.mdx). ::: :::note From 176d520d5e8973cb8af92ab2968996662be02561 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:49:24 +0200 Subject: [PATCH 03/25] More comment --- docs/paper/dev/api/registries.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index f25d37c4a..b6a97f1da 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -126,7 +126,8 @@ public class TestPluginBootstrap implements PluginBootstrap { context.getLifecycleManager().registerEventHandler(RegistryEvents.ENCHANTMENT.freeze().newHandler(event -> { event.registry().register( // The key of the registry - TypedKey.create(RegistryKey.ENCHANTMENT, Key.key("papermc:pointy")), // Plugins should use their own namespace instead of minecraft or papermc + // 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) From f475232cafd0606fe902fcaa0fd4912735976b9e Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:52:20 +0200 Subject: [PATCH 04/25] Update docs/paper/dev/api/registries.mdx Co-authored-by: Nassim Jahnke --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index b6a97f1da..1185e43aa 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -107,7 +107,7 @@ See the [Lifecycle Events](./lifecycle.mdx) page for more information. The general entrypoint for mutating registries is the RegistryEvents type, which provides an entry point for each registry that can be modified. -Modification of a registries can take two different forms. +Modification of a registry can take two different forms. ### Create new entries From bd9f5c3ce92a076cdc872d0564492b9254bba04b Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:52:31 +0200 Subject: [PATCH 05/25] Update docs/paper/dev/api/registries.mdx Co-authored-by: Nassim Jahnke --- docs/paper/dev/api/registries.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 1185e43aa..062d0017d 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -27,11 +27,11 @@ To retrieve elements from a registry, their respective keys can be used. The API defines two types of keys.
  1. - `net.kyori.adventure.key.Key` represent a namespace and a key. + `net.kyori.adventure.key.Key` represents a namespace and a key.
  2. - TypedKey wrap an adventure key - but also including the key of + TypedKey wraps an adventure key, + but also includes the key of the registry the TypedKey belongs to.
    3. From c0da570302b843320e2bdf831cc7a8682cbf6388 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:54:51 +0200 Subject: [PATCH 06/25] Add note about exceptions in bootstrap --- docs/paper/dev/api/registries.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 062d0017d..1c8066051 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -95,6 +95,9 @@ Beyond plain reading access to registries, paper also offers a way for plugins t :::warning Mutating registries needs to be done during the servers 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 From 10de6a700847f95e9429df25a8fe10af08b21f6f Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 21:58:55 +0200 Subject: [PATCH 07/25] Update docs/paper/dev/api/registries.mdx Co-authored-by: powercas_gamer --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 1c8066051..24f160763 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -147,7 +147,7 @@ public class TestPluginBootstrap implements PluginBootstrap { ### Modifying existing entries -Modification of existing entries is useful for plugins that aim to change the way vanilla entries +Modification of existing entries is useful for plugins that aim to change the way Vanilla entries behave. For this the `entryAdd` lifecycle event. 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. From 5ef8902b49968f370322dd1bfa7ebf7c39b78744 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:00:13 +0200 Subject: [PATCH 08/25] Vanilla --- docs/paper/dev/api/registries.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 24f160763..466729551 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -52,7 +52,7 @@ final Enchantment enchantment = enchantmentRegistry.getOrThrow(TypedKey.create( ); // Same as above, but using generated typed keys. -// Only vanilla entries have generated keys, for custom entries, the above method must be used. +// Only Vanilla entries have generated keys, for custom entries, the above method must be used. final Enchantment enchantment = enchantmentRegistry.getOrThrow(EnchantmentKeys.SHARPNESS); ``` @@ -86,7 +86,7 @@ final RegistryKeySet<@NotNull Enchantment> bestEnchantments = RegistrySet.keySet A `Tag` follows up the concept of a `RegistryKeySet` but is itself named and can hence be referenced. -A list of vanilla tags can be found on the minecraft wiki. +A list of Vanilla tags can be found on the minecraft wiki. ## Mutating registries @@ -116,7 +116,7 @@ Modification of a registry can take two different forms. Creating new entries is done via the `freeze` lifecycle event on the respective registries. -The freeze event is called right before a registries content is frozen in-place, meaning all vanilla entries are registered. +The freeze event is called right before a registries 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: @@ -158,7 +158,7 @@ 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. + // Configure the handled to only be called for the Vanilla sharpness enchantment. .filter(EnchantmentKeys.SHARPNESS) ); } From a9a19e24e1f5bac6e9219e95b121a4103f4324c0 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:17:07 +0200 Subject: [PATCH 09/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 466729551..42bc041ae 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -13,7 +13,7 @@ The Registry API and anything that uses it is currently experimental and may cha 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 ItemType registry which holds all known item types. -Registries are available via the RegistryAccess. +Registries are available via the RegistryAccess 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. From acaa65b16e82c3962b1490efa07f2ab5a16e79aa Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:17:34 +0200 Subject: [PATCH 10/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 42bc041ae..0f54d5f30 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -17,7 +17,7 @@ Registries are available via the Date: Mon, 17 Jun 2024 22:17:45 +0200 Subject: [PATCH 11/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 0f54d5f30..b087930e1 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -116,7 +116,7 @@ Modification of a registry can take two different forms. Creating new entries is done via the `freeze` lifecycle event on the respective registries. -The freeze event is called right before a registries content is frozen in-place, meaning all Vanilla entries are registered. +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: From c8b049e9b98a50bdcc247a1a765157e2baf9cb0b Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:17:56 +0200 Subject: [PATCH 12/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index b087930e1..54b9fece9 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -114,7 +114,7 @@ Modification of a registry can take two different forms. ### Create new entries -Creating new entries is done via the `freeze` lifecycle event +Creating new entries is done via the `freeze` lifecycle event 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. From 4baa6cd5a032ed92fcc1025db23b7c14d1fa6ac7 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:18:04 +0200 Subject: [PATCH 13/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 54b9fece9..c026554aa 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -30,7 +30,7 @@ The API defines two types of keys. `net.kyori.adventure.key.Key` represents a namespace and a key.
  3. - TypedKey wraps an adventure key, + TypedKey wraps an Adventure key, but also includes the key of the registry the TypedKey belongs to. From b2c5f5278dad87f7305f52dab0c7c5d3ef30dd61 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:18:13 +0200 Subject: [PATCH 14/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index c026554aa..cf0097872 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -36,7 +36,7 @@ The API defines two types of keys. TypedKey belongs to.
-An example of retrieving the sharpness enchantment using +An example of retrieving the `Sharpness` enchantment using TypedKeys looks as follows: ```java From f83727d63ae0a0e95480c9614a5d0128735d6ce1 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:18:36 +0200 Subject: [PATCH 15/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index cf0097872..5417431af 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -83,7 +83,7 @@ final RegistryKeySet<@NotNull Enchantment> bestEnchantments = RegistrySet.keySet ); ``` -A `Tag` follows up the concept +A `Tag` follows up the concept of a `RegistryKeySet` but is itself named and can hence be referenced. A list of Vanilla tags can be found on the minecraft wiki. From 89346f17f05992f09bc2f10fea9f3588ad364970 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:18:46 +0200 Subject: [PATCH 16/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 5417431af..27edb3088 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -148,7 +148,7 @@ public class TestPluginBootstrap implements PluginBootstrap { ### Modifying existing entries Modification of existing entries is useful for plugins that aim to change the way Vanilla entries -behave. For this the `entryAdd` lifecycle event. +behave. For this, use the `entryAdd` lifecycle event. 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. From b57f35d1e562071703f9f4a2db8c7fdb8b077b62 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:18:57 +0200 Subject: [PATCH 17/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 27edb3088..ecb77d0a3 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -149,7 +149,7 @@ public class TestPluginBootstrap implements PluginBootstrap { Modification of existing entries is useful for plugins that aim to change the way Vanilla entries behave. For this, use the `entryAdd` lifecycle event. -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 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 From 492bae03602a20d7141f944708709974a6614b8a Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:19:05 +0200 Subject: [PATCH 18/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index ecb77d0a3..82e27d4f6 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -150,7 +150,7 @@ public class TestPluginBootstrap implements PluginBootstrap { Modification of existing entries is useful for plugins that aim to change the way Vanilla entries behave. For this, use the `entryAdd` lifecycle event. 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. +The following example shows how to increase the maximum level of the `Sharpness` enchantment. ```java @Override From 93bb85c372fb150e38554f0b00d74608a4c0d405 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:19:16 +0200 Subject: [PATCH 19/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 82e27d4f6..b58109da1 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -86,7 +86,7 @@ final RegistryKeySet<@NotNull Enchantment> bestEnchantments = RegistrySet.keySet A `Tag` follows up the concept of a `RegistryKeySet` but is itself named and can hence be referenced. -A list of Vanilla tags can be found on the minecraft wiki. +A list of Vanilla tags can be found [on the Minecraft wiki](https://minecraft.wiki/w/Tag#Java_Edition_2). ## Mutating registries From e50aea751f17496b54fd53d9a5a359291e052187 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:19:28 +0200 Subject: [PATCH 20/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index b58109da1..64fff32fc 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -1,6 +1,6 @@ --- slug: /dev/registries -description: A guide to registries and their modification on paper +description: A guide to registries and their modification on Paper. --- # Registries From 991d99cd5a19fd25a41c2a5ea2a6c26c1a64485f Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:19:36 +0200 Subject: [PATCH 21/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 64fff32fc..d570ca994 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -9,7 +9,7 @@ description: A guide to registries and their modification on Paper. The Registry API and anything that uses it is currently experimental and may change in the future. ::: -## What is a registry ? +## 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 ItemType registry which holds all known item types. From c44dd5ce01d9772d5e843d8df03743dd3e5f7828 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:19:52 +0200 Subject: [PATCH 22/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index d570ca994..4b6f97974 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -93,7 +93,7 @@ A list of Vanilla tags can be found [on the Minecraft wiki](https://minecraft.wi 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 servers bootstrap phase. +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 From 2f8ec9435d4ee650322281fe208f94226d6b1990 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:20:09 +0200 Subject: [PATCH 23/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 4b6f97974..68402b33d 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -90,7 +90,7 @@ A list of Vanilla tags can be found [on the Minecraft wiki](https://minecraft.wi ## Mutating registries -Beyond plain reading access to registries, paper also offers a way for plugins to modify 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. From 6669c5ca475062a713fb93343eb6c66933e64f35 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:21:16 +0200 Subject: [PATCH 24/25] Update docs/paper/dev/api/registries.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Matouš Kučera --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 68402b33d..c68dcc306 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -96,7 +96,7 @@ Beyond plain reading access to registries, Paper also offers a way for plugins t 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 +**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. ::: From 648039627fc8ea77228e0e64b79fdf95cc6d1c93 Mon Sep 17 00:00:00 2001 From: Bjarne Koll Date: Mon, 17 Jun 2024 22:23:06 +0200 Subject: [PATCH 25/25] Javadoc Collection --- docs/paper/dev/api/registries.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index c68dcc306..80aa0ed3c 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -59,7 +59,7 @@ final Enchantment enchantment = enchantmentRegistry.getOrThrow(EnchantmentKeys.S ### Referencing registry values Referencing entries in a registry is easier said then done. -While for most cases a plain Collection of the values might suffice, alternative approaches are +While for most cases a plain Collection of the values might suffice, alternative approaches are more often used by Minecraft and will hence be encountered. A `RegistrySet` defines a