The relative block vector describing the relative location
- * @param yawThe yaw pointing outwards from a portal (in the relative vector's distance direction)
+ * @param yawThe yaw pointing outwards from a portal (in the relative vector's out direction)
* @returnA location relative to this location
*/ public BlockLocation getRelativeLocation(RelativeBlockVector relativeVector, double yaw) { Vector realVector = DirectionHelper.getCoordinateVectorFromRelativeVector(relativeVector.getRight(), - relativeVector.getDepth(), relativeVector.getDistance(), yaw); + relativeVector.getDown(), relativeVector.getOut(), yaw); return makeRelativeBlockLocation(realVector.getBlockX(), realVector.getBlockY(), realVector.getBlockZ()); } /** * Makes a location relative to the current location according to given parameters * - *The distance goes in the direction of the yaw. Right goes in the direction of (yaw - 90) degrees. + *
Out goes in the direction of the yaw. Right goes in the direction of (yaw - 90) degrees. * Depth goes downwards following the -y direction.
* * @param rightThe amount of blocks to go right when looking towards a portal
- * @param depthThe amount of blocks to go downwards when looking towards a portal
- * @param distanceThe amount of blocks to go outwards when looking towards a portal
+ * @param downThe amount of blocks to go downwards when looking towards a portal
+ * @param outThe amount of blocks to go outwards when looking towards a portal
* @param portalYawThe yaw when looking out from the portal
* @return A new location relative to this block location */ - public Location getRelativeLocation(double right, double depth, double distance, float portalYaw) { - Vector realVector = DirectionHelper.getCoordinateVectorFromRelativeVector(right, depth, distance, portalYaw); + public Location getRelativeLocation(double right, double down, double out, float portalYaw) { + Vector realVector = DirectionHelper.getCoordinateVectorFromRelativeVector(right, down, out, portalYaw); return makeRelativeLocation(0.5 + realVector.getBlockX(), realVector.getBlockY(), 0.5 + realVector.getBlockZ(), portalYaw); } diff --git a/src/main/java/net/knarcraft/stargate/container/RelativeBlockVector.java b/src/main/java/net/knarcraft/stargate/container/RelativeBlockVector.java index 30b23de..932ee84 100644 --- a/src/main/java/net/knarcraft/stargate/container/RelativeBlockVector.java +++ b/src/main/java/net/knarcraft/stargate/container/RelativeBlockVector.java @@ -5,28 +5,33 @@ package net.knarcraft.stargate.container; * *A relative block vector stores a vector relative to some origin. The origin in this plugin is usually the * top-left block of a gate (top-left when looking at the side with the sign). The right is therefore the distance - * from the top-left corner towards the top-right corner. Depth is the distance from the top-left corner to the - * bottom-left corner. Distance is the distance outward from the gate.
+ * from the top-left corner towards the top-right corner. Down is the distance from the top-left corner towards the + * bottom-left corner. Out is the distance outward from the gate. */ public class RelativeBlockVector { private final int right; - private final int depth; - private final int distance; + private final int down; + private final int out; - public enum Property {RIGHT, DEPTH, DISTANCE} + public enum Property {RIGHT, DOWN, OUT} /** * Instantiates a new relative block vector * - * @param rightThe distance to the right relative to the origin
- * @param depthThe distance downward relative to the origin
- * @param distanceThe distance outward relative to the origin
+ *Relative block vectors start from a top-left corner. A yaw is used to orient a relative block vector in the + * "real world". + * In terms of a gate layout, the origin is 0,0. Right is towards the end of the line. Down is to the + * next line. Out is towards the observer.
+ * + * @param rightThe distance rightward relative to the origin
+ * @param downThe distance downward relative to the origin
+ * @param outThe distance outward relative to the origin
*/ - public RelativeBlockVector(int right, int depth, int distance) { + public RelativeBlockVector(int right, int down, int out) { this.right = right; - this.depth = depth; - this.distance = distance; + this.down = down; + this.out = out; } /** @@ -39,11 +44,11 @@ public class RelativeBlockVector { public RelativeBlockVector addToVector(Property propertyToAddTo, int valueToAdd) { switch (propertyToAddTo) { case RIGHT: - return new RelativeBlockVector(this.right + valueToAdd, this.depth, this.distance); - case DEPTH: - return new RelativeBlockVector(this.right, this.depth + valueToAdd, this.distance); - case DISTANCE: - return new RelativeBlockVector(this.right, this.depth, this.distance + valueToAdd); + return new RelativeBlockVector(this.right + valueToAdd, this.down, this.out); + case DOWN: + return new RelativeBlockVector(this.right, this.down + valueToAdd, this.out); + case OUT: + return new RelativeBlockVector(this.right, this.down, this.out + valueToAdd); default: throw new IllegalArgumentException("Invalid relative block vector property given"); } @@ -55,7 +60,7 @@ public class RelativeBlockVector { * @returnThis vector, but inverted
*/ public RelativeBlockVector invert() { - return new RelativeBlockVector(-this.right, -this.depth, -this.distance); + return new RelativeBlockVector(-this.right, -this.down, -this.out); } /** @@ -72,8 +77,8 @@ public class RelativeBlockVector { * * @returnThe distance downward relative to the origin
*/ - public int getDepth() { - return depth; + public int getDown() { + return down; } /** @@ -81,13 +86,13 @@ public class RelativeBlockVector { * * @returnThe distance outward relative to the origin
*/ - public int getDistance() { - return distance; + public int getOut() { + return out; } @Override public String toString() { - return String.format("(right = %d, depth = %d, distance = %d)", right, depth, distance); + return String.format("(right = %d, down = %d, out = %d)", right, down, out); } @Override @@ -99,8 +104,8 @@ public class RelativeBlockVector { return false; } RelativeBlockVector otherVector = (RelativeBlockVector) other; - return this.right == otherVector.right && this.depth == otherVector.depth && - this.distance == otherVector.distance; + return this.right == otherVector.right && this.down == otherVector.down && + this.out == otherVector.out; } } diff --git a/src/main/java/net/knarcraft/stargate/portal/Gate.java b/src/main/java/net/knarcraft/stargate/portal/Gate.java index 31b36c1..0d0c312 100644 --- a/src/main/java/net/knarcraft/stargate/portal/Gate.java +++ b/src/main/java/net/knarcraft/stargate/portal/Gate.java @@ -189,7 +189,7 @@ public class Gate { MapThe yaw here is the direction an observer a the first location has to look to face the second location. - * The yaw is only meant to be calculated for locations with equal x or equal z.
+ * The yaw is only meant to be calculated for locations where both have either the same x value or the same z value. + * Equal locations, or locations with equal x and equal z will throw an exception. * * @param location1The first location, which works as the origin
- * @param location2The second location, which the yaw will point at
- * @returnThe yaw
+ * @param location2The second location, which the yaw will point towards
+ * @returnThe yaw pointing from the first location to the second location
*/ public static float getYawFromLocationDifference(Location location1, Location location2) { Location difference = location1.clone().subtract(location2.clone()); @@ -38,9 +39,11 @@ public final class DirectionHelper { } /** - * Gets a block face given a yaw + * Gets a block face given a yaw value * - * @param yawThe yaw to use
+ *The supplied yaw must be a value such that (yaw mod 90) = 0. If not, an exception is thrown.
+ * + * @param yawThe yaw value to convert
* @returnThe block face the yaw corresponds to
*/ public static BlockFace getBlockFaceFromYaw(double yaw) { @@ -56,15 +59,15 @@ public final class DirectionHelper { } else if (yaw == 270) { return BlockFace.EAST; } else { - throw new IllegalArgumentException("Invalid yaw given"); + throw new IllegalArgumentException("Invalid yaw given. Yaw must be divisible by 90."); } } /** * Gets a direction vector given a yaw * - * @param yawThe yaw to use
- * @returnThe direction vector of the yaw
+ * @param yawThe yaw to convert to a direction vector
+ * @returnThe direction vector pointing in the same direction as the yaw
*/ public static Vector getDirectionVectorFromYaw(double yaw) { //Make sure the yaw is between 0 and 360 @@ -84,37 +87,40 @@ public final class DirectionHelper { } /** - * Moves a location relatively + * Moves a location by the given amounts * - * @param locationThe location to move
- * @param rightThe amount to go right (When looking at the front of a portal)
- * @param depthThe amount to go downward (When looking at the front of a portal)
- * @param distanceThe amount to go outward (When looking a the front of a portal)
+ *The right, down and out work the same as for the relative block vector. Looking a the front of a portal, + * right goes rightwards, down goes downwards and out goes towards the observer.
+ * + * @param locationThe location to start at
+ * @param rightThe amount to go right
+ * @param downThe amount to go downward
+ * @param outThe amount to go outward
* @param yawThe yaw when looking directly outwards from a portal
* @returnA location relative to the given location
*/ - public static Location moveLocation(Location location, double right, double depth, double distance, double yaw) { - return location.add(getCoordinateVectorFromRelativeVector(right, depth, distance, yaw)); + public static Location moveLocation(Location location, double right, double down, double out, double yaw) { + return location.add(getCoordinateVectorFromRelativeVector(right, down, out, yaw)); } /** * Gets a vector in Minecraft's normal X,Y,Z-space from a relative block vector * - * @param rightThe amount of right steps from the top-left origin
- * @param depthThe amount of downward steps from the top-left origin
- * @param distanceThe distance outward from the top-left origin
- * @param yawThe yaw when looking directly outwards from a portal
+ * @param rightThe amount of rightward steps from the top-left origin
+ * @param downThe amount of downward steps from the top-left origin
+ * @param outThe distance outward from the top-left origin
+ * @param yawThe yaw when looking directly outwards from a portal
* @returnA normal vector
*/ - public static Vector getCoordinateVectorFromRelativeVector(double right, double depth, double distance, double yaw) { + public static Vector getCoordinateVectorFromRelativeVector(double right, double down, double out, double yaw) { Vector distanceVector = DirectionHelper.getDirectionVectorFromYaw(yaw); - distanceVector.multiply(distance); + distanceVector.multiply(out); Vector rightVector = DirectionHelper.getDirectionVectorFromYaw(yaw - 90); rightVector.multiply(right); Vector depthVector = new Vector(0, -1, 0); - depthVector.multiply(depth); + depthVector.multiply(down); return distanceVector.add(rightVector).add(depthVector); } diff --git a/src/test/java/net/knarcraft/stargate/RelativeBlockVectorTest.java b/src/test/java/net/knarcraft/stargate/RelativeBlockVectorTest.java index 8310474..f75aefe 100644 --- a/src/test/java/net/knarcraft/stargate/RelativeBlockVectorTest.java +++ b/src/test/java/net/knarcraft/stargate/RelativeBlockVectorTest.java @@ -12,8 +12,8 @@ public class RelativeBlockVectorTest { public void getTest() { RelativeBlockVector relativeBlockVector = new RelativeBlockVector(56, 44, 23); assertEquals(56, relativeBlockVector.getRight()); - assertEquals(44, relativeBlockVector.getDepth()); - assertEquals(23, relativeBlockVector.getDistance()); + assertEquals(44, relativeBlockVector.getDown()); + assertEquals(23, relativeBlockVector.getOut()); } @Test diff --git a/src/test/java/net/knarcraft/stargate/container/BlockLocationTest.java b/src/test/java/net/knarcraft/stargate/container/BlockLocationTest.java index c3cd916..520627a 100644 --- a/src/test/java/net/knarcraft/stargate/container/BlockLocationTest.java +++ b/src/test/java/net/knarcraft/stargate/container/BlockLocationTest.java @@ -27,22 +27,22 @@ public class BlockLocationTest { RelativeBlockVector relativeBlockVector = new RelativeBlockVector(2, 1, 3); BlockLocation relativeLocation1 = startLocation.getRelativeLocation(relativeBlockVector, 0); - //With yaw = 0, going right goes in the x direction, and distance goes in the z direction, while y is decremented + //With yaw = 0, going right goes in the x direction, and out goes in the z direction, while y is decremented BlockLocation targetLocation1 = new BlockLocation(world, 9, 2, 9); Assertions.assertEquals(targetLocation1, relativeLocation1); BlockLocation relativeLocation2 = startLocation.getRelativeLocation(relativeBlockVector, 90); - //With yaw = 90, going right goes in the z direction, and distance goes in the -x direction, while y is decremented + //With yaw = 90, going right goes in the z direction, and out goes in the -x direction, while y is decremented BlockLocation targetLocation2 = new BlockLocation(world, 4, 2, 8); Assertions.assertEquals(targetLocation2, relativeLocation2); BlockLocation relativeLocation3 = startLocation.getRelativeLocation(relativeBlockVector, 180); - //With yaw = 180, going right goes in the -x direction, and distance goes in the -z direction, while y is decremented + //With yaw = 180, going right goes in the -x direction, and out goes in the -z direction, while y is decremented BlockLocation targetLocation3 = new BlockLocation(world, 5, 2, 3); Assertions.assertEquals(targetLocation3, relativeLocation3); BlockLocation relativeLocation4 = startLocation.getRelativeLocation(relativeBlockVector, 270); - //With yaw = 270, going right goes in the -z direction, and distance goes in the x direction, while y is decremented + //With yaw = 270, going right goes in the -z direction, and out goes in the x direction, while y is decremented BlockLocation targetLocation4 = new BlockLocation(world, 10, 2, 4); Assertions.assertEquals(targetLocation4, relativeLocation4); } diff --git a/src/test/java/net/knarcraft/stargate/container/RelativeBlockVectorTest.java b/src/test/java/net/knarcraft/stargate/container/RelativeBlockVectorTest.java index 54613f1..8259b37 100644 --- a/src/test/java/net/knarcraft/stargate/container/RelativeBlockVectorTest.java +++ b/src/test/java/net/knarcraft/stargate/container/RelativeBlockVectorTest.java @@ -8,21 +8,21 @@ public class RelativeBlockVectorTest { @Test public void addToVectorTest() { int right = 5; - int depth = 5; - int distance = 3; + int down = 5; + int out = 3; - RelativeBlockVector relativeBlockVector = new RelativeBlockVector(right, depth, distance); + RelativeBlockVector relativeBlockVector = new RelativeBlockVector(right, down, out); for (int i = 0; i < 1000; i++) { int randomValue = getRandomNumber(); RelativeBlockVector newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.RIGHT, randomValue); - Assertions.assertEquals(new RelativeBlockVector(right + randomValue, depth, distance), newVector); + Assertions.assertEquals(new RelativeBlockVector(right + randomValue, down, out), newVector); - newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.DISTANCE, randomValue); - Assertions.assertEquals(new RelativeBlockVector(right, depth, distance + randomValue), newVector); + newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.OUT, randomValue); + Assertions.assertEquals(new RelativeBlockVector(right, down, out + randomValue), newVector); - newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.DEPTH, randomValue); - Assertions.assertEquals(new RelativeBlockVector(right, depth + randomValue, distance), newVector); + newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.DOWN, randomValue); + Assertions.assertEquals(new RelativeBlockVector(right, down + randomValue, out), newVector); } }