#837: Add more bell API

By: Parker Hawke <hawkeboyz2@hotmail.com>

paper-api/src/main/java/org/bukkit/block/Bell.java

@@ -1,6 +1,89 @@
 package org.bukkit.block;
 
+import org.bukkit.entity.Entity;
+import org.bukkit.event.block.BellRingEvent;
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents a captured state of Bell.
  */
-public interface Bell extends TileState { }
+public interface Bell extends TileState {
+
+    /**
+     * Ring this bell. This will call a {@link BellRingEvent}.
+     *
+     * @param entity the entity ringing the bell
+     * @param direction the direction from which the bell was rung or null to
+     * ring in the direction that the bell is facing
+     * @return true if rung successfully, false if the event was cancelled
+     */
+    public boolean ring(@Nullable Entity entity, @Nullable BlockFace direction);
+
+    /**
+     * Ring this bell in the direction that the bell is facing. This will call a
+     * {@link BellRingEvent}.
+     *
+     * @param entity the entity ringing the bell
+     * @return true if rung successfully, false if the event was cancelled
+     */
+    public boolean ring(@Nullable Entity entity);
+
+    /**
+     * Ring this bell. This will call a {@link BellRingEvent}.
+     *
+     * @param direction the direction from which the bell was rung or null to
+     * ring in the direction that the bell is facing
+     * @return true if rung successfully, false if the event was cancelled
+     */
+    public boolean ring(@Nullable BlockFace direction);
+
+    /**
+     * Ring this bell in the direction that the bell is facing. This will call a
+     * {@link BellRingEvent}.
+     *
+     * @return true if rung successfully, false if the event was cancelled
+     */
+    public boolean ring();
+
+    /**
+     * Check whether or not this bell is shaking. A bell is considered to be
+     * shaking if it was recently rung.
+     * <p>
+     * A bell will typically shake for 50 ticks.
+     *
+     * @return true if shaking, false otherwise
+     */
+    public boolean isShaking();
+
+    /**
+     * Get the amount of ticks since this bell has been shaking, or 0 if the
+     * bell is not currently shaking.
+     * <p>
+     * A bell will typically shake for 50 ticks.
+     *
+     * @return the time in ticks since the bell was rung, or 0 if not shaking
+     */
+    public int getShakingTicks();
+
+    /**
+     * Check whether or not this bell is resonating. A bell is considered to be
+     * resonating if {@link #isShaking() while shaking}, raiders were detected
+     * in the area and are ready to be highlighted to nearby players.
+     * <p>
+     * A bell will typically resonate for 40 ticks.
+     *
+     * @return true if resonating, false otherwise
+     */
+    public boolean isResonating();
+
+    /**
+     * Get the amount of ticks since this bell has been resonating, or 0 if the
+     * bell is not currently resonating.
+     * <p>
+     * A bell will typically resonate for 40 ticks.
+     *
+     * @return the time in ticks since the bell has been resonating, or 0 if not
+     * resonating
+     */
+    public int getResonatingTicks();
+}

paper-api/src/main/java/org/bukkit/event/block/BellResonateEvent.java

@@ -0,0 +1,50 @@
+package org.bukkit.event.block;
+
+import java.util.List;
+import org.bukkit.block.Block;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+
+/**
+ * Called when a bell resonated after being rung and highlights nearby raiders.
+ * A bell will only resonate if raiders are in the vicinity of the bell.
+ */
+public class BellResonateEvent extends BlockEvent {
+
+    private static final HandlerList handlers = new HandlerList();
+    private final List<LivingEntity> resonatedEntities;
+
+    public BellResonateEvent(@NotNull Block theBlock, @NotNull List<LivingEntity> resonatedEntities) {
+        super(theBlock);
+        this.resonatedEntities = resonatedEntities;
+    }
+
+    /**
+     * Get a mutable list of all {@link LivingEntity LivingEntities} to be
+     * highlighted by the bell's resonating. This list can be added to or
+     * removed from to change which entities are highlighted, and may be empty
+     * if no entities were resonated as a result of this event.
+     * <p>
+     * While the highlighted entities will change, the particles that display
+     * over a resonated entity and their colors will not. This is handled by the
+     * client and cannot be controlled by the server.
+     *
+     * @return a list of resonated entities
+     */
+    @NotNull
+    public List<LivingEntity> getResonatedEntities() {
+        return resonatedEntities;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}

paper-api/src/main/java/org/bukkit/event/block/BellRingEvent.java

@@ -0,0 +1,67 @@
+package org.bukkit.event.block;
+
+import org.bukkit.block.Block;
+import org.bukkit.block.BlockFace;
+import org.bukkit.entity.Entity;
+import org.bukkit.event.Cancellable;
+import org.bukkit.event.HandlerList;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Called when a bell is being rung.
+ */
+public class BellRingEvent extends BlockEvent implements Cancellable {
+
+    private static final HandlerList handlers = new HandlerList();
+    private final BlockFace direction;
+    private final Entity entity;
+    private boolean cancelled;
+
+    public BellRingEvent(@NotNull Block theBlock, @NotNull BlockFace direction, @Nullable Entity entity) {
+        super(theBlock);
+        this.direction = direction;
+        this.entity = entity;
+    }
+
+    /**
+     * Get the direction in which the bell was rung.
+     *
+     * @return the direction
+     */
+    @NotNull
+    public BlockFace getDirection() {
+        return direction;
+    }
+
+    /**
+     * Get the {@link Entity} that rang the bell (if there was one).
+     *
+     * @return the entity
+     */
+    @Nullable
+    public Entity getEntity() {
+        return entity;
+    }
+
+    @Override
+    public void setCancelled(boolean cancelled) {
+        this.cancelled = cancelled;
+    }
+
+    @Override
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    @NotNull
+    @Override
+    public HandlerList getHandlers() {
+        return handlers;
+    }
+
+    @NotNull
+    public static HandlerList getHandlerList() {
+        return handlers;
+    }
+}