GravityModels now take position into account

- Also documented GravityModel

src/main/java/ru/windcorp/progressia/client/graphics/world/LayerWorld.java

@@ -204,7 +204,7 @@ public class LayerWorld extends Layer {
 		}
 
 		Vec3 gravitationalAcceleration = Vectors.grab3();
-		ClientState.getInstance().getWorld().getData().getGravityModel().getGravity(gravitationalAcceleration);
+		ClientState.getInstance().getWorld().getData().getGravityModel().getGravity(entity.getPosition(), gravitationalAcceleration);
 		
 		gravitationalAcceleration.mul(tickLength);
 		entity.getVelocity().add(gravitationalAcceleration);

src/main/java/ru/windcorp/progressia/common/world/GravityModel.java

@@ -17,25 +17,67 @@
  */
 package ru.windcorp.progressia.common.world;
 
+import java.util.Objects;
+
 import glm.vec._3.Vec3;
+import ru.windcorp.progressia.common.util.crash.CrashReports;
 import ru.windcorp.progressia.common.util.namespaces.Namespaced;
 
+/**
+ * Gravity model specifies the gravitational acceleration field. A gravity model may be queried for the vector of gravitational acceleration that should affect an object. This vector is, generally speaking, a function of space: gravity in two different locations may vary. Gravity may also be a zero vector.
+ * 
+ * @author javapony
+ */
 public abstract class GravityModel extends Namespaced {
 	
 	public GravityModel(String id) {
 		super(id);
 	}
 
-	public Vec3 getGravity(Vec3 output) {
+	/**
+	 * Computes the vector of gravitational acceleration at the provided location.
+	 * 
+	 * @param pos the position to compute gravity at
+	 * @param output a {@link Vec3} where the result is stored. May be {@code null}.
+	 * 
+	 * @return the vector of gravitational acceleration. The returned object will match {@code output} parameter is it is non-null.
+	 */
+	public Vec3 getGravity(Vec3 pos, Vec3 output) {
+		Objects.requireNonNull(pos, "pos");
+		
 		if (output == null) {
 			output = new Vec3();
 		}
 		
-		doGetGravity(output);
+		try {
+			doGetGravity(pos, output);
+		} catch (Exception e) {
+			throw CrashReports.report(e, "%s failed to compute gravity at (%d; %d; %d)", this, pos.x, pos.y, pos.z);
+		}
 		
 		return output;
 	}
 	
-	protected abstract void doGetGravity(Vec3 output);
+	/**
+	 * Computes the up direction at the provided location. Up vector is defined as the normalized gravitational acceleration vector or {@code (0; 0; 0)} if there is no gravity. 
+	 * 
+	 * @param pos the position to compute up vector at
+	 * @param output a {@link Vec3} where the result is stored. May be {@code null}.
+	 * 
+	 * @return the up vector. The returned object will match {@code output} parameter is it is non-null.
+	 */
+	public Vec3 getUp(Vec3 pos, Vec3 output) {
+		output = getGravity(pos, output);
+		if (output.any()) output.normalize();
+		return output;
+	}
+	
+	/**
+	 * Computes the gravitational acceleration vector at the provided location. Actual computation of gravity is delegated to this method by the other methods in this class.
+	 * 
+	 * @param pos the position to compute gravity at
+	 * @param output a {@link Vec3} where the result must be stored. Never {@code null}.
+	 */
+	protected abstract void doGetGravity(Vec3 pos, Vec3 output);
 
 }

src/main/java/ru/windcorp/progressia/test/gen/TestGravityModel.java

@@ -27,7 +27,7 @@ public class TestGravityModel extends GravityModel {
 	}
 
 	@Override
-	protected void doGetGravity(Vec3 output) {
+	protected void doGetGravity(Vec3 pos, Vec3 output) {
 		output.set(0, 0, -9.8);
 	}