source:releases/beta/beta_doc/documentation.tex@460

Last change on this file since 460 was 460, checked in by jelinson, 3 years ago

updated beta doc with user test results and use cases

File size: 18.1 KB
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
90\section*{Program 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
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
118\section*{Program Design}
119
121\subsection*{Beta Use Cases}
122Note: \textbf{Bold} steps indicate a separate, hyperlinked use case.\\ \\
124\begin{usecase}
126 \item \hyperlink{playgame}{\textbf{Play Game}}
127\begin{usecase}
128  \item \hyperlink{save}{\textbf{Save Game}}
130\end{usecase}
131
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}}
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
155\end{usecase}
156\hypertarget{turn}{Turn}
157
158\begin{usecase}
160
161\begin{usecase}
164  \item \hyperlink{end turn}{\uc{End Turn}}
165 \item Undo Turn
167\end{usecase}
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}
183\item Display scenes corresponding to event triggered by updated stats
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}
207 \item \hyperlink{updatevisuals}{\uc{Update Visuals}}
208\end{usecase}
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}
294\begin{usecase}
295 \item Prompt player for name
296 \item Load game data of given file name
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}
305\end{usecase}
306\end{usecase}
307
308
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
318\subsection*{Class Diagram}
319\begin{center}
320 %\includegraphics[scale=.45, angle=-90]{rsc/class_diagram.pdf}
321\end{center}
322\phantomsection
324\subsection*{Sequence Diagrams}
325%\begin{center}
327 %\includegraphics[scale=.85, angle=-90]{rsc/playgame.pdf}
328       \subsubsection*{}
330
331  %\includegraphics[scale=.85, angle=-90]{rsc/turn.pdf}
332        \subsubsection*{}
334   %\includegraphics[scale=.85, angle=-90]{rsc/build.pdf}
335         \subsubsection*{}
337
338    %\includegraphics[scale=.85, angle=-90]{rsc/updatevisuals.pdf}
339%\end{center}
340
341\phantomsection
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.\\ \\