[Feature] Add ITrackV2 for complex logic (and bump to 1.3) (#15)

* ref: modernize buildscript and mapping

* feat: add PathingContext for packed data

* ref: add more predefined gauges

* feat: add ITrackV2 for complex pathing logics

* bump version to 1.3

* ref: refactor PathingContext

* ref: add Vec3 getter

* rename WheelData to PathingData

* ref: add comment on roll

* ref: remove Vec3 as it may introduce more unnecessary calculation

* remove final on PathingData

* change visibility of PathingData.position & roll

* Revert "ref: remove Vec3 as it may introduce more unnecessary calculation"

* ref: reconstruct PathingData

* ref: cleanup calculation

* ref: rename

* ref: add back ITrackBlock compat

* ref: rename vanillaPos back to pos

* ref: change return of ITrackV2.getNextPosition to void

* fix prev commit

* docs

Author: Goldenfield192

build.gradle

@@ -1,9 +1,9 @@
-import cam72cam.universalmodcore.Util;
+import cam72cam.universalmodcore.Util
 
 buildscript {
     repositories {
-        jcenter()
-        maven { url = "http://files.minecraftforge.net/maven" }
+        mavenCentral()
+        maven { url = "http://maven.minecraftforge.net/" }
         maven { url = "https://teamopenindustry.cc/maven" }
     }
     dependencies {
@@ -16,7 +16,7 @@ apply plugin: 'net.minecraftforge.gradle.forge'
 apply plugin: 'maven'
 
 
-String baseVersion = "1.2"
+String baseVersion = "1.3"
 if (!"release".equalsIgnoreCase(System.getProperty("target"))) {
     baseVersion += "-" + Util.GitRevision()
 }
@@ -30,15 +30,15 @@ compileJava {
 }
 
 minecraft {
-    version = "1.12.2-14.23.0.2529"
+    version = "1.12.2-14.23.5.2847"
     runDir = "run"
 
     // the mappings can be changed at any time, and must be in the following format.
     // snapshot_YYYYMMDD   snapshot are built nightly.
     // stable_#            stables are built at the discretion of the MCP team.
     // Use non-default mappings at your own risk. they may not always work.
     // simply re-run your setup task after changing the mappings to update your workspace.
-    mappings = "snapshot_20171003"
+    mappings = "stable_39"
     // makeObfSourceJar = false // an Srg named sources jar is made by default. uncomment this to disable.
 }
 

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-2.14-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.5-bin.zip

src/main/java/trackapi/TrackAPI.java

@@ -6,5 +6,5 @@
 public class TrackAPI
 {
     public static final String MODID = "trackapi";
-    public static final String VERSION = "1.2";
+    public static final String VERSION = "1.3";
 }

src/main/java/trackapi/compat/MinecraftRail.java

@@ -6,15 +6,17 @@
 import net.minecraft.util.math.BlockPos;
 import net.minecraft.util.math.Vec3d;
 import net.minecraft.world.World;
-import trackapi.lib.Gauges;
-import trackapi.lib.ITrack;
+import trackapi.lib.*;
 
 import java.util.HashMap;
 import java.util.Map;
 
-public class MinecraftRail implements ITrack {
-	private static Map<EnumRailDirection, Vec3d> vectors = new HashMap<>();
-	private static Map<EnumRailDirection, Vec3d> centers = new HashMap<>();
+/**
+ * Wrapper for vanilla rail
+ */
+public class MinecraftRail implements ITrackV2 {
+	private static final Map<EnumRailDirection, Vec3d> vectors = new HashMap<>();
+	private static final Map<EnumRailDirection, Vec3d> centers = new HashMap<>();
 	static {
 		Vec3d north = new Vec3d(0, 0, 1);
 		Vec3d south = new Vec3d(0, 0, -1);
@@ -46,8 +48,8 @@ public class MinecraftRail implements ITrack {
 	}
 
 
-	private EnumRailDirection direction;
-	private BlockPos pos;
+	private final EnumRailDirection direction;
+	private final BlockPos pos;
 
 	public MinecraftRail(World world, BlockPos pos) {
 		this.pos = pos;
@@ -57,33 +59,37 @@ public MinecraftRail(World world, BlockPos pos) {
 	}
 
 	@Override
-	public double getTrackGauge() {
-		return Gauges.MINECRAFT;
+	public double[] getTrackGauges() {
+		return new double[]{Gauges.MINECRAFT};
 	}
 
 	@Override
-	public Vec3d getNextPosition(Vec3d currentPosition, Vec3d motion) {
-		Vec3d trackMovement = vectors.get(direction);
+	public<D extends PathingData> void getNextPosition(D inputData, Vec3d motion, double gauge) {
+		Vec3d currentPosition = inputData.getPos();
+
+        Vec3d trackMovement = vectors.get(direction);
 		Vec3d trackCenter = centers.get(direction);
 
-		Vec3d posRelativeToCenter = currentPosition.subtractReverse(new Vec3d(pos).add(trackCenter));
-		double distanceToCenter = posRelativeToCenter.lengthVector();
+		Vec3d pos = new Vec3d(this.pos).add(trackCenter);
+		Vec3d posRelativeToCenter = currentPosition.subtractReverse(pos);
+		double distanceToCenter = posRelativeToCenter.length();
 
 		// Determine if trackMovement should be positive or negative as relative to block center
 		boolean trackPosMotionInverted = posRelativeToCenter.distanceTo(trackMovement) < posRelativeToCenter.scale(-1).distanceTo(trackMovement);
 
 		boolean trackMotionInverted = motion.distanceTo(trackMovement) > motion.scale(-1).distanceTo(trackMovement);
 
-		Vec3d newPosition = new Vec3d(pos).add(trackCenter);
-		//Correct new pos to track alignment
-		newPosition = newPosition.add(trackMovement.scale(trackPosMotionInverted ? -distanceToCenter : distanceToCenter));
-		// Move new pos along track alignment
-		newPosition = newPosition.add(trackMovement.scale(trackMotionInverted ? -motion.lengthVector() : motion.lengthVector()));
-		return newPosition;
+		Vec3d newPosition = pos;
+		double factor =
+				//Correct new pos to track alignment
+				(trackPosMotionInverted ? -distanceToCenter : distanceToCenter)
+				//And Move new pos along track alignment
+				+ (trackMotionInverted ? -motion.length() : motion.length());
+		newPosition = newPosition.add(trackMovement.scale(factor));
+		inputData.setPos(newPosition).setRoll(0d);
 	}
 
 	public static boolean isRail(World world, BlockPos pos) {
 		return BlockRailBase.isRailBlock(world, pos);
 	}
-	
 }

src/main/java/trackapi/lib/Gauges.java

@@ -1,13 +1,46 @@
 package trackapi.lib;
 
+/**
+ * Some gauge constants in meters
+ */
 public class Gauges {
 	/**
-	 * US Standard Gauge in meters
+	 * Minecraft Gauge
+	 */
+	public static final double MINECRAFT = 0.632;
+
+	/**
+	 * 2 Foot 6 Inches Narrow Gauge
+	 */
+	public static final double TWO_FOOT_SIX_INCHES = 0.762;
+
+	/**
+	 * 3 Foot Narrow Gauge
+	 */
+	public static final double THREE_FOOT = 0.9144;
+
+	/**
+	 * Meter Gauge
+	 */
+	public static final double METER = 1.000;
+
+	/**
+	 * Cape gauge
+	 */
+	public static final double CAPE = 1.067;
+
+	/**
+	 * US Standard Gauge
 	 */
 	public static final double STANDARD = 1.435;
 
 	/**
-	 * Minecraft Gauge in meters
+	 * Russian Standard Gauge
 	 */
-	public static final double MINECRAFT = 0.632;
+	public static final double RU_STANDARD = 1.524;
+
+	/**
+	 * Brunel Gauge
+	 */
+	public static final double BRUNEL = 2.140;
 }

src/main/java/trackapi/lib/ITrack.java

@@ -7,19 +7,16 @@ public interface ITrack {
 	/**
 	 * The distance between the rails measured in meters
 	 * 
-	 * @see Gauges#STANDARD
-	 * @see Gauges#MINECRAFT
+	 * @see Gauges
 	 */
-	public double getTrackGauge();
+	double getTrackGauge();
 
 	/**
-	 * Used by rolling stock to look up their next position.
+	 * Used by rolling stocks to look up their next position.
 	 * 
-	 * @param currentPosition - Current entity or bogey position
-	 * @param rotationYaw - Current entity rotation in degrees
-	 * @param bogieYaw - Current bogey rotation in degrees (set to rotationYaw if unused)
-	 * @param distance - Distanced traveled in meters
-	 * @return The new position of the entity or bogey
+	 * @param currentPosition Current position of entity or bogey
+	 * @param motion Current velocity of entity or bogey
+	 * @return Next found position on the track
 	 */
-	public Vec3d getNextPosition(Vec3d currentPosition, Vec3d motion);
+	Vec3d getNextPosition(Vec3d currentPosition, Vec3d motion);
 }

src/main/java/trackapi/lib/ITrackBlock.java

@@ -5,27 +5,27 @@
 import net.minecraft.world.World;
 
 /**
- * Compatibility layer for block only tracks
- *
+ * Compatibility layer between <code>ITrack</code> and blocks which only contain tracks
+ * @deprecated Use <code>ITrackV2</code> instead for forward compatibility, instances of this class will only be returned when querying <code>ITrack</code>
  */
+@Deprecated
 public interface ITrackBlock {
 
 	/**
 	 * The distance between the rails measured in meters
 	 * 
-	 * @see Gauges#STANDARD
-	 * @see Gauges#MINECRAFT
+	 * @see Gauges
 	 */
-	public double getTrackGauge(World world, BlockPos pos);
+	double getTrackGauge(World world, BlockPos pos);
 
 	/**
-	 * Used by rolling stock to look up their next position.
-	 * 
-	 * @param currentPosition - Current entity or bogey position
-	 * @param rotationYaw - Current entity rotation in degrees
-	 * @param bogieYaw - Current bogey rotation in degrees (set to rotationYaw if unused)
-	 * @param distance - Distanced traveled in meters
-	 * @return The new position of the entity or bogey
+	 * Used by rolling stock to look up their next position (and related data).
+	 *
+	 * @param world World to query
+	 * @param pos Position of the block
+	 * @param currentPosition Current entity or bogey position
+	 * @param motion Current velocity of entity or bogey
+	 * @return Next found position on the track
 	 */
-	public Vec3d getNextPosition(World world, BlockPos pos, Vec3d currentPosition, Vec3d motion);
+	Vec3d getNextPosition(World world, BlockPos pos, Vec3d currentPosition, Vec3d motion);
 }

src/main/java/trackapi/lib/ITrackV2.java

@@ -0,0 +1,36 @@
+package trackapi.lib;
+
+import net.minecraft.util.math.Vec3d;
+
+public interface ITrackV2 extends ITrack {
+
+    /**
+     * Find available gauges within this track
+     *
+     * @return All available gauges
+     */
+    double[] getTrackGauges();
+
+    /**
+     * Used by rolling stocks to look up their next position and related data
+     * @param inputData Mutable PathingData contains input parameters, like position and roll, and will be overridden with output data
+     * @param motion Current velocity of entity or bogey
+     * @param gauge Gauge of the pathing stock
+     */
+     <D extends PathingData> void getNextPosition(D inputData, Vec3d motion, double gauge);
+
+    //Overrides for forward compatibility, don't use
+    @Override
+    @Deprecated
+    default double getTrackGauge() {
+        return getTrackGauges()[0];
+    }
+
+    @Override
+    @Deprecated
+    default Vec3d getNextPosition(Vec3d currentPosition, Vec3d motion) {
+        PathingData data = new PathingData(currentPosition, 0d);
+        getNextPosition(data, motion, getTrackGauge());
+        return data.getPos();
+    }
+}

src/main/java/trackapi/lib/PathingData.java

@@ -0,0 +1,34 @@
+package trackapi.lib;
+
+import net.minecraft.util.math.Vec3d;
+
+/**
+ * Mutable data storaging object used by stocks to query data
+ */
+public class PathingData {
+    private Vec3d pos;
+    private double roll;
+
+    public PathingData(Vec3d pos, double roll) {
+        this.pos = pos;
+        this.roll = roll;
+    }
+
+    public Vec3d getPos() {
+        return pos;
+    }
+
+    public PathingData setPos(Vec3d pos) {
+        this.pos = pos;
+        return this;
+    }
+
+    public double getRoll() {
+        return roll;
+    }
+
+    public PathingData setRoll(double roll) {
+        this.roll = roll;
+        return this;
+    }
+}