OpenSource/PaperMC
OpenSource/PaperMC
1
0
Fork 0
mirror of https://github.com/PaperMC/Paper.git synced 2024-12-27 06:50:12 +01:00
Code Issues Projects Releases Packages Wiki Activity

Introduce registry entry and builders

Browse source 
Co-authored-by: kokiriglade <git@kokirigla.de>
This commit is contained in:
Bjarne Koll 2024-06-13 22:35:05 +02:00
parent 146cd1a015
commit fcc777a0a8
8 changed files with 551 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
paper-api/src/main/java/io/papermc/paper/registry/RegistryKey.java
View file

@ -74,9 +74,10 @@ public sealed interface RegistryKey<T> extends Keyed permits RegistryKeyImpl {
@ApiStatus.Internal
RegistryKey<BlockType> BLOCK = create("block");
/**
* @apiNote DO NOT USE
* @apiNote use preferably only in the context of registry entries.
* @see io.papermc.paper.registry.data
*/
@ApiStatus.Internal
@ApiStatus.Experimental // Paper - already required for registry builders
RegistryKey<ItemType> ITEM = create("item");
/**
* Built-in registry for cat variants.

329
paper-api/src/main/java/io/papermc/paper/registry/data/EnchantmentRegistryEntry.java Normal file
View file

@ -0,0 +1,329 @@
package io.papermc.paper.registry.data;
import io.papermc.paper.registry.RegistryBuilder;
import io.papermc.paper.registry.RegistryKey;
import io.papermc.paper.registry.TypedKey;
import io.papermc.paper.registry.set.RegistryKeySet;
import io.papermc.paper.registry.set.RegistrySet;
import io.papermc.paper.registry.tag.TagKey;
import java.util.List;
import net.kyori.adventure.text.Component;
import org.bukkit.enchantments.Enchantment;
import org.bukkit.inventory.EquipmentSlotGroup;
import org.bukkit.inventory.ItemType;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.Range;
import org.jetbrains.annotations.Unmodifiable;
import org.jspecify.annotations.Nullable;
/**
* A data-centric version-specific registry entry for the {@link Enchantment} type.
*/
@ApiStatus.Experimental
@ApiStatus.NonExtendable
public interface EnchantmentRegistryEntry {
/**
* Provides the description of this enchantment entry as displayed to the client, e.g. "Sharpness" for the sharpness
* enchantment.
*
* @return the description component.
*/
Component description();
/**
* Provides the registry key set referencing the items this enchantment is supported on.
*
* @return the registry key set.
*/
RegistryKeySet<ItemType> supportedItems();
/**
* Provides the registry key set referencing the item types this enchantment can be applied to when
* enchanting in an enchantment table.
* <p>
* If this value is {@code null}, {@link #supportedItems()} will be sourced instead in the context of an enchantment table.
* Additionally, the tag {@link io.papermc.paper.registry.keys.tags.EnchantmentTagKeys#IN_ENCHANTING_TABLE} defines
* which enchantments can even show up in an enchantment table.
*
* @return the registry key set.
*/
@Nullable RegistryKeySet<ItemType> primaryItems();
/**
* Provides the weight of this enchantment used by the weighted random when selecting enchantments.
*
* @return the weight value.
* @see <a href="https://minecraft.wiki/w/Enchanting">https://minecraft.wiki/w/Enchanting</a> for examplary weights.
*/
@Range(from = 1, to = 1024) int weight();
/**
* Provides the maximum level this enchantment can have when applied.
*
* @return the maximum level.
*/
@Range(from = 1, to = 255) int maxLevel();
/**
* Provides the minimum cost needed to enchant an item with this enchantment.
* <p>
* Note that a cost is not directly related to the consumed xp.
*
* @return the enchantment cost.
* @see <a href="https://minecraft.wiki/w/Enchanting/Levels">https://minecraft.wiki/w/Enchanting/Levels</a> for
* examplary costs.
*/
EnchantmentCost minimumCost();
/**
* Provides the maximum cost allowed to enchant an item with this enchantment.
* <p>
* Note that a cost is not directly related to the consumed xp.
*
* @return the enchantment cost.
* @see <a href="https://minecraft.wiki/w/Enchanting/Levels">https://minecraft.wiki/w/Enchanting/Levels</a> for
* examplary costs.
*/
EnchantmentCost maximumCost();
/**
* Provides the cost of applying this enchantment using an anvil.
* <p>
* Note that this is halved when using an enchantment book, and is multiplied by the level of the enchantment.
* See <a href="https://minecraft.wiki/w/Anvil_mechanics">https://minecraft.wiki/w/Anvil_mechanics</a> for more
* information.
* </p>
*
* @return the anvil cost of this enchantment
*/
@Range(from = 0, to = Integer.MAX_VALUE) int anvilCost();
/**
* Provides a list of slot groups this enchantment may be active in.
* <p>
* If the item enchanted with this enchantment is equipped in a slot not covered by the returned list and its
* groups, the enchantment's effects, like attribute modifiers, will not activate.
*
* @return a list of equipment slot groups.
* @see Enchantment#getActiveSlotGroups()
*/
@Unmodifiable List<EquipmentSlotGroup> activeSlots();
/**
* Provides the registry key set of enchantments that this enchantment is exclusive with.
* <p>
* Exclusive enchantments prohibit the application of this enchantment to an item if they are already present on
* said item.
*
* @return a registry set of enchantments exclusive to this one.
*/
RegistryKeySet<Enchantment> exclusiveWith();
/**
* A mutable builder for the {@link EnchantmentRegistryEntry} plugins may change in applicable registry events.
* <p>
* The following values are required for each builder:
* <ul>
* <li>{@link #description(Component)}</li>
* <li>{@link #supportedItems(RegistryKeySet)}</li>
* <li>{@link #weight(int)}</li>
* <li>{@link #maxLevel(int)}</li>
* <li>{@link #minimumCost(EnchantmentCost)}</li>
* <li>{@link #maximumCost(EnchantmentCost)}</li>
* <li>{@link #anvilCost(int)}</li>
* <li>{@link #activeSlots(Iterable)}</li>
* </ul>
*/
@ApiStatus.Experimental
@ApiStatus.NonExtendable
interface Builder extends EnchantmentRegistryEntry, RegistryBuilder<Enchantment> {
/**
* Configures the description of this enchantment entry as displayed to the client, e.g. "Sharpness" for the
* sharpness enchantment.
*
* @param description the description component.
* @return this builder instance.
*/
@Contract(value = "_ -> this", mutates = "this")
Builder description(Component description);
/**
* Configures the set of supported items this enchantment can be applied on. This
* can be a {@link RegistryKeySet} created via {@link RegistrySet#keySet(io.papermc.paper.registry.RegistryKey, Iterable)} or
* a tag obtained via {@link io.papermc.paper.registry.event.RegistryFreezeEvent#getOrCreateTag(TagKey)} with
* tag keys found in {@link io.papermc.paper.registry.keys.tags.ItemTypeTagKeys} such as
* {@link io.papermc.paper.registry.keys.tags.ItemTypeTagKeys#ENCHANTABLE_ARMOR} and
* {@link io.papermc.paper.registry.keys.tags.ItemTypeTagKeys#ENCHANTABLE_SWORD}.
*
* @param supportedItems the registry key set representing the supported items.
* @return this builder instance.
* @see RegistrySet#keySet(RegistryKey, TypedKey[])
* @see io.papermc.paper.registry.event.RegistryFreezeEvent#getOrCreateTag(TagKey)
*/
@Contract(value = "_ -> this", mutates = "this")
Builder supportedItems(RegistryKeySet<ItemType> supportedItems);
/**
* Configures a set of item types this enchantment can naturally be applied to, when enchanting in an
* enchantment table.This can be a {@link RegistryKeySet} created via
* {@link RegistrySet#keySet(io.papermc.paper.registry.RegistryKey, Iterable)} or a tag obtained via
* {@link io.papermc.paper.registry.event.RegistryFreezeEvent#getOrCreateTag(TagKey)} with
* tag keys found in {@link io.papermc.paper.registry.keys.tags.ItemTypeTagKeys} such as
* {@link io.papermc.paper.registry.keys.tags.ItemTypeTagKeys#ENCHANTABLE_ARMOR} and
* {@link io.papermc.paper.registry.keys.tags.ItemTypeTagKeys#ENCHANTABLE_SWORD}.
* <p>
* Defaults to {@code null} which means all {@link #supportedItems()} are considered primary items.
* Additionally, the tag {@link io.papermc.paper.registry.keys.tags.EnchantmentTagKeys#IN_ENCHANTING_TABLE} defines
* which enchantments can even show up in an enchantment table.
*
* @param primaryItems the registry key set representing the primary items.
* @return this builder instance.
* @see RegistrySet#keySet(RegistryKey, TypedKey[])
* @see io.papermc.paper.registry.event.RegistryFreezeEvent#getOrCreateTag(TagKey)
*/
@Contract(value = "_ -> this", mutates = "this")
Builder primaryItems(@Nullable RegistryKeySet<ItemType> primaryItems);
/**
* Configures the weight of this enchantment used by the weighted random when selecting enchantments.
*
* @param weight the weight value.
* @return this builder instance.
* @see <a href="https://minecraft.wiki/w/Enchanting">https://minecraft.wiki/w/Enchanting</a> for examplary weights.
*/
@Contract(value = "_ -> this", mutates = "this")
Builder weight(@Range(from = 1, to = 1024) int weight);
/**
* Configures the maximum level this enchantment can have when applied.
*
* @param maxLevel the maximum level.
* @return this builder instance.
*/
@Contract(value = "_ -> this", mutates = "this")
Builder maxLevel(@Range(from = 1, to = 255) int maxLevel);
/**
* Configures the minimum cost needed to enchant an item with this enchantment.
* <p>
* Note that a cost is not directly related to the consumed xp.
*
* @param minimumCost the enchantment cost.
* @return this builder instance.
* @see <a href="https://minecraft.wiki/w/Enchanting/Levels">https://minecraft.wiki/w/Enchanting/Levels</a> for
* examplary costs.
*/
@Contract(value = "_ -> this", mutates = "this")
Builder minimumCost(EnchantmentCost minimumCost);
/**
* Configures the maximum cost to enchant an item with this enchantment.
* <p>
* Note that a cost is not directly related to the consumed xp.
*
* @param maximumCost the enchantment cost.
* @return this builder instance.
* @see <a href="https://minecraft.wiki/w/Enchanting/Levels">https://minecraft.wiki/w/Enchanting/Levels</a> for
* examplary costs.
*/
@Contract(value = "_ -> this", mutates = "this")
Builder maximumCost(EnchantmentCost maximumCost);
/**
* Configures the cost of applying this enchantment using an anvil.
* <p>
* Note that this is halved when using an enchantment book, and is multiplied by the level of the enchantment.
* See <a href="https://minecraft.wiki/w/Anvil_mechanics">https://minecraft.wiki/w/Anvil_mechanics</a> for more information.
* </p>
*
* @param anvilCost the anvil cost of this enchantment
* @return this builder instance.
* @see Enchantment#getAnvilCost()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder anvilCost(@Range(from = 0, to = Integer.MAX_VALUE) int anvilCost);
/**
* Configures the list of slot groups this enchantment may be active in.
* <p>
* If the item enchanted with this enchantment is equipped in a slot not covered by the returned list and its
* groups, the enchantment's effects, like attribute modifiers, will not activate.
*
* @param activeSlots a list of equipment slot groups.
* @return this builder instance.
* @see Enchantment#getActiveSlotGroups()
*/
@Contract(value = "_ -> this", mutates = "this")
default Builder activeSlots(final EquipmentSlotGroup... activeSlots) {
return this.activeSlots(List.of(activeSlots));
}
/**
* Configures the list of slot groups this enchantment may be active in.
* <p>
* If the item enchanted with this enchantment is equipped in a slot not covered by the returned list and its
* groups, the enchantment's effects, like attribute modifiers, will not activate.
*
* @param activeSlots a list of equipment slot groups.
* @return this builder instance.
* @see Enchantment#getActiveSlotGroups()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder activeSlots(Iterable<EquipmentSlotGroup> activeSlots);
/**
* Configures the registry key set of enchantments that this enchantment is exclusive with.
* <p>
* Exclusive enchantments prohibit the application of this enchantment to an item if they are already present on
* said item.
* <p>
* Defaults to an empty set allowing this enchantment to be applied regardless of other enchantments.
*
* @param exclusiveWith a registry set of enchantments exclusive to this one.
* @return this builder instance.
* @see RegistrySet#keySet(RegistryKey, TypedKey[])
* @see io.papermc.paper.registry.event.RegistryFreezeEvent#getOrCreateTag(TagKey)
*/
@Contract(value = "_ -> this", mutates = "this")
Builder exclusiveWith(RegistryKeySet<Enchantment> exclusiveWith);
}
/**
* The enchantment cost interface represents the cost of applying an enchantment, split up into its different components.
*/
interface EnchantmentCost {
/**
* Returns the base cost of this enchantment cost, no matter what level the enchantment has.
*
* @return the cost in levels.
*/
int baseCost();
/**
* Returns the additional cost added per level of the enchantment to be applied.
* This cost is applied per level above the first.
*
* @return the cost added to the {@link #baseCost()} for each level above the first.
*/
int additionalPerLevelCost();
/**
* Creates a new enchantment cost instance based on the passed values.
*
* @param baseCost the base cost of the enchantment cost as returned by {@link #baseCost()}
* @param additionalPerLevelCost the additional cost per level, as returned by {@link #additionalPerLevelCost()}
* @return the created instance.
*/
@Contract(value = "_,_ -> new", pure = true)
static EnchantmentCost of(final int baseCost, final int additionalPerLevelCost) {
record Impl(int baseCost, int additionalPerLevelCost) implements EnchantmentCost {
}
return new Impl(baseCost, additionalPerLevelCost);
}
}
}

47
paper-api/src/main/java/io/papermc/paper/registry/data/GameEventRegistryEntry.java Normal file
View file

@ -0,0 +1,47 @@
package io.papermc.paper.registry.data;
import io.papermc.paper.registry.RegistryBuilder;
import org.bukkit.GameEvent;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.Range;
/**
* A data-centric version-specific registry entry for the {@link GameEvent} type.
*/
@ApiStatus.Experimental
@ApiStatus.NonExtendable
public interface GameEventRegistryEntry {
/**
* Provides the range in which this game event will notify its listeners.
*
* @return the range of blocks, represented as an int.
* @see GameEvent#getRange()
*/
@Range(from = 0, to = Integer.MAX_VALUE) int range();
/**
* A mutable builder for the {@link GameEventRegistryEntry} plugins may change in applicable registry events.
* <p>
* The following values are required for each builder:
* <ul>
* <li>{@link #range(int)}</li>
* </ul>
*/
@ApiStatus.Experimental
@ApiStatus.NonExtendable
interface Builder extends GameEventRegistryEntry, RegistryBuilder<GameEvent> {
/**
* Sets the range in which this game event should notify its listeners.
*
* @param range the range of blocks.
* @return this builder instance.
* @see GameEventRegistryEntry#range()
* @see GameEvent#getRange()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder range(@Range(from = 0, to = Integer.MAX_VALUE) int range);
}
}

128
paper-api/src/main/java/io/papermc/paper/registry/data/PaintingVariantRegistryEntry.java Normal file
View file

@ -0,0 +1,128 @@
package io.papermc.paper.registry.data;
import io.papermc.paper.registry.RegistryBuilder;
import net.kyori.adventure.key.Key;
import net.kyori.adventure.text.Component;
import org.bukkit.Art;
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.Contract;
import org.jetbrains.annotations.Range;
import org.jspecify.annotations.Nullable;
/**
* A data-centric version-specific registry entry for the {@link Art} type.
*/
@ApiStatus.Experimental
@ApiStatus.NonExtendable
public interface PaintingVariantRegistryEntry {
/**
* Provides the width of this painting in blocks.
*
* @return the width.
* @see Art#getBlockWidth()
*/
@Range(from = 1, to = 16) int width();
/**
* Provides the height of this painting in blocks.
*
* @return the height.
* @see Art#getBlockHeight()
*/
@Range(from = 1, to = 16) int height();
/**
* Provides the title of the painting visible in the creative inventory.
*
* @return the title.
* @see Art#title()
*/
@Nullable Component title();
/**
* Provides the author of the painting visible in the creative inventory.
*
* @return the author.
* @see Art#author()
*/
@Nullable Component author();
/**
* Provides the asset id of the painting, which is the location of the sprite to use.
*
* @return the asset id.
* @see Art#assetId()
*/
Key assetId();
/**
* A mutable builder for the {@link PaintingVariantRegistryEntry} plugins may change in applicable registry events.
* <p>
* The following values are required for each builder:
* <ul>
* <li>{@link #width(int)}</li>
* <li>{@link #height(int)}</li>
* <li>{@link #assetId(Key)}</li>
* </ul>
*/
@ApiStatus.Experimental
@ApiStatus.NonExtendable
interface Builder extends PaintingVariantRegistryEntry, RegistryBuilder<Art> {
/**
* Sets the width of the painting in blocks.
*
* @param width the width in blocks.
* @return this builder instance.
* @see PaintingVariantRegistryEntry#width()
* @see Art#getBlockWidth()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder width(@Range(from = 1, to = 16) int width);
/**
* Sets the height of the painting in blocks.
*
* @param height the height in blocks.
* @return this builder instance.
* @see PaintingVariantRegistryEntry#height()
* @see Art#getBlockHeight()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder height(@Range(from = 1, to = 16) int height);
/**
* Sets the title of the painting.
*
* @param title the title.
* @return this builder instance.
* @see PaintingVariantRegistryEntry#title()
* @see Art#title()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder title(@Nullable Component title);
/**
* Sets the author of the painting.
*
* @param author the author.
* @return this builder instance.
* @see PaintingVariantRegistryEntry#author()
* @see Art#author()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder author(@Nullable Component author);
/**
* Sets the asset id of the painting, which is the location of the sprite to use.
*
* @param assetId the asset id.
* @return this builder instance.
* @see PaintingVariantRegistryEntry#assetId()
* @see Art#assetId()
*/
@Contract(value = "_ -> this", mutates = "this")
Builder assetId(Key assetId);
}
}

12
paper-api/src/main/java/io/papermc/paper/registry/data/package-info.java Normal file
View file

@ -0,0 +1,12 @@
/**
* Collection of registry entry types that may be created or modified via the
* {@link io.papermc.paper.registry.event.RegistryEvent}.
* <p>
* A registry entry represents its runtime API counterpart as a version-specific data-focused type.
* Registry entries are not expected to be used during plugin runtime interactions with the API but are mostly
* exposed during registry creation/modification.
*/
@NullMarked
package io.papermc.paper.registry.data;
import org.jspecify.annotations.NullMarked;

13
paper-api/src/main/java/io/papermc/paper/registry/event/RegistryEvents.java
View file

@ -1,8 +1,17 @@
package io.papermc.paper.registry.event;
import io.papermc.paper.registry.RegistryKey;
import io.papermc.paper.registry.data.EnchantmentRegistryEntry;
import io.papermc.paper.registry.data.GameEventRegistryEntry;
import io.papermc.paper.registry.data.PaintingVariantRegistryEntry;
import org.bukkit.Art;
import org.bukkit.GameEvent;
import org.bukkit.enchantments.Enchantment;
import org.jetbrains.annotations.ApiStatus;
import org.jspecify.annotations.NullMarked;
import static io.papermc.paper.registry.event.RegistryEventProviderImpl.create;
/**
* Holds providers for {@link RegistryEntryAddEvent} and {@link RegistryFreezeEvent}
* handlers for each applicable registry.
@ -11,6 +20,10 @@ import org.jspecify.annotations.NullMarked;
@NullMarked
public final class RegistryEvents {
public static final RegistryEventProvider<GameEvent, GameEventRegistryEntry.Builder> GAME_EVENT = create(RegistryKey.GAME_EVENT);
public static final RegistryEventProvider<Enchantment, EnchantmentRegistryEntry.Builder> ENCHANTMENT = create(RegistryKey.ENCHANTMENT);
public static final RegistryEventProvider<Art, PaintingVariantRegistryEntry.Builder> PAINTING_VARIANT = create(RegistryKey.PAINTING_VARIANT);
private RegistryEvents() {
}
}

18
paper-api/src/main/java/org/bukkit/GameEvent.java
View file

@ -141,4 +141,22 @@ public abstract class GameEvent implements Keyed {
private static GameEvent getEvent(@NotNull String key) {
return Registry.GAME_EVENT.getOrThrow(NamespacedKey.minecraft(key));
}
// Paper start
/**
* Gets the range of the event which is used to
* notify listeners of the event.
*
* @return the range
*/
public abstract int getRange();
/**
* Gets the vibration level of the game event for vibration listeners.
* Not all events have vibration levels, and a level of 0 means
* it won't cause any vibrations.
*
* @return the vibration level
*/
public abstract int getVibrationLevel();
// Paper end
}

2
paper-api/src/main/java/org/bukkit/inventory/ItemType.java
View file

@ -46,7 +46,7 @@ import org.jetbrains.annotations.Nullable;
* official replacement for the aforementioned enum. Entirely incompatible
* changes may occur. Do not use this API in plugins.
*/
@ApiStatus.Internal
@ApiStatus.Experimental // Paper - already required for registry builders
public interface ItemType extends Keyed, Translatable, net.kyori.adventure.translation.Translatable { // Paper - add Translatable
/**