#831: Add a standard of annotations for Minecraft experimental things and API

By: Doc <nachito94@msn.com> Also-by: 2008Choco <hawkeboyz2@hotmail.com>
2024-12-28 11:58:06 +01:00 · 2023-04-07 09:41:58 +10:00 · 2023-04-07 09:41:58 +10:00 · bec81a9aff
commit bec81a9aff
parent 0bf4318605
40 changed files with 559 additions and 36 deletions
--- a/paper-api/README.md
+++ b/paper-api/README.md
@ -83,6 +83,10 @@ Code Requirements
 * Do not attempt to fix multiple problems with a single patch or pull request.
 * Avoid moving or renaming classes.
 * All non-private methods and constructors must have specified nullability through [annotations](https://github.com/JetBrains/java-annotations)
+* All classes/methods/fields related to a [Minecraft Experimental Feature](https://minecraft.fandom.com/wiki/Experimental_Gameplay) must be marked with [`@MinecraftExperimental`](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/MinecraftExperimental.html)
+* If necessary, you may consider the use of one of the following [ApiStatus Annotations](https://javadoc.io/doc/org.jetbrains/annotations-java5/23.0.0/org/jetbrains/annotations/ApiStatus.html):
+  * [`@ApiStatus.Experimental`](https://javadoc.io/doc/org.jetbrains/annotations-java5/23.0.0/org/jetbrains/annotations/ApiStatus.Experimental.html) for API that is subject to change
+  * [`@ApiStatus.Internal`](https://javadoc.io/doc/org.jetbrains/annotations-java5/23.0.0/org/jetbrains/annotations/ApiStatus.Internal.html) for API that is intended only for internal use in the Bukkit project and will not adhere to Bukkit's API contract

 Bukkit/CraftBukkit employs [JUnit 4](https://www.vogella.com/tutorials/JUnit4/article.html) for testing. Pull Requests(PR) should attempt to integrate within that framework as appropriate.
 Bukkit is a large project and what seems simple to a PR author at the time of writing may easily be overlooked by other authors and updates. Including unit tests with your PR
@ -93,4 +97,4 @@ will help to ensure the PR can be easily maintained over time and encourage the
    * Do not group packages
    * __Absolutely no wildcard imports outside of tests.__

-Any questions about these requirements can be asked in #help-development in Discord.
+Any questions about these requirements can be asked in [#help-development](https://www.spigotmc.org/go/discord) in Discord.
--- a/paper-api/checkstyle.xml
+++ b/paper-api/checkstyle.xml
@ -23,6 +23,10 @@
    <!-- See https://checkstyle.sourceforge.io/config_javadoc.html#JavadocPackage-->
    <module name="JavadocPackage"/>

+    <module name="SuppressionSingleFilter">
+        <property name="message" value="'(implNote|implSpec|apiNote)'\."/>
+    </module>
+
    <module name="TreeWalker">
        <!-- See https://checkstyle.org/config_javadoc.html -->
        <module name="AtclauseOrder"/>
--- a/paper-api/pom.xml
+++ b/paper-api/pom.xml
@ -190,6 +190,13 @@
                        <link>https://javadoc.io/doc/org.yaml/snakeyaml/1.33/</link>
                        <link>https://javadoc.io/doc/org.jetbrains/annotations-java5/23.0.0/</link>
                    </links>
+                    <tags>
+                        <tag>
+                            <name>apiNote</name>
+                            <placement>a</placement>
+                            <head>API Note:</head>
+                        </tag>
+                    </tags>
                </configuration>
            </plugin>
        </plugins>
--- a/paper-api/src/main/java/org/bukkit/Instrument.java
+++ b/paper-api/src/main/java/org/bukkit/Instrument.java
@ -2,6 +2,7 @@ package org.bukkit;

 import com.google.common.collect.Maps;
 import java.util.Map;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;

 public enum Instrument {
@ -78,30 +79,44 @@ public enum Instrument {
    /**
     * Zombie is normally played when a Zombie Head is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ZOMBIE,
    /**
     * Skeleton is normally played when a Skeleton Head is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SKELETON,
    /**
     * Creeper is normally played when a Creeper Head is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CREEPER,
    /**
     * Dragon is normally played when a Dragon Head is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    DRAGON,
    /**
     * Wither Skeleton is normally played when a Wither Skeleton Head is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    WITHER_SKELETON,
    /**
     * Piglin is normally played when a Piglin Head is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    PIGLIN,
    /**
     * Custom Sound is normally played when a Player Head with the required data is on top of the note block.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CUSTOM_HEAD;

    private final byte type;
--- a/paper-api/src/main/java/org/bukkit/Material.java
+++ b/paper-api/src/main/java/org/bukkit/Material.java
@ -109,6 +109,7 @@ import org.bukkit.block.data.type.WallSign;
 import org.bukkit.inventory.CreativeCategory;
 import org.bukkit.inventory.EquipmentSlot;
 import org.bukkit.material.MaterialData;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

@ -154,12 +155,18 @@ public enum Material implements Keyed, Translatable {
    BIRCH_PLANKS(29322),
    JUNGLE_PLANKS(26445),
    ACACIA_PLANKS(31312),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_PLANKS(8354),
    DARK_OAK_PLANKS(20869),
    MANGROVE_PLANKS(7078),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_PLANKS(8520),
    CRIMSON_PLANKS(18812),
    WARPED_PLANKS(16045),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_MOSAIC(10715),
    /**
     * BlockData: {@link Sapling}
@ -184,6 +191,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Sapling}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_SAPLING(25204, Sapling.class),
    /**
     * BlockData: {@link Sapling}
@ -198,6 +207,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link SuspiciousSand}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SUSPICIOUS_SAND(18410, SuspiciousSand.class),
    RED_SAND(16279),
    GRAVEL(7804),
@ -339,6 +350,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Orientable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_LOG(20847, Orientable.class),
    /**
     * BlockData: {@link Orientable}
@ -367,6 +380,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Orientable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_BLOCK(20770, Orientable.class),
    /**
     * BlockData: {@link Orientable}
@ -391,6 +406,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Orientable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    STRIPPED_CHERRY_LOG(18061, Orientable.class),
    /**
     * BlockData: {@link Orientable}
@ -431,6 +448,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Orientable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    STRIPPED_CHERRY_WOOD(19647, Orientable.class),
    /**
     * BlockData: {@link Orientable}
@ -475,6 +494,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Orientable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_WOOD(9826, Orientable.class),
    /**
     * BlockData: {@link Orientable}
@ -515,6 +536,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Leaves}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_LEAVES(20856, Leaves.class),
    /**
     * BlockData: {@link Leaves}
@ -580,6 +603,8 @@ public enum Material implements Keyed, Translatable {
    CORNFLOWER(15405),
    LILY_OF_THE_VALLEY(7185),
    WITHER_ROSE(8619),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    TORCHFLOWER(4501),
    SPORE_BLOSSOM(20627),
    BROWN_MUSHROOM(9665),
@ -609,6 +634,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link PinkPetals}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    PINK_PETALS(10420, PinkPetals.class),
    MOSS_BLOCK(9175),
    /**
@ -650,6 +677,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Slab}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_SLAB(16673, Slab.class),
    /**
     * BlockData: {@link Slab}
@ -662,10 +691,14 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Slab}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_SLAB(17798, Slab.class),
    /**
     * BlockData: {@link Slab}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_MOSAIC_SLAB(22118, Slab.class),
    /**
     * BlockData: {@link Slab}
@ -752,10 +785,14 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link ChiseledBookshelf}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHISELED_BOOKSHELF(8099, ChiseledBookshelf.class),
    /**
     * BlockData: {@link DecoratedPot}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    DECORATED_POT(8720, 1, DecoratedPot.class),
    MOSSY_COBBLESTONE(21900),
    OBSIDIAN(32723),
@ -841,6 +878,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Fence}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_FENCE(32047, Fence.class),
    /**
     * BlockData: {@link Fence}
@ -1021,6 +1060,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Stairs}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_STAIRS(18380, Stairs.class),
    /**
     * BlockData: {@link Stairs}
@ -1033,10 +1074,14 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Stairs}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_STAIRS(25674, Stairs.class),
    /**
     * BlockData: {@link Stairs}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_MOSAIC_STAIRS(20977, Stairs.class),
    /**
     * BlockData: {@link Stairs}
@ -1872,6 +1917,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Switch}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_BUTTON(9058, Switch.class),
    /**
     * BlockData: {@link Switch}
@ -1932,6 +1979,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Powerable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_PRESSURE_PLATE(8651, Powerable.class),
    /**
     * BlockData: {@link Powerable}
@ -1980,6 +2029,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Door}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_DOOR(12684, Door.class),
    /**
     * BlockData: {@link Door}
@ -2028,6 +2079,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link TrapDoor}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_TRAPDOOR(6293, TrapDoor.class),
    /**
     * BlockData: {@link TrapDoor}
@ -2072,6 +2125,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Gate}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_FENCE_GATE(28222, Gate.class),
    /**
     * BlockData: {@link Gate}
@ -2128,7 +2183,11 @@ public enum Material implements Keyed, Translatable {
    JUNGLE_CHEST_BOAT(20133, 1),
    ACACIA_BOAT(27326, 1),
    ACACIA_CHEST_BOAT(28455, 1),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_BOAT(13628, 1),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_CHEST_BOAT(7165, 1),
    DARK_OAK_BOAT(28618, 1),
    DARK_OAK_CHEST_BOAT(8733, 1),
@ -2260,6 +2319,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Sign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_SIGN(16520, 16, Sign.class),
    /**
     * BlockData: {@link Sign}
@ -2284,46 +2345,68 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    OAK_HANGING_SIGN(20116, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SPRUCE_HANGING_SIGN(24371, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BIRCH_HANGING_SIGN(17938, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    JUNGLE_HANGING_SIGN(27671, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ACACIA_HANGING_SIGN(30257, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_HANGING_SIGN(5088, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    DARK_OAK_HANGING_SIGN(23360, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    MANGROVE_HANGING_SIGN(25106, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_HANGING_SIGN(4726, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CRIMSON_HANGING_SIGN(20696, 16, HangingSign.class),
    /**
     * BlockData: {@link HangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    WARPED_HANGING_SIGN(8195, 16, HangingSign.class),
    BUCKET(15215, 16),
    WATER_BUCKET(8802, 1),
@ -2347,6 +2430,8 @@ public enum Material implements Keyed, Translatable {
    EGG(21603, 16),
    COMPASS(24139),
    RECOVERY_COMPASS(12710),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BUNDLE(16835, 1),
    FISHING_ROD(4167, 1, 64),
    CLOCK(14980),
@ -2487,6 +2572,8 @@ public enum Material implements Keyed, Translatable {
    BEE_SPAWN_EGG(22924),
    BLAZE_SPAWN_EGG(4759),
    CAT_SPAWN_EGG(29583),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CAMEL_SPAWN_EGG(14760),
    CAVE_SPIDER_SPAWN_EGG(23341),
    CHICKEN_SPAWN_EGG(5462),
@ -2534,6 +2621,8 @@ public enum Material implements Keyed, Translatable {
    SKELETON_SPAWN_EGG(15261),
    SKELETON_HORSE_SPAWN_EGG(21356),
    SLIME_SPAWN_EGG(17196),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SNIFFER_SPAWN_EGG(27473),
    SNOW_GOLEM_SPAWN_EGG(24732),
    SPIDER_SPAWN_EGG(14984),
@ -2598,6 +2687,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Rotatable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    PIGLIN_HEAD(5512, Rotatable.class),
    NETHER_STAR(12469),
    PUMPKIN_PIE(28725),
@ -2689,6 +2780,8 @@ public enum Material implements Keyed, Translatable {
    END_CRYSTAL(19090),
    CHORUS_FRUIT(7652),
    POPPED_CHORUS_FRUIT(27844),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    TORCHFLOWER_SEEDS(18153),
    BEETROOT(23305),
    BEETROOT_SEEDS(21282),
@ -2936,22 +3029,56 @@ public enum Material implements Keyed, Translatable {
    PEARLESCENT_FROGLIGHT(21441, Orientable.class),
    FROGSPAWN(8350),
    ECHO_SHARD(12529),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BRUSH(30569, 1, 64),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    NETHERITE_UPGRADE_SMITHING_TEMPLATE(7615),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SENTRY_ARMOR_TRIM_SMITHING_TEMPLATE(16124),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    DUNE_ARMOR_TRIM_SMITHING_TEMPLATE(30925),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    COAST_ARMOR_TRIM_SMITHING_TEMPLATE(25501),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    WILD_ARMOR_TRIM_SMITHING_TEMPLATE(5870),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    WARD_ARMOR_TRIM_SMITHING_TEMPLATE(24534),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    EYE_ARMOR_TRIM_SMITHING_TEMPLATE(14663),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    VEX_ARMOR_TRIM_SMITHING_TEMPLATE(25818),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    TIDE_ARMOR_TRIM_SMITHING_TEMPLATE(20420),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SNOUT_ARMOR_TRIM_SMITHING_TEMPLATE(14386),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    RIB_ARMOR_TRIM_SMITHING_TEMPLATE(6010),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SPIRE_ARMOR_TRIM_SMITHING_TEMPLATE(29143),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    POTTERY_SHARD_ARCHER(26154),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    POTTERY_SHARD_PRIZE(31677),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    POTTERY_SHARD_ARMS_UP(29222),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    POTTERY_SHARD_SKULL(14619),
    /**
     * BlockData: {@link Levelled}
@ -3005,6 +3132,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link WallSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_WALL_SIGN(20188, 16, WallSign.class),
    /**
     * BlockData: {@link WallSign}
@ -3025,46 +3154,68 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    OAK_WALL_HANGING_SIGN(15637, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SPRUCE_WALL_HANGING_SIGN(18833, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BIRCH_WALL_HANGING_SIGN(15937, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ACACIA_WALL_HANGING_SIGN(22477, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_WALL_HANGING_SIGN(10953, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    JUNGLE_WALL_HANGING_SIGN(16691, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    DARK_OAK_WALL_HANGING_SIGN(14296, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    MANGROVE_WALL_HANGING_SIGN(16974, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CRIMSON_WALL_HANGING_SIGN(28982, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    WARPED_WALL_HANGING_SIGN(20605, WallHangingSign.class),
    /**
     * BlockData: {@link WallHangingSign}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BAMBOO_WALL_HANGING_SIGN(6669, WallHangingSign.class),
    /**
     * BlockData: {@link RedstoneWallTorch}
@ -3112,12 +3263,16 @@ public enum Material implements Keyed, Translatable {
     * BlockData: {@link Tripwire}
     */
    TRIPWIRE(8810, Tripwire.class),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    POTTED_TORCHFLOWER(21278),
    POTTED_OAK_SAPLING(11905),
    POTTED_SPRUCE_SAPLING(29498),
    POTTED_BIRCH_SAPLING(32484),
    POTTED_JUNGLE_SAPLING(7525),
    POTTED_ACACIA_SAPLING(14096),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    POTTED_CHERRY_SAPLING(30785),
    POTTED_DARK_OAK_SAPLING(6486),
    POTTED_MANGROVE_PROPAGULE(22003),
@ -3174,6 +3329,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Directional}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    PIGLIN_WALL_HEAD(4446, Directional.class),
    /**
     * BlockData: {@link Directional}
@ -3242,6 +3399,8 @@ public enum Material implements Keyed, Translatable {
    /**
     * BlockData: {@link Ageable}
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    TORCHFLOWER_CROP(28460, Ageable.class),
    /**
     * BlockData: {@link Ageable}
--- a/paper-api/src/main/java/org/bukkit/MinecraftExperimental.java
+++ b/paper-api/src/main/java/org/bukkit/MinecraftExperimental.java
@ -0,0 +1,27 @@
+package org.bukkit;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import org.jetbrains.annotations.ApiStatus;
+
+/**
+ * Indicates that the annotated element (class, method, field, etc.) is part of a
+ * <a href="https://minecraft.fandom.com/wiki/Experimental_Gameplay">minecraft experimental feature</a>
+ * and is subject to changes by Mojang.
+ * <p>
+ * <b>Note:</b> Elements marked with this annotation require the use of a datapack or otherwise
+ * non-standard feature to be enabled on the server.
+ *
+ * @see <a href="https://www.minecraft.net/en-us/article/testing-new-minecraft-features/feature-toggles-java-edition">Features Toggles - Minecraft Article</a>
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({
+        ElementType.TYPE, ElementType.ANNOTATION_TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.FIELD, ElementType.PACKAGE
+})
+@ApiStatus.Internal
+public @interface MinecraftExperimental {
+}
--- a/paper-api/src/main/java/org/bukkit/Particle.java
+++ b/paper-api/src/main/java/org/bukkit/Particle.java
@ -4,6 +4,7 @@ import com.google.common.base.Preconditions;
 import org.bukkit.block.data.BlockData;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.material.MaterialData;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 public enum Particle {
@ -123,8 +124,14 @@ public enum Particle {
    SCULK_CHARGE(Float.class),
    SCULK_CHARGE_POP,
    SHRIEK(Integer.class),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    DRIPPING_CHERRY_LEAVES,
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    FALLING_CHERRY_LEAVES,
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    LANDING_CHERRY_LEAVES,
    /**
     * Uses {@link BlockData} as DataType
--- a/paper-api/src/main/java/org/bukkit/Sound.java
+++ b/paper-api/src/main/java/org/bukkit/Sound.java
@ -1,5 +1,6 @@
 package org.bukkit;

+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
@ -84,10 +85,20 @@ public enum Sound implements Keyed {
    BLOCK_BAMBOO_WOOD_FALL("block.bamboo_wood.fall"),
    BLOCK_BAMBOO_WOOD_FENCE_GATE_CLOSE("block.bamboo_wood_fence_gate.close"),
    BLOCK_BAMBOO_WOOD_FENCE_GATE_OPEN("block.bamboo_wood_fence_gate.open"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_BAMBOO_WOOD_HANGING_SIGN_BREAK("block.bamboo_wood_hanging_sign.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_BAMBOO_WOOD_HANGING_SIGN_FALL("block.bamboo_wood_hanging_sign.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_BAMBOO_WOOD_HANGING_SIGN_HIT("block.bamboo_wood_hanging_sign.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_BAMBOO_WOOD_HANGING_SIGN_PLACE("block.bamboo_wood_hanging_sign.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_BAMBOO_WOOD_HANGING_SIGN_STEP("block.bamboo_wood_hanging_sign.step"),
    BLOCK_BAMBOO_WOOD_HIT("block.bamboo_wood.hit"),
    BLOCK_BAMBOO_WOOD_PLACE("block.bamboo_wood.place"),
@ -158,47 +169,125 @@ public enum Sound implements Keyed {
    BLOCK_CHAIN_HIT("block.chain.hit"),
    BLOCK_CHAIN_PLACE("block.chain.place"),
    BLOCK_CHAIN_STEP("block.chain.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_LEAVES_BREAK("block.cherry_leaves.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_LEAVES_FALL("block.cherry_leaves.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_LEAVES_HIT("block.cherry_leaves.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_LEAVES_PLACE("block.cherry_leaves.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_LEAVES_STEP("block.cherry_leaves.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_SAPLING_BREAK("block.cherry_sapling.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_SAPLING_FALL("block.cherry_sapling.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_SAPLING_HIT("block.cherry_sapling.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_SAPLING_PLACE("block.cherry_sapling.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_SAPLING_STEP("block.cherry_sapling.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_BREAK("block.cherry_wood.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_BUTTON_CLICK_OFF("block.cherry_wood_button.click_off"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_BUTTON_CLICK_ON("block.cherry_wood_button.click_on"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_DOOR_CLOSE("block.cherry_wood_door.close"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_DOOR_OPEN("block.cherry_wood_door.open"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_FALL("block.cherry_wood.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_FENCE_GATE_CLOSE("block.cherry_wood_fence_gate.close"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_FENCE_GATE_OPEN("block.cherry_wood_fence_gate.open"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_HANGING_SIGN_BREAK("block.cherry_wood_hanging_sign.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_HANGING_SIGN_FALL("block.cherry_wood_hanging_sign.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_HANGING_SIGN_HIT("block.cherry_wood_hanging_sign.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_HANGING_SIGN_PLACE("block.cherry_wood_hanging_sign.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_HANGING_SIGN_STEP("block.cherry_wood_hanging_sign.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_HIT("block.cherry_wood.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_PLACE("block.cherry_wood.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_PRESSURE_PLATE_CLICK_OFF("block.cherry_wood_pressure_plate.click_off"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_PRESSURE_PLATE_CLICK_ON("block.cherry_wood_pressure_plate.click_on"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_STEP("block.cherry_wood.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_TRAPDOOR_CLOSE("block.cherry_wood_trapdoor.close"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHERRY_WOOD_TRAPDOOR_OPEN("block.cherry_wood_trapdoor.open"),
    BLOCK_CHEST_CLOSE("block.chest.close"),
    BLOCK_CHEST_LOCKED("block.chest.locked"),
    BLOCK_CHEST_OPEN("block.chest.open"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_BREAK("block.chiseled_bookshelf.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_FALL("block.chiseled_bookshelf.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_HIT("block.chiseled_bookshelf.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_INSERT("block.chiseled_bookshelf.insert"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_INSERT_ENCHANTED("block.chiseled_bookshelf.insert.enchanted"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_PICKUP("block.chiseled_bookshelf.pickup"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_PICKUP_ENCHANTED("block.chiseled_bookshelf.pickup.enchanted"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_PLACE("block.chiseled_bookshelf.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_CHISELED_BOOKSHELF_STEP("block.chiseled_bookshelf.step"),
    BLOCK_CHORUS_FLOWER_DEATH("block.chorus_flower.death"),
    BLOCK_CHORUS_FLOWER_GROW("block.chorus_flower.grow"),
@ -223,11 +312,23 @@ public enum Sound implements Keyed {
    BLOCK_CORAL_BLOCK_PLACE("block.coral_block.place"),
    BLOCK_CORAL_BLOCK_STEP("block.coral_block.step"),
    BLOCK_CROP_BREAK("block.crop.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_DECORATED_POT_BREAK("block.decorated_pot.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_DECORATED_POT_FALL("block.decorated_pot.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_DECORATED_POT_HIT("block.decorated_pot.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_DECORATED_POT_PLACE("block.decorated_pot.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_DECORATED_POT_SHATTER("block.decorated_pot.shatter"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_DECORATED_POT_STEP("block.decorated_pot.step"),
    BLOCK_DEEPSLATE_BREAK("block.deepslate.break"),
    BLOCK_DEEPSLATE_BRICKS_BREAK("block.deepslate_bricks.break"),
@ -470,10 +571,20 @@ public enum Sound implements Keyed {
    BLOCK_PACKED_MUD_HIT("block.packed_mud.hit"),
    BLOCK_PACKED_MUD_PLACE("block.packed_mud.place"),
    BLOCK_PACKED_MUD_STEP("block.packed_mud.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_PINK_PETALS_BREAK("block.pink_petals.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_PINK_PETALS_FALL("block.pink_petals.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_PINK_PETALS_HIT("block.pink_petals.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_PINK_PETALS_PLACE("block.pink_petals.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_PINK_PETALS_STEP("block.pink_petals.step"),
    BLOCK_PISTON_CONTRACT("block.piston.contract"),
    BLOCK_PISTON_EXTEND("block.piston.extend"),
@ -612,10 +723,20 @@ public enum Sound implements Keyed {
    BLOCK_STONE_PRESSURE_PLATE_CLICK_OFF("block.stone_pressure_plate.click_off"),
    BLOCK_STONE_PRESSURE_PLATE_CLICK_ON("block.stone_pressure_plate.click_on"),
    BLOCK_STONE_STEP("block.stone.step"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_SUSPICIOUS_SAND_BREAK("block.suspicious_sand.break"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_SUSPICIOUS_SAND_FALL("block.suspicious_sand.fall"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_SUSPICIOUS_SAND_HIT("block.suspicious_sand.hit"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_SUSPICIOUS_SAND_PLACE("block.suspicious_sand.place"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    BLOCK_SUSPICIOUS_SAND_STEP("block.suspicious_sand.step"),
    BLOCK_SWEET_BERRY_BUSH_BREAK("block.sweet_berry_bush.break"),
    BLOCK_SWEET_BERRY_BUSH_PICK_BERRIES("block.sweet_berry_bush.pick_berries"),
@ -708,16 +829,27 @@ public enum Sound implements Keyed {
    ENTITY_BLAZE_SHOOT("entity.blaze.shoot"),
    ENTITY_BOAT_PADDLE_LAND("entity.boat.paddle_land"),
    ENTITY_BOAT_PADDLE_WATER("entity.boat.paddle_water"),
+    @MinecraftExperimental
    ENTITY_CAMEL_AMBIENT("entity.camel.ambient"),
+    @MinecraftExperimental
    ENTITY_CAMEL_DASH("entity.camel.dash"),
+    @MinecraftExperimental
    ENTITY_CAMEL_DASH_READY("entity.camel.dash_ready"),
+    @MinecraftExperimental
    ENTITY_CAMEL_DEATH("entity.camel.death"),
+    @MinecraftExperimental
    ENTITY_CAMEL_EAT("entity.camel.eat"),
+    @MinecraftExperimental
    ENTITY_CAMEL_HURT("entity.camel.hurt"),
+    @MinecraftExperimental
    ENTITY_CAMEL_SADDLE("entity.camel.saddle"),
+    @MinecraftExperimental
    ENTITY_CAMEL_SIT("entity.camel.sit"),
+    @MinecraftExperimental
    ENTITY_CAMEL_STAND("entity.camel.stand"),
+    @MinecraftExperimental
    ENTITY_CAMEL_STEP("entity.camel.step"),
+    @MinecraftExperimental
    ENTITY_CAMEL_STEP_SAND("entity.camel.step_sand"),
    ENTITY_CAT_AMBIENT("entity.cat.ambient"),
    ENTITY_CAT_BEG_FOR_FOOD("entity.cat.beg_for_food"),
@ -1159,17 +1291,41 @@ public enum Sound implements Keyed {
    ENTITY_SLIME_JUMP_SMALL("entity.slime.jump_small"),
    ENTITY_SLIME_SQUISH("entity.slime.squish"),
    ENTITY_SLIME_SQUISH_SMALL("entity.slime.squish_small"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_DEATH("entity.sniffer.death"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_DIGGING("entity.sniffer.digging"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_DIGGING_STOP("entity.sniffer.digging_stop"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_DROP_SEED("entity.sniffer.drop_seed"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_EAT("entity.sniffer.eat"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_HAPPY("entity.sniffer.happy"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_HURT("entity.sniffer.hurt"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_IDLE("entity.sniffer.idle"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_SCENTING("entity.sniffer.scenting"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_SEARCHING("entity.sniffer.searching"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_SNIFFING("entity.sniffer.sniffing"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ENTITY_SNIFFER_STEP("entity.sniffer.step"),
    ENTITY_SNOWBALL_THROW("entity.snowball.throw"),
    ENTITY_SNOW_GOLEM_AMBIENT("entity.snow_golem.ambient"),
@ -1353,7 +1509,11 @@ public enum Sound implements Keyed {
    ITEM_BOTTLE_EMPTY("item.bottle.empty"),
    ITEM_BOTTLE_FILL("item.bottle.fill"),
    ITEM_BOTTLE_FILL_DRAGONBREATH("item.bottle.fill_dragonbreath"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ITEM_BRUSH_BRUSHING("item.brush.brushing"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    ITEM_BRUSH_BRUSH_SAND_COMPLETED("item.brush.brush_sand_completed"),
    ITEM_BUCKET_EMPTY("item.bucket.empty"),
    ITEM_BUCKET_EMPTY_AXOLOTL("item.bucket.empty_axolotl"),
@ -1440,6 +1600,8 @@ public enum Sound implements Keyed {
    MUSIC_NETHER_NETHER_WASTES("music.nether.nether_wastes"),
    MUSIC_NETHER_SOUL_SAND_VALLEY("music.nether.soul_sand_valley"),
    MUSIC_NETHER_WARPED_FOREST("music.nether.warped_forest"),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    MUSIC_OVERWORLD_CHERRY_GROVE("music.overworld.cherry_grove"),
    MUSIC_OVERWORLD_DEEP_DARK("music.overworld.deep_dark"),
    MUSIC_OVERWORLD_DRIPSTONE_CAVES("music.overworld.dripstone_caves"),
--- a/paper-api/src/main/java/org/bukkit/Tag.java
+++ b/paper-api/src/main/java/org/bukkit/Tag.java
@ -2,6 +2,7 @@ package org.bukkit;

 import java.util.Set;
 import org.bukkit.entity.EntityType;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
@ -118,6 +119,8 @@ public interface Tag<T extends Keyed> extends Keyed {
    /**
     * Vanilla block tag representing all cherry log and bark variants.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> CHERRY_LOGS = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("cherry_logs"), Material.class);
    /**
     * Vanilla block tag representing all jungle log and bark variants.
@ -316,14 +319,20 @@ public interface Tag<T extends Keyed> extends Keyed {
    /**
     * Vanilla block tag representing all ceiling signs.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> CEILING_HANGING_SIGNS = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("ceiling_hanging_signs"), Material.class);
    /**
     * Vanilla block tag representing all wall hanging signs.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> WALL_HANGING_SIGNS = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("wall_hanging_signs"), Material.class);
    /**
     * Vanilla block tag representing all hanging signs.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ALL_HANGING_SIGNS = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("all_hanging_signs"), Material.class);
    /**
     * Vanilla block tag representing all signs, regardless of type.
@ -687,6 +696,8 @@ public interface Tag<T extends Keyed> extends Keyed {
    /**
     * Vanilla block tag representing blocks which can be dug by sniffers.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> SNIFFER_DIGGABLE_BLOCK = Bukkit.getTag(REGISTRY_BLOCKS, NamespacedKey.minecraft("sniffer_diggable_block"), Material.class);
    /**
     * Key for the built in item registry.
@ -776,26 +787,38 @@ public interface Tag<T extends Keyed> extends Keyed {
    /**
     * Vanilla item tag representing all items which modify note block sounds when placed on top.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_NOTE_BLOCK_TOP_INSTRUMENTS = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("noteblock_top_instruments"), Material.class);
    /**
     * Vanilla item tag representing all trimmable armor items.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_TRIMMABLE_ARMOR = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("trimmable_armor"), Material.class);
    /**
     * Vanilla item tag representing all materials which can be used for trimming armor.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_TRIM_MATERIALS = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("trim_materials"), Material.class);
    /**
     * Vanilla item tag representing all trimming templates.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_TRIM_TEMPLATES = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("trim_templates"), Material.class);
    /**
     * Vanilla item tag representing all food for sniffers.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_SNIFFER_FOOD = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("sniffer_food"), Material.class);
    /**
     * Vanilla item tag representing all decorated pot shards.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_DECORATED_POT_SHARDS = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("decorated_pot_shards"), Material.class);
    /**
     * Vanilla item tag representing all swords.
@ -824,6 +847,8 @@ public interface Tag<T extends Keyed> extends Keyed {
    /**
     * Vanilla item tag representing all item which break decorated pots.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    Tag<Material> ITEMS_BREAKS_DECORATED_POTS = Bukkit.getTag(REGISTRY_ITEMS, NamespacedKey.minecraft("breaks_decorated_pots"), Material.class);
    /**
     * Vanilla item tag representing all items that confer freeze immunity on
--- a/paper-api/src/main/java/org/bukkit/TreeType.java
+++ b/paper-api/src/main/java/org/bukkit/TreeType.java
@ -1,5 +1,7 @@
 package org.bukkit;

+import org.jetbrains.annotations.ApiStatus;
+
 /**
 * Tree and organic structure types.
 */
@ -96,5 +98,7 @@ public enum TreeType {
    /**
     * Cherry tree
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY,
 }
--- a/paper-api/src/main/java/org/bukkit/UndefinedNullability.java
+++ b/paper-api/src/main/java/org/bukkit/UndefinedNullability.java
@ -2,6 +2,7 @@ package org.bukkit;

 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import org.jetbrains.annotations.ApiStatus;

 /**
 * Annotation for types, whose nullability is not well defined, so
@ -13,6 +14,7 @@ import java.lang.annotation.RetentionPolicy;
 * suggests a bad API design.
 */
@Retention(RetentionPolicy.CLASS)
+@ApiStatus.Internal
@Deprecated
 public @interface UndefinedNullability {

--- a/paper-api/src/main/java/org/bukkit/block/Biome.java
+++ b/paper-api/src/main/java/org/bukkit/block/Biome.java
@ -2,7 +2,9 @@ package org.bukkit.block;

 import java.util.Locale;
 import org.bukkit.Keyed;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.NamespacedKey;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
@ -72,6 +74,8 @@ public enum Biome implements Keyed {
    FROZEN_PEAKS,
    JAGGED_PEAKS,
    STONY_PEAKS,
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CHERRY_GROVE,
    /**
     * Represents a custom Biome
--- a/paper-api/src/main/java/org/bukkit/block/ChiseledBookshelf.java
+++ b/paper-api/src/main/java/org/bukkit/block/ChiseledBookshelf.java
@ -1,12 +1,16 @@
 package org.bukkit.block;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.inventory.BlockInventoryHolder;
 import org.bukkit.inventory.ChiseledBookshelfInventory;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
 * Represents a captured state of a chiseled bookshelf.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface ChiseledBookshelf extends TileState, BlockInventoryHolder {

    /**
--- a/paper-api/src/main/java/org/bukkit/block/DecoratedPot.java
+++ b/paper-api/src/main/java/org/bukkit/block/DecoratedPot.java
@ -2,12 +2,16 @@ package org.bukkit.block;

 import java.util.List;
 import org.bukkit.Material;
+import org.bukkit.MinecraftExperimental;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

 /**
 * Represents a captured state of a decorated pot.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface DecoratedPot extends TileState {

    /**
--- a/paper-api/src/main/java/org/bukkit/block/HangingSign.java
+++ b/paper-api/src/main/java/org/bukkit/block/HangingSign.java
@ -1,7 +1,12 @@
 package org.bukkit.block;

+import org.bukkit.MinecraftExperimental;
+import org.jetbrains.annotations.ApiStatus;
+
 /**
 * Represents a captured state of a hanging sign.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface HangingSign extends Sign {
 }
--- a/paper-api/src/main/java/org/bukkit/block/Skull.java
+++ b/paper-api/src/main/java/org/bukkit/block/Skull.java
@ -1,11 +1,13 @@
 package org.bukkit.block;

 import org.bukkit.Material;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.NamespacedKey;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.SkullType;
 import org.bukkit.block.data.BlockData;
 import org.bukkit.profile.PlayerProfile;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@ -94,6 +96,8 @@ public interface Skull extends TileState {
     *
     * @return the key of the sound, or null
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    @Nullable
    public NamespacedKey getNoteBlockSound();

@ -104,7 +108,10 @@ public interface Skull extends TileState {
     * see {@link org.bukkit.Instrument}.
     *
     * @param noteBlockSound the key of the sound to be played, or null
+     *
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    public void setNoteBlockSound(@Nullable NamespacedKey noteBlockSound);

    /**
--- a/paper-api/src/main/java/org/bukkit/block/SuspiciousSand.java
+++ b/paper-api/src/main/java/org/bukkit/block/SuspiciousSand.java
@ -1,12 +1,16 @@
 package org.bukkit.block;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.loot.Lootable;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;

 /**
 * Represents a captured state of suspicious sand.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface SuspiciousSand extends Lootable, TileState {

    /**
--- a/paper-api/src/main/java/org/bukkit/block/data/type/ChiseledBookshelf.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/ChiseledBookshelf.java
@ -1,7 +1,9 @@
 package org.bukkit.block.data.type;

 import java.util.Set;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.data.Directional;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
@ -11,6 +13,8 @@ import org.jetbrains.annotations.NotNull;
 * <br>
 * Block may have 0, 1... {@link #getMaximumOccupiedSlots()}-1 occupied slots.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface ChiseledBookshelf extends Directional {

    /**
--- a/paper-api/src/main/java/org/bukkit/block/data/type/DecoratedPot.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/DecoratedPot.java
@ -1,7 +1,11 @@
 package org.bukkit.block.data.type;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.data.Directional;
 import org.bukkit.block.data.Waterlogged;
+import org.jetbrains.annotations.ApiStatus;

+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface DecoratedPot extends Directional, Waterlogged {
 }
--- a/paper-api/src/main/java/org/bukkit/block/data/type/HangingSign.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/HangingSign.java
@ -1,8 +1,12 @@
 package org.bukkit.block.data.type;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.data.Attachable;
 import org.bukkit.block.data.Rotatable;
 import org.bukkit.block.data.Waterlogged;
+import org.jetbrains.annotations.ApiStatus;

+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface HangingSign extends Attachable, Rotatable, Waterlogged {
 }
--- a/paper-api/src/main/java/org/bukkit/block/data/type/PinkPetals.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/PinkPetals.java
@ -1,10 +1,14 @@
 package org.bukkit.block.data.type;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.data.Directional;
+import org.jetbrains.annotations.ApiStatus;

 /**
 * 'flower_amount' represents the number of petals.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface PinkPetals extends Directional {

    /**
--- a/paper-api/src/main/java/org/bukkit/block/data/type/SuspiciousSand.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/SuspiciousSand.java
@ -1,10 +1,14 @@
 package org.bukkit.block.data.type;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.data.BlockData;
+import org.jetbrains.annotations.ApiStatus;

 /**
 * 'dusted' represents how far uncovered by brush the block is.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface SuspiciousSand extends BlockData {

    /**
--- a/paper-api/src/main/java/org/bukkit/block/data/type/WallHangingSign.java
+++ b/paper-api/src/main/java/org/bukkit/block/data/type/WallHangingSign.java
@ -1,7 +1,11 @@
 package org.bukkit.block.data.type;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.data.Directional;
 import org.bukkit.block.data.Waterlogged;
+import org.jetbrains.annotations.ApiStatus;

+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface WallHangingSign extends Directional, Waterlogged {
 }
--- a/paper-api/src/main/java/org/bukkit/entity/Boat.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Boat.java
@ -1,7 +1,9 @@
 package org.bukkit.entity;

 import org.bukkit.Material;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.TreeSpecies;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
@ -141,9 +143,13 @@ public interface Boat extends Vehicle {
        BIRCH(Material.BIRCH_PLANKS),
        JUNGLE(Material.JUNGLE_PLANKS),
        ACACIA(Material.ACACIA_PLANKS),
+        @MinecraftExperimental
+        @ApiStatus.Experimental
        CHERRY(Material.CHERRY_PLANKS),
        DARK_OAK(Material.DARK_OAK_PLANKS),
        MANGROVE(Material.MANGROVE_PLANKS),
+        @MinecraftExperimental
+        @ApiStatus.Experimental
        BAMBOO(Material.BAMBOO_PLANKS),
        ;

--- a/paper-api/src/main/java/org/bukkit/entity/Camel.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Camel.java
@ -1,8 +1,16 @@
 package org.bukkit.entity;

+import org.bukkit.MinecraftExperimental;
+import org.jetbrains.annotations.ApiStatus;
+
 /**
 * Represents a Camel.
+ *
+ * @apiNote This entity is part of an experimental feature of Minecraft and
+ * hence subject to change.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface Camel extends AbstractHorse, Sittable {

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/Entity.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Entity.java
@ -19,6 +19,7 @@ import org.bukkit.metadata.Metadatable;
 import org.bukkit.persistence.PersistentDataHolder;
 import org.bukkit.util.BoundingBox;
 import org.bukkit.util.Vector;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@ -528,9 +529,9 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     * will need to be called before the entity is visible to a given player.
     *
     * @param visible default visibility status
-     * @deprecated draft API
+     * @apiNote draft API
     */
-    @Deprecated
+    @ApiStatus.Experimental
    public void setVisibleByDefault(boolean visible);

    /**
@ -541,9 +542,9 @@ public interface Entity extends Metadatable, CommandSender, Nameable, Persistent
     * will need to be called before the entity is visible to a given player.
     *
     * @return default visibility status
-     * @deprecated draft API
+     * @apiNote draft API
     */
-    @Deprecated
+    @ApiStatus.Experimental
    public boolean isVisibleByDefault();

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/EntityType.java
+++ b/paper-api/src/main/java/org/bukkit/entity/EntityType.java
@ -6,6 +6,7 @@ import java.util.Map;
 import org.bukkit.Bukkit;
 import org.bukkit.Keyed;
 import org.bukkit.Location;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.NamespacedKey;
 import org.bukkit.Translatable;
 import org.bukkit.World;
@ -18,6 +19,7 @@ import org.bukkit.entity.minecart.SpawnerMinecart;
 import org.bukkit.entity.minecart.StorageMinecart;
 import org.bukkit.inventory.ItemStack;
 import org.bukkit.potion.PotionEffectType;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Contract;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@ -278,10 +280,14 @@ public enum EntityType implements Keyed, Translatable {
    FROG("frog", Frog.class, -1),
    TADPOLE("tadpole", Tadpole.class, -1),
    WARDEN("warden", Warden.class, -1),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    CAMEL("camel", Camel.class, -1),
    BLOCK_DISPLAY("block_display", BlockDisplay.class, -1),
    INTERACTION("interaction", Interaction.class, -1),
    ITEM_DISPLAY("item_display", ItemDisplay.class, -1),
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    SNIFFER("sniffer", Sniffer.class, -1),
    TEXT_DISPLAY("text_display", TextDisplay.class, -1),
    /**
--- a/paper-api/src/main/java/org/bukkit/entity/Player.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Player.java
@ -33,6 +33,7 @@ import org.bukkit.map.MapView;
 import org.bukkit.plugin.Plugin;
 import org.bukkit.plugin.messaging.PluginMessageRecipient;
 import org.bukkit.scoreboard.Scoreboard;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

@ -959,9 +960,9 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     *
     * @param plugin Plugin that wants to hide the entity
     * @param entity Entity to hide
-     * @deprecated draft API
+     * @apiNote draft API
     */
-    @Deprecated
+    @ApiStatus.Experimental
    public void hideEntity(@NotNull Plugin plugin, @NotNull Entity entity);

    /**
@ -971,9 +972,9 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     *
     * @param plugin Plugin that wants to show the entity
     * @param entity Entity to show
-     * @deprecated draft API
+     * @apiNote draft API
     */
-    @Deprecated
+    @ApiStatus.Experimental
    public void showEntity(@NotNull Plugin plugin, @NotNull Entity entity);

    /**
@ -982,9 +983,9 @@ public interface Player extends HumanEntity, Conversable, OfflinePlayer, PluginM
     * @param entity Entity to check
     * @return True if the provided entity is not being hidden from this
     *     player
-     * @deprecated draft API
+     * @apiNote draft API
     */
-    @Deprecated
+    @ApiStatus.Experimental
    public boolean canSee(@NotNull Entity entity);

    /**
--- a/paper-api/src/main/java/org/bukkit/entity/Sniffer.java
+++ b/paper-api/src/main/java/org/bukkit/entity/Sniffer.java
@ -2,6 +2,7 @@ package org.bukkit.entity;

 import java.util.Collection;
 import org.bukkit.Location;
+import org.bukkit.MinecraftExperimental;
 import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@ -9,15 +10,16 @@ import org.jetbrains.annotations.Nullable;
 /**
 * Represents a Sniffer.
 *
- * <b>Note: This entity is part of an experimental feature of Minecraft and
- * hence subject to change.</b>
+ * @apiNote This entity is part of an experimental feature of Minecraft and
+ * hence subject to change.
 */
+@MinecraftExperimental
@ApiStatus.Experimental
 public interface Sniffer extends Animals {

    /**
     * Gets the locations explored by the sniffer.
-     *
+     * <br>
     * <b>Note:</b> the returned locations use sniffer's current world.
     *
     * @return a collection of locations
@ -27,11 +29,10 @@ public interface Sniffer extends Animals {

    /**
     * Remove a location of the explored locations.
-     *
+     * <br>
     * <b>Note:</b> the location must be in the sniffer's current world for this
     * method to have any effect.
     *
-     *
     * @param location the location to remove
     * @see #getExploredLocations()
     */
@ -39,11 +40,10 @@ public interface Sniffer extends Animals {

    /**
     * Add a location to the explored locations.
-     *
+     * <br>
     * <b>Note:</b> the location must be in the sniffer's current world for this
     * method to have any effect.
     *
-     *
     * @param location the location to add
     * @see #getExploredLocations()
     */
--- a/paper-api/src/main/java/org/bukkit/entity/memory/MemoryKey.java
+++ b/paper-api/src/main/java/org/bukkit/entity/memory/MemoryKey.java
@ -7,7 +7,9 @@ import java.util.Set;
 import java.util.UUID;
 import org.bukkit.Keyed;
 import org.bukkit.Location;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.NamespacedKey;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

@ -69,6 +71,8 @@ public final class MemoryKey<T> implements Keyed {
    public static final MemoryKey<Location> LIKED_NOTEBLOCK_POSITION = new MemoryKey<>(NamespacedKey.minecraft("liked_noteblock"), Location.class);
    public static final MemoryKey<Integer> LIKED_NOTEBLOCK_COOLDOWN_TICKS = new MemoryKey<>(NamespacedKey.minecraft("liked_noteblock_cooldown_ticks"), Integer.class);
    public static final MemoryKey<Integer> ITEM_PICKUP_COOLDOWN_TICKS = new MemoryKey<>(NamespacedKey.minecraft("item_pickup_cooldown_ticks"), Integer.class);
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    public static final MemoryKey<Location> SNIFFER_EXPLORED_POSITIONS = new MemoryKey<>(NamespacedKey.minecraft("sniffer_explored_positions"), Location.class);

    /**
--- a/paper-api/src/main/java/org/bukkit/event/block/InventoryBlockStartEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/block/InventoryBlockStartEvent.java
@ -1,10 +1,10 @@
 package org.bukkit.event.block;

-import org.bukkit.Warning;
 import org.bukkit.block.Block;
 import org.bukkit.event.HandlerList;
 import org.bukkit.event.inventory.FurnaceStartSmeltEvent;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
@ -15,10 +15,9 @@ import org.jetbrains.annotations.NotNull;
 * <li>A Campfire starts cooking {@link CampfireStartEvent}</li>
 * </ul>
 *
- * @deprecated draft API
+ * @apiNote draft API
 */
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
 public class InventoryBlockStartEvent extends BlockEvent {

    private static final HandlerList handlers = new HandlerList();
--- a/paper-api/src/main/java/org/bukkit/event/inventory/InventoryType.java
+++ b/paper-api/src/main/java/org/bukkit/event/inventory/InventoryType.java
@ -1,5 +1,6 @@
 package org.bukkit.event.inventory;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.inventory.InventoryHolder;
 import org.jetbrains.annotations.NotNull;

@ -145,9 +146,9 @@ public enum InventoryType {
    /**
     * The new smithing inventory, with 3 CRAFTING slots and 1 RESULT slot.
     *
-     * @deprecated draft, experimental 1.20 API
+     * @apiNote draft, experimental 1.20 API
     */
-    @Deprecated
+    @MinecraftExperimental
    SMITHING_NEW(4, "Upgrade Gear"),
    ;

--- a/paper-api/src/main/java/org/bukkit/event/player/PlayerHideEntityEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerHideEntityEvent.java
@ -1,24 +1,23 @@
 package org.bukkit.event.player;

-import org.bukkit.Warning;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
 * Called when a visible entity is hidden from a player.
- *
+ * <br>
 * This event is only called when the entity's visibility status is actually
 * changed.
- *
+ * <br>
 * This event is called regardless of if the entity was within tracking range.
 *
 * @see Player#hideEntity(org.bukkit.plugin.Plugin, org.bukkit.entity.Entity)
- * @deprecated draft API
+ * @apiNote draft API
 */
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
 public class PlayerHideEntityEvent extends PlayerEvent {

    private static final HandlerList handlers = new HandlerList();
--- a/paper-api/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
+++ b/paper-api/src/main/java/org/bukkit/event/player/PlayerShowEntityEvent.java
@ -1,25 +1,24 @@
 package org.bukkit.event.player;

-import org.bukkit.Warning;
 import org.bukkit.entity.Entity;
 import org.bukkit.entity.Player;
 import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
 * Called when a hidden entity is shown to a player.
- *
+ * <br>
 * This event is only called when the entity's visibility status is actually
 * changed.
- *
+ * <br>
 * This event is called regardless of whether the entity was within tracking
 * range.
 *
 * @see Player#showEntity(org.bukkit.plugin.Plugin, org.bukkit.entity.Entity)
- * @deprecated draft API
+ * @apiNote draft API
 */
-@Deprecated
-@Warning(false)
+@ApiStatus.Experimental
 public class PlayerShowEntityEvent extends PlayerEvent {

    private static final HandlerList handlers = new HandlerList();
--- a/paper-api/src/main/java/org/bukkit/inventory/ChiseledBookshelfInventory.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/ChiseledBookshelfInventory.java
@ -1,11 +1,15 @@
 package org.bukkit.inventory;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.block.ChiseledBookshelf;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.Nullable;

 /**
 * Interface to the inventory of a chiseled bookshelf.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface ChiseledBookshelfInventory extends Inventory {

    @Nullable
--- a/paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/ItemFlag.java
@ -1,5 +1,8 @@
 package org.bukkit.inventory;

+import org.bukkit.MinecraftExperimental;
+import org.jetbrains.annotations.ApiStatus;
+
 /**
 * A ItemFlag can hide some Attributes from ItemStacks
 */
@ -37,5 +40,7 @@ public enum ItemFlag {
    /**
     * Setting to show/hide armor trim from leather armor.
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    HIDE_ARMOR_TRIM;
 }
--- a/paper-api/src/main/java/org/bukkit/inventory/SmithingInventory.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/SmithingInventory.java
@ -1,10 +1,15 @@
 package org.bukkit.inventory;

+import org.bukkit.MinecraftExperimental;
 import org.jetbrains.annotations.Nullable;

 /**
 * Interface to the inventory of a Smithing table.
+ *
+ * @apiNote Check {@link #getType()} to better handle either the current or experimental
+ * variant of this inventory
 */
+@MinecraftExperimental
 public interface SmithingInventory extends Inventory {

    /**
--- a/paper-api/src/main/java/org/bukkit/inventory/SmithingTrimRecipe.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/SmithingTrimRecipe.java
@ -1,12 +1,19 @@
 package org.bukkit.inventory;

 import org.bukkit.Material;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.NamespacedKey;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;

 /**
 * Represents a smithing trim recipe.
+ *
+ * @apiNote This recipe is part of an experimental feature of Minecraft and
+ * hence subject to change.
 */
+@MinecraftExperimental
+@ApiStatus.Experimental
 public class SmithingTrimRecipe extends SmithingRecipe implements ComplexRecipe {

    private final RecipeChoice template;
--- a/paper-api/src/main/java/org/bukkit/inventory/meta/BundleMeta.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/meta/BundleMeta.java
@ -1,10 +1,14 @@
 package org.bukkit.inventory.meta;

 import java.util.List;
+import org.bukkit.MinecraftExperimental;
 import org.bukkit.inventory.ItemStack;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

+@MinecraftExperimental
+@ApiStatus.Experimental
 public interface BundleMeta extends ItemMeta {

    /**
--- a/paper-api/src/main/java/org/bukkit/inventory/meta/SkullMeta.java
+++ b/paper-api/src/main/java/org/bukkit/inventory/meta/SkullMeta.java
@ -1,8 +1,10 @@
 package org.bukkit.inventory.meta;

+import org.bukkit.MinecraftExperimental;
 import org.bukkit.NamespacedKey;
 import org.bukkit.OfflinePlayer;
 import org.bukkit.profile.PlayerProfile;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;

@ -88,6 +90,8 @@ public interface SkullMeta extends ItemMeta {
     *
     * @param noteBlockSound the key of the sound to be played, or null
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    void setNoteBlockSound(@Nullable NamespacedKey noteBlockSound);

    /**
@ -98,6 +102,8 @@ public interface SkullMeta extends ItemMeta {
     *
     * @return the key of the sound, or null
     */
+    @MinecraftExperimental
+    @ApiStatus.Experimental
    @Nullable
    NamespacedKey getNoteBlockSound();