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