#986: Add more Conduit API

By: 2008Choco <hawkeboyz2@hotmail.com>

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

@@ -1,6 +1,110 @@
 package org.bukkit.block;
 
+import java.util.Collection;
+import org.bukkit.entity.LivingEntity;
+import org.bukkit.util.BoundingBox;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents a captured state of a conduit.
  */
-public interface Conduit extends TileState { }
+public interface Conduit extends TileState {
+
+    /**
+     * Checks whether or not this conduit is active.
+     * <p>
+     * A conduit is considered active if there are at least 16 valid frame
+     * blocks surrounding it and the conduit is surrounded by a 3x3x3 area of
+     * water source blocks (or waterlogged blocks), at which point its animation
+     * will activate, start spinning, and apply effects to nearby players.
+     *
+     * @return true if active, false otherwise
+     */
+    public boolean isActive();
+
+    /**
+     * Get whether or not this conduit is actively hunting for nearby hostile
+     * creatures.
+     * <p>
+     * A conduit will hunt if it is active (see {@link #isActive()}) and its
+     * frame is complete (it is surrounded by at least 42 valid frame blocks).
+     * While hunting, the {@link #getTarget()
+     * conduit's target}, if within its {@link #getHuntingArea() hunting area},
+     * will be damaged every 2 seconds.
+     *
+     * @return true if hunting, false otherwise
+     */
+    public boolean isHunting();
+
+    /**
+     * Get a {@link Collection} of all {@link Block Blocks} that make up the
+     * frame of this conduit. The returned collection will contain only blocks
+     * that match the types required by the conduit to make up a valid frame,
+     * <strong>not</strong> the blocks at which the conduit is searching,
+     * meaning it will be of variable size depending on how many valid frames
+     * are surrounding the conduit at the time of invocation.
+     *
+     * @return the frame blocks
+     */
+    @NotNull
+    public Collection<Block> getFrameBlocks();
+
+    /**
+     * Get the amount of valid frame blocks that are currently surrounding the
+     * conduit.
+     *
+     * @return the frame block count
+     */
+    public int getFrameBlockCount();
+
+    /**
+     * Get the range (measured in blocks) within which players will receive the
+     * conduit's benefits.
+     *
+     * @return the conduit range
+     */
+    public int getRange();
+
+    /**
+     * Set the conduit's hunting target.
+     * <p>
+     * Note that the value set by this method may be overwritten by the
+     * conduit's periodic hunting logic. If the target is ever set to
+     * {@code null}, the conduit will continue to look for a new target.
+     * Additionally, if the target is set to an entity that does not meet a
+     * conduit's hunting conditions (e.g. the entity is not within the
+     * {@link #getHuntingArea() hunting area}, has already been killed, etc.)
+     * then the passed entity will be ignored and the conduit will also continue
+     * to look for a new target.
+     *
+     * @param target the target entity, or null to remove the target
+     *
+     * @return true if the target was changed, false if the target was the same
+     */
+    public boolean setTarget(@Nullable LivingEntity target);
+
+    /**
+     * Get the conduit's hunting target.
+     *
+     * @return the hunting target, or null if the conduit does not have a target
+     */
+    @Nullable
+    public LivingEntity getTarget();
+
+    /**
+     * Check whether or not this conduit has an active (alive) hunting target.
+     *
+     * @return true if has a hunting target, false otherwise
+     */
+    public boolean hasTarget();
+
+    /**
+     * Get a {@link BoundingBox} (relative to real-world coordinates) in which
+     * the conduit will search for hostile entities to target.
+     *
+     * @return the hunting area bounding box
+     */
+    @NotNull
+    public BoundingBox getHuntingArea();
+}