implement new level events

Author: Lulu13022002

paper-api/.checkstyle/checkstyle.xml

@@ -12,7 +12,7 @@
     <module name="SuppressWarningsFilter" />
     <module name="TreeWalker">
         <module name="SuppressWarningsHolder" />
-        <!--Skip generate content by typewriter-->
+        <!--Skip generated content by typewriter-->
         <module name="SuppressionCommentFilter">
             <property name="offCommentFormat" value="Start generate - [\w\|]+"/>
             <property name="onCommentFormat" value="End generate - [\w\|]+"/>

paper-api/src/main/java/io/papermc/paper/datacomponent/item/ItemComponentTypesBridge.java

@@ -18,10 +18,8 @@
 import org.bukkit.inventory.ItemType;
 import org.bukkit.inventory.meta.trim.ArmorTrim;
 import org.bukkit.map.MapCursor;
-import org.jetbrains.annotations.ApiStatus;
 import org.jspecify.annotations.Nullable;
 
-@ApiStatus.Internal
 interface ItemComponentTypesBridge {
 
     Optional<ItemComponentTypesBridge> BRIDGE = ServiceLoader.load(ItemComponentTypesBridge.class, ItemComponentTypesBridge.class.getClassLoader()).findFirst();

paper-api/src/main/java/io/papermc/paper/datacomponent/item/SignText.java

@@ -10,7 +10,7 @@
 import org.jetbrains.annotations.Contract;
 
 /**
- * Represents the text on a sign side.
+ * Represents the lines of text on a sign side.
  *
  * @see io.papermc.paper.datacomponent.DataComponentTypes#SIGN_TEXT_FRONT
  * @see io.papermc.paper.datacomponent.DataComponentTypes#SIGN_TEXT_BACK
@@ -29,20 +29,20 @@ static SignText.Builder signText() {
     }
 
     /**
-     * Gets the list of messages on this sign side.
+     * Gets the lines on this sign side.
      *
      * @return the list of messages
      */
     @Contract(pure = true)
-    List<Component> messages();
+    List<Component> lines();
 
     /**
-     * Gets the list of messages on this sign side, filtered for the player.
+     * Gets the lines on this sign side, filtered for the player.
      *
      * @return the list of messages
      */
     @Contract(pure = true)
-    List<Component> filteredMessages();
+    List<Component> filteredLines();
 
     /**
      * Gets the color of the text on this sign side.
@@ -67,22 +67,32 @@ static SignText.Builder signText() {
     interface Builder extends DataComponentBuilder<SignText> {
 
         /**
-         * Sets the list of messages on this sign side.
+         * Sets the lines on this sign side.
          *
          * @param messages the list of messages
          * @return the builder for chaining
          */
         @Contract(value = "_ -> this", mutates = "this")
-        Builder messages(List<? extends ComponentLike> messages);
+        Builder lines(List<? extends ComponentLike> messages);
 
         /**
-         * Adds a message to the list of messages on this sign side.
+         * Sets a line at the specified index on this sign side.
          *
-         * @param message the message to add
+         * @param index the line index
+         * @param message the message
+         * @return the builder for chaining
+         */
+        @Contract(value = "_, _ -> this", mutates = "this")
+        Builder line(int index, ComponentLike message);
+
+        /**
+         * Adds a line on this sign side.
+         *
+         * @param message the message
          * @return the builder for chaining
          */
         @Contract(value = "_ -> this", mutates = "this")
-        Builder addMessage(ComponentLike message);
+        Builder addLine(ComponentLike message);
 
         /**
          * Sets the color of the text on this sign side.
@@ -96,7 +106,7 @@ interface Builder extends DataComponentBuilder<SignText> {
         /**
          * Sets whether the text on this sign side has a glowing effect.
          *
-         * @param hasGlowingText true if the text has a glowing effect, false otherwise
+         * @param hasGlowingText {@code true} if the text has a glowing effect
          * @return the builder for chaining
          */
         @Contract(value = "_ -> this", mutates = "this")

paper-api/src/main/java/io/papermc/paper/datacomponent/item/consumable/ConsumableTypesBridge.java

@@ -24,7 +24,5 @@ static ConsumableTypesBridge bridge() {
 
     ConsumeEffect.PlaySound playSoundEffect(Key sound);
 
-    ConsumeEffect.TeleportRandomly teleportRandomlyEffect(float diameter);
-
     ConsumeEffect.TeleportRandomly teleportRandomlyEffect(float diameter, boolean directionalParticles);
 }

paper-api/src/main/java/io/papermc/paper/datacomponent/item/consumable/ConsumeEffect.java

@@ -19,10 +19,23 @@ public interface ConsumeEffect {
      *
      * @param diameter diameter of random teleportation
      * @return the effect instance
+     * @see #teleportRandomlyEffect(float, boolean)
      */
     @Contract(value = "_ -> new", pure = true)
     static TeleportRandomly teleportRandomlyEffect(final float diameter) {
-        return ConsumableTypesBridge.bridge().teleportRandomlyEffect(diameter);
+        return teleportRandomlyEffect(diameter, true);
+    }
+
+    /**
+     * Creates a consume effect that randomly teleports the entity on consumption.
+     *
+     * @param diameter diameter of random teleportation
+     * @param directionalParticles show a particle trail in the direction of the teleportation
+     * @return the effect instance
+     */
+    @Contract(value = "_, _ -> new", pure = true)
+    static TeleportRandomly teleportRandomlyEffect(final float diameter, final boolean directionalParticles) {
+        return ConsumableTypesBridge.bridge().teleportRandomlyEffect(diameter, directionalParticles);
     }
 
     /**
@@ -83,9 +96,9 @@ interface TeleportRandomly extends ConsumeEffect {
         float diameter();
 
         /**
-         * If the teleport need to show a particle trail into the direction of the teleportation.
+         * Checks whether to show a particle trail in the direction of the teleportation.
          *
-         * @return true if the particle trail should be shown
+         * @return {@code true} if the particle trail should be shown
          */
         boolean directionalParticles();
     }

paper-api/src/main/java/io/papermc/paper/event/block/CompostItemEvent.java

@@ -40,17 +40,16 @@ public ItemStack getItem() {
      * Gets whether the composter will rise a level.
      *
      * @return {@code true} if successful
-     * @deprecated items can now control how many layers they add on click. Use {@link #getLevelsToRaise()}.
      */
-    @Deprecated(since = "26.3", forRemoval = true)
     public boolean willRaiseLevel() {
         return this.raisedLevels > 0;
     }
 
     /**
      * Sets whether the composter will rise a level.
      *
-     * @param willRaiseLevel {@code true} if the composter should rise a level. Use {@link #setLevelsToRaise(int)}.
+     * @param willRaiseLevel {@code true} if the composter should rise a level
+     * @deprecated items can now control how many layers they add on click. Use {@link #setLevelsToRaise(int)}.
      */
     @Deprecated(since = "26.3", forRemoval = true)
     public void setWillRaiseLevel(final boolean willRaiseLevel) {
@@ -67,7 +66,7 @@ public int getLevelsToRaise() {
     /**
      * Configures the levels the composter will be raised by.
      *
-     * @param raisedLevels the levels to raise the composter by.
+     * @param raisedLevels the levels to raise the composter by
      */
     public void setLevelsToRaise(final int raisedLevels) {
         this.raisedLevels = raisedLevels;

paper-api/src/main/java/io/papermc/paper/event/entity/EntityBreakByEntityEvent.java

@@ -12,10 +12,6 @@ public class EntityBreakByEntityEvent extends EntityBreakEvent {
     private final DamageSource damageSource;
 
     @ApiStatus.Internal
-    public EntityBreakByEntityEvent(final Entity entity, final Entity remover, final DamageSource damageSource) {
-        this(entity, remover, damageSource, RemoveCause.ENTITY);
-    }
-
     public EntityBreakByEntityEvent(final Entity entity, final Entity remover, final DamageSource damageSource, final RemoveCause cause) {
         super(entity, cause);
         this.remover = remover;

paper-api/src/main/java/io/papermc/paper/event/entity/EntityBreakEvent.java

@@ -22,7 +22,7 @@ public EntityBreakEvent(final Entity entity, final RemoveCause cause) {
     }
 
     /**
-     * Gets the cause for the entity's removal
+     * Gets the cause for the entity's removal.
      *
      * @return the RemoveCause for the entity's removal
      */
@@ -50,27 +50,27 @@ public static HandlerList getHandlerList() {
     }
 
     /**
-     * An enum to specify the cause of the removal
+     * An enum to specify the cause of the removal.
      */
     public enum RemoveCause {
         /**
-         * Removed by an entity
+         * Removed by an entity.
          */
         ENTITY,
         /**
-         * Removed by an explosion
+         * Removed by an explosion.
          */
         EXPLOSION,
         /**
-         * Removed by placing a block on it
+         * Removed by placing a block on it.
          */
         OBSTRUCTION,
         /**
-         * Removed by destroying the block behind it, etc
+         * Removed by destroying the block behind it, etc.
          */
         PHYSICS,
         /**
-         * Removed by an uncategorised cause
+         * Removed by an uncategorised cause.
          */
         DEFAULT,
     }

paper-api/src/main/java/io/papermc/paper/event/entity/EntityCompostItemEvent.java

@@ -18,8 +18,8 @@ public class EntityCompostItemEvent extends CompostItemEvent implements Cancella
     private boolean cancelled;
 
     @ApiStatus.Internal
-    public EntityCompostItemEvent(final Entity entity, final Block composter, final ItemStack item, final int willRaiseLevel) {
-        super(composter, item, willRaiseLevel);
+    public EntityCompostItemEvent(final Entity entity, final Block composter, final ItemStack item, final int raisedLevels) {
+        super(composter, item, raisedLevels);
         this.entity = entity;
     }
 

paper-api/src/main/java/io/papermc/paper/potion/PotionMix.java

@@ -13,7 +13,7 @@
 /**
  * Represents a potion mix made in a Brewing Stand.
  *
- * @deprecated Fully replaced by {@link org.bukkit.inventory.BrewingRecipe}.
+ * @deprecated fully replaced by {@link org.bukkit.inventory.BrewingRecipe}
  */
 @NullMarked
 @Deprecated(since = "26.3", forRemoval = true)