diff --git a/paper-api/src/main/java/org/bukkit/block/Conduit.java b/paper-api/src/main/java/org/bukkit/block/Conduit.java index 5543165536..5ae4f4f357 100644 --- a/paper-api/src/main/java/org/bukkit/block/Conduit.java +++ b/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. + *

+ * 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. + *

+ * 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, + * not 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 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. + *

+ * 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(); +}