#590 add explanation for Game Loop

game-loop/README.md

@@ -9,33 +9,227 @@ tags:
 ---  
   
 ## Intent  
-A game loop runs continuously during gameplay. Each turn of the loop, it processes user input without blocking, updates the game state, and renders the game. It tracks the passage of time to control the rate of gameplay.
+A game loop runs continuously during gameplay. Each turn of the loop, it processes user input without blocking, updates 
+the game state, and renders the game. It tracks the passage of time to control the rate of gameplay.
 
-This pattern decouple the progression of game time from user input and processor speed.
+This pattern decouples progression of game time from user input and processor speed.
 
 ## Applicability  
 This pattern is used in every game engine. 
 
 ## Explanation
-Game loop is the main process of all the game rendering threads. It drives input process, internal status update, rendering, AI and all the other processes. 
+Real world example
 
-There are a lot of implementations of game loop:
+> Game loop is the main process of all the game rendering threads. It's present in all modern games. It drives input process, internal status update, rendering, AI and all the other processes.
 
-- Frame-based game loop
+In plain words
 
-Frame-based game loop is the easiest implementation. The loop always keeps spinning for the following three processes: processInput, update and render. The problem with it is you have no control over how fast the game runs. On a fast machine, that loop will spin so fast users won’t be able to see what’s going on. On a slow machine, the game will crawl. If you have a part of the game that’s content-heavy or does more AI or physics, the game will actually play slower there.
+> Game Loop pattern ensures that game time progresses in equal speed in all different hardware setups. 
 
-- Variable-step game loop
+Wikipedia says
 
-The variable-step game loop chooses a time step to advance based on how much real time passed since the last frame. The longer the frame takes, the bigger steps the game takes. It always keeps up with real time because it will take bigger and bigger steps to get there.
+> The central component of any game, from a programming standpoint, is the game loop. The game loop allows the game to run smoothly regardless of a user's input or lack thereof.
 
-- Fixed-step game loop
+**Programmatic Example**
 
-For fixed-step game loop, a certain amount of real time has elapsed since the last turn of the game loop. This is how much game time need to be simulated for the game’s “now” to catch up with the player’s.
+Let's start with something simple. Here's a bullet that will move in our game. For demonstration it's enough that it has 1-dimensional position.
+
+```java
+public class Bullet {
+
+  private float position;
+
+  public Bullet() {
+    position = 0.0f;
+  }
+
+  public float getPosition() {
+    return position;
+  }
+
+  public void setPosition(float position) {
+    this.position = position;
+  }
+}
+```
+
+GameController is responsible for moving objects in the game. Including the aforementioned bullet.
+
+```java
+public class GameController {
+
+  protected final Bullet bullet;
+
+  public GameController() {
+    bullet = new Bullet();
+  }
+
+  public void moveBullet(float offset) {
+    var currentPosition = bullet.getPosition();
+    bullet.setPosition(currentPosition + offset);
+  }
+
+  public float getBulletPosition() {
+    return bullet.getPosition();
+  }
+}
+```
+
+Now we introduce the game loop. Or actually in this demo we have 3 different game loops.
+
+```java
+public enum GameStatus {
+
+  RUNNING, STOPPED
+}
+
+public abstract class GameLoop {
+
+  protected final Logger logger = LoggerFactory.getLogger(this.getClass());
+
+  protected volatile GameStatus status;
+
+  protected GameController controller;
+
+  private Thread gameThread;
+
+  public GameLoop() {
+    controller = new GameController();
+    status = GameStatus.STOPPED;
+  }
+
+  public void run() {
+    status = GameStatus.RUNNING;
+    gameThread = new Thread(() -> processGameLoop());
+    gameThread.start();
+  }
+
+  public void stop() {
+    status = GameStatus.STOPPED;
+  }
+
+  public boolean isGameRunning() {
+    return status == GameStatus.RUNNING;
+  }
+
+  protected void processInput() {
+    try {
+      var lag = new Random().nextInt(200) + 50;
+      Thread.sleep(lag);
+    } catch (InterruptedException e) {
+      logger.error(e.getMessage());
+    }
+  }
+
+  protected void render() {
+    var position = controller.getBulletPosition();
+    logger.info("Current bullet position: " + position);
+  }
+
+  protected abstract void processGameLoop();
+}
+
+public class FrameBasedGameLoop extends GameLoop {
+
+  @Override
+  protected void processGameLoop() {
+    while (isGameRunning()) {
+      processInput();
+      update();
+      render();
+    }
+  }
+
+  protected void update() {
+    controller.moveBullet(0.5f);
+  }
+}
+
+public class VariableStepGameLoop extends GameLoop {
+
+  @Override
+  protected void processGameLoop() {
+    var lastFrameTime = System.currentTimeMillis();
+    while (isGameRunning()) {
+      processInput();
+      var currentFrameTime = System.currentTimeMillis();
+      var elapsedTime = currentFrameTime - lastFrameTime;
+      update(elapsedTime);
+      lastFrameTime = currentFrameTime;
+      render();
+    }
+  }
+
+  protected void update(Long elapsedTime) {
+    controller.moveBullet(0.5f * elapsedTime / 1000);
+  }
+}
+
+public class FixedStepGameLoop extends GameLoop {
+
+  private static final long MS_PER_FRAME = 20;
+
+  @Override
+  protected void processGameLoop() {
+    var previousTime = System.currentTimeMillis();
+    var lag = 0L;
+    while (isGameRunning()) {
+      var currentTime = System.currentTimeMillis();
+      var elapsedTime = currentTime - previousTime;
+      previousTime = currentTime;
+      lag += elapsedTime;
+
+      processInput();
+
+      while (lag >= MS_PER_FRAME) {
+        update();
+        lag -= MS_PER_FRAME;
+      }
+
+      render();
+    }
+  }
+
+  protected void update() {
+    controller.moveBullet(0.5f * MS_PER_FRAME / 1000);
+  }
+}
+```
+
+Finally we can show all these game loops in action.
+
+```java
+    try {
+      LOGGER.info("Start frame-based game loop:");
+      var frameBasedGameLoop = new FrameBasedGameLoop();
+      frameBasedGameLoop.run();
+      Thread.sleep(GAME_LOOP_DURATION_TIME);
+      frameBasedGameLoop.stop();
+      LOGGER.info("Stop frame-based game loop.");
+
+      LOGGER.info("Start variable-step game loop:");
+      var variableStepGameLoop = new VariableStepGameLoop();
+      variableStepGameLoop.run();
+      Thread.sleep(GAME_LOOP_DURATION_TIME);
+      variableStepGameLoop.stop();
+      LOGGER.info("Stop variable-step game loop.");
+
+      LOGGER.info("Start fixed-step game loop:");
+      var fixedStepGameLoop = new FixedStepGameLoop();
+      fixedStepGameLoop.run();
+      Thread.sleep(GAME_LOOP_DURATION_TIME);
+      fixedStepGameLoop.stop();
+      LOGGER.info("Stop variable-step game loop.");
+      
+    } catch (InterruptedException e) {
+      LOGGER.error(e.getMessage());
+    }
+```
 
 ## Class diagram
 ![alt text](./etc/game-loop.urm.png "Game Loop pattern class diagram")
 
 ## Credits  
-  
 * [Game Programming Patterns - Game Loop](http://gameprogrammingpatterns.com/game-loop.html)
+* [Game Programming Patterns](https://www.amazon.com/gp/product/0990582906/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=0990582906&linkId=1289749a703b3fe0e24cd8d604d7c40b)
+* [Game Engine Architecture, Third Edition](https://www.amazon.com/gp/product/1138035459/ref=as_li_qf_asin_il_tl?ie=UTF8&tag=javadesignpat-20&creative=9325&linkCode=as2&creativeASIN=1138035459&linkId=94502746617211bc40e0ef49d29333ac)