diff --git a/paper-api/src/main/java/org/bukkit/block/SculkCatalyst.java b/paper-api/src/main/java/org/bukkit/block/SculkCatalyst.java index ed94fbc0dd..46260df893 100644 --- a/paper-api/src/main/java/org/bukkit/block/SculkCatalyst.java +++ b/paper-api/src/main/java/org/bukkit/block/SculkCatalyst.java @@ -1,7 +1,27 @@ package org.bukkit.block; +import org.bukkit.event.entity.EntityDeathEvent; +import org.jetbrains.annotations.NotNull; + /** * Represents a captured state of a sculk catalyst. */ public interface SculkCatalyst extends TileState { + + /** + * Causes a new sculk bloom, as if an entity just died around this catalyst. + *

+ * Typically, charges should be set to the exp reward of a mob + * ({@link EntityDeathEvent#getDroppedExp()}), which is usually + * 3-5 for animals, and 5-10 for the average mob (up to 50 for + * wither skeletons). Roughly speaking, for each charge, 1 more + * sculk block will be placed. + *

+ * If charges > 1000, multiple cursors will be spawned in the + * block. + * + * @param block which block to spawn the cursor in + * @param charges how much charge to spawn. + */ + void bloom(@NotNull Block block, int charges); } diff --git a/paper-api/src/main/java/org/bukkit/block/SculkShrieker.java b/paper-api/src/main/java/org/bukkit/block/SculkShrieker.java index 044823a32b..323269780a 100644 --- a/paper-api/src/main/java/org/bukkit/block/SculkShrieker.java +++ b/paper-api/src/main/java/org/bukkit/block/SculkShrieker.java @@ -1,5 +1,8 @@ package org.bukkit.block; +import org.bukkit.entity.Player; +import org.jetbrains.annotations.Nullable; + /** * Represents a captured state of a sculk shrieker. */ @@ -24,4 +27,11 @@ public interface SculkShrieker extends TileState { * @param level new warning level */ void setWarningLevel(int level); + + /** + * Simulates a player causing a vibration. + * + * @param player the player that "caused" the shriek + */ + void tryShriek(@Nullable Player player); } diff --git a/paper-api/src/main/java/org/bukkit/event/block/SculkBloomEvent.java b/paper-api/src/main/java/org/bukkit/event/block/SculkBloomEvent.java new file mode 100644 index 0000000000..d8be01f0d8 --- /dev/null +++ b/paper-api/src/main/java/org/bukkit/event/block/SculkBloomEvent.java @@ -0,0 +1,88 @@ +package org.bukkit.event.block; + +import com.google.common.base.Preconditions; +import org.bukkit.block.Block; +import org.bukkit.block.SculkCatalyst; +import org.bukkit.event.Cancellable; +import org.bukkit.event.HandlerList; +import org.bukkit.event.entity.EntityDeathEvent; +import org.jetbrains.annotations.NotNull; + +/** + * Represents an event triggered when a new cursor is created by a {@link SculkCatalyst}. + *

+ * Cursor Definition: + * A cursor in this context is a dynamic marker or pointer generated by the + * SculkCatalyst. It occupies a block and spreads sculk as it moves. It is + * similar to entity, but it is not an entity. Cursors are ticked by the + * tile entity. + *

+ * Triggers for Cursor Creation: + *

+ * + * The result of {@link #getBlock()} is the location that the cursor is spawning at. + */ +public class SculkBloomEvent extends BlockEvent implements Cancellable { + + private static final HandlerList handlers = new HandlerList(); + private boolean cancel = false; + + private int charge; + + public SculkBloomEvent(@NotNull Block theBlock, int charge) { + super(theBlock); + this.charge = charge; + } + + /** + * Returns the charge of the cursor, <1000 by default. + * + * @return the charge of the cursor + */ + public int getCharge() { + return charge; + } + + /** + * Sets the charge of the cursor. + *

+ * Increasing the charge of a cursor makes the cursor last longer, giving + * it more time to spread sculk blocks across a larger range. + *

+ * Typically, charges should be set to the exp reward of a mob + * ({@link EntityDeathEvent#getDroppedExp()}), which is usually + * 3-5 for animals, and 5-10 for the average mob (up to 50 for + * wither skeletons). Roughly speaking, for each charge, 1 more + * sculk block will be placed. + * + * @param charge the charge of the cursor. + */ + public void setCharge(int charge) { + Preconditions.checkArgument(charge >= 0 && charge <= 1000, charge + " is not in range [0, 1000]"); + this.charge = charge; + } + + @Override + public boolean isCancelled() { + return cancel; + } + + @Override + public void setCancelled(boolean cancel) { + this.cancel = cancel; + } + + @NotNull + @Override + public HandlerList getHandlers() { + return handlers; + } + + @NotNull + public static HandlerList getHandlerList() { + return handlers; + } +}