root/releases/beta/beta_doc/documentation.tex @ 460

Revision 460, 18.1 KB (checked in by jelinson, 2 years ago)

updated beta doc with user test results and use cases

Line 
1\documentclass[pdftex,12pt,a4paper]{article}
2
3\usepackage[usenames,dvipsnames]{color}
4\usepackage[margin=1in]{geometry}
5\usepackage[pdftex]{graphicx}
6\usepackage[T1]{fontenc}
7\usepackage{amsmath}
8\usepackage{amsthm}
9\usepackage{amsfonts}
10\usepackage{amssymb}
11\usepackage{verbatim}
12\usepackage{mathpazo}
13\usepackage{xfrac}
14\usepackage{ushort}
15\usepackage{algorithmic}
16\usepackage{algorithm}
17\usepackage{hyperref}
18
19\setlength{\parindent}{0pt}
20
21\newcommand{\block}{\mathbb}
22\newcommand{\script}{\mathcal}
23\newcommand{\fancy}{\mathfrak}
24\newcommand{\C}{\block{C}}
25\newcommand{\R}{\block{R}}
26\newcommand{\Z}{\block{Z}}
27\newcommand{\Q}{\block{Q}}
28\newcommand{\N}{\block{N}}
29\newcommand{\I}{^{-1}}
30\newcommand{\set}[2]{\{#1|#2\}}
31\newcommand{\topic}[1]{\noindent{\textbf{#1}}}
32\newcommand{\bij}{\longleftrightarrow}
33\newcommand{\bslash}{\setminus}
34\newcommand{\cl}[1]{\overline{#1}}
35\newcommand{\seq}{\subseteq}
36\newcommand{\ds}{\displaystyle}
37\newcommand{\Wlog}{Without loss of generality }
38\newcommand{\rp}{$(\Rightarrow)$ }
39\newcommand{\lp}{$(\Leftarrow)$ }
40\newcommand{\cbox}[2]{\fcolorbox{#1}{white}{#2}}
41\newcommand{\into}{\ds\bar{\int}}
42\newcommand{\intu}{\ds\ushort{\int}}
43\newcommand{\tx}[1]{\text{#1}}
44
45\renewcommand{\qedsymbol}{\tiny$\blacksquare$}
46%\renewcommand{\labelenumi}{(\alph{enumi})}
47
48\newtheorem{thm}{Theorem}
49\newtheorem{prop}[thm]{Proposition}
50\newtheorem{cor}[thm]{Corollary}
51\newtheorem{lem}[thm]{Lemma}
52
53\theoremstyle{definition}
54\newtheorem{defn}{Definition}
55\newtheorem{ex}{Example}
56\newtheorem{nex}[ex]{Non-Example}
57
58\theoremstyle{remark}
59\newtheorem*{rec}{Recall}
60\newtheorem*{rem}{Remark}
61\newtheorem*{note}{Note}
62\newtheorem*{notate}{Notation}
63\newtheorem*{idea}{Idea}
64\newtheorem*{question}{Question}
65\newenvironment{usecase}{
66\begin{enumerate}
67 \setlength{\itemsep}{.3cm} 
68\setlength{\parskip}{-.25cm}
69\setlength{\parsep}{1cm}}
70{\end{enumerate}}
71\newcommand{\uc}[1]{\textbf{#1}}
72\DeclareMathOperator*{\mesh}{mesh}
73
74
75\begin{document}
76
77%%%%%%%%%%%%%
78%\setlength{\topmargin}{-.9in}
79\newcommand{\HRule}{\rule{\linewidth}{0.4mm}}
80\begin{center}
81\HRule \\
82\textsc{Erin Coughlan, Julius Elinson, Michael Morton, Rebecca Thomas}\\[.1cm]
83\textsc{\Large{TechTrek -- Beta Release Documentation}}\\[-.1cm] % Title
84\HRule \\[.4cm]
85\end{center}
86%%%%%%%%%%%%%
87\tableofcontents
88\phantomsection
89\addcontentsline{toc}{section}{Program Guide}
90\section*{Program Guide}
91\addcontentsline{toc}{subsection}{Installation Guide}
92\subsection*{Installation Guide}
93The game requires a computer running Windows XP or Windows 7 operating systems. The most recent release of the game should be available from the following website:
94\begin{center}
95 \url{https://www.cs.hmc.edu/trac/cs121sp2012_5/wiki/MostRecentRelease}
96\end{center}
97Upon downloading the file called \verb+beta.zip+, uncompress the folder and place it in a directory of choice. The folder will contain two subfolders called \verb+resources+ and \verb+game+. Go to \verb+\beta\game+ where there will be an executable program named \verb+TechTrek.exe+. Open this program to begin playing the game.\\ \\
98Note that it is important not to rearrange the subdirectories in \verb+beta+. For any troubleshooting, read \verb+TechTrek.exe.log+, which will provide a traceback in the event that the program crashes.
99\phantomsection
100\addcontentsline{toc}{subsection}{User Guide}
101\subsection*{User Guide}
102\subsubsection*{Goals \& Motivation}
103TechTrek casts you, the player, as an intergalactic space traveler whose ship crash lands on an alien planet. Friendly aliens inhabit this world and welcome you. They are impressed by your technology and want to learn more about it. Simultaneously, however, you want to build a new spaceship and return home. Thus, it is your job to introduce the society of aliens to various technologies until you have advanced them enough that they can help you build a spaceship and return home. As you know too well from your experience on Earth, some technologies can have negative consequences on a society, and therefore it is your responsibility to discern between the technologies that should and should not be introduced.
104\subsubsection*{Gameplay \& Instructions}
105To start a new game from the opening menu, click the ``New Game'' button. This will initiate a sequence of introductory images, explaining the background story. Use the ``Next'' and ``Back'' buttons to navigate through this until you arrive at the main screen. The main screen displays a selected landscape of the alien planet, progress bars representing stats in the upper right corner and a tool bar along the left side with various buttons.\\ \\
106The map consists of multiple blocks. Use the left and right arrows (or left and right keys) or the small icons underneath the map to toggle between blocks. When you build something, it will be displayed in the current block, provided there is sufficient space (if not, you will be notified).\\ \\
107The stats represent your progress. The colors indicate that quality of the stat: the brighter green it is, the better; the more red it is, the worse. Thus, for example increasing pollution substantially will cause it to go from green low levels to bright red level. Click on any stat to see the actual numerical value and a brief description of the stat and suggestions on how to improve it. If any of these stats become too bad, you lose. Each building will affect your stats both initially as you first buy them and on subsequent turns.\\ \\
108Use the ``Build'' button on the main screen to open a menu where you can choose 3 categories and navigate to the various items you wish to build. When you click on an item in the menu, a side window will appear with a detailed description, including a message if the building is not yet unlocked. Clicking on ``Build'' in this window will purchase the item, or hit ``Cancel'' to exit. In order to finish the construction, you must click ``End Turn'' for the item to show up on the map.\\ \\
109The ``Research'' buttons allows you to invest in different technologies. In particular, clicking on it will open a window with the different categories you can research.  When you click on an item, a side window will appear with a spinner.  You can use the arrows (or up and down keys) to increase or decrease the amount you want to research, given that you do not exceed the amount of money you have.  Clicking on ``Research'' in this window will research the indicated amount.\\ \\
110Over the course of a given turn, if you make purchases or invest in research that you want to undo, click the ``Undo Turn'' button which will restore the game to the start of the turn.\\ \\
111Click on ``Main Menu'' to start a new game or quit. Later versions will allow saving and loading of games.
112\phantomsection
113\addcontentsline{toc}{subsection}{Disabled Features \& Known Issues}\subsection*{Disabled Features \& Known Issues}
114While all the features have been implemented for the beta release, a number of aesthetic changes still to come will affect the gameplay. In particular, the map images (both the landscapes and buildings) will be redesigned to make the overlap appear more realistic and also to give it a more alien appearance. Additionally, a number of buildings will be added to broaden the amount of buying options throughout the game. Lastly, we will continue to add more heuristics to analyze the game state, which will triggered more scenes. These additions will contribute both to the fun of game and offer more outlets for conveying the education message.\\ \\
115The known bugs are documented in the test report--a separate document that details the testing strategy and the log of tests implemented.
116\phantomsection
117\addcontentsline{toc}{section}{Program Design}
118\section*{Program Design}
119
120\addcontentsline{toc}{subsection}{Use Cases}
121\subsection*{Beta Use Cases}
122Note: \textbf{Bold} steps indicate a separate, hyperlinked use case.\\ \\
123\hypertarget{mainmenu}{Main Menu}\label{mainmenu}
124\begin{usecase}
125\item Show loading scene
126 \item \hyperlink{playgame}{\textbf{Play Game}}
127\begin{usecase}
128  \item \hyperlink{save}{\textbf{Save Game}}
129 \item \hyperlink{load}{\textbf{Load Game}}
130\end{usecase}
131
132 \item \hyperlink{quit}{\textbf{Quit}}
133\end{usecase}
134\hypertarget{playgame}{Play Game}
135\begin{usecase}
136 \item Initialize
137 \item Story
138 \item \hyperlink{tut}{\uc{Tutorial/First Move}}
139 \item \hyperlink{turn}{\uc{Turn}}
140 \item \hyperlink{updatevisuals}{\uc{Update Visuals}}
141 \item Go to 4
142\begin{usecase}
143 \item Rocket build, \uc{Win}*
144 \item Stats exceed thresholds, \uc{Lose}*
145\end{usecase}
146\item End game
147\end{usecase}
148\hypertarget{tut}{Tutorial/First Move}
149\begin{usecase}
150 \item Display instructions and arrow for each button
151 \item Instruct user to research power
152 \item Instruct user to build a windmill
153 \item Instruct user to end turn
154 \item \hyperlink{turn}{\uc{Turn}}
155\end{usecase}
156\hypertarget{turn}{Turn}
157
158\begin{usecase}
159\item \hyperlink{build}{\uc{Build}}
160
161\begin{usecase}
162 \item \hyperlink{research}{\uc{Research}}
163 \item \hyperlink{interact}{\uc{Interact}}
164  \item \hyperlink{end turn}{\uc{End Turn}}
165 \item Undo Turn
166 \item \hyperlink{mainmenu}{\uc{Main Menu}}
167\end{usecase}
168\item \hyperlink{update}{\uc{Update}}
169\item Go to 2
170 \end{usecase}
171 \hypertarget{interact}{Interact}
172\begin{usecase}
173 \item Display message from alien on map
174\begin{usecase}
175\item Display information about building on map
176\item Display information about stats
177\item Toggle between maps
178\end{usecase}
179\end{usecase}
180 \hypertarget{end turn}{End Turn}
181\begin{usecase}
182\item \hyperlink{update}{\uc{Update}}
183\item Display scenes corresponding to event triggered by updated stats
184\item \hyperlink{turn}{\uc{Turn}}
185\end{usecase}
186\hypertarget{research}{Research}
187\begin{usecase}
188 \item Display research menu
189 \item \hyperlink{rt}{\uc{Research Transportation}}
190\begin{usecase}
191 \item \hyperlink{rp}{\uc{Research Power}}
192  \item \hyperlink{rm}{\uc{Research Materials}}
193\end{usecase}
194\end{usecase}
195\hypertarget{build}{Build}
196\begin{usecase}
197 \item Display build menu
198 \item \hyperlink{bt}{\uc{Build Transportation} }
199\begin{usecase}
200 \item \hyperlink{bp}{\uc{Build Power}}
201 \item \hyperlink{bm}{\uc{Build Materials}}
202\end{usecase}
203\end{usecase}
204\hypertarget{update}{Update}
205\begin{usecase}
206 \item \hyperlink{updatestats}{\uc{Update Stats}}
207 \item \hyperlink{updatevisuals}{\uc{Update Visuals}}
208\end{usecase}
209\hypertarget{updatestats}{Update Stats}
210\begin{usecase}
211\item Update each stat based on the one-time cost of the new buildings
212 \item Update each stat based on the continuous cost of existing buildings
213\end{usecase}
214\hypertarget{updatevisuals}{Update Visuals}
215\begin{usecase}
216 \item Update map
217 \item Update stat display
218\end{usecase}
219\hypertarget{rt}{Research Transportation}
220\begin{usecase}
221 \item Display research transportation menu
222 \item Select value with spinner
223 \item Give money to trains; if past threshold, unlock trains
224\begin{usecase}
225 \item Give money to planes; if past threshold, unlock planes
226 \item Give money to spaceship; if past threshold, unlock spaceship
227 \item Back to research
228\end{usecase}
229\item Go to 2
230\end{usecase}
231\hypertarget{rp}{Research Power}
232\begin{usecase}
233 \item Display research power menu
234  \item Select value with spinner
235 \item Give money to wind; if past threshold, unlock windmill
236\begin{usecase}
237 \item Give money to solar panel; if past threshold, unlock solar panels
238 \item Give money to nuclear; if past threshold, unlock nuclear plant
239 \item Back to research
240\end{usecase}
241\item Go to 2
242\end{usecase}
243\hypertarget{rm}{Research Materials}
244\begin{usecase}
245 \item Display research materials menu
246  \item Select value with spinner
247 \item Give money to increased efficiency in mining
248\begin{usecase}
249 \item Back to research
250\end{usecase}
251\item Go to 2
252\end{usecase}
253\hypertarget{bt}{Build Transportation}
254\begin{usecase}
255 \item Display build transportation menu
256 \item Build truck, if requirements met
257\begin{usecase}
258 \item Build train, if unlocked and requirements met
259 \item Build plane, if unlocked and requirements met
260 \item Build spaceship, if unlocked and requirements met
261 \item Back to build menu
262\end{usecase}
263\item Go to 2
264\end{usecase}
265\hypertarget{bp}{Build Power}
266\begin{usecase}
267 \item Display build power menu
268 \item Build windmill, if requirements met
269\begin{usecase}
270 \item Build solar panel, if unlocked and requirements met
271 \item Build nuclear plant, if unlocked and requirements met
272 \item Back to build menu
273\end{usecase}
274\item Go to 2
275\end{usecase}
276\hypertarget{bm}{Build Materials}
277\begin{usecase}
278 \item Display build materials menu
279  \item Build mine, if requirements met
280\begin{usecase}
281
282 \item Back to build menu
283\end{usecase}
284\item Go to 2
285\end{usecase}
286
287\hypertarget{save}{Save Game}
288\begin{usecase}
289 \item Prompt player for name
290 \item Write game data to given file name
291 \item Alert player of successful save
292\end{usecase}
293\hypertarget{load}{Load Game}
294\begin{usecase}
295 \item Prompt player for name
296 \item Load game data of given file name
297 \item \hyperlink{turn}{Turn}
298\end{usecase}
299\hypertarget{quit}{Quit Game}
300\begin{usecase}
301 \item Prompt player to confirm quit
302 \item Program exits
303\begin{usecase}
304 \item \hyperlink{mainmenu}{Main Menu}
305\end{usecase}
306\end{usecase}
307
308
309\addcontentsline{toc}{subsection}{Domain Diagram}
310\subsection*{Domain Diagram}
311Note that the domain diagram portrays only the essential components of the program and hence some smaller classes are not represented explicitly by a particular domain.
312\vspace{-1cm}
313\begin{center}
314 %\includegraphics[scale=.58]{rsc/domain_diagram.pdf}
315\end{center}
316\phantomsection
317\addcontentsline{toc}{subsection}{Class Diagram}
318\subsection*{Class Diagram}
319\begin{center}
320 %\includegraphics[scale=.45, angle=-90]{rsc/class_diagram.pdf}
321\end{center}
322\phantomsection
323\addcontentsline{toc}{subsection}{Sequence Diagrams}
324\subsection*{Sequence Diagrams}
325%\begin{center}
326\addcontentsline{toc}{subsubsection}{Play Game}
327 %\includegraphics[scale=.85, angle=-90]{rsc/playgame.pdf}
328       \subsubsection*{}
329 \addcontentsline{toc}{subsubsection}{Turn}
330
331  %\includegraphics[scale=.85, angle=-90]{rsc/turn.pdf}
332        \subsubsection*{}
333  \addcontentsline{toc}{subsubsection}{Build}
334   %\includegraphics[scale=.85, angle=-90]{rsc/build.pdf}
335         \subsubsection*{}
336   \addcontentsline{toc}{subsubsection}{Update Visuals}
337
338    %\includegraphics[scale=.85, angle=-90]{rsc/updatevisuals.pdf}
339%\end{center}
340
341\phantomsection
342\addcontentsline{toc}{subsection}{UI Test Results}
343\subsection*{User Test Results}
344After a number of user tests with a pre-beta version of our game, we receive an abundance of feedback that we parsed through and selectively decided to implement. We looked for trends among users as well as assessed the potential benefit to the educational message and the fun of the game play for each suggested change or complaint. While we've identified a number of changes we'd like to incorporate, only a subset of them have been implemented for the beta release and the remainder, while pertain mostly to data files or general aesthetics, are set as priorities for the final release.\\ \\
345One common observation is that the program lagged a lot, especially as the player progressed through the game. In particular, clicking ``End Turn'' caused the program to either respond slowly or completely stall. We addressed this by making a number of optimizations and removing some redundancy specifically for expensive operations like file loading and image manipulations.\\ \\
346Another concern brought up was the lack of notifications for certain events and exceptions. For example, users complained that ``Undo Turn'' was unclear because it can only undo decisions since the beginning of the turn, while they expected it to go as far back as they wanted. To address this, the button now displays an alert either asking the user to confirm their choice or informs them that there is nothing to be undone, explaining why. Similarly, end turn now displays an update about the changes that occurred during the turn. This addressed a concern that it was unclear how resources change throughout the game play. Another complaint was that there was no indication if the current map block doesn't have room for an additional building and thus was added a notification to change the block. Lastly, quitting the game now requests confirmation from the user.\\ \\
347A number of concerns that were brought up were specific to some of the terminology we use. These included the term ``spinner'' for the up and down arrows when researching, calling both the menu and action ``build'' or ``research'' and interchanging food and space. We will consult our liaison and further discuss the best alternatives for the game's vocabulary. Since these are simple changes, they are not reflected in the beta, but will be essential in the final release.\\ \\
348Another piece of feedback was that the build menu was formatted poorly in that a player could not immediately tell what was unlocked and what was the implied sequence of building. These two aesthetic changes indeed would be more conducive to ease of game play and will be incorporated in our final result.\\ \\
349A very common concern expressed by users was that, while the final goal of building a spaceship was clear, they did not know the intermediate, turn-by-turn goals that would get them to final goal. In other words, the game play felt unmotivated and confusing. Given this helpful feedback, we have already implemented a few changes addressing this, along with plans for more. In particular, we have edited some the tutorial text to be more specific and we have added a scene to the end of the tutorial to emphasize the flow of the game play and some of the intermediate goals. This simultaneously addressed a number of complains that the tutorial ends abruptly. Furthermore, we intend have scenes at the end of each turn that remind the player of their broader goal, as well as suggest smaller steps in getting there.\\ \\
350Lastly, a number of users found that the game did not emphasize all the different technologies and found strategies of doing a limited number of actions in order to win as quickly as possible. This has been and will continue to be improved by changing the stats of buildings to make them harder to build by requiring buildings in other categories to be built first as well as increasing the difficulty by changing the building stats and costs. Making the game harder will make it more fun, better emphasize the learning objective and make the resource management seem more realistic.
351\end{document}
Note: See TracBrowser for help on using the browser.