From 1ba6c5935bf395cb74dd6d0fe805152f0fb96f8c Mon Sep 17 00:00:00 2001 From: Pacien TRAN-GIRARD Date: Sun, 1 Jun 2014 19:29:02 +0200 Subject: Update report --- report/document.tex | 4 + report/packages.tex | 36 ++++++ report/progression.tex | 290 ++++++++++++++++++++++++++++--------------------- report/tools.tex | 16 ++- report/userguide.tex | 14 ++- 5 files changed, 230 insertions(+), 130 deletions(-) create mode 100644 report/packages.tex diff --git a/report/document.tex b/report/document.tex index 981ecf3..c3ec4d1 100644 --- a/report/document.tex +++ b/report/document.tex @@ -45,6 +45,10 @@ \cleardoublepage +\input{packages} + +\cleardoublepage + \input{tools} \cleardoublepage diff --git a/report/packages.tex b/report/packages.tex new file mode 100644 index 0000000..dde1d0b --- /dev/null +++ b/report/packages.tex @@ -0,0 +1,36 @@ +\chapter{External packages} + +Some external packages that are not part of the Java Standard Development Kit +were used in this project. + +\section{StretchIcon} + +StretchIcon enables the resize of the Room illustration according to the +window's size in the rich Swing GUI, keeping a correct ratio. + +\section{Guava} + + +\section{Intrinsic Map} + + + +\section{Google Web Toolkit} + + + + + + + + +\section{JSON Simple} + +JSON Simple was used to implement the save and load functionalities by enabling +the serialisation of the game datas into JSON Objects. + +\subsection{rejava.io} + +As some packages required by JSON Simple were not compatible with GWT, +the standard Java StringReader and StringWriter classes were partially +rewritten. diff --git a/report/progression.tex b/report/progression.tex index 0108d2d..cca0477 100644 --- a/report/progression.tex +++ b/report/progression.tex @@ -1,82 +1,72 @@ \chapter{Work progression} -\section{Zuul bad} - - - - - \section{Zuul better v1} \subsection{printLocationInfo} -This code duplication has been previously avoided with the printRoomInfo() -method. -It has been renamed to printLocationInfo(), as part of the commit e52a34789, to -match the exercise. +e52a34789 - This code duplication has been previously avoided with the +printRoomInfo() method. +It has been renamed to printLocationInfo() to match the exercise. \subsection{getExit} -The exit attributes have been made private and a getter was added in commit -53c427ff3. A switch statement has been used instead of multiple if statements. +53c427ff3 - The exit attributes have been made private and a getter has been +added. +A switch statement has been used instead of multiple if statements. \subsection{getExitString} -This method has been added as part of commit ca65af2e2. +ca65af2e2 - This method, which returns a String containing the informations +about the Room's exits, has been added. \subsection{HashMap, setExit} -Room exits are now stored in an HashMap since commit c9d890b9b. The setExits() -method has been replaced by setExit() which takes advantages of the HashMap. +c9d890b9b - Room exits are now stored in an HashMap. The setExits() method has +been replaced by setExit() which takes advantages of the HashMap. \subsection{Vertical direction} -In commit 4145a5e8c, the getExitString() method has been modified to be able to +4145a5e8c - The getExitString() method has been modified to be able to print the availability of the new exits, used in the stairwell at wing 3. Due to the architecture of these rooms, the side exits that were previously settled to link them have been kept. \subsection{keySet ?} -The keySet() method of the class HashMap returns a Set of the keys contained in -the map. +The keySet() method of the class HashMap returns a Set of the keys +associated to values stored in the Map. \subsection{getExitString ?} -The getExitString() method returns a String listing the room's exits. -To achieve that, it iterates through the exits Map's keys, that is a Set of -Strings, appending each one to the String that it returns. +The getExitString() method returns a String listing the Room's exits. +To achieve that, it iterates through the exits Map's keys, which is a Set of +String-s, appending each one to the String that it returns. \subsection{getLongDescription} -The Room class now uses the previously explained getExitString() method and -includes the getLongDescription() method that returns the full description of -the room since commit e510b08d0. - -\subsection{Object diagram} - -%TODO - -\subsubsection{Changes on execution} +e510b08d0 - The Room class now uses the previously explained getExitString() +method and includes the getLongDescription() method that returns the full description of +the room. -%TODO \section{Zuul with features} \subsection{look} -The look command has been added with the commit 698e3cd25. +698e3cd25 - The look command, which prints informations about the current Room, +has been added. \subsection{eat} -The eat command has been added with the commit 40b9b4816. - +40b9b4816 - The eat command, that just prints a special message, has been added. +This command has then been deleted later in the development since it was +useless in the scenario. \section{Zuul better v2} \subsection{showAll, showCommands} -This modifications are part of the commit 79d33230b. +79d33230b - Theses methods have been implemented. \subsection{Adding commands} @@ -86,50 +76,49 @@ the Game class and its processCommand() method. \subsection{getCommandList} -The command list is not printed in the CommandWords class anymore. Instead, this -class returns a String, forwarded by the Parser class, that is then printed in -the Game class, thanks to commit 5f1d0ada2. +5f1d0ada2 - The command list is not printed in the CommandWords class anymore. +Instead, this class returns a String, forwarded by the Parser class, that is +then printed in the Game class. \subsection{Comparison with reference} -The printLocationInfo() method, used only twice, has been trimmed by the commit -590a932e5 and has been replaced by a call to the getLongDescription() method of -the Room class. +590a932e5 - The printLocationInfo() method, used only twice, has been trimmed +and has been replaced by a call to the getLongDescription() method of the Room +class. -A missing getter for the Room description has been added as part of the commit -f84606424. +f84606424 - A missing getter for the Room description has been added. -The loop building the command list String has been modified to use an Iterator -with the commit 0c5793abf. +0c5793abf - The loop building the command list String has been modified to use +an Iterator. \subsection{StringBuilder} -The command list and the exit list are now created using a StringBuilder since -commit ee5ec33aa. This avoids the creation of a new String object at each +ee5ec33aa - The command list and the exit list are now created using a +StringBuilder. This avoids the creation of a new String object at each concatenation, and thus allows better performances. \subsection{Room objects} -Rooms are now stored in an HashMap since commit f64f1ffb0, so they can be -passed to any method in any class. +f64f1ffb0 - Rooms are now stored in an HashMap, so they can be passed to any +method in any class. \section{Zuul with images} \subsection{Game, GameEngine, UserInterface} -The following methods was implemented as part of commit 54e102463. +54e102463 - The methods have been implemented. \subsubsection{Game} The constructor of this class instantiates the GameEngine and the UserInterface, -and set the output of the first to the second. +and sets the output of the first to the second. \subsubsection{GameEngine} This class contains the attributes and methods previously contained in the Game class. -Instead of printing to the standard console output, it prints to the GUI. +Instead of printing to the standard console output, it prints to the Swing GUI. \subsubsection{UserInterface} @@ -140,7 +129,9 @@ interact with them. \subsection{Parser/Scanner} Since commands are entered through a text field instead of the console, the -use of Scanner that read from the standard system input is not required anymore. +use of Scanner that read from the standard system input is not required for the +Swing GUI. + \subsection{addActionListener() and actionPerformed()} @@ -153,10 +144,10 @@ event that happened. \subsection{Add a button} -A help button was added with commit 7f153a4c1. The processCommand() method was -modified to take the command String as parameter instead of reading it only from -the text field, and the actionPerformed() method was modified accordingly to -forward the command. +7f153a4c1 - A help button has been added. The processCommand() method has been +modified to take the command String as a parameter instead of reading it only +from the text field, and the actionPerformed() method has been modified +accordingly to forward the command. \section{Zuul MVC} @@ -178,15 +169,21 @@ program, which are the GameEngine, the Interpret, the Parser and the Performer. They handle the events created by the user's actions and modify the Game model accordingly, refreshing the view to display the new game state. -Several internal modifications in the existing classes were made in order to -separate the logic from the data storage as part of commit bd639caa0. +bd639caa0 - Several internal modifications in the existing classes were made in +order to separate the logic from the data storage. + +Later in the development, it has been found that this pattern is not easily +usable in a language like Java, and has been replaced by a +model-coordinator-view pattern in this project. Then, this pattern faded as some +classes had to implement logical interfaces themselves. However, the view/ui +package has been kept appart. \section{Zuul with items v1} \subsection{Item} -Item support was added as part of commit 3fc06f393. +3fc06f393 - Item support has been added. \subsection{item description} @@ -195,7 +192,8 @@ description from the Item model and ask the View to display it. \subsection{items} -A Room can contain multiple items since commit 04f03d128. +04f03d128 - A Room can now contain multiple items, which are stored in an +HashMap. \subsection{Collection choice} @@ -207,12 +205,12 @@ to perform actions on a particular one (take, drop, use, etc\ldots). \subsection{back} -The back command was implemented as part of commit f218bf5fa. +f218bf5fa - The back command has been implemented. \subsection{back test} The back command works even with any parameter. We will check this later with -"zuul-with-enums". +``zuul-with-enums``. \subsection{back back} @@ -226,7 +224,7 @@ method allows to add and element at the top of the stack and the pop() method allows to retrieve the top item and removes it. A condition checks whether the Stack is empty before calling the pop() method, -so that the program does not throw an Exception. This resolve the case when the +so that the program does not throw an Exception. This solves the case when the player is at the starting point. \section{Zuul with tests} @@ -234,7 +232,7 @@ player is at the starting point. \subsection{tests} In the current version of the game, the outputs of commands such as help or quit -might be easily tested. Furthermore, movement from rooms to rooms, and arising +might be easily tested. Furthermore, movement from Room-s to Room-s, and arising modifications on the model, can also be candidates for testing. \subsubsection{Automatic tests} @@ -243,16 +241,16 @@ Functionalities of the program can be tested automatically using unit testing for classes and methods, and interactive testing to simulate the user's interactions. -Unit tests will later be implemented using the JUnit testing framework. +Unit tests can later be implemented using the JUnit testing framework. User interactions like command input can be simulated by reading and interpreting commands from a text file. \subsection{test command} -The test command was implemented by modifying the Console view with commit -967f40d71. Instead of reading commands from the user's input from the console, -the Scanner reads the commands from a text file. +967f40d71 - The test command has been implemented by modifying the Console view. +Instead of reading commands from the user's input from the console, the Scanner +reads the commands from a text file. This functionnality was not implemented as a command inside the game, but as a command line flag that can be used by executing the program from a terminal with @@ -260,8 +258,8 @@ command line flag that can be used by executing the program from a terminal with \subsubsection{test files} -Three test files were created. The first one tests simple commands such as help -and quit, the second one explores all rooms, and the last one executes all actions +Three test files have been created. The first one tests simple commands such as +help and quit, the second one explores all rooms, and the last one executes all actions to win the game. @@ -269,92 +267,97 @@ to win the game. \subsection{Player} -The current room and the previous rooms were moved from Game to Player with -commit 92f671b84. +92f671b84 - The current Room and the previous Room-s were moved from the Game +class to the Player class. \subsection{take, drop} -The take and drop commands were implemented as part of the commit number -5ddb6df63. An Inventory interface, used by the Room and Player classes, was -added. Items are stored using HashMaps, and a moveItem procedure was added to -the Performer. +5ddb6df63 - The take and drop commands have been implemented. An Inventory +interface, used by the Room and Player classes, was added. Items are stored +using HashMaps, and a moveItem procedure was added to the Performer. \subsection{Carry several items} -Multiple items carrying was already implemented in the commit number 5ddb6df63. +5ddb6df63 - The possibility to carry multiple Item-s was already implemented. \subsection{ItemList} -The ItemList was implemented as the Inventory class in commit number db2c22c9b. +db2c22c9b - The ItemList was implemented as the Inventory class. The Inventory is no longer an interface. \subsection{Maximum weight} -The maximum carryable weight was implement with the commit number b8771ccb2. +b8771ccb2 - The maximum carryable weight has been implement. In order to achieve this, a getTotalWeight() function was added to the Inventory class. \subsection{Inventory} -The player's inventory items listing was implemented with the commit number -a3f6ce16e, using the recently added listing utility class. +a3f6ce16e - The Player's Inventory Item-s listing has been implemented, using +the recently added listing utility class. \subsection{Magic cookie} -Since there are already too many commands, the carryable weight +35ee3b1ee - Since there are already too many commands, the carryable weight expansion was implemented in a smarter way using a negative weight -item in the commit number 35ee3b1ee. +item. We could have instead increased the maximum carryable weight with a setter on the Player class, called by the Performer with the ``eat'' command. \subsection{Tests} -The commands test file was updated in the commit number 7b610fc05. +7b610fc05 - The commands test file was updated. \section{Zuul with enums} \subsection{switch} -The String switch statement was replaced by an enum switch with the -commit number d24dd6cc9. Instead of using an HashMap to match entered Strings to -the corresponding enum value, the valueOf() method was used. +d24dd6cc9 - The String switch statement was replaced by an enum switch. Instead +of using an HashMap to match entered Strings to the corresponding enum value, +the valueOf() method was used. \subsection{help with enum} -The help command now generates the list of the available commands from the enum -with the commit number 159b168b2. +159b168b2 - The help command now generates the list of the available commands +from the enum. \section{Zuul extended} \subsection{Time limit} -The time limit was implemented as a steps limit for the player. When this limit -is reached, the game quits with a message. The argument --challenge is necessary -to enable this game mode. Commit number 2fee72805. +2fee72805 - The limit was implemented as a steps limit for the player. When +this limit is reached, the game quits with a message. +This limit can be activated by initiating a new game using the ``new challenge`` +command. \subsection{GUI} -The actuel GUI will be improved at the end of the project, when all new -functionnalities will be implemented. +The current GUI will be improved at the end of the project, once all new +functionalities will be implemented. \subsection{Trap door} -A TrapDoor was added to link the main map to the off-script map, and all Rooms -are linked through Doors since the commit number 6e388ec78. When crossing a +6e388ec78 - A TrapDoor has been added. When crossing a TrapDoor, the Performer clears the Player's previous Rooms Stack. +It has been used to link the secret corridor of the off-script map to a trap +Room, which can possibly be escaped using the Beamer. + + In later versions, the TrapDoor extends the Door class and implements its +own cross() function, which performs the action the clear the Player's Stack. + \subsection{Beamer} -A Beamer was added with the commit number 6a154d2fe. It can be used once picked -up via the ``use'' command. It alternatively memorises the player's current room +6a154d2fe - A Beamer has been added. It can be used once picked +up via the ``use'' command. It alternatively memorises the Player's current Room and teleports him back. \subsection{Locked door} -A locked door was implement with the commit number e9c61548b. To pass through, -the player needs to pick up a corresponding key. +e9c61548b - A locked door has been added in the off-script area. To pass +through, the player needs to have a corresponding Key in his Inventory. \subsection{Tests} @@ -362,22 +365,28 @@ The test files were updated to fit the last modifications. \subsection{Transporter room} -The transporter was implemented as a sub-type of Door instead of Room, since the -Player has to be transported when he crosses the Door. This is part of the -commit number c5a766345. +c5a766345 - The transporter has been implemented as a sub-type of Door instead +of Room, since the Player has to be transported when he crosses the Door. + +A transporter Room, which is a simple Room that has only TransporterDoor-s, has +then been added in the off-script area. \subsubsection{alea} -c99590be11 - An alea overriding command for the random TransporterDoor was -implemented. It is now possible to force the destination room with this command. +c99590be11 - An ``alea`` overriding command for the random TransporterDoor was +implemented. It is now possible to force the destination Room with this command. \subsection{Character} -3e7f68425 - Characters that can talk were added. +3e7f68425 - Characters that can talk have been added. \subsubsection{Moving character} -Moving characters that can move to adjacent rooms once permitted were added. +Moving characters that can move randomly (WanderingCharacter) or by following +the player's moves (FollowingCharacter) once permitted have been added. + +The MovingCharacter class contains a method moveAll() which is called each time +the player enters a command. \section{Zuul even better} @@ -387,7 +396,7 @@ Moving characters that can move to adjacent rooms once permitted were added. \subsection{Inheritance} Inheritance (and interfaces) was already used for Character-s, Door-s, Item-s, -and View-s since the beginning. +and View-s since the beginning of the project. \subsection{Abstract Command} @@ -397,65 +406,96 @@ The Performer class was replaced by multiple Command sub-types. The code was already organised in packages. +The ``pkg\_'' prefix was NOT used in this project, since it led to +inconsistences with other packages. + \section{Zuul without BlueJ} \subsection{main} +The main() static method has been already implement in the Main class. + \subsection{jar} +An executable .jar archive containing the Game, the manifest file, and some +resources (pictures and musics) is automatically generated at each modification. + \subsection{JApplet} +An init() method has been added to the startup Main class and an HTML file +embedding the applet has been created at /applet.html. + +Since applets are deprecated, an alternative has been implemented (see +\ref{subsec:Better GUI}). \section{Zuul awesome} \subsection{Non-droppable items} -Non-droppable items were added with the commit number ef51d5137. +ef51d5137 - Non-droppable items were added. \subsection{Hidden doors} -Hidden Doors that are not shown as exits were added with the commit number -20c9b8b28. +20c9b8b28 - Hidden Doors that are not shown as exits were added and used to +hide the off-script part of the map. \subsection{Room sides} +Each Room has been divided into four Side-s that have each an corresponding +image and inventory. This makes the Player look at the elements as the main +character, rather than looking by the top, and makes easier for him to navigate +in the map. + +The ``Turn'' has been also added to enable the Player to turn on himself. + \subsection{Quests} +Quests were added to the Game to guide the Player to the predefined goals and to +defines losing and winning situations. + \subsection{Better GUI} +\label{subsec:Better GUI} As applets were designated as deprecated a long time ago, and because newer versions of the Oracle Java Runtime Environment are requiring a mandatory code signing certificate that we can not affors, a new graphical interface using the Google Web Toolkit was implemented. -This set of tools enabled translating the game code from Java to Javascript, +This set of tools enabled translating the game code from Java to JavaScript, allowing its execution directly in the user's browser, without the need of having the Java Runtime Environment installed. -This addition made in commit 12a0686cb was facilitated by the use of the MVC +12a0686cb - This addition was facilitated by the use of the MVC model and required a few changes in the core classes. \subsection{Music} -\subsection{Scenes} +Background musics corresponding to the current Quest were added, using the new +HTML5