From a9e78d5583517ccee8b490d7d385ed58ff13e83d Mon Sep 17 00:00:00 2001 From: TheMode Date: Sun, 11 Jul 2021 19:35:07 +0200 Subject: [PATCH] Add comments --- .../net/minestom/server/coordinate/Point.java | 62 ++++++++++++++++++- .../net/minestom/server/coordinate/Pos.java | 28 +++++++-- 2 files changed, 84 insertions(+), 6 deletions(-) diff --git a/src/main/java/net/minestom/server/coordinate/Point.java b/src/main/java/net/minestom/server/coordinate/Point.java index c2ebac45d..34677ec4a 100644 --- a/src/main/java/net/minestom/server/coordinate/Point.java +++ b/src/main/java/net/minestom/server/coordinate/Point.java @@ -42,36 +42,87 @@ public interface Point { @Contract(pure = true) double z(); + /** + * Gets the floored value of the X component + * + * @return the block X + */ @Contract(pure = true) default int blockX() { return MathUtils.floor(x()); } + /** + * Gets the floored value of the X component + * + * @return the block X + */ @Contract(pure = true) default int blockY() { return MathUtils.floor(y()); } + /** + * Gets the floored value of the X component + * + * @return the block X + */ @Contract(pure = true) default int blockZ() { return MathUtils.floor(z()); } + /** + * Creates a point with a modified X coordinate based on its value. + * + * @param operator the operator providing the current X coordinate and returning the new + * @return a new point + */ @Contract(pure = true) @NotNull Point withX(@NotNull DoubleUnaryOperator operator); + /** + * Creates a point with the specified X coordinate. + * + * @param x the new X coordinate + * @return a new point + */ @Contract(pure = true) @NotNull Point withX(double x); + /** + * Creates a point with a modified Y coordinate based on its value. + * + * @param operator the operator providing the current Y coordinate and returning the new + * @return a new point + */ @Contract(pure = true) @NotNull Point withY(@NotNull DoubleUnaryOperator operator); + /** + * Creates a point with the specified Y coordinate. + * + * @param y the new Y coordinate + * @return a new point + */ @Contract(pure = true) @NotNull Point withY(double y); + /** + * Creates a point with a modified Z coordinate based on its value. + * + * @param operator the operator providing the current Z coordinate and returning the new + * @return a new point + */ @Contract(pure = true) @NotNull Point withZ(@NotNull DoubleUnaryOperator operator); + /** + * Creates a point with the specified Z coordinate. + * + * @param z the new Z coordinate + * @return a new point + */ @Contract(pure = true) @NotNull Point withZ(double z); @@ -126,8 +177,9 @@ public interface Point { return sub(1, 0, 0); case EAST: return add(1, 0, 0); + default: // should never be called + return this; } - return this; // should never be called } /** @@ -172,6 +224,12 @@ public interface Point { Double.compare(point.z(), z()) == 0; } + /** + * Gets if the three coordinates {@link #x()}, {@link #y()} and {@link #z()} + * are equals to {@code 0}. + * + * @return true if the three coordinates are zero + */ default boolean isZero() { return x() == 0 && y() == 0 && z() == 0; } @@ -180,7 +238,7 @@ public interface Point { * Gets if two points are in the same chunk. * * @param point the point to compare two - * @return true if 'this' is in the same chunk as {@code position} + * @return true if 'this' is in the same chunk as {@code point} */ default boolean inSameChunk(@NotNull Point point) { return ChunkUtils.getChunkCoordinate(x()) == ChunkUtils.getChunkCoordinate(point.x()) && diff --git a/src/main/java/net/minestom/server/coordinate/Pos.java b/src/main/java/net/minestom/server/coordinate/Pos.java index 17177dc54..59c563b3c 100644 --- a/src/main/java/net/minestom/server/coordinate/Pos.java +++ b/src/main/java/net/minestom/server/coordinate/Pos.java @@ -2,7 +2,6 @@ package net.minestom.server.coordinate; import net.minestom.server.instance.block.BlockFace; import net.minestom.server.utils.MathUtils; -import net.minestom.server.utils.Position; import org.jetbrains.annotations.Contract; import org.jetbrains.annotations.NotNull; @@ -40,12 +39,27 @@ public final class Pos implements Point { this(point, 0, 0); } + /** + * Converts a {@link Point} into a {@link Pos}. + * Will cast if possible, or instantiate a new object. + * + * @param point the point to convert + * @return the converted position + */ public static @NotNull Pos fromPoint(@NotNull Point point) { if (point instanceof Pos) return (Pos) point; return new Pos(point.x(), point.y(), point.z()); } + /** + * Changes the 3 coordinates of this position. + * + * @param x the X coordinate + * @param y the Y coordinate + * @param z the Z coordinate + * @return a new position + */ @Contract(pure = true) public @NotNull Pos withCoord(double x, double y, double z) { return new Pos(x, y, z, yaw, pitch); @@ -152,9 +166,15 @@ public final class Pos implements Point { return z; } + /** + * Returns a new position based on this position fields. + * + * @param operator the operator deconstructing this object and providing a new position + * @return the new position + */ @Contract(pure = true) - public @NotNull Pos with(@NotNull Operator operator) { - return operator.apply(x, y, z); + public @NotNull Pos apply(@NotNull Operator operator) { + return operator.apply(x, y, z, yaw, pitch); } @Override @@ -303,6 +323,6 @@ public final class Pos implements Point { @FunctionalInterface public interface Operator { - @NotNull Pos apply(double x, double y, double z); + @NotNull Pos apply(double x, double y, double z, float yaw, float pitch); } }