From 3bc1c40642c773a899a7651c407b9ff3246c543d Mon Sep 17 00:00:00 2001 From: pacien Date: Sun, 4 Feb 2018 23:57:21 +0100 Subject: Merge branch 'master' of https://github.com/pacien/upem-java-wallj Signed-off-by: pacien # Conflicts: # src/main/java/fr/umlv/java/wallj/viewer/ScreenManager.java --- src/docs/class.puml | 2 -- src/docs/dev.md | 73 ++++++++++++++++++++++++++++++++--------------------- src/docs/user.md | 13 ++++------ 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 -- cgit v1.2.3