Renames RelativeBlockVector's right, depth and distance to right, down and out respectively

src/main/java/net/knarcraft/stargate/container/BlockLocation.java

@@ -86,29 +86,29 @@ public class BlockLocation extends Location {
      * Gets a location relative to this block location
      *
      * @param relativeVector <p>The relative block vector describing the relative location</p>
-     * @param yaw            <p>The yaw pointing outwards from a portal (in the relative vector's distance direction)</p>
+     * @param yaw            <p>The yaw pointing outwards from a portal (in the relative vector's out direction)</p>
      * @return <p>A location relative to this location</p>
      */
     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
      *
-     * <p>The distance goes in the direction of the yaw. Right goes in the direction of (yaw - 90) degrees.
+     * <p>Out goes in the direction of the yaw. Right goes in the direction of (yaw - 90) degrees.
      * Depth goes downwards following the -y direction.</p>
      *
      * @param right     <p>The amount of blocks to go right when looking towards a portal</p>
-     * @param depth     <p>The amount of blocks to go downwards when looking towards a portal</p>
+     * @param down      <p>The amount of blocks to go downwards when looking towards a portal</p>
-     * @param distance  <p>The amount of blocks to go outwards when looking towards a portal</p>
+     * @param out       <p>The amount of blocks to go outwards when looking towards a portal</p>
      * @param portalYaw <p>The yaw when looking out from the portal</p>
      * @return A new location relative to this block location
      */
-    public Location getRelativeLocation(double right, double depth, double distance, float portalYaw) {
+    public Location getRelativeLocation(double right, double down, double out, float portalYaw) {
-        Vector realVector = DirectionHelper.getCoordinateVectorFromRelativeVector(right, depth, distance, portalYaw);
+        Vector realVector = DirectionHelper.getCoordinateVectorFromRelativeVector(right, down, out, portalYaw);
         return makeRelativeLocation(0.5 + realVector.getBlockX(), realVector.getBlockY(),
                 0.5 + realVector.getBlockZ(), portalYaw);
     }

src/main/java/net/knarcraft/stargate/container/RelativeBlockVector.java

@@ -5,28 +5,33 @@ package net.knarcraft.stargate.container;
  *
  * <p>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
+ * from the top-left corner towards the top-right corner. Down is the distance from the top-left corner towards the
- * bottom-left corner. Distance is the distance outward from the gate.</p>
+ * bottom-left corner. Out is the distance outward from the gate.</p>
  */
 public class RelativeBlockVector {
 
     private final int right;
-    private final int depth;
+    private final int down;
-    private final int distance;
+    private final int out;
 
-    public enum Property {RIGHT, DEPTH, DISTANCE}
+    public enum Property {RIGHT, DOWN, OUT}
 
     /**
      * Instantiates a new relative block vector
      *
-     * @param right    <p>The distance to the right relative to the origin</p>
+     * <p>Relative block vectors start from a top-left corner. A yaw is used to orient a relative block vector in the
-     * @param depth    <p>The distance downward relative to the origin</p>
+     * "real world".
-     * @param distance <p>The distance outward relative to the origin</p>
+     * 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.</p>
+     *
+     * @param right <p>The distance rightward relative to the origin</p>
+     * @param down  <p>The distance downward relative to the origin</p>
+     * @param out   <p>The distance outward relative to the origin</p>
      */
-    public RelativeBlockVector(int right, int depth, int distance) {
+    public RelativeBlockVector(int right, int down, int out) {
         this.right = right;
-        this.depth = depth;
+        this.down = down;
-        this.distance = distance;
+        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);
+                return new RelativeBlockVector(this.right + valueToAdd, this.down, this.out);
-            case DEPTH:
+            case DOWN:
-                return new RelativeBlockVector(this.right, this.depth + valueToAdd, this.distance);
+                return new RelativeBlockVector(this.right, this.down + valueToAdd, this.out);
-            case DISTANCE:
+            case OUT:
-                return new RelativeBlockVector(this.right, this.depth, this.distance + valueToAdd);
+                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 {
      * @return <p>This vector, but inverted</p>
      */
     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 {
      *
      * @return <p>The distance downward relative to the origin</p>
      */
-    public int getDepth() {
+    public int getDown() {
-        return depth;
+        return down;
     }
 
     /**
@@ -81,13 +86,13 @@ public class RelativeBlockVector {
      *
      * @return <p>The distance outward relative to the origin</p>
      */
-    public int getDistance() {
+    public int getOut() {
-        return distance;
+        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 &&
+        return this.right == otherVector.right && this.down == otherVector.down &&
-                this.distance == otherVector.distance;
+                this.out == otherVector.out;
     }
 
 }

src/main/java/net/knarcraft/stargate/portal/Gate.java

@@ -189,7 +189,7 @@ public class Gate {
         Map<Character, Material> characterMaterialMap = new HashMap<>(this.characterMaterialMap);
         for (RelativeBlockVector borderVector : layout.getBorder()) {
             int rowIndex = borderVector.getRight();
-            int lineIndex = borderVector.getDepth();
+            int lineIndex = borderVector.getDown();
             Character key = layout.getLayout()[lineIndex][rowIndex];
 
             Material materialInLayout = characterMaterialMap.get(key);

src/main/java/net/knarcraft/stargate/portal/PortalCreator.java

@@ -276,7 +276,7 @@ public class PortalCreator {
                                       BlockFace buttonFacing) {
         //Go one block outwards to find the button's location rather than the control block's location
         BlockLocation button = topLeft.getRelativeLocation(buttonVector.addToVector(
-                RelativeBlockVector.Property.DISTANCE, 1), portal.getYaw());
+                RelativeBlockVector.Property.OUT, 1), portal.getYaw());
 
         Directional buttonData = (Directional) Bukkit.createBlockData(portal.getGate().getPortalButton());
         buttonData.setFacing(buttonFacing);

src/main/java/net/knarcraft/stargate/portal/Teleporter.java

@@ -146,7 +146,7 @@ public abstract class Teleporter {
         RelativeBlockVector openingEdge = relativeExit;
         do {
             RelativeBlockVector possibleOpening = new RelativeBlockVector(openingEdge.getRight() + direction,
-                    openingEdge.getDepth(), openingEdge.getDistance());
+                    openingEdge.getDown(), openingEdge.getOut());
             if (portal.getGate().getLayout().getExits().contains(possibleOpening)) {
                 openingEdge = possibleOpening;
             } else {

src/main/java/net/knarcraft/stargate/utility/DirectionHelper.java

@@ -5,7 +5,7 @@ import org.bukkit.block.BlockFace;
 import org.bukkit.util.Vector;
 
 /**
- * This class helps with direction-dependent calculations
+ * This class helps with direction-related calculations
  */
 public final class DirectionHelper {
 
@@ -17,11 +17,12 @@ public final class DirectionHelper {
      * Gets a yaw by comparing two locations
      *
      * <p>The 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.</p>
+     * 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.</p>
      *
      * @param location1 <p>The first location, which works as the origin</p>
-     * @param location2 <p>The second location, which the yaw will point at</p>
+     * @param location2 <p>The second location, which the yaw will point towards</p>
-     * @return <p>The yaw</p>
+     * @return <p>The yaw pointing from the first location to the second location</p>
      */
     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 yaw <p>The yaw to use</p>
+     * <p>The supplied yaw must be a value such that (yaw mod 90) = 0. If not, an exception is thrown.</p>
+     *
+     * @param yaw <p>The yaw value to convert</p>
      * @return <p>The block face the yaw corresponds to</p>
      */
     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 yaw <p>The yaw to use</p>
+     * @param yaw <p>The yaw to convert to a direction vector</p>
-     * @return <p>The direction vector of the yaw</p>
+     * @return <p>The direction vector pointing in the same direction as the yaw</p>
      */
     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 location <p>The location to move</p>
+     * <p>The right, down and out work the same as for the relative block vector. Looking a the front of a portal,
-     * @param right    <p>The amount to go right (When looking at the front of a portal)</p>
+     * right goes rightwards, down goes downwards and out goes towards the observer.</p>
-     * @param depth    <p>The amount to go downward (When looking at the front of a portal)</p>
+     *
-     * @param distance <p>The amount to go outward (When looking a the front of a portal)</p>
+     * @param location <p>The location to start at</p>
+     * @param right    <p>The amount to go right</p>
+     * @param down     <p>The amount to go downward</p>
+     * @param out      <p>The amount to go outward</p>
      * @param yaw      <p>The yaw when looking directly outwards from a portal</p>
      * @return <p>A location relative to the given location</p>
      */
-    public static Location moveLocation(Location location, double right, double depth, double distance, double yaw) {
+    public static Location moveLocation(Location location, double right, double down, double out, double yaw) {
-        return location.add(getCoordinateVectorFromRelativeVector(right, depth, distance, 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 right    <p>The amount of right steps from the top-left origin</p>
+     * @param right <p>The amount of rightward steps from the top-left origin</p>
-     * @param depth    <p>The amount of downward steps from the top-left origin</p>
+     * @param down  <p>The amount of downward steps from the top-left origin</p>
-     * @param distance <p>The distance outward from the top-left origin</p>
+     * @param out   <p>The distance outward from the top-left origin</p>
-     * @param yaw      <p>The yaw when looking directly outwards from a portal</p>
+     * @param yaw   <p>The yaw when looking directly outwards from a portal</p>
      * @return <p>A normal vector</p>
      */
-    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);
     }

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(44, relativeBlockVector.getDown());
-        assertEquals(23, relativeBlockVector.getDistance());
+        assertEquals(23, relativeBlockVector.getOut());
     }
 
     @Test

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);
     }

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 down = 5;
-        int distance = 3;
+        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);
+            newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.OUT, randomValue);
-            Assertions.assertEquals(new RelativeBlockVector(right, depth, distance + randomValue), newVector);
+            Assertions.assertEquals(new RelativeBlockVector(right, down, out + randomValue), newVector);
 
-            newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.DEPTH, randomValue);
+            newVector = relativeBlockVector.addToVector(RelativeBlockVector.Property.DOWN, randomValue);
-            Assertions.assertEquals(new RelativeBlockVector(right, depth + randomValue, distance), newVector);
+            Assertions.assertEquals(new RelativeBlockVector(right, down + randomValue, out), newVector);
         }
     }