Merge branch 'master' of https://github.com/pacien/upem-java-walljHEADmaster

Signed-off-by: pacien <pacien.trangirard@pacien.net>

# Conflicts:
#	src/main/java/fr/umlv/java/wallj/viewer/ScreenManager.java

3 files changed, 49 insertions, 39 deletions

diff --git a/src/docs/class.puml b/src/docs/class.puml
index 6b76380..eceb954 100644
--- a/src/docs/class.puml
+++ b/src/docs/class.puml
@@ -1,8 +1,6 @@
 @startuml
 
 skinparam linetype ortho
-skinparam monochrome reverse
-skinparam backgroundColor #FFFFFF
 
 package viewer {
   class Viewer {
diff --git a/src/docs/dev.md b/src/docs/dev.md
index fb3e614..9df3b3f 100644
--- a/src/docs/dev.md
+++ b/src/docs/dev.md
@@ -1,7 +1,7 @@
 ---
 title: "BSc IN S5 / OOP with Java / Wall-J / Wall-J / Devel. notes"
 author: [Pacien TRAN-GIRARD, Adam NAILI]
-date: 2018-01-14
+date: 2018-02-04
 ...
 
 # Preamble
@@ -60,9 +60,9 @@ Their respective properties such as their traversability by the player have been
 Additional constraints on board validity have been added to ensure their correctness during their manipulation in the
 program. Those conditions have been described in the user manual as well.
 
+
 ## Unit testing
 
-_"Sir, the testing?"_, Caroline reminds.
 Most utility, logic functions and algorithms have been covered by automatic unit tests to reduce the risk of
 small-but-yet-critical mistakes and regressions during the development.
 Those automatic tests are ran with the help of the JUnit 5 test framework.
@@ -70,50 +70,65 @@ Those automatic tests are ran with the help of the JUnit 5 test framework.
 Components and modules related to the graphical user interface could not have been easily tested automatically.
 Quality control of such parts of the program have been handled manually.
 
+
 ## Architecture
 
-The architecture of the program is loosely based on the _Model-View-Controller_ pattern, combined with an event-driven
-approach, separating state objects from actions and events handlers.
+The architecture of the program is loosely based on the _Model-View-Controller_ pattern,
+combined with an event-driven approach.
 
-A more complete package and class diagram is attached to this report.
+Input and game generated events are propagated recursively through each sub-module,
+which can return new events to be broadcast on the next tick.
 
-TODO:
+Those events are fed to controller methods which alter their parent state holding object.
 
-- include a simplified diagram here
-- explain event handling and propagation
-- explain why not mailbox/event subscription system
-- explain how it minimizes coupling
-- explain how we can add stuff like a second robot and whatnot
+This architecture ensures a low class coupling while allowing the program to be extended.
+
+\newpage
 
 ## Implementation details
 
-TODO:
+### Physics
+
+This game makes use of the JBox2D physics engine to simulate a physical world.
+Each block is linked to a corresponding JBox2D body which is used to determine its position and detect collisions.
+
+Bomb explosion management uses the physics engine's ray cast feature to determine which garbage blocks are affected by a blast.
+This solution is more realistic than a blast radius-based approach, while being less resource demanding than a particle propagation system.
+
+### Event propagation
+
+Events are broadcast to each and every game entity.
+This simple method has been profiled and validated for the low number of events propagated in this game.
+A more complex mailbox-driven approach has been considered but was not implemented due to its unnecessary complexity and
+the unavailability of a dependency injection framework.
 
-- per-module remarks:
-    - tell who did what in parallel
-    - using a ray tracer for explosions
 
 ## Additional features
 
-None yet.
+None of the suggested additional feature was implemented.
 
-## Notes
+Those could have been easily added as follows:
+
+- Bouncy walls can be added by defining a new block type with a greater restitution coefficient or a custom collision handler.
+- Imploding bombs can be added by defining a new block and a new implosion event types, which would be handled similarly
+to the explosion events with a reversed impulse vector.
+- A timer can be added in the viewer.
 
-TODO:
 
-- complain about Ant, beg for Gradle and dependency management
-- check that zen5 is actually using a double buffer
-- include git commit log?
+## Notes
+
+- Body in the physics engine should have been scaled down.
+- Zen5 could not handle _RETURN_ key events.
+- Zen5 ScreenInfo are not updated after a window resize.
+- Ant is hell. Gradle is better. 
 
 ---
 
 # References
 
-TODO:
-
-- jbox2d, zen5, jdk, ant, junit docs
-- A* on wikipedia
-- common sense
-- https://stackoverflow.com/a/8929199
-- http://thisiswhatiknowabout.blogspot.com/2011/11/hello-world-jbox2d-with-javafx-20.html
-- http://www.iforce2d.net/b2dtut/explosions
+- Javadocs of JBox2D, Zen5, JUnit
+- Documentations of the JDK and the Ant build tool
+- [A* search algorithm article on Wikipedia](https://en.wikipedia.org/wiki/A*_search_algorithm)
+- [JBox2D tutorial request on StackOverflow](https://stackoverflow.com/a/8929199)
+- [Hello World JBox2D with JavaFX 2.0](http://thisiswhatiknowabout.blogspot.com/2011/11/hello-world-jbox2d-with-javafx-20.html)
+- [Box2D C++ tutorials - Explosions](http://www.iforce2d.net/b2dtut/explosions)
diff --git a/src/docs/user.md b/src/docs/user.md
index 8dd78d2..57193ed 100644
--- a/src/docs/user.md
+++ b/src/docs/user.md
@@ -1,7 +1,7 @@
 ---
 title: "BSc IN S5 / OOP with Java / Wall-J / User manual"
 author: [Pacien TRAN-GIRARD, Adam NAILI]
-date: 2018-01-14
+date: 2018-02-04
 ...
 
 # Preamble
@@ -54,7 +54,7 @@ The player controls a robot, dropping bombs whose explosion can push garbage int
 Garbage bounce when colliding other elements such as walls, unexploded bombs or other garbage blocks,
 and disappear of the screen when reaching a garbage can.
 
-The explosion of each of the dropped bombs can be delayed using independent timers.
+The explosion of each of the dropped bombs can be delayed using independent timers, up to 9 seconds.
 The robot must drop exactly 3 bombs on each level.
 
 A stage is considered done once the world has been cleared of all its garbage.
@@ -78,18 +78,16 @@ Robot       Blue disk    /                /
 
 ## Controls
 
-Controls are defined as follows:
-
 Trigger                                 Action
 -------------------------------         -------------------------------------------------------
 Click on a traversable tile             Moves the robot to the pointed location
 `SPACE` on a free tile                  Drops a bomb at the current location
 `SPACE` on a tile with a bomb           Increases the timer of the bomb at the current location
 `S` while controlling the robot         Puts Wall-j into a safe place before activating the bombs
-`R` at any moment                       Restarts the current level if the stage is not cleared or continues to the next one if possible
+`R` at any moment                       Restarts the current level or continues to the next one if solved
 `Q` at any moment                       Exits the game
-*__Note__: The specifications precise that the _RETURN_ button must be used for the bomb management. This key is not defined in the Zen5 library. 
-The *SPACE* key is used in substitution*
+
+
 ## Custom levels
 
 Custom world can be defined by the user in plain text files, each of which containing a single world.
@@ -113,7 +111,6 @@ A world is defined as valid if its blocks fulfill the following criteria:
 * The world must have enough free tiles to contain all droppable bombs.
 
 Only valid worlds can be loaded into the game.
-
 The validity of a world may not guaranty the solvability of the puzzle.
 
 \newpage