Användarhandledning move test

[AntiTD.git] / report / report.tex

\documentclass[titlepage, a4paper, 12pt]{article}
\usepackage[swedish]{babel}
\usepackage[utf8]{inputenc}
\usepackage{verbatim}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage{parskip}

% SourceCode
\usepackage{listings}
\usepackage{color}

% Include pdf with multiple pages ex \includepdf[pages=-, nup=2x2]{filename.pdf}
\usepackage[final]{pdfpages}
% Place figures where they should be
\usepackage{float}

% SourceCode
\definecolor{keywordcolor}{rgb}{0.5,0,0.75}
\lstset{
  inputencoding=utf8,
  language=Java,
  extendedchars=true,
  basicstyle=\scriptsize\ttfamily,
  stringstyle=\color{blue},
  commentstyle=\color{red},
  numbers=left,
  firstnumber=auto,
  numberblanklines=true,
  stepnumber=1,
  showstringspaces=false,
  keywordstyle=\color{keywordcolor}
  % identifierstyle=\color{identifiercolor}
}

% Float for text
\floatstyle{ruled}
\newfloat{kod}{H}{lop}
\floatname{kod}{Kodsnutt}

% vars
\def\title{AntiTD}
\def\preTitle{Laboration 4}
\def\kurs{Applikationsprogrammering i Java, HT-08}

\def\namn{Andreas Jakobsson}
\def\mail{dit06ajs@cs.umu.se}
\def\namnTva{Anton Johansson}
\def\mailTva{dit06ajn@cs.umu.se}

\def\pathtocode{$\sim$dit06ajn/edu/apjava/lab4}

\def\handledareEtt{Johan Eliasson, johane@cs.umu.se}
\def\handledareTva{Tor Sterner-Johansson, tors@cs.umu.se}
\def\handledareTre{Daniel Henriksson, danielh@cs.umu.se}
\def\handledareFyra{Johan Granberg, johang@cs.umu.se}

\def\inst{datavetenskap}
\def\dokumentTyp{Laborationsrapport}

\begin{document}
\begin{titlepage}
  \thispagestyle{empty}
  \begin{small}
    \begin{tabular}{@{}p{\textwidth}@{}}
      UMEÅ UNIVERSITET \hfill \today \\
      Institutionen för \inst \\
      \dokumentTyp \\
    \end{tabular}
  \end{small}
  \vspace{10mm}
  \begin{center}
    \LARGE{\preTitle} \\
    \huge{\textbf{\kurs}} \\
    \vspace{10mm}
    \LARGE{\title} \\
    \vspace{15mm}
    \begin{large}
      \namn, \mail \\
      \namnTva, \mailTva\\
      \texttt{\pathtocode}
    \end{large}
    \vfill
    \large{\textbf{Handledare}}\\
    \mbox{\large{\handledareTre}}
    \mbox{\large{\handledareTva}}
    \mbox{\large{\handledareEtt}}
    \mbox{\large{\handledareFyra}}
  \end{center}
\end{titlepage}

\newpage
\mbox{}
\vspace{70mm}
\begin{center}
% Dedication goes here
\end{center}
\thispagestyle{empty}
\newpage

\pagestyle{fancy}
\rhead{\today}
\lhead{\footnotesize{\namn, \mail\\\namnTva, \mailTva}}
\chead{}
\lfoot{}
\cfoot{}
\rfoot{}

\cleardoublepage
\newpage
\tableofcontents
\cleardoublepage

\fancyfoot[LE,RO]{\thepage}
\pagenumbering{arabic}

\section{Problemspecifikation}\label{Problemspecifikation}
% Beskriv med egna ord vad uppgiften gick ut på. Är det någonting som
% varit oklart och ni gjort egna tolkningar så beskriv dessa.
Uppgiften för denna laboration är att implementera spelet
\textit{Anti-Tower Defence} i Java. Kortfattat går ett typiskt sådant
spel ut på släppa ut enheter med olika egenskaper på en bana på ett
sådant sätt att de överlever till ett mål på banan. När ett antal
enheter kommit i mål vinner man banan.

Kraven från specifikationen är uppdelade i tre nivåer där den första
nivån är grundnivån. Här ska spelet implementeras med en
uppdateringsfrekvens oberoende av datorns hastighet. Två stycken
enheter med olika egenskaper ska finnas. En bana innehåller zoner där
datorn kan placera ut torn och zoner där enheter kan röra sig. Vid
vinst eller förlust ska användaren ha möjlighet att spela igen eller
att avsluta applikationen. Alla renderingar ska ske med dubbelbuffring
för att undvika flimmer.

I nivå två tillkommer ytterligare krav utöver de i grundnivån. Flera
banor ska finnas och laddas från fil \textit{''levels.xml''}. Denna
fil ska valideras mot en egen specifierad standard. Varje bana ska ha
egna regler för hur många trupper i mål som krävs för att klara
banan. Banor ska kunna ha flera alternativa vägar till mål. Slutligen
ska highscores sparas och visas i applikationen med hjälp av servicen
från laboration 3

I den sista nivån ska banan utökas med ''växlar'' där användaren kan
påverka vilket håll trupperna rör sig i svängar. Dessutom ska enheter
kunna påverkas av zoner de går över genom att zoner implementerar ett
gränssnitt med en metod med t.ex. namnet \textit{landOn()}. En
truppmedlem ska implementeras med egenskapen att den kan lägga ut
teleporterplattor som andra enheter sedan kan landa på och förflyttas
mellan. Till sist ska projektet finnas i JAR-filen \textit{AnitTD.jar}
och gå att köra genom kommandot:
\begin{footnotesize}
        \verb!> java -jar AntiTD.jar!
\end{footnotesize}

Problemspecifikation finns i original på sidan:\\
\begin{footnotesize}
  \verb!http://www.cs.umu.se/kurser/5DV085/HT08/labbar/lab4.html/!
  (kontrollerad 090112) % DONE check
\end{footnotesize}

\subsection{Antaganden om problemspecifikationen}
I samtliga nivåer nämns i originalspecifikationen hur menyradens
funktionalitet ska utvecklas. Specifika riktlinjer ges om hur
menyalternativ ska byta namn beroende på applikationens
tillstånd. Eftersom lösningen som presenteras i denna rapport hanterar
namnbyten för de menyalternativ som för författarna känns relevant,
görs antagandet att detta räcker för att visa att tekniken behärskas.

Vidare nämns ett gränssnitt som innehåller metod \textit{landOn()}. I
denna lösning antas denna metod få förändras enligt tycke, t.ex. genom
att låta metoden ta paramterar.

\section{Användarhandledning}\label{Anvandarhandledning}
% Förklara var programmet och källkoden ligger samt hur man kompilerar,
% startar och använder det. Förklara även översiktligt vad som händer
% när man använder de olika kommandona. Det räcker alltså inte att
% skriva "man skriver 'ant' för att kompilera", utan det måste även ingå
% en liten förklaring om vad som egentligen händer när man kör ant och
% varför det fungerar. Använd Internet eller litteratur för att själva
% ta reda på den information ni tycker känns relevant, dels för
% rapportens skull och dels för er egen. Kom ihåg att skriva tydliga
% (vetenskapliga) referenser!
Nedan följer en beskrivningar om hur spelet kompileras, startas och
används.

\subsection{Att kompilera och starta spelet}
%% TODO servar ...
Alla filer som behövs för att kompilera och köra detta spel ligger på
servrar som tillhandahålls av institutionen för datavetenskap i Umeå i katalogen:\\
\texttt{\pathtocode}

Denna katalog innehåller i sin tur några kataloger:
\begin{itemize}
\item Katalogen \verb!src! innehåller källkoden.
\item Katalogen \verb!test! innehåller testkod.
\item Katalogen \verb!bin! innehåller vid kompilering alla .class
  filer och andra filer, såsom bilder och ljud.
\item Katalogen \verb!lib! innehåller olika bibliotek som behövs för
  att köra och kompilera programmet. En sådan jar-fil är
  \verb!jdom.jar!, som används för att spara och läsa XML-filer. Alla
  andra filer rör sparande av poäng till en webbtjänst, det vill säga
  jar-filer från webbtjänstbiblioteket \textit{Apache
    Axis2}\footnote{http://ws.apache.org/axis2}.
\item Katalogen \verb!doc! innehåller Javadoc API-dokumentation.

\end{itemize}
Följande kommandon förutsätter att programmet \textit{Apache
  Ant}\footnote{http://ant.apache.org/} är installerat. Verktyget
\textit{Ant} är ett byggverktyg som använder sig av specifikationen
lagrad i en XML-fil, oftast \textit{build.xml}, för att automatisera
alla nödvändiga operationen vid kompilering av ett projekt. Detta kan
innefatta all typ av filhantering, det vill säga kopiering,
borttagning och flyttning, men även själva kompileringen av
projektet. Verktyget kan ses som ett specialanpassat skript för att
kompilera hela projekt.

Programmet kompileras med kommandot:\\
\begin{footnotesize}
\verb!salt:~/edu/apjava/lab4> ant!
\end{footnotesize}

Det som händer vid anrop av kommandot ovan är att \textit{Ant} läser
av filen \textit{build.xml} och letar efter standardkommandona att
köra. I det här fallet är det operationerna som är definierade i
XML-elementet \verb!<target />! med attributet
\verb!name="compile"!. Oftast har taggarna i \textit{build.xml}
relativt självförklarande namn, de motsvarar i många fall direkta
kommandon som går att köra i en terminal. Nu ska programmet vara
kompilerat och ligga i katalogen \verb!bin/main!.

\subsection{Att använda det grafiska gränssnittet}
Ett spel startas automatiskt vid start men när som helst kan ett helt
nytt spel startas genom att i menyraden välja \textit{AntiTD} och
därefter \textit{New Game}. I menyn \textit{AntiTD} finns också andra
självförklarande funktioner som \textit{Restart Level, Paus/Resume,
  Mute/unMute} och \textit{Quit}, se skärmdumpar från avsnitt
\ref{Testkorningar}, sida \pageref{Testkorningar}. Till höger om
spelplanen tillhandahålls en kontrollpanel där enheter markeras genom
att klicka på dem i listan. Därefter, kontrollera att en lämplig
startruta är markerad. En markerad startruta visas genom att ett grönt
sträck ritas ut under startrutans bild. Tryck på knappen
\textit{Release Unit} för att nu släppa ut enheten på
banan. Manipulera enhetens frammarsch på banan genom att snurra på
riktningspilarna i kurvor och korsningar. Detta görs genom att klicka
på pilarna och dessa snurrar då runt till nästa giltiga riktning.

\section{Systembeskrivning}\label{Systembeskrivning}
% Beskriv översiktligt hur programmet är uppbyggt och hur det löser
% problemet.

Följande avsnitt beskriver de olika delarna av programmet uppdelat
paketvis med beskrivningar över vad de olika klasserna har för
funktion. Även en kort beskrivning över resurserna programmet använder
när det gäller filer som inte är Java-kod.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/Paintables.pdf}
    \caption{UML klassdiagram}
    \label{fig:image/Paintable}
  \end{center}
\end{figure}

\subsection{Resurser}
Resurser som används av programmet men som inte är Java-filer ligger i
katalogen \verb!src/resources!. Nedan avsnitt beskriver de filer och
mappar som ligger i denna katalog.

\subsubsection{Filen levels.xml}\label{sec:levels.xml}
Filen \textit{levels.xml} innehåller standarduppsättningen av banor
spelet använder. Filen följer schemat \textit{levels.xsd} och kan
exempelvis vara utformad enligt kodsnutt \ref{kod:levels.xml}.

\begin{kod}
  \begin{footnotesize}
\begin{verbatim}
  <level name="MegaMap" unitsToWin="5">
    <towers>
      <tower type="BasicTower" />
      <tower type="BasicTower" />
    </towers>
    <row>
      <square type="BlockedSquare" />
      <square type="StartSquare direction="RIGHT" />
      <square type="PathSquare" />
      <square type="BlockedSquare" />
    </row>
    <row>
      <square type="BlockedSquare" />
      <square type="BlockedSquare" />
      <square type="GoalSquare" />
      <square type="BlockedSquare" />
    </row>
</level>
\end{verbatim}
  \end{footnotesize}
  \caption{Exempel XML}\label{kod:levels.xml}
  \end{kod}

\subsubsection{Filen levels.xsd}\label{sec:levels.xsd}
Filer \textit{levels.xsd} innehåller ett XML-Schema
\footnote{http://www.w3.org/XML/Schema} som definierar hur giltiga
XML-dokument till spelet ska vara utformade. Se kodsnutt
\ref{kod:levels.xml} för exempel på ett giltigt dokument.

\subsubsection{Katalogen sounds}\label{sec:sounds}
Katalogen \textit{sounds} innehåller ljud som spelas upp i spelet.

\subsubsection{Katalogen map-images}\label{sec:map-images}
Katalogen \textit{map-images} innehåller bilder som används av klasser av
typen \textit{MapSquare} (se avsnitt \ref{sec:MapSquare}).

\subsubsection{Katalogen tower-images}\label{sec:tower-images}
Katalogen \textit{tower-images} innehåller bilder som används av klasser
av typen \textit{Tower} (se avsnitt \ref{sec:Tower}).

\subsubsection{Katalogen unit-images}\label{sec:unit-images}
Katalogen \textit{unit-images} innehåller bilder som används av
klasser av typen \textit{Unit} (se avsnitt \ref{sec:Unit}).

\subsection{Paketet se.umu.cs.dit06ajnajs}
Paketet \textit{se.umu.cs.dit06ajnajs} är huvudpaket som används i
programmet. I detta paket ligger de klasser som startar och
kontrollerar körningen av hela programmet. Se diagram i figur
\ref{fig:dit06ajnajs-uml} för en översiktlig beskrivning över hur
klasserna använder varandra.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/mvc.pdf}
    \caption{}
    \label{fig:dit06ajnajs-uml}
  \end{center}
\end{figure}

\subsubsection{AntiTD}\label{sec:AntiTD}
Klassen \textit{AntiTD} används för att en användare ska kunna starta
programmet. Här kan ett argument skickas med vid start som ska hänvisa
till en XML-fil som innehåller information om banorna som ska spelas i
spelet. Om inget argument anges kommer en förinställd fil att
användas, se \textit{levels.xml} sida
\pageref{sec:levels.xml}. XML-filerna ska följa schemat
\textit{levels.xsd}, se sida \pageref{sec:levels.xsd}.

\subsubsection{ATDController}\label{sec:ATDController}
Klassen \textit{ATDController} är programmets huvudklass. Enligt
design-mönstret \textit{Model-View-Controller} motsvarar denna klass
\textit{Controllern}, alltså den klass som kontrollerar hela
programmets exekvering. Från denna klass konstruktor skapas
motsvarande \textit{Model} och \textit{View}. 

Det startas två viktiga trådar när denna klass skapas,
\textit{AnimationThread} och \textit{CreditThread}, se
algoritmbeskrivning på sida \pageref{sec:Algoritmbeskrivning}.

\subsubsection{ATDModel}\label{sec:ATDModel}
Klassen \textit{ATDModel} hanterar informationen som behövs för varje
spel. Här finns en spelare (\textit{Player}), en lista med banor
(\textit{Level}), en lista med alla enheter (\textit{Unit})som är ute
på den aktiva banan, och så vidare. Denna information använder och
ändrar \textit{ATDController} och \textit{ATDView} läser
informationen.

Denna klass agerar som ett mellansteg för informationen som finns
sparade i många av de klasser som finns i de paketen
\textit{se.umu.cs.dit06ajnajs.agent} och
\textit{se.umu.cs.dit06ajnajs.level}. Bland annat finns det metoder
för att lägga till torn och enheter i spelet.

\subsubsection{ATDView}\label{sec:ATDView}
Klassen \textit{ATDView} är spelets grafiska gränssnitt. Här ritas en
komponent ut som innehåller själva spelplanen och ett antal
komponenter för att styra spelets flöde finns. Metoder för att fästa
lyssnare på specifika komponenter finns för att \textit{ATDController}
ska kunna fästa lyssnare på dem.

Metoder för att rita om spelplanen finns tillgängliga för att
\textit{ATDController} ska kunna uppdatera gränssnittet efter varje
uppdatering av speldatan.

\subsubsection{Paintable}\label{sec:Paintable}
Gränssnittet \textit{Paintable} ska implementeras av allt som ska
kunna ritas upp på spelplanen. Detta görs då med metoden
\textit{paint(Graphics g)}.

\subsubsection{Clickable}\label{sec:Clickable}
Gränssnittet \textit{Clickable}, är ett gränssnitt med metod
\textit{click()}. Instanser av \textit{Clickable} reagerar på
metodanropet på olika sätt beroende på implementation.

\subsubsection{Player}\label{sec:Player}
Klassen \textit{Player} representerar en spelare av spelate. Här
sparas poäng, krediter och vilken nivån användaren spelar.

\subsection{Paketet se.umu.cs.dit06ajnajs.agent}
Klasserna i paket \textit{dit06ajnajs.agent} representerar agenter i
spelet som ska kunna agera på kartan. Se klassdiagrammet i figur
\ref{fig:agent-uml} för en överblick hur de olika agentera beror av
varandra.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/agent.pdf}
    \caption{}
    \label{fig:agent-uml}
  \end{center}
\end{figure}

\subsubsection{Agent}\label{sec:Agent}
Gränssnittet \textit{Agent}, implementeras av alla klasser som ska
agera under spelets gång, detta gäller för närvarande instanser av
underklasser till \textit{Unit} och \textit{Tower}. Gränssnittet
utökar gränssnitten \textit{Paintable}, \textit{Clickable} och
\textit{Cloneable}. Det vill säga varje agent i spelat ska kunna rita
ut sig själv, det ska gå att klicka på dem och det ska gå att klona
dem se avsnitt \ref{sec:AgentPrototypeFactory}.

\subsubsection{AgentPrototypeFactory}\label{sec:AgentPrototypeFactory}
Klassen \textit{AgentPrototypeFactory} används för att skapa instanser
av underklasser till de abstrakta klasserna \textit{Tower} och
\textit{Unit}. Klassen är implementerad enligt designmönstret
\textit{Singleton}, det vill säga det får enbart finnas en instans av
denna klass under programmets körning. För att få tag på denna instans
används den statiska metoden \textit{getInstance()}.

I konstruktorn instansieras och sätts variabler som definierar de
olika enheterna, se beskrivning av \textit{Unit}, sida
\pageref{sec:Unit}, och \textit{Tower}, sida \pageref{sec:Tower}, för
vilka variabler som finns och vad de gör. Detta innebär att det inte
behöver skapas en ny klass för varje ny typ av enhet eller torn som
ska skapas, det går dock alltid att skapa unika beteenden genom att
göra en ny klass som utökar klassen \textit{Unit} och överlagrar någon
av dess metoder, till exempel \textit{act()}.

En positiv effekt som fås genom kloning av enheter är att många av
dess resurser delas för varje enhet. Varje enhet som finns i spelet
har gemensamma referenser till bilder och ljud de ritar upp och
spelar.

\subsubsection{Tower}\label{sec:Tower}
Den abstrakta klassen \textit{Tower} ska utökas av underklasser för
att skapa representationer av torn som ska kunna agera i ett spel. Ett
torn består av ett flertal attribut som kommer att definiera stora
delar av dess utseende och beteende.

Klassen implementerar gränssnitten \textit{Agent},
\textit{Observer}. Torn observerar de rutor av typen
\textit{PathSquare}, som är inom dess räckvid, för att få information
om det kommer enheter (av typen \textit{Unit}) att möjligtvis skjuta
på, se algoritmbeskrivning på sida \pageref{sec:algo-tower}.

Metoder med logik för att flytta enheten finns implementerade, bland
dessa är \textit{act()} och \textit{collision()} viktiga.

\subsubsection{BasicTower}\label{sec:BasicTower}
Klassen \textit{BasicTower} utökar den abstrakta klassen
\textit{Tower} och representerar det enklast möjliga tornet som finns
implementerat i detta spel. Klassen innehåller inga egna
implementationer utan ärver metoderna i \textit{Tower} rakt av.

\subsubsection{Unit}\label{sec:Unit}
Den abstrakta klassen \textit{Unit} ska utökas av underklasser för att
skapa representationer av enheter som ska kunna agera i ett
spel. En enhet består av ett flertal attribut som kommer att definiera
stora delar av dess utseende och beteende. Exempelvis finns en tabell
som innehåller olika bilder för varje rikting enheter har, en annan
tabell innehåller ljud för olika tillfällen.

Viktiga attribut är x- och y-position på kartan, dessa används för att
enheten ska kunna rita ut sig själv på rätt plats. Vid förflyttning av
en enhet ändras x- y-position.

En centerpunkt räknas även ut för varje ändring av x- och
y-position. Denna punkt används bland annat för att räkna avstånd
mellan torn och enhet.

Varje enhet har även metoder för att returnera en rektangel som
definierar dess nuvarande och framtida yttre gränser på en bana. Denna
rektangel används vid kollisionsuträkning se algoritmbeskrivning på
sida \pageref{sec:alog-kollision}.

Metoder med logik för att flytta enheten finns implementerade, bland
dessa är \textit{act()} och \textit{collision()} viktiga.
 % TODO algobeskrivning nånstans här?

\subsubsection{FootmanUnit}\label{sec:FootmanUnit}
Klassen \textit{FootmanUnit} utökar den abstrakta klassen
\textit{Unit} och representerar den enklast möjliga enheten som finns
implementerat i detta spel. Klassen innehåller inga egna
implementationer utan ärver metoderna i \textit{Unit} rakt av.

\subsubsection{Direction}\label{sec:Direction}
Uppräkningen (''Enumeration'') \textit{Direction} innehåller olika
riktningar som är giltiga i spelet. Giltiga värden är \textit{UP,
  DOWN, LEFT, RIGHT, NONE}. Riktningen \textit{NONE} finns med för att
hantera skapande av rutor i banredigeraren som ännu inte har någon
riktning.

\subsection{Paketet se.umu.cs.dit06ajnajs.level}
Paketet \textit{level} innehåller en samling klasser som har en
koppling till en bana i spelet. En bana är uppbyggd utav rutor av
olika karaktär. Se klassdiagram över de olika kartrutorna i figur
\ref{fig:kartrutor-uml}.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/level.pdf}
    \caption{Klassdiagram över kartrutor}
    \label{fig:kartrutor-uml}
  \end{center}
\end{figure}

\subsubsection{Clickable}\label{sec:Clickable}
Gränssnittet \textit{Clickable}, är ett gränssnitt med metod
\textit{click()}. Instanser av \textit{Clickable} reagerar på
metodanropet på olika sätt beroende på implementation.

\subsubsection{Traversable}\label{sec:Traversable}
Gränssnittet \textit{Traversable}, är ett gränssnitt med metod
\textit{landOn()} vilket tar emot en \textit{Unit} som parameter och
manipulerar denna beroende av tillståndet av instansen av
\textit{Traversible}.

\subsubsection{Level}\label{sec:Level}
Klassen \textit{Level}, motsvarar en bana tänkt att användas i ett
rutbaserat spel. Klassen implementerar gränsnitten \textit{Paintable,
  Cloneable, Clickable}. Banan kan alltså bland annat representeras
grafiskt genom \textit{Paintable} och kan reagera på musklick genom
\textit{Clickable}. Klassen innehåller en två-dimensionell lista
vilket innehåller instanser av typen \textit{MapSquare}. Listor finns
även med pekare till de rutor som representerar start- och målrutor.

\subsubsection{MapSquare}\label{sec:MapSquare}
Klassen \textit{Level}, är en abstrakt klass som motsvarar en ruta
tänkt att användas för att kombineras till en bana i ett rutbaserat
spel. Gränsnitten \textit{Paintable, Cloneable, Clickable}
implementeras. Rutan kan alltså bland annat representeras grafiskt
genom \textit{Paintable} och kan reagera på musklick genom
\textit{Clickable}. Dessutom ärver klassen från \textit{Observable}
för att kunna registrera lyssnare som sedan notifieras när en enhet
går på rutan. Ett objekt av typen \textit{MapSquare} kan vara av typen
\textit{PathSquare, TurnSquare, BlockedSquare, TowerSquare,
  BlockedSquare, StartSquare} och \textit{GoalSquare}. Typernas
egenskaper beskrivs nedan.

\subsubsection{MapSquareFactory}\label{sec:MapSquareFactory} 
Klassen \textit{MapSquareFactory}, används för att skapa nya instanser
av olika implementationer av \textit{MapSquareFactory} från en
sträng. Detta för att underlätta skapandet av nya sorters
rutor. Designmönstret \textit{Singelton} implementeras för att
säkerställa att en och endast en instans finns tillgänglig.

\subsubsection{PathSquare}\label{sec:PathSquare}
Klassen \textit{PathSquare}, representerar en vägruta och
implementerar därför gräns\-snittet \textit{Traversible}. Enheter kan
alltså befinna sig och färdas framåt på en ruta av denna typ. Klassen
implementerar designmönstret \textit{Observer/Observable} tillsammans
med klassen \textit{Tower} ur paketet \textit{agent}. När en enhet
anropar en rutas \textit{landOn()}-metod notifieras kringliggande torn
och pekaren till den anropande enheten skickas vidare till tornen (se
\pageref{sec:Tower}).

\subsubsection{TurnSquare}\label{sec:TurnSquare}
Klassen \textit{PathSquare}, representerar en sväng och ärver från
\textit{PathSquare}. Klassen innehåller en lista med giltiga
riktningar samt ett attribut för den nuvarande vald riktning. När en
enhet anropar metoden \textit{landOn()} som kontrollerar om enheten
har passerat mittlinjen av rutan relativt enhetens riktning. Om det är
sant tilldelas enheten rutans nuvarande valda riktning. Metoden
\textit{click()} byter den nuvarande valda riktningen till nästa
giltiga riktning samt roterar bilden till den nya riktningen.

\subsubsection{BlockedSquare}\label{sec:BlockedSquare}
Klassen \textit{PathSquare}, representerar en blockerad ruta. I
nuvarande version innehåller klassen inga implementationer och
fungerar enbart som en utfyllnad.

\subsubsection{TowerSquare}\label{sec:TowerSquare}
Klassen \textit{PathSquare}, representerar en ruta där torn kan
placeras ut. Rutan kan innehålla en referens till ett torn och
markeras då som upptagen.

\subsubsection{StartSquare}\label{sec:StartSquare}
Klassen \textit{PathSquare}, representerar en startruta som enheter
kan släppas ut på. Den innehåller en kö där enheter lagras och släpper
ut en efter en då detta inte skapar kollisioner mellan enheter. En
startruta kan markeras med metoden \textit{click()} och detta sätter
boolean \textit{active} till sann och i den grafiska representationen
läggs en grön ram till runt rutan.

\subsubsection{GoalSquare}\label{sec:GoalSquare}
Klassen \textit{PathSquare}, representerar en målruta där enheter
samlas in % TODO is something lost here?

\subsubsection{NoActiveStartSquareException}\label{sec:NoActiveStartSquareException}
Klassen \textit{NoActiveStartSquareException} är ett undantag som
utökar \textit{RuntimeException}. Detta undantag kan kastas om det
skulle vara så att ingen aktiv startruta är aktiv när en användare
försöker sätta ut en ny enhet.

\subsection{Paketet se.umu.cs.dit06ajnajs.util}
Paketet \textit{se.umu.cs.dit06ajnajs.util} innerhåller främst klasser
för att hantera läsning och skrivning av XML, från och till filerna
där banor sparas. De flesta av dessa klasser är deklarerade som
\textit{final} och innehåller enbart statiska metoder.

\subsubsection{SoundPlayer}\label{sec:SoundPlayer}
Klassen \textit{SoundPlayer} används för att spela upp allt ljud som
finns i spelet. En variabel håller reda på om ljuden ska spelas eller
inte, det vill säga om användaren vill höra ljud till spelet eller om
spelet ska vara helt tyst.

\subsubsection{LevelEditor}\label{sec:LevelEditor}
Klassen \textit{LevelEditor} är ett litet program i sig. Klassen har
en \textit{main(String[]~args)-metod} vilket innebär att den kan
startas. Startas \textit{LevelEditor} kommer ett gränssnitt att visas
där användaren kan välja bland de olika typer av kartrutor (av typen
\textit{MapSquare}) och sedan klicka på en component för att ''rita''
ut och skapa en ny bana. Det finns en knapp \textit{Save map} för att
spara kartan som är gjord. Denna karta sparas till katalogen
\textit{resources} i root-katalogen från vilken programmet körs och
kommer att heta \textit{temp-levels.xml}. För att denna karta ska gå
att använda i spelet måste det läggas till information om vilken
riktning startrutor ska släppa ut nya enheter, hur många enheter som
behövs för vinst och vilka torn som ska finnas vid start.

Denna klass implementerades för att på ett snabbt och enkelt sätt
kunna skapa flera olika kartor till spelet.

\subsubsection{LevelsXMLOutputter}\label{sec:LevelsXMLOutputter}
Klassen \textit{LevelsXMLOutputter} är deklarerad som \textit{final}
och har en statisk metod för att skriva och konvertera en
\textit{Level} (\ref{sec:Level}) till en \textit{java.io.Writer}. I
den nuvarande implementationen sparas inte all nödvändig information
undan, enbart informationen som \textit{LevelEditorn} kan skapa
sparas.

\subsubsection{LevelsXMLParser}\label{sec:LevelsXMLParser}
Klassen \textit{LevelsXMLParser} har två metoder för att tolka
XML-dokument som följer XML-schemat i avsnitt \ref{sec:levels.xsd} och
bygga upp kompletta ban-instanser \textit{Level} (\ref{sec:Level}).

\subsubsection{XMLUtil}\label{sec:XMLUtil}
Klassen \textit{XMLUtil} har metoder för att ladda en fil, via
\textit{java.net.URL} eller \textit{java.io.File}, och returnera ett
validerat dokument, \textit{org.jdom.Document}.

\subsection{Algoritmbeskrivning}\label{sec:Algoritmbeskrivning}
Följande avsnitt förklarar några av algoritmerna som finns
implementerade i spelet i mer detalj.

\subsubsection{Tråden AnimationThread}
Tråden \textit{AnimationThread} är aktiv under hela applikationens
livstid. Följande steg genomförs för varje iteration.

\begin{enumerate}
        \item Starta tidtagning.
        \item Är spelet pausat?
        \begin{itemize}
   \item Om ja, gå till en inre oändlig loop som fortsätter snurra
tills dess att spelet går ur pausläget.
   \item Om nej, gå till nästa steg.
        \end{itemize}
 \item För varje enhet på bana, kontrollera kollisioner och säg till
enhet att agera (se algoritmbeskrivning \textit{Kollisionshantering}
samt algoritmbeskrivning \textit{Enheternas act()}).
        \item Samla upp döda enheter och meddela \textit{ATDController} att
dessa ska tas bort från modellen.
        \item För varje torn på banan, säg till torn att agera (se
algoritmbeskrivning \textit{Tornens act()}).
        \item För varje målruta, samla in enheter och räkna mängden tjänade
krediter.
        \item Är spelet redan vunnit?
        \begin{itemize}
                \item Om ja, gör inget av krediterna och gå vidare.
                \item Om nej, tilldela spelaren (\textit{Player}) krediterna och
gå vidare.
        \end{itemize}
        \item För varje startruta, släpp ut enheter från kö om utsläppet
inte innebär en kollision
        \item För varje \textit{Agent}, anropa dess metod \textit{Paint()}.
        \item Uppdatera spelkomponenten i \textit{ATDView} (se
algoritmbeskrivning \textit{Utritning av spelet}).
        \item Stoppa tidtagning och sov tråden den kvarvarande tiden av det
förinställda tidssteget för att sedan börja om från steg 1.
\end{enumerate}
        


\subsubsection{Tråden CreditThread}
Tråden \textit{CreditThread} är aktiv under hela applikationens
livstid. Följande steg genomförs för varje iteration.

\begin{enumerate}
        \item Är spelet pausat?
        \begin{itemize}
                \item Om ja, gå till en inre oändlig loop som fortsätter snurra
tills dess att spelet går ur pausläget.
                \item Om nej, gå till nästa steg.
        \end{itemize}
        \item Beräkna antalet tjänade krediter genom att kontrollera hur
många enheter som finns ute på spelplanen. Lägg dessa till spelaren
(\textit{Player}).
        \item Är målet för banan uppnått?
        \begin{itemize}
                \item Om ja, sluta räkna poäng och meddela
\textit{ATDController} att banan är avklarad.
                \item Om nej, gå till nästa steg.
        \end{itemize}
        \item Är banan förlorad?
        \begin{itemize}
                \item Om ja, meddela \textit{ATDControllern} att banan är
avklarad.
                \item Om nej, gå till nästa steg.
        \end{itemize}
        \item Sov ett förinställt intervall och börja sedan om.
\end{enumerate}

\subsubsection{Kollisionshantering}\label{sec:alog-kollision}
För att inte enheter ska gå över varandra är kollisionshantering
implementerat. Innan varje enhet rör sig kollas enhetens framtida
position med alla andra enheters nuvarande position för att se om det
kommer att bli någon kollision.

Om det inträffar en kollision och enheterna har motsatt riktning, det
vill säga ena enheten rör sig med riktning \textit{UP} och andra
\textit{DOWN} eller \textit{LEFT} mot \textit{RIGHT}, sätts båda
enheternas riktning till den motsatta de för närvarande färdas i och
första enheten flyttar sig. Om det inträffa kollision där enheterna
inte har motsatt riktning får enheten som kollen gjordes för inte
förflytta sig denna omgång.

% TODO ALgoritm besk vis
\subsubsection{Krediträkning}
I nuläget beräknas spelarens intjänade krediter på ett mycket enkelt
sätt och kan ses som en tillfällig implementation. För varje iteration
i tråden \textit{CreditThread} baseras den intjänade krediten av
antalet enheter på kartan multiplicerat med 10. För varje iteration i
tråden \textit{AnimationThread} samlas enheter in från målrutor och
totala antalet multipliceras med 100.

\subsubsection{Tornens act()}\label{sec:algo-tower}

\subsubsection{Enheternas act()}

\subsubsection{Svängar}

\subsubsection{Utritning av spelet}
Spelplanen ritas ut på en komponent i \textit{ATDView}. Denna
komponent är en inre klass som utökar Javas \textit{JComponent} och är
döpt till \textit{GameComponent}. När denna komponent skapas hämtas en
bild från \textit{ATDModel} och sparas undan i ett attribut.

Metoden \textit{paintComponent(Graphics g)} överlagras för att rita ut
spelet i gräns\-snittet. Vid varje uppdatering av spelplanen körs denna
metod enligt kodsnutt \ref{kod:paintComponent}.

\begin{kod}
  \begin{footnotesize}
\begin{verbatim}
public void paintComponent(Graphics g) {
    logger.fine("paintComponent: " + Thread.currentThread().toString());
    
    // Draw backgroundImage
    g.drawImage(backgroundImage, 0, 0, null);
    
    // Draw gameImage which should contain updated information from
    // Controller
    g.drawImage(gameImage, 0, 0, null);
    
    // Clear gameImage image with a big transparent rectangle.
    Color transparent = new Color(0, 0, 0, 0);
    gameGraphics.setColor(transparent);
    gameGraphics.setComposite(AlphaComposite.Src);
    gameGraphics.fill(new Rectangle2D.Double(0, 0, width, height));
}
\end{verbatim}
  \end{footnotesize}
  \caption{Metoden paintComponent(Graphics g)}\label{kod:paintComponent}
\end{kod}

För att få en uppdaterad bild där alla enheter ritar ut sig själv
sparas tillhörande \textit{Graphics}-objekt som ett attribut i
\textit{ATDView} som sedan kan hämtas av animationstråden för att låta
varje aktuell instans av \textit{Paintable} (se avsnitt
\ref{sec:Paintable} på sida \pageref{sec:Paintable}) rita ut sig själv
på bilden, se kodsnutt \ref{kod:paint}. Nedersta raden,
\verb!view.repaintGame();!, ritar om hela spelkomponenten, se kodsnutt
\ref{kod:paintComponent};

\begin{kod}
  \begin{footnotesize}
\begin{verbatim}
// Repaint all agents
Graphics g = view.getGameGraphics();
for (Unit unit : units) {
    unit.paint(g);
}
for (Tower tower : towers) {
    tower.paint(g);
}

// Refresh the game view
view.repaintGame();
\end{verbatim}
  \end{footnotesize}
  \caption{Utsnitt ur AnimationThread i ATDController}\label{kod:paint}
\end{kod}

\section{Begränsningar}\label{Begransningar}
% Vilka problem och begränsningar har din lösning av uppgiften? Hur
% skulle de kunna rättas till?

% NOTE Antingen skriver vi bara om buggar här och låter icke-uppfyllda specpunkter ligga i diskussion eller så skiver vi båda och låter diskussion ta upp saker vi skulle vilja göra

\section{Reflektioner}\label{Reflektioner}
% Reflektioner - Var det något som var speciellt krångligt? Vilka
% problem uppstod och hur löste ni dem? Vilka verktyg använde ni? Hur
% upplevde ni de verktygen? + Allmänna synpunkter. Om ni har upplevt
% problem på grund av olika miljöer (i termer av operativsystem och
% liknande) så kan det även vara intressant att nämna det, samt motivera
% ert val av miljö.

\section{Testkörningar}\label{Testkorningar}
% Noggranna testkörningar där man ser att programmet fungerar som det
% ska.
I denna sektion presenteras några skärmdumpar från körningar av applikationen.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/ingame1.png}
    \caption{Skärmdump av applikationen}
    \label{fig:ingame1}
  \end{center}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/ingame2.png}
    \caption{Skärmdump av applikationen}
    \label{fig:ingame2}
  \end{center}
\end{figure}

Figur \ref{fig:ingame1} och figur \ref{fig:ingame2} visar hela
applikationen under ett pågående spel.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/promptWinIngame.png}
    \caption{Skärmdump av dialogruta ''Level completed''}
    \label{fig:win}
  \end{center}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/promptLose.png}
    \caption{Skärmdump av dialogruta ''Level lost''}
    \label{fig:lose}
  \end{center}
\end{figure}

Efter att användaren vunnit eller förlorat en bana låses
användargränssnittet och användaren får upp alternativ för fortsatt
spel i dialogrutor så som figur \ref{fig:win} och figur
\ref{fig:lose} visar. Enheter som fortfarande är ute på banan
fortsätter att gå runt och kan dö eller gå i mål. Dock slutar
poängräkningen.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/promptHighscore.png}
    \caption{Skärmdump av dialogruta ''Input highscore''}
    \label{fig:highscore}
  \end{center}
\end{figure}

När inga fler banor finns att spela får användaren möjlighet att
skicka in sin ihoptjänade poäng till en highscore lista. Denna
funktionalitet drivs av en webservice som ingick i den laboration som
gjordes innan denna laboration.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/menu_AntiTD.png}
    \caption{Skärmdump av meny ''AntiTD''}
    \label{fig:menu_antitd}
  \end{center}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/menu_Help.png}
    \caption{Skärmdump av meny ''Help''}
    \label{fig:menu_help}
  \end{center}
\end{figure}

Figur \ref{fig:menu_antitd} och figur \ref{fig:menu_help} visar de
alternativ som döljer sig i menyraden. I figur \ref{fig:menu_antitd}
syns det tredje alternativet \textit{Resume} vilket vid start heter
\textit{Paus} men är nu i ett annat tillstånd eftersom applikationen
vid detta tillfälle var pausat. Detsamma gäller för fjärde
alternativet \textit{unMute} vilket börjar som \textit{Mute}. Figur
\ref{fig:menu_help} visar menyalternativen \textit{Help} och
\textit{About}. Dessa innehåller en kort beskrivning av spelets regler
och mål respektive en kort beskrivning om vilka som skapat
applikationen.

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/leveleditor1.png}
    \caption{Skärmdump ''LevelEditor'', applikationen har just startat}
    \label{fig:editor1}
  \end{center}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/leveleditor2.png}
    \caption{Skärmdump ''LevelEditor'', ''MapSquares'' av typen ''BlockedSquare''}
    \label{fig:editor2}
  \end{center}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/leveleditor3.png}
    \caption{Skärmdump ''LevelEditor'', ''Mapsquares'' av typen ''PathSquare'', ''StartSquare'' och ''GoalSquare''}
    \label{fig:editor3}
  \end{center}
\end{figure}

\begin{figure}[H]
  \begin{center}
    \includegraphics[width=110mm]{images/leveleditor4.png}
    \caption{Skärmdump ''LevelEditor'', ''Mapsquares'' av typen ''TurnSquare''}
    \label{fig:editor4}
  \end{center}
\end{figure}

I figur \ref{fig:editor1} till figur \ref{fig:editor4} visas
skärmdumpar av testapplikationen för att skapa banor. En hel bana har
skapats genom att klicka ut rutor av olika typ.

\section{Diskussion}\label{Diskussion}
% Diskutera om laborationen samt allmänt kring Web services och om hur
% och när det är användbart (och inte användbart). Saker som kan vara
% trevliga att ta upp är interoperabilitet, lite om prestanda, koncepten
% lös koppling och så vidare. Den här sektionen ska vara en betydande
% del av rapporten. Det är upp till er själva att ta reda på den
% information ni behöver, även om föreläsningsmaterialet kan vara
% väldigt användbart. Kom även här ihåg att referera till era källor
% (även om det är från föreläsningsmaterialet).
Projektet är implementerat enligt design-mönstret
\textit{Model-View-Controller}. Resultatet diskuteras under rubriken
\textit{Model-View-Controller}. I detta stadie finns en bra grund för
att lägga till funktionalitet så som nya enheter och nya banrutor med
speciella egenskaper samt att utveckla användargränssnittet. I
nedanstående avsnitt \textit{Vidareutveckling} diskuteras olika
möjligheter till vidareutveckling av spelet.

\subsection{Model-View-Controller}
% TODO Fill this section
Detta projekt har från inledning 

\subsection{Vidareutveckling}
Nedan följer förslag på förändringar för att vidareutveckla spelet.

\subsubsection{Klass Item}
I inledningar av projektet planerades en abstrakt klass \textit{Item}
som skulle representera en pryl vilken skulle kunna lagras i ett
attribut i en MapSquare. Objekt av typen \textit{Item} skulle
t.ex. kunna vara \textit{HealtItem, SpeedItem, CreditItem} som kan
representera prylar som ger mer hälsa, ökad fart respektive ett antal
crediter att handla med. Dessa prylar skulle användas genom att
slumpmässigt läggas till i objekt av typen \textit{PathSquare} och
alltså representeras grafiskt genom att rutan ritar ut prylen ovanpå
sig. En ruta med en pryl på skulle sedan skicka vidare en inkommande
enhets referens till prylen som i sin tur skulle manipulera enhetens
attribut. En pryl med teleporterbeteende diskuteras under rubrik
\textit{Unit av typen TeleportUnit} (se \pageref{TeleportUnit}).

\subsubsection{Unit av typen TeleportUnit}\label{TeleportUnit}
För att uppfylla nivå tre av denna laborations kravspecifikation krävs
en enhet med möjlighet att placera ut så kallade
teleport-plattor. Detta kan uppnås i detta projekt genom att skapa
subklasser av \textit{Item} kallad t.ex. \textit{TeleportStartItem}
och \textit{TeleportEndItem}. Prylen \textit{TeleportStartItem} skulle
kunna bäras av en \textit{Unit} av typen \textit{TeleporterUnit} och
kunna läggas ut på nuvarande ruta genom t.ex. musklick på
enheten. Attribut som behövs i \textit{TeleportStartItem} är x- och
y-koordinater till den tillhörande prylen \textit{TeleportEndItem}
vilket i sin tur innehåller attribut för aktuell riktning som
utsläppta enheter ska ha samt en kö där uppsamlade enheter läggs till
för att sedan släppas ut en efter en då positionen är ledig. Algoritm
för kollisionsdetektering skulle fungera på samma sätt som algoritmen
som används när enheter släpps ut ur startrutor (se
\pageref{sec:StartSquare});

\subsubsection{Gränssnitt}
I nuläget startas första banan direkt när applikationen startar. Att
få se en så kallad splash-screen (introduktionsbild) kan vara önskvärt
och åtgärdas enkelt genom att i konstruktor för \textit{ATDController}
lägga till ett metodanrop till metod i \textit{ATDView} som visar
något och väntar på att användaren ska välja ett nytt spel.

I kontrollpanelen finns stora möjligheter till vidareutveckling då den
nuvarande just täcker den funktionalitet som behövs för att köra
spelet. Till en början skulle listan med tillgängliga units kunna
bytas ut mot ikoner som visar enhetens grafiska representation. För
att lättare kunna få en översikt över en enhets egenskaper skulle
hälsa och hastighet kunna förmedlas med staplar istället för med
text. Om listan byts mot ikoner finns även möjligheten att ta bort
knappen \textit{Release Units} och låta användaren skicka ut önskad
enhet genom att direkt klicka på enhetens ikon.

\subsubsection{Observer–Obervable}
Eftersom Javas \textit{Observalbe} är en klass som måste utökas för
att användas kan inte \textit{MapSquares} klonas utan att alla får en
gemensam lista med \textit{Observers}. En egen implementation av
\textit{Observer–Observalbe} skulle behövas för att kunna klona
kartrutor på ett användbart sätt. Med en sådan implementation hade det
varit lättare i ett senare skede läsa in alla konfigurationsdetaljer
för att skapa både kartrutor och enheter utifrån XML-dokument.

\subsubsection{LevelEditor}
Klassen \textit{LevelEditor} hade behövt vidareutvecklas för att kunna
användas för att skapa kompletta banor och redigera tillgängliga
banor. Några punkter som hade behövts:

\begin{itemize}
\item Möjlighet att sätta riktning på en \textit{StartSquare}
\item Möjlighet att skapa flera banor och spara dem i en gemensam XML-fil.
\item Möjlighet att välja bilder som ska användas för rutorna.
\item Möjlighet att sätta antal enheter som krävs i mål för att vinna en bana.
\item Möjlighet att sätta ut torn.
\end{itemize}

\bibliographystyle{alpha}
\bibliography{books.bib}

\newpage
\appendix
\pagenumbering{roman}
\section{Källkod}\label{sec:kallkod}
% Källkoden ska finnas tillgänglig i er hemkatalog
% ~/edu/apjava/lab1/. Bifoga även utskriven källkod.
Härefter följer utskrifter från källkoden och andra filer som hör till
denna laboration.

\newpage
\subsection{AntiTD.java}\label{AntiTD.java}
\lstinputlisting{../src/se/umu/cs/dit06ajnajs/AntiTD.java}
% \begin{footnotesize}
% \verbatiminput{../src/se/umu/cs/dit06ajnajs/AntiTD.java}
% \end{footnotesize}
\end{document}