[documentation] Added documentation on tilemaps

docs/SUMMARY.md

@@ -6,7 +6,6 @@
 - [Entities aka Game Objects](entities.md)
     - [Creating Entities](creating-entities.md)
     - [Entity interactions](entity-interactions.md)
-    - [Adding many Entities at once](tilemaps.md)
 - [Handling user input](user-input.md)
 - [Sounds](sounds.md)
 - [Timing things](timing-things.md)

docs/creating-entities.md

@@ -17,3 +17,28 @@ spawn to life, or when it snows.
 
 For such cases, Yaeger provides an `EntitySpawner`, which was designed for
 specifically this case.
+
+## Creating many entities at once, using a `TileMap`
+
+When many entities populate the scene, a `TileMap` can be used to easily
+create them and to let Yaeger calculate the exact location where they should
+be placed.
+
+Imagine the image below should be used multiple times on the scene:
+
+![A tile](images/tile.png),
+
+and should be placed in such a way that we get the following scene:
+
+![A scene with tiles](images/tile-scene.png).
+
+A `TileMap` facilitates this, by defining a two-dimensional array that
+represents the scene and stating which entities should be used. The
+`TileMap` will then calculate the location and size of each entity,
+instantiate them and add them to the scene.
+
+To be able to use a `TileMap`, the scene should implement the interface
+`TileMapContainer`.
+
+
+

docs/entities.md

@@ -28,6 +28,14 @@ lower the value, the closer the entity is placed to the front of the scene.
 
 ## Movement of dynamic entities
 
+Dynamic entities can move around the scene, by setting their motion. This
+movement is applied each GWU, which means the entity moves discretely across the
+scene (as opposed to continuously).
+
+The motion consists of a `direction` and `speed`, which can be set
+individually or together. The `direction` is a double, where the value 0
+denotes downward and 180 logically means upward.
+
 ## Different types of entities
 
 There are several Entities available, which can be divided into four different

src/main/java/com/github/hanyaeger/api/scenes/TileMap.java

@@ -19,12 +19,14 @@
 import java.util.*;
 
 /**
- * A {@link TileMap} encapsulate a two-dimensional map of {@link SpriteEntity}.
+ * A {@code TileMap} encapsulate a two-dimensional map of instances of {@link YaegerEntity}, which should be added to
+ * a {@link YaegerScene}. It is a convenience way to let Yaeger calculate the location and size of each of the entities,
+ * and place them on the scene.
  * <p>
- * By default a {@link TileMap} will assume
- * the full width of the {@link YaegerScene} must be used for placing the tiles.
- * For this, it will require both tiles to be added, as a map to be defined. Based on those, it will automatically
- * calculate the width, height and placement of all tiles.
+ * By default a {@link TileMap} will assume the full width of the {@link YaegerScene} must be used for placing the
+ * tiles. It will require a two dimensional array that represents the scene and sets which entity should be where, and
+ * a list of the actual entities. Of these the classes are required, since the {@code TileMap} itself will create the
+ * instances. It will use the two-dimensional array to calculate the location and size of each entity.
  */
 public abstract class TileMap extends EntitySupplier implements Anchorable, Activatable {
 

src/main/java/com/github/hanyaeger/api/scenes/TileMapContainer.java

@@ -36,7 +36,7 @@ default void initTileMaps() {
      *
      * @param tileMap The {@link TileMap} that should be registered.
      */
-    default void addTileMap(TileMap tileMap) {
+    default void addTileMap(final TileMap tileMap) {
         if (getTileMaps() != null) {
             tileMap.setDimensionsProvider(this);
             getTileMaps().add(tileMap);