Add FluidState API

paper-api/src/main/java/io/papermc/paper/block/fluid/FluidData.java

@@ -0,0 +1,69 @@
+package io.papermc.paper.block.fluid;
+
+import org.bukkit.Fluid;
+import org.bukkit.Location;
+import org.bukkit.util.Vector;
+import org.jetbrains.annotations.Range;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * A representation of a fluid in a specific state of data.
+ * This type is not linked to a specific location and hence mostly resembles a {@link org.bukkit.block.data.BlockData}.
+ */
+@NullMarked
+public interface FluidData extends Cloneable {
+
+    /**
+     * Gets the fluid type of this fluid data.
+     *
+     * @return the fluid type
+     */
+    Fluid getFluidType();
+
+    /**
+     * Returns a copy of this FluidData.
+     *
+     * @return a copy of the fluid data
+     */
+    FluidData clone();
+
+    /**
+     * Computes the direction of the flow of the liquid at the given location as a vector.
+     * <p>
+     * This method requires the passed location's chunk to be loaded.
+     * If said chunk is not loaded when this method is called, the chunk will first be loaded prior to the computation
+     * which leads to a potentially slow sync chunk load.
+     *
+     * @param location - the location to check the liquid flow
+     * @return the flow direction vector at the given location
+     */
+    Vector computeFlowDirection(Location location);
+
+    /**
+     * Returns the level of liquid this fluid data holds.
+     *
+     * @return the amount as an integer, between 0 and 8
+     */
+    @Range(from = 0, to = 8)
+    int getLevel();
+
+    /**
+     * Computes the height of the fluid in the world.
+     * <p>
+     * This method requires the passed location's chunk to be loaded.
+     * If said chunk is not loaded when this method is called, the chunk will first be loaded prior to the computation
+     * which leads to a potentially slow sync chunk load.
+     *
+     * @param location the location at which to check the high of this fluid data.
+     * @return the height as a float value
+     */
+    @Range(from = 0, to = 1)
+    float computeHeight(Location location);
+
+    /**
+     * Returns whether this fluid is a source block
+     *
+     * @return true if the fluid is a source block, false otherwise
+     */
+    boolean isSource();
+}

paper-api/src/main/java/io/papermc/paper/block/fluid/type/FallingFluidData.java

@@ -0,0 +1,16 @@
+package io.papermc.paper.block.fluid.type;
+
+import io.papermc.paper.block.fluid.FluidData;
+
+/**
+ * A specific subtype of {@link FluidData} that is returned by the API for fluid data of potentially falling fluids.
+ */
+public interface FallingFluidData extends FluidData {
+
+    /**
+     * Get if this liquid is falling.
+     *
+     * @return true if falling
+     */
+    boolean isFalling();
+}

paper-api/src/main/java/io/papermc/paper/block/fluid/type/FlowingFluidData.java

@@ -0,0 +1,10 @@
+package io.papermc.paper.block.fluid.type;
+
+import io.papermc.paper.block.fluid.FluidData;
+
+/**
+ * A specific subtype of {@link FluidData} that is returned by the API for fluid data of potentially falling fluids.
+ */
+public interface FlowingFluidData extends FallingFluidData {
+
+}