From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001 From: vicisacat <victor.branchu@gmail.com> Date: Fri, 17 Nov 2023 20:21:47 +0100 Subject: [PATCH] Add FluidState API diff --git a/src/main/java/io/papermc/paper/block/fluid/FluidData.java b/src/main/java/io/papermc/paper/block/fluid/FluidData.java new file mode 100644 index 0000000000000000000000000000000000000000..0750219fc68261e5c396636967e0b633ae17b72e --- /dev/null +++ b/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(); +} diff --git a/src/main/java/io/papermc/paper/block/fluid/type/FallingFluidData.java b/src/main/java/io/papermc/paper/block/fluid/type/FallingFluidData.java new file mode 100644 index 0000000000000000000000000000000000000000..7bd9f28ba646f09080b5c29b9d3be5af676c912e --- /dev/null +++ b/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(); +} diff --git a/src/main/java/io/papermc/paper/block/fluid/type/FlowingFluidData.java b/src/main/java/io/papermc/paper/block/fluid/type/FlowingFluidData.java new file mode 100644 index 0000000000000000000000000000000000000000..fbccdffe8d73e517204081c73bca9154f8c7d69f --- /dev/null +++ b/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 { + +} diff --git a/src/main/java/org/bukkit/RegionAccessor.java b/src/main/java/org/bukkit/RegionAccessor.java index 43dd6c59cceba12f27e6b265acc3ad97eea37abd..eb33e8e671972aa308ad75a7ce9aa9ac526f470f 100644 --- a/src/main/java/org/bukkit/RegionAccessor.java +++ b/src/main/java/org/bukkit/RegionAccessor.java @@ -102,6 +102,41 @@ public interface RegionAccessor extends Keyed { // Paper @NotNull BlockState getBlockState(int x, int y, int z); + // Paper start - FluidState API + /** + * Gets the {@link io.papermc.paper.block.fluid.FluidData} at the specified position. + * + * @param x The x-coordinate of the position + * @param y The y-coordinate of the position + * @param z The z-coordinate of the position + * @return The {@link io.papermc.paper.block.fluid.FluidData} at the specified position + */ + @NotNull + io.papermc.paper.block.fluid.FluidData getFluidData(int x, int y, int z); + + /** + * Gets the {@link io.papermc.paper.block.fluid.FluidData} at the given position + * + * @param position The position of the fluid + * @return The fluid data at the given position + */ + @NotNull + default io.papermc.paper.block.fluid.FluidData getFluidData(@NotNull io.papermc.paper.math.Position position) { + return getFluidData(position.blockX(), position.blockY(), position.blockZ()); + } + + /** + * Gets the {@link io.papermc.paper.block.fluid.FluidData} at the given position + * + * @param location The location of the fluid + * @return The fluid data at the given position + */ + @NotNull + default io.papermc.paper.block.fluid.FluidData getFluidData(@NotNull Location location) { + return getFluidData(location.blockX(), location.blockY(), location.blockZ()); + } + // Paper end + /** * Gets the {@link BlockData} at the given {@link Location}. *