javadocs

1 files changed, 209 insertions, 13 deletions

diff --git a/patches/api/0480-WIP-DataComponent-API.patch b/patches/api/0480-WIP-DataComponent-API.patch
index abc31f57bb..62d9a052ec 100644
--- a/patches/api/0480-WIP-DataComponent-API.patch
+++ b/patches/api/0480-WIP-DataComponent-API.patch
@@ -138,12 +138,13 @@ index 0000000000000000000000000000000000000000..50d15b4e0ed5cd17fdc95476ee4650ef
 +}
 diff --git a/src/main/java/io/papermc/paper/component/DataComponentTypes.java b/src/main/java/io/papermc/paper/component/DataComponentTypes.java
 new file mode 100644
-index 0000000000000000000000000000000000000000..f5cc964e0976b5c256cc2271c31942cc87a34388
+index 0000000000000000000000000000000000000000..5c76b3e09be7c6b525ff71aae5fd9233ed567876
 --- /dev/null
 +++ b/src/main/java/io/papermc/paper/component/DataComponentTypes.java
-@@ -0,0 +1,116 @@
+@@ -0,0 +1,311 @@
 +package io.papermc.paper.component;
 +
++import com.destroystokyo.paper.MaterialSetTag;
 +import io.papermc.paper.component.item.BannerPatternLayers;
 +import io.papermc.paper.component.item.BlockItemDataProperties;
 +import io.papermc.paper.component.item.BundleContents;
@@ -181,6 +182,9 @@ index 0000000000000000000000000000000000000000..f5cc964e0976b5c256cc2271c31942cc
 +import org.bukkit.NamespacedKey;
 +import org.bukkit.Registry;
 +import org.bukkit.inventory.ItemRarity;
++import org.checkerframework.checker.index.qual.NonNegative;
++import org.checkerframework.checker.index.qual.Positive;
++import org.checkerframework.common.value.qual.IntRange;
 +import java.security.Key;
 +import java.util.List;
 +
@@ -189,61 +193,252 @@ index 0000000000000000000000000000000000000000..f5cc964e0976b5c256cc2271c31942cc
 +public final class DataComponentTypes {
 +
 +    // public static final DataComponentType.Valued<BinaryTagHolder> CUSTOM_DATA = valued("custom_data");
-+    public static final DataComponentType.Valued<Integer> MAX_STACK_SIZE = valued("max_stack_size");
-+    public static final DataComponentType.Valued<Integer> MAX_DAMAGE = valued("max_damage");
-+    public static final DataComponentType.Valued<Integer> DAMAGE = valued("damage");
++    /**
++     * Controls the maximum stacking size of this item
++     * <br>
++     * Values greater than 1 are mutually exclusive with the {@link #MAX_DAMAGE} component
++     */
++    public static final DataComponentType.Valued<@IntRange(from = 1, to = 99) Integer> MAX_STACK_SIZE = valued("max_stack_size");
++    /**
++     * Controls the maximum amount of damage than an item can take,
++     * if not present, the item cannot be damaged
++     * <br>
++     * Mutually exclusive with the {@link #MAX_STACK_SIZE} component greater than 1
++     * @see #DAMAGE
++     */
++    public static final DataComponentType.Valued<@Positive Integer> MAX_DAMAGE = valued("max_damage");
++    /**
++     * The amount of durability removed from an item,
++     * for damageable items (with the {@link #MAX_DAMAGE} component), has an implicit default value of: {@code 0}
++     * @see #MAX_DAMAGE
++     */
++    public static final DataComponentType.Valued<@NonNegative Integer> DAMAGE = valued("damage");
++    /**
++     * If set, the item will not lose any durability when used
++     */
 +    public static final DataComponentType.Valued<Unbreakable> UNBREAKABLE = valued("unbreakable");
++    /**
++     * Custom name override for an item (as set by renaming with an Anvil)
++     * @see #ITEM_NAME
++     */
 +    public static final DataComponentType.Valued<Component> CUSTOM_NAME = valued("custom_name");
++    /**
++     * When present, replaces default item name with contained chat component
++     * <p>
++     * Differences from {@link #CUSTOM_NAME}:
++     * <li>can't be changed or removed in Anvil</li>
++     * <li>is not styled with italics when displayed to player</li>
++     * <li>does not show labels where applicable
++     *      (for example: banner markers, names in item frames)</li>
++     * @see #CUSTOM_NAME
++     */
 +    public static final DataComponentType.Valued<Component> ITEM_NAME = valued("item_name");
++    /**
++     * Additional lines to include in an item's tooltip
++     */
 +    public static final DataComponentType.Valued<ItemLore> LORE = valued("lore");
++    /**
++     * Controls the color of the item name
++     */
 +    public static final DataComponentType.Valued<ItemRarity> RARITY = valued("rarity");
++    /**
++     * Controls the enchantments on an item
++     * <br>
++     * If not present on a non-enchantment book, this item will not work in an anvil
++     * @see #STORED_ENCHANTMENTS
++     */
 +    public static final DataComponentType.Valued<ItemEnchantments> ENCHANTMENTS = valued("enchantments");
++    /**
++     * Controls which blocks a player in Adventure mode can place on with this item.
++     */
 +    public static final DataComponentType.Valued<ItemAdventurePredicate> CAN_PLACE_ON = valued("can_place_on");
++    /**
++     * Controls which blocks a player in Adventure mode can break with this item.
++     */
 +    public static final DataComponentType.Valued<ItemAdventurePredicate> CAN_BREAK = valued("can_break");
++    /**
++     * Holds attribute modifiers applied to any item,
++     * if not set, has an implicit default value based on the item type's
++     * default attributes (e.g. attack damage for weapons)
++     */
 +    public static final DataComponentType.Valued<ItemAttributeModifiers> ATTRIBUTE_MODIFIERS = valued("attribute_modifiers");
++    /**
++     * Controls the minecraft:custom_model_data property in the item model
++     */
 +    public static final DataComponentType.Valued<CustomModelData> CUSTOM_MODEL_DATA = valued("custom_model_data");
++    /**
++     * If set, disables 'additional' tooltip part which comes from the item type
++     * (e.g. content of a shulker)
++     */
 +    public static final DataComponentType.NonValued HIDE_ADDITIONAL_TOOLTIP = unvalued("hide_additional_tooltip");
++    /**
++     * If set, it will completely hide whole item tooltip (that includes item name)
++     */
 +    public static final DataComponentType.NonValued  HIDE_TOOLTIP = unvalued("hide_tooltip");
-+    public static final DataComponentType.Valued<Integer> REPAIR_COST = valued("repair_cost");
-+    public static final DataComponentType.NonValued  CREATIVE_SLOT_LOCK = unvalued("creative_slot_lock");
++    /**
++     * The additional experience cost required to modify an item in an Anvil.
++     * If not present, has an implicit default value of: {@code 0}
++     */
++    public static final DataComponentType.Valued<@NonNegative Integer> REPAIR_COST = valued("repair_cost");
++    /**
++     * Causes an item to not be pickable in the creative menu, currently not very useful.
++     */
++    public static final DataComponentType.NonValued CREATIVE_SLOT_LOCK = unvalued("creative_slot_lock");
++    /**
++     * Overrides the enchantment glint effect on an item.
++     * If not present, default behaviour is used
++     */
 +    public static final DataComponentType.Valued<Boolean> ENCHANTMENT_GLINT_OVERRIDE = valued("enchantment_glint_override");
++    /**
++     * Marks that a projectile item would be intangible when fired
++     * (i.e. can only be picked up by a creative mode player)
++     */
 +    public static final DataComponentType.NonValued INTANGIBLE_PROJECTILE = unvalued("intangible_projectile");
++    /**
++     * When present, this item will behave as if a food (can be eaten)
++     */
 +    public static final DataComponentType.Valued<FoodProperties> FOOD = valued("food");
++    /**
++     * If present, this item will not burn in fire
++     */
 +    public static final DataComponentType.NonValued FIRE_RESISTANT = unvalued("fire_resistant");
++    /**
++     * Controls the behavior of the item as a tool
++     */
 +    public static final DataComponentType.Valued<Tool> TOOL = valued("tool");
++    /**
++     * Stores list of enchantments and their levels for an Enchanted Book.
++     * Unlike {@link #ENCHANTMENTS}, the effects provided by enchantments
++     * do not apply from this component.
++     * <br>
++     * If not present on an Enchanted Book, it will not work in an anvil
++     * <br>
++     * Has an undefined behaviour if present on an item that is not an Enchanted Book
++     * (currently the presence of this component allows enchantments from {@link #ENCHANTMENTS}
++     * to be applied as if this item was an Enchanted Book)
++     * @see #ENCHANTMENTS
++     */
 +    public static final DataComponentType.Valued<ItemEnchantments> STORED_ENCHANTMENTS = valued("stored_enchantments");
++    /**
++     * Represents a color applied to a dyeable item (in the {@link org.bukkit.Tag#ITEMS_DYEABLE} item tag)
++     */
 +    public static final DataComponentType.Valued<DyedItemColor> DYED_COLOR = valued("dyed_color");
++    /**
++     * Represents the tint of the decorations on the Filled Map item
++     */
 +    public static final DataComponentType.Valued<MapItemColor> MAP_COLOR = valued("map_color");
++    /**
++     * References the shared map state holding map contents and markers for a Filled Map
++     */
 +    public static final DataComponentType.Valued<MapID> MAP_ID = valued("map_id");
++    /**
++     * Holds a list of markers to be placed on a Filled Map (used for Explorer Maps)
++     */
 +    public static final DataComponentType.Valued<MapDecorations> MAP_DECORATIONS = valued("map_decorations");
++    /**
++     * Internal map item state used in the map crafting recipe
++     */
 +    public static final DataComponentType.Valued<MapPostProcessing> MAP_POST_PROCESSING = valued("map_post_processing");
++    /**
++     * Holds all projectiles that have been loaded into a Crossbow.
++     * If not present, the Crossbow is not charged
++     */
 +    public static final DataComponentType.Valued<ChargedProjectiles> CHARGED_PROJECTILES = valued("charged_projectiles");
++    /**
++     * Holds all items stored inside a Bundle.
++     * If removed, items cannot be added to the Bundle
++     */
 +    public static final DataComponentType.Valued<BundleContents> BUNDLE_CONTENTS = valued("bundle_contents");
++    /**
++     * Holds the contents of a potion (Potion, Splash Potion, Lingering Potion),
++     * or potion applied to an item (Tipped Arrow)
++     */
 +    public static final DataComponentType.Valued<PotionContents> POTION_CONTENTS = valued("potion_contents");
++    /**
++     * Holds the effects that will be applied when consuming Suspicious Stew
++     */
 +    public static final DataComponentType.Valued<SuspiciousStewEffects> SUSPICIOUS_STEW_EFFECTS = valued("suspicious_stew_effects");
++    /**
++     * Holds the contents in a Book and Quill
++     */
 +    public static final DataComponentType.Valued<WritableBookContent> WRITABLE_BOOK_CONTENT = valued("writable_book_content");
++    /**
++     * Holds the contents and metadata of a Written Book
++     */
 +    public static final DataComponentType.Valued<WrittenBookContent> WRITTEN_BOOK_CONTENT = valued("written_book_content");
++    /**
++     * Holds the trims applied to an item in recipes
++     */
 +    public static final DataComponentType.Valued<ItemArmorTrim> TRIM = valued("trim");
 +    // debug_stick_state - Block Property API
 +    // entity_data
 +    // bucket_entity_data
 +    // block_entity_data
++    /**
++     * Holds the instrument type used by a Goat Horn
++     */
 +    public static final DataComponentType.Valued<MusicInstrument> INSTRUMENT = valued("instrument");
-+    public static final DataComponentType.Valued<Integer> OMINOUS_BOTTLE_AMPLIFIER = valued("ominous_bottle_amplifier");
++    /**
++     * Controls the amplifier amount for an Ominous Bottle's Bad Omen effect
++     */
++    public static final DataComponentType.Valued<@IntRange(from = 0, to = 4) Integer> OMINOUS_BOTTLE_AMPLIFIER = valued("ominous_bottle_amplifier");
++    /**
++     * List of recipes that should be unlocked when using the Knowledge Book item
++     */
 +    public static final DataComponentType.Valued<JukeboxPlayable> JUKEBOX_PLAYABLE = valued("jukebox_playable");
 +    public static final DataComponentType.Valued<List<Key>> RECIPES = valued("recipes");
++    /**
++     * If present, specifies that the Compass is a Lodestone Compass
++     */
 +    public static final DataComponentType.Valued<LodestoneTracker> LODESTONE_TRACKER = valued("lodestone_tracker");
++    /**
++     * Stores the explosion crafted in a Firework Star
++     */
 +    public static final DataComponentType.Valued<FireworkEffect> FIREWORK_EXPLOSION = valued("firework_explosion");
++    /**
++     * Stores all explosions crafted into a Firework Rocket, as well as flight duration
++     */
 +    public static final DataComponentType.Valued<Fireworks> FIREWORKS = valued("fireworks");
++    /**
++     * Controls the skin displayed on a Player Head
++     */
 +    public static final DataComponentType.Valued<ResolvableProfile> PROFILE = valued("profile");
++    /**
++     * Controls the sound played by a Player Head when placed on a Note Block
++     */
 +    public static final DataComponentType.Valued<NamespacedKey> NOTE_BLOCK_SOUND = valued("note_block_sound");
++    /**
++     * Stores the additional patterns applied to a Banner or Shield
++     */
 +    public static final DataComponentType.Valued<BannerPatternLayers> BANNER_PATTERNS = valued("banner_patterns");
++    /**
++     * Stores the base color for a Shield
++     */
 +    public static final DataComponentType.Valued<DyeColor> BASE_COLOR = valued("base_color");
++    /**
++     * Stores the Sherds applied to each side of a Decorated Pot
++     */
 +    public static final DataComponentType.Valued<PotDecorations> POT_DECORATIONS = valued("pot_decorations");
++    /**
++     * Holds the contents of container blocks (Chests, Shulker Boxes) in item form
++     */
 +    public static final DataComponentType.Valued<ItemContainerContents> CONTAINER = valued("container");
++    /**
++     * Holds block state properties to apply when placing a block
++     */
 +    public static final DataComponentType.Valued<BlockItemDataProperties> BLOCK_DATA = valued("block_state");
 +    // bees
++    /**
++     * Holds the lock state of a container-like block,
++     * copied to container block when placed
++     * <br>
++     * An item with a custom name of the same value must be used
++     * to open this container
++     */
 +    public static final DataComponentType.Valued<LockCode> LOCK = valued("lock");
++    /**
++     * Holds the unresolved loot table and seed of a container-like block
++     */
 +    public static final DataComponentType.Valued<SeededContainerLoot> CONTAINER_LOOT = valued("container_loot");
 +
 +    private static DataComponentType.NonValued unvalued(final String name) {
@@ -896,16 +1091,17 @@ index 0000000000000000000000000000000000000000..41c91487c3e60c744dba7cf0be86adce
 +}
 diff --git a/src/main/java/io/papermc/paper/component/item/ItemEnchantments.java b/src/main/java/io/papermc/paper/component/item/ItemEnchantments.java
 new file mode 100644
-index 0000000000000000000000000000000000000000..97d1dca2b7f7ea2a786408d064973e271e946ac6
+index 0000000000000000000000000000000000000000..7787de27d3931e9c305916228517fa3bbea83971
 --- /dev/null
 +++ b/src/main/java/io/papermc/paper/component/item/ItemEnchantments.java
-@@ -0,0 +1,36 @@
+@@ -0,0 +1,37 @@
 +package io.papermc.paper.component.item;
 +
 +import io.papermc.paper.component.ComponentBuilder;
 +import java.util.Map;
 +import org.bukkit.enchantments.Enchantment;
 +import org.checkerframework.checker.nullness.qual.NonNull;
++import org.checkerframework.common.value.qual.IntRange;
 +import org.jetbrains.annotations.ApiStatus;
 +import org.jetbrains.annotations.Contract;
 +import org.jetbrains.annotations.Unmodifiable;
@@ -914,7 +1110,7 @@ index 0000000000000000000000000000000000000000..97d1dca2b7f7ea2a786408d064973e27
 +public interface ItemEnchantments extends ShownInTooltip<ItemEnchantments> {
 +
 +    @Contract(value = "_, _ -> new", pure = true)
-+    static @NonNull ItemEnchantments itemEnchantments(final @NonNull Map<Enchantment, Integer> enchantments, final boolean showInTooltip) {
++    static @NonNull ItemEnchantments itemEnchantments(final @NonNull Map<Enchantment, @IntRange(from = 0, to = 255) Integer> enchantments, final boolean showInTooltip) {
 +        return itemEnchantments().addAll(enchantments).showInTooltip(showInTooltip).build();
 +    }
 +
@@ -924,7 +1120,7 @@ index 0000000000000000000000000000000000000000..97d1dca2b7f7ea2a786408d064973e27
 +    }
 +
 +    @Contract(pure = true)
-+    @NonNull @Unmodifiable Map<@NonNull Enchantment, @NonNull Integer> enchantments();
++    @NonNull @Unmodifiable Map<@NonNull Enchantment, @NonNull @IntRange(from = 0, to = 255) Integer> enchantments();
 +
 +    @ApiStatus.NonExtendable
 +    interface Builder extends ShownInTooltip.Builder<Builder>, ComponentBuilder<ItemEnchantments> {
@@ -933,7 +1129,7 @@ index 0000000000000000000000000000000000000000..97d1dca2b7f7ea2a786408d064973e27
 +        @NonNull Builder add(@NonNull Enchantment enchantment, int level);
 +
 +        @Contract(value = "_ -> this", mutates = "this")
-+        @NonNull Builder addAll(@NonNull Map<@NonNull Enchantment, @NonNull Integer> enchantments);
++        @NonNull Builder addAll(@NonNull Map<@NonNull Enchantment, @NonNull @IntRange(from = 0, to = 255) Integer> enchantments);
 +    }
 +}
 diff --git a/src/main/java/io/papermc/paper/component/item/ItemLore.java b/src/main/java/io/papermc/paper/component/item/ItemLore.java