A bit of Saturday afternoon code cleanup.

Cleaned up the Game Entity code a lot - added comments, moved things to be
in more logical places, and did some other general care. Refs #12,
although this is far from complete. I also got rid of the object cache,
preferring static collections per object type. Need to do some more
caretaking to make sure that you don't accidentally recycle objects of the
wrong type (ie. call GameEntity.RecycleEntity on a ChestEntity), but this
is a start.

I also added a bunch of comments on the Constants file, and removed unused
constants.

Platformer2012/src/ca/kess/games/Constants.java

@@ -1,23 +1,85 @@
 package ca.kess.games;
 
+/**
+ * A list of constants that affect the world.
+ */
 public class Constants {
+    /**
+     * The minimum velocity for something to bounce. This is so that objects don't jitter when bouncing at low velocities.
+     * If after a bounce their velocity would be less than this, it is set to zero.
+     */
     public static final float MINIMUM_BOUNCE_VELOCITY = 4.0f;
+
+    /**
+     * The minimum velocity for something to travel at. This is so that things that are decelerating don't slide slowly.
+     */
     public static final float MINIMUM_GROUND_VELOCITY = 1.0f;
+
+    /**
+     * The minimum velocity for traveling through the air.
+     */
     public static final float MINIMUM_AIR_VELOCITY = 4.0f;
-    public static final float AIR_RESISTENCE = 0.9f;
-    public static final float FRICTION = 0.05f;
+
+    /**
+     * The maximum number of collisions returned when getting all collisions.
+     */
     public static final int MAX_COLLISIONS = 8;
-    public static final int ZOOM_FACTOR = 3;
+
+    /**
+     * How far the camera is zoomed in. ZOOM_FACTOR * TILE_SIZE determines the relative size of a pixel.
+     */
+    public static final int ZOOM_FACTOR = 4;
+
+    /**
+     * The size of a tile, in pixels.
+     */
+    public static final int TILE_SIZE = 8;
+
+    /**
+     * The drag coefficient. The force of drag is determined by DRAG * velocity^2.
+     * In the future, it might be useful for this to be a per entity or even a per tile
+     * property.
+     */
     public static final float DRAG = 1.7f;
+
+    /**
+     * A dummy friction value for all blocks. This is a placeholder until the physics code
+     * is more fleshed out.
+     */
     public static final float DUMMY_FRICTION = 0.8f;
+
+    /**
+     * The maximum force that the a game entity can have affecting it in the X direction. This should be a per entity property.
+     */
     public static final float HERO_MAX_FORCE = 100.0f;
+
+    /**
+     * How much thrust is applied when the hero is jumping.
+     */
     public static final float HERO_JUMP_FORCE = 1000.0f;
+
+    /**
+     * How many (physics) frames the hero can jump for. This should be part of a degrading thrust function
+     * to allow for variable height jumps.
+     */
     public static final int HERO_JUMP_THRUST_FRAMES = 1; //How many frames the player gets a boost for holding the jump key for.
+
+    /**
+     * The force of gravity, in the -Y direction.
+     */
     public static final float GRAVITY = 80.0f;
 
+    /**
+     * The timestep for updating physics.
+     */
     public static final float PHYSICS_DELTA = 1.0f/60.0f;
 
-    public static final String LOG = "mdkess-platformer";
+    /**
+     * How many frames we should skip on. In the update loop, the world physics is updated at a constant rate of 
+     * PHYSICS_DELTA, and then renders. If the frame rate is less than 1 / (SKIP_FRAMES * PHYSICS_DELTA) the game will
+     * stop updating and render, so the game will not freeze. This will cause the game to slow down however.
+     */
     public static final int SKIP_FRAMES = 3;
-	public static final int TILE_SIZE = 8;
+
+    public static final String LOG = "mdkess-platformer";
 }

Platformer2012/src/ca/kess/games/camera/FixedCamera.java

@@ -8,30 +8,26 @@
 import com.badlogic.gdx.graphics.OrthographicCamera;
 import com.badlogic.gdx.graphics.g2d.SpriteBatch;
 import com.badlogic.gdx.math.Matrix4;
-import com.badlogic.gdx.math.Vector2;
 
 public class FixedCamera extends GameCamera {
-	private GameEntity mGameEntity;
-
-	public FixedCamera(OrthographicCamera camera, GameEntity entity) {
-		super(camera);
-		mGameEntity = entity;
-	}
-
-	public final GameEntity getTarget() {
-		return mGameEntity;
-	}
-
-	@Override
-	public void update() {
-        Vector2 pos = mGameEntity.getPosition();
-        getCamera().position.set(pos.x, pos.y, 0);
+    private GameEntity mGameEntity;
+
+    public FixedCamera(OrthographicCamera camera, GameEntity entity) {
+        super(camera);
+        mGameEntity = entity;
+    }
+
+    public final GameEntity getTarget() {
+        return mGameEntity;
+    }
+
+    @Override
+    public void update() {
         getCamera().update();
-
-	}
-
-	@Override
-	public void render(SpriteBatch b, WorldLevel worldLevel) {
+    }
+
+    @Override
+    public void render(SpriteBatch b, WorldLevel worldLevel) {
         float mx = getCamera().position.x;
         float my = getCamera().position.y;
         float width = Gdx.graphics.getWidth()/(8*Constants.ZOOM_FACTOR);
@@ -42,15 +38,15 @@ public void render(SpriteBatch b, WorldLevel worldLevel) {
         int y1 = Math.min((int) (my + height/2), worldLevel.getHeight());
 
         worldLevel.render(b, x0, y0, x1, y1);
-	}
-	
-	@Override
-	public void onResize(int width, int height) {
-		getCamera().setToOrtho(false, width/(Constants.TILE_SIZE*Constants.ZOOM_FACTOR), height/(Constants.TILE_SIZE*Constants.ZOOM_FACTOR));
-	}
-
-	@Override
-	public Matrix4 getCombined() {
-		return getCamera().combined;
-	}
+    }
+
+    @Override
+    public void onResize(int width, int height) {
+        getCamera().setToOrtho(false, width/(Constants.TILE_SIZE*Constants.ZOOM_FACTOR), height/(Constants.TILE_SIZE*Constants.ZOOM_FACTOR));
+    }
+
+    @Override
+    public Matrix4 getCombined() {
+        return getCamera().combined;
+    }
 }

Platformer2012/src/ca/kess/games/camera/MarioCamera.java

@@ -18,19 +18,20 @@ public MarioCamera(OrthographicCamera camera, GameEntity entity, Rectangle area)
 		mArea = area;
 	}
 
+	private Vector2 update_entityPos = new Vector2();
 	@Override
 	public void update() {
 		Vector3 cameraPos = getCamera().position;
-		Vector2 entityPos = getTarget().getPosition();
+		update_entityPos.set(getTarget().getPositionX(), getTarget().getPositionY());
 
 		float f = Constants.ZOOM_FACTOR * Constants.TILE_SIZE;
 		//Transform entity position to screen space.
 		float cameraX = cameraPos.x; //in world space (1 = 1 tile)
 		float cameraY = cameraPos.y;
 
 		//Convert to screen space.
-		float offsetX = (entityPos.x - cameraPos.x)*f;
-		float offsetY = (entityPos.y - cameraPos.y)*f;
+		float offsetX = (update_entityPos.x - cameraPos.x)*f;
+		float offsetY = (update_entityPos.y - cameraPos.y)*f;
 
 		if(offsetX > mArea.width/2) {
 			cameraX += (offsetX - (mArea.width/2))/f;
@@ -44,6 +45,8 @@ public void update() {
 			cameraY += (offsetY + (mArea.height/2))/f;
 		}
 
+		// Also restrict the camera to the visible level, forced to the bottom left if the camera views the entire world.
+
 		getCamera().position.set(cameraX, cameraY, 0);
 		getCamera().update();
 	}

Platformer2012/src/ca/kess/games/entities/ChestEntity.java

@@ -1,8 +1,13 @@
 package ca.kess.games.entities;
 
+import java.util.LinkedList;
+import java.util.Queue;
+
+import ca.kess.games.Constants;
 import ca.kess.games.timers.DeathFadeTimer;
 import ca.kess.games.world.WorldLevel;
 
+import com.badlogic.gdx.Gdx;
 import com.badlogic.gdx.graphics.g2d.Animation;
 
 public class ChestEntity extends GameEntity {
@@ -17,12 +22,23 @@ public enum ChestState {
     ChestState mState;
 
     GameEntity mContents;
-    public ChestEntity() {
+    private ChestEntity() {
 
     }
 
-    public ChestEntity initialize(Animation openAnimation, Animation closedAnimation, WorldLevel worldLevel, float bounciness, GameEntity contents) { 
-        super.initialize(closedAnimation, worldLevel, bounciness);
+    public ChestEntity initialize(WorldLevel worldLevel,
+            float x, float y,
+            float vx, float vy,
+            float width, float height,
+            float mass, float bounciness,
+            Animation openAnimation, Animation closedAnimation, 
+            GameEntity contents) { 
+        super.initialize(worldLevel,
+                x, y,
+                vx, vy,
+                width, height,
+                mass, bounciness,
+                closedAnimation);
         // TODO Auto-generated constructor stub
         mOpenAnimation = openAnimation;
         mClosedAnimation = closedAnimation;
@@ -38,10 +54,52 @@ public void onInteraction(GameEntity other) {
             mState = ChestState.OPEN;
             setVelocityY(15);
             mContents.setVelocityY(30);
-            mContents.getPosition().set(getPosition());
+            mContents.setPosition(getPositionX(), getPositionY());
             getWorld().addEntity(mContents);
             setAnimation(mOpenAnimation);
             getWorld().addTimer(new DeathFadeTimer(this, 1.0f));
         }
     }
+
+
+
+    /**
+     * Some boilerplate code for the internal object pool.
+     */
+    // A list of all uninitialized game entities
+    private static Queue<ChestEntity> sAvailableEntities = new LinkedList<ChestEntity>();
+
+    // Pre-allocate some game entities
+    private static void CreateGameEntities(int num) {
+        Gdx.app.log(Constants.LOG, "ChestEntity::GetGameEntity. Allocating " + num + " entities");
+        for(int i=0; i < num; ++i) {
+            sAvailableEntities.add(new ChestEntity());
+        }
+    }
+
+    // Get an uninitialized game entity. It is the caller's responsibility to initialize it.
+    public static ChestEntity GetChestEntity() {
+        Gdx.app.log(Constants.LOG, "ChestEntity::GetChestEntity. There are " + sAvailableEntities.size() + " available.");
+        if(sAvailableEntities.size() == 0) {
+            Gdx.app.log(Constants.LOG, "No available game entities, creating new ones");
+            CreateGameEntities(100);
+        }
+        return sAvailableEntities.remove();
+    }
+
+    // Put the entity back in the pool.
+    public static void RecycleEntity(ChestEntity entity) {
+        Gdx.app.log(Constants.LOG, "ChestEntity::RecycleEntity");
+        entity.getWorld().removeEntity(entity);
+        entity.recycle(); //marks the entity as initialized.
+        sAvailableEntities.add(entity);
+    }
+
+    // Dispose the object pool for the game entity
+    public static void DisposeObjectPool() {
+        Gdx.app.log(Constants.LOG, "ChestEntity::DisposeObjectPool");
+        for(ChestEntity entity : sAvailableEntities) {
+            entity.dispose();
+        }
+    }
 }