Merge branch 'master' of ssh://repo.or.cz/srv/git/AntiTD
[AntiTD.git] / README.org
blobbd101188beceec21101dd4822864b45b62c8211e
1 #+TITLE:     Spec/plan laboration 4, apjava
2 #+AUTHOR:    Anton Johansson, Andreas Jacobsson
3 #+EMAIL:     anton.johansson@gmail.com
4 #+DATE:      2008-12-08 Mon
6 * Plan / Tankar
7   Se [[file:report/timplan.xsl][timplan.xsl]]
8   - Trådosäkert att lägga till torn från en anan tråd.
9   - repaint() är trådsäker.
10   - Synkronisera gemensam variabel? agents?
11   - Synkronisera HashMap i PrototypeFactory?
12   - Systembeskrivningen är extra viktig i denna labb. Hur kan
13     programmet utökas och vidareutvecklas.
14 * Frågor
15 ** DONE Trådar
16    Vad skulle fördelen kunna vara med att försöka sätta varje Unit i
17    en separat tråd? Vad blir mest beräkningstungt, att göra massa
18    saker i samma tråd mot att hantera varje enhets logik separat?
20 *** Svar: Vi väljer inte separata trådar för varje enhet, detta eftersom det verkar bli mer problem.
21    
22 ** DONE Statiska metoder vs andra
23    Hur ska man på ett bra sätt implementerar Builder/Factory klasser?
24    Vad är fördelen/nackdelen med att dessa enbart innehåller statiska
25    metoder om så är möjligt.
27 ** DONE Interface som extendar annat interface, se UML.
28    Svar: Detta är okej, nyckelordet är extends men det betyder exakt
29    samma sak som implements.
30 ** DONE Protected attribut
31    Känns farligt att använda men när ska man göra det? Om det inte
32    krävs någon koll för get och set kan det väl lika gärna vara
33    protected?
35    Svar: Kör inte med det! Bra för framtiden att kunna lägga till
36    kontroller, t ex positioner ska inte kunna vara negativa.
37 ** TODO ImageObserver?
38    Hur är det tänkt att det ska användas, t ex om man vill kolla
39    getWidth(ImageObserver) på en BufferedImage.
40 ** TODO Decorator at runtime för att dekorera Agents?
41 ** DONE Observer, observerar den automatiskt sig själv?
42    Eftersom objekten klonas så kommer de ha referenser till samma
43    listor, d v s sista Observern lägger till Observers för alla
44    föregående.
45 * Planeringsmöten
46 ** Första
47    CLOCK: [2008-12-10 Wed 20:30]--[2008-12-11 Thu 00:36] =>  4:06
48    
49 *** Klasser
50     - Item <|- Health, Teleport, SpeedBoost, Guns 'n' ammo.
51     - Square <|- Stone, Savanna, Road. Idé, varje Square har en
52       instans av Javas Rectangle för att kunna använda dess intersects
53       metod.
54     - Road <|- Sand, Ice.
55     - Intersection en Item? Ett sätt att välja väg vid
56       flervalskorsningar.
57     - Map, JComponent?
58     - Model håller koll på alla enheter.
59     - Controller, The allseeing eye, säger till varje enhet att
60       uppdatera sig själv.
61     - View, ritas upp för varje fram. Kontroller meddelar när det är
62       dags, data hämtas från Model.
63     - Poängräkning skulle kunna ske i separat tråd som sover
64       specificerat antal millisekunder för att sedan vakna upp och
65       räkna av antalet enheter på plan.
66     - Player, synchronized score!
67       
68 *** Interface
69     - Ett interface för att se till att allt som behöver det har en
70       =intersects()= metod för att testa om den överlappar annan klass
71       som implementerar samma interface. Främst för Unit.
72       
73 *** Logik
74    Squares extends JComponent, Observable (Towers ska vara Observers),
75    Units meddelar rutor att de befinner sig i dem. Towers får då en
76    referns till aktuell Unit och lägger denna i en lista för
77    beskjutning.
78    
79    Anledningen till något typ av arv av JComponent är att
80    vi vill ha metoden getComponentAt(Point) från en högre nivå (Map av
81    typ JComponent?) för att Units ska kunna veta vilken ruta de
82    befinner sig på.
84 *** Kartor XML
85     : <map>
86     :  <row>
87     :    <square type="stone"/>
88     :    <square type="road">
89     :      <item type="health"/>
90     :    </square>
91     :  </row>
92     : </map>
93    
94 *** Collision detection
95     Varje Unit kollar om den intersectar med någon annan Unit innan
96     den rör sig. Om den gör det så minskar den flytten tills den
97     hittar en flytt som inte intersectar med någon Unit.
99 *** Flytt av Unit
100     1) Unit leter upp rutan den befinner sig i: Frågar map (JComponent
101        getComponentAt(Point?))
102     2) Fråga ruta om aktuell speedFactor, för att modifiera sin
103        hastighet. 1 är standard, 1 * UnitSpeed.
104     3) Unit meddelar sin ruta att den befinner sig där, Obervable
105        ruta. Rutan meddelar Tower, Tower sparar Unit i kö. Se [[*Logik]]
106     4) Unit har en tidsenhet som intervall på hur ofta den får göra
107       förflyttningar, detta representerar hastighet. Unit tidstämplas
108       vid varje flytt med aktuell tid i millisekunder. Vid nästa flytt
109       kollar den så att satt tidsintervall har förflutit.
110     5) Enumeration håller koll på riktning.
111     6) Se [[*Collision%20detection][*Collision detection]]
112   
113   - Vi använder XMLSchema.
114     
115 *** TODO Till nästa gång
116 **** TODO Ta reda på hur vi svänger i kurvor.
117 **** TODO Metoderna intersects och contains.
118 **** TODO Easter eggs?
119      
120 ** Andra
121    CLOCK: [2008-12-11 Thu 16:07]--[2008-12-11 Thu 19:06] =>  2:59
122    
123 *** Path <|- Turnpath
124     Hela Canvas har en mouseListener som lyssnar på musklick, dessa
125     koordinater kollas mot matris för spelplanen och objekt som finns
126     där returneras, Object instanceof Turnpath ger ändring i sväng.
127 *** Flyweight pattern för rutor?
128 *** En matris för spelplanen
129     Spelplanen vet koordinater för varje ruta, Units kan fråga
130     spelplanen efter ruta för aktuell koordinat!
131     
132 *** DoubleBuffering
133     Skapa en instans av bakgrundsbild att rita hämtas till en instans
134     av BufferedImage för att rita upp gubbar på för varje
135     uppritning. Clear Canvas, rita upp BufferedImage och vipps så är
136     där DoubleBuffering.
137     
138 *** Animationtråd
139     Tården kan se ut så här:
140     : while(running) {
141     :     for (Unit unit : units) {
142     :         unit.update();
143     :     }
144     :     for (Unit unit : units) {
145     :         unit.paint(Graphics g);
146     :     }
147     : }
148 *** Gränssnitt
149     Tänk på att knappar kan vara bilder.
150 *** Ett Game
151     - Nytt game startas, spelare finns redan.
152     - Karta skapas
153     - Pengar ges
154     - Poäng är noll
155     - Torn placeras
156     - Game on!
157       
158 *** Levels.xml
159     - Levevels.xml Innerhåller information om hur banan ska byggas
160     upp.
161     - LevelStyle.xml innerhåller information om vilka bilder som hör
162       ihop med vilka ban-element.
163     - UnitStyles.xml innehåller information om vilka bilder som hör
164       ihop med vilka Units.
165       
166 ** Tredje
167    CLOCK: [2008-12-18 Thu 14:45]--[2008-12-18 Thu 16:10] =>  1:25
168 *** DONE Plan för framtida arbeta uppgjord se, [[*Plan][Plan]]
170 * Implementeringstillfällen
171 ** Första
172    CLOCK: [2008-12-14 Sun 14:00]--[2008-12-14 Sun 20:36] =>  6:36
173 *** DONE Animerade Units
174     Units förflyttar sig över skärmen, statisk bakgrundsbild ligger
175     kvar, är detta dubbelbuffrat?
176 *** DONE Början på hela programmets struktur.
177    
178 ** Andra
179    CLOCK: [2008-12-15 Mon 14:15]--[2008-12-15 Mon ?]
180 *** DONE Kartan ritas upp med bilder
181 *** DONE Tower implementerad och utsatt på karta!
182 *** DONE MouseListener på GameComponent
183 *** DONE Plan för framtida arbeta initierad se, [[*Plan][Plan]]
184 ** Tredje
185    CLOCK: [2008-12-16 Tue 18:30]--[2008-12-16 Tue 23:37] =>  5:07
186 *** DONE GoalSquare
187 *** DONE Register Observer, Observable Tower observs PathSquares.
189 * Om spelet
190   Ett Tower Defence-spel är ett spel i vilket användarens uppgift är att
191   skydda sig mot fiender genom att sätta upp torn. Dessa torn ska sedan
192   skjuta ner fienden innan de når ett givet mål, och tornen måste
193   således placeras ut strategiskt.
194   
195   För att göra spelet intressantare brukar det krävas att en viss mängd
196   fienden tar sig i mål för att man ska förlora, och det kan finnas
197   flera sorters fiender och torn (flygande och markgående fienden etc.).
198   
199 * Spelets regler
200   - Att släppa ut trupper ska kosta valuta (nedan kallat kredit), och
201     spelaren får ett antal krediter tilldelade varje bana. När dessa
202     är slut kan inga trupper köpas, och spelaren förlorar om de
203     trupper på banan inte tar sig i mål och ger upphov till vinst.
204   - Vinst är när ett visst antal "målkrediter" tjänats. Detta brukar
205     bara vara ett antal truppmedlemmar, men kan mycket väl viktas med
206     deras hälsa när de kommer in i mål.
207   - Krediter tjänas på något sätt under banans gång, förslagsvis en
208     viss krediter/sekund för varje truppmedlem, samt en viss mängd
209     krediter vid målgång.
210   - Fienden behöver inte vara smarta. Det räcker med att de väljer en
211     varelse inom räckhåll och skjuter på den.
212   - Fienden får ha endast laser (ljusstråle som träffar direkt så ni
213     slipper beräkna en projektils bana).
214   - Utplacering av tornen som skjuter på trupperna behöver endast
215     placeras ut slumpmässigt i tillåtna zoner.
217 * Laborationen
218   Laborationen ska lösas i grupper om 2 (två) personer. Det ses från vår
219   sida som en näst intill omöjlig uppgift att göra laborationen enskilt
220   under kursens gång, därför finns det inga undantag. Parindelningen är
221   upp till er att fixa, men alla grupper ska anmäla sig på denna
222   sida. Vet ni inte om någon att jobba med så skriv in er i en ny grupp
223   , eller om det redan finns en grupp med bara en person så skriv in er
224   i den och kontakta så snart som möjligt personen som redan stod där om
225   att du vill jobba med honnom/henne.
227   Målet med spelet är att skapa en bas för utbyggnad av
228   funktionaliteten. Därför är det väldigt viktigt att ni lägger stor
229   möda på spelets interna struktur för att få en lättnavigerad kodbas
230   med logisk uppbyggnad. Dokumentationen är väldigt viktig den med,
231   vilket innebär att samtliga klasser, samtliga metoder samt
232   medlemsvariabler ska kommenteras med utförliga
233   JavaDoc-kommentarer. JavaDoc är dock inte den enda typen av grundlig
234   dokumentation som krävs, se nedan.  Syfte
236 * Syftet med laborationen är att få pröva på och använda:
237   - Trådar
238   - XML / DTD / XMLSchema
239   - GUI (Swing)
240   - Grafik
241   - Öva färdigheten i rapportskrivning med en specifik målgrupp
242   - Följa en given kodkonvention
244 * Er uppgift
245   Er uppgift är inte att implementera ett Tower Defence-spel, utan ett
246   Anti-Tower Defence-spel. Ni ska alltså låta användaren skicka ut
247   fienden som sedan datorn ska skjuta ner. Ett exempel på ett sådant
248   spel är: [[http://www.sugar-free-games.com/playgame.php%3Fgame%3D1127][Anti-TD]] på Sugar Free Games.
249 ** Kravlista
250    För att göra spelet mer intressant ut laborationssynpunkt finns det
251    en del krav på er lösning:
252    
253 *** I alla nivåer gäller:
254 **** TODO Implementera spelet AntiTD i Java
255 **** DONE Följa SUN:s kodkonvention: http://java.sun.com/docs/codeconv/index.html
256 **** TODO Följa god OO- och MDI-stil.
257 **** DONE Källkoden skall ligga i katalogen
258      : ~/edu/apjava/lab4/src/
259 **** DONE En komplierad version i katalogen
260      : ~/edu/apjava/lab4/bin/
261 **** DONE Rapporten skall ligga i katalogen
262      : ~/edu/apjava/lab4/report/
263 **** TODO JavaDoc-sidorna skall ligga i katalogen
264      : ~/edu/apjava/lab4/doc/
265    
266 *** TODO Nivå 1 (grundnivå)
267 **** DONE Klassen "AntiTD"
268      Startar ett Anti Tower Defence-spel utan att ta emot några argument från användaren.
269 **** DONE Trådar
270      Spelet ska använda sig av flera trådar för att låta flera delar jobba parallellt.
271 **** DONE Uppdateringsintervall
272      Spelets uppdateringsintervall skall vara tidsberoende och inte
273      beroende av datorns hastighet.
274 **** DONE Banor
275      Det ska finnas minst en bana längs vilken man kan skicka ut
276      trupper.
277 **** TODO Vinst/Förlust
278      Vid "vinst" eller "förlust" så ska användaren presenteras med
279      valet om att spela igen eller avsluta spelet. Medans detta val
280      pågår så ska inte användaren kunna göra nåt annat, men objekt på
281      spelplanen ska fortsätta röra sig.
282 **** DONE GUI:t skall använda sig av Swing-biblioteket.
283 **** DONE Rendering
284      All rendering skall ske dubbelbuffrat för att undvika flimmer.
285 **** TODO Det ska finnas minst två huvudmenyer:
286      - En meny med valen:
287        + DONE New Game/Restart
288          + Om inget spel har startats så heter menypunkten tex. "New
289            Game" och vid klick så startar den ett nytt spel. Om spelet
290            redan är igång så ska menypunkten heta tex. "Restart" och
291            spelet börjar om från början.
292        + DONE Pause/Resume
293          + Menypunkten kan tex. heta "Pause" om spelet är igång och
294            när man klickar på menypunkten så ska alla trupper och torn
295            stanna och inga knappar ska gå att klicka på. Om spelet är
296            i "Pause"-läge så ska menypunkten byta namn till
297            tex. "Resume" och vid klick så ska spelet återupptas där
298            det sist var, dvs. fordonen skall fortsätta röra på sig
299            samt att användaren kan skicka ut fler trupper.
300        + TODO Mute
301          + Sluta spela upp ljud. Då den här menyn väljs ska
302            menyalternativet bytas till "Unmute" och vice versa.
303        + DONE Quit
304          + Avsluta spelet.
305      - DONE Den andra menyn ska innehålla:
306        + About: Berättar i en dialogruta vem som gjort spelet och när.
307        + Help: Berättar i en dialogruta hur man spelar.
308 **** DONE Zoner i banor
309      Varje bana skall innehålla zoner där datorn kan placera ut torn,
310      vägar längs vilka trupper kan röra sig.
311 **** DONE Grupptyper
312      Minst två typer av trupper ska implementeras med olika förmågor
313      (klarar olika antal träffar, kostar olika mycket, har olika
314      hastighet, etc.).
316 *** TODO Nivå 2 (multipla banor/XML)
317 **** DONE Flera banor
318      Spelet ska klara av flera banor. Banorna ska se olika ut,
319      exempelvis hur trupperna kan röra sig.
320 **** DONE Spara banor i fil levels.xml
321      Flera banor skall lagras i en fil som heter
322      "levels.xml". XML-formatet skall följa en DTD som ni själva
323      specificerar. XML-filen skall valideras mot den DTD (eller XML
324      Schema) ni skriver.
325 **** DONE Banzoner
326      Varje bana skall innehålla zoner där datorn kan placera ut torn,
327      vägar längs vilka trupper kan röra sig, samt regler för banan,
328      exempelvis hur många trupper som måste komma igenom för att
329      användaren ska vinna. Allt detta ska stå i XML-filen under varje
330      bana.
331 **** DONE Vinst/förlust
332      När användaren "vinner" en bana så skall spelet fråga användaren
333      om den vill spela samma bana en gång till eller fortsätta till
334      nästa bana.
335 **** DONE Restart level
336      Den första menyn ska byggas ut med alternativet "restart level".
337 **** DONE Flera vägsträckor per bana
338      Det ska finnas (möjlighet till, samt exempel på) flera möjliga
339      vägsträckor per bana för trupperna.
340 **** DONE Spara resultat till Highscoreservice
341      Alla resultat ska sparas med hjälp av det ni gjorde i
342      lab 3. Highscores ska kunna visas (baserat på tid, poäng, nivå,
343      etc.).
344 **** DONE Parameter som anger levels.xml vid start
345      Ges ett argument vid körning ska detta tolkas som ett filnamn och
346      läsas in istället för levels.xml och på så vis kan fler banor
347      göras och köras utan att modifiera i spelets katalog.
349 *** TODO Nivå 3 (triggers / jar)
350 **** DONE Triggers, vägpekare i vägskäl?
351      Banor ska kunna innehålla (och det ska finnas exempel på banor
352      som innehåller) "växlar" som gör att en väg kan mynna ut i en
353      T-korsning där spelaren klickar på ex. en knapp för att välja åt
354      vilket håll trupperna ska gå.
355 **** DONE Skapa ett interface som har en metod "landOn".
356 **** DONE Banklasser implements landOn
357      De olika områdena på en bana skall finnas i egna klasser. Varje
358      sådan klass kan implementera interfacet beskrivet ovan.
359 **** DONE Läsa in class-filer från XML?
360      Vid start av en ny bana så skall programmet läsa in de
361      class-filer som XML-filen har deklarerat som sina områden och när
362      truppmedlemmarna går på ett visst område så ska denna
363      områdesklass funktion "landOn" anropas och någonting skall hända,
364      förutsatt att den implementerat ovan nämnda interface.
365 **** TODO Områden, ex Teleporters
366      Ett speciellt område utöver de beskrivna hittills skall
367      finnas. Tex: Teleporters, när en truppmedlem går på en viss ruta
368      så flyttas den till en annan på vägen.
369 **** TODO Teleportertrupper
370      Teleportertrupper ska implementeras som kostar mer, men ska kunna
371      lägga ner teleporterplattor när användaren väljer, och på så vis
372      kommer trupperna att kunna slippa förflytta sig lika långt.
373 **** DONE Spelet sparas i AntiTD.jar 
374      Spelet samt de filer som behövs för grundspelet skall finnas i en
375      JAR-fil som heter "AntiTD.jar". Spelet ska startas med kommandot:
376      java -jar AntiTD.jar
378 * Redovisning
379   Den här laborationen har inte bara ett fungerande system som mål, utan
380   den ska även vara en bas för vidareutveckling. Därför ska den visas
381   upp för en fiktiv kund som ska köpa spelet av er för en stor hög
382   pengar. Därför är det viktigt att ni gör bra ifrån er på både spelets
383   uppvisning, och dokumentationen som ska lämnas in.
384   
385 ** Milestone DEADLINE: <2008-12-18 Thu 15:00>
386    Innan jul ska ni boka in er för ett tillfälle hos handledarna för
387    att redovisa projektets framskridande. Vid detta möte bör delar av
388    programmet vara implementerat och ni bör kunna redovisa en plan (i
389    form av följande dokument) för hur arbetet ska fortskrida fram till
390    de olika redovisningstillfällena. Ni kommer att kunna boka in er
391    för denna redovisning 18/12 mellan 15-17. Bokning av tid kommer att
392    kunna ske senast veckan innan (info om detta kommer via mail). Om
393    ni av någon anledning vet att ni ej kan delta vid detta tillfälle
394    så hör av er till handledarna i förväg så kan redovisningen
395    genomföras vid något tidigare tillfälle.
396    
397 ** Uppvisning (promotion) DEADLINE: <2009-01-13 Tue>
398   Samtliga lösningar ska visas på gruppövningen den 13e
399   januari. Ungefär 10 minuter per grupp ges. Tar uppvisningen för
400   lång, eller för kort tid, minskar intresset från kunden. Hjälpmedel
401   ni har att tillgå är: OH-apparat, ... Mer info kommer senare.
402   
403 ** Fysisk inlämning av dokumentation
404    Det som i normala fall brukar vara en rapport om själva utvecklandet
405    kommer på den här laborationen ha en annan uppgift.
407    Utöver dokumentationen av programmet så ska ni även lämna in en
408    detaljerad beskrivning av vem som gjort vad i projektet. Detta för att
409    individuell poängbedömning ska kunna göras (var nogrann med
410    denna). Denna del ska ges som en bilaga till rapporten. Till exempel
411    kan en uppdaterad version av dokumentet från milestone tillfället
412    ingpå. Observera att det inte räcker med en mening där ni säger att ni
413    båda varit inblandade i allt och gjort lika mkt (lite mer detaljnivå
414    krävs).
416 * Programdokumentation  DEADLINE: <2009-01-13 Tue 15:15>
417   Dokumentation av arbetet ska vara inlämnad senast Tisdag 13/1-09
418   15:15 Den största vikten i rapporten ligger på hur systemet är
419   uppbyggt. Vilka delar ska modifieras för att olika effekter ska
420   uppnås. Här hör ett eller flera UML-diagram hemma,
421   algoritmbeskrivningar i grafisk form, etc.
422   
423   Tänk på att den här delen ska fungera som referenslitteratur. Det
424   ska alltså inte vara uppsatser, utan listor, bilder, grafer,
425   tabeller, träd, etc. Små textstycken behövs med, men en
426   beskrivningar i uppsatsform är inget alternativ.
428 * Bedömning
429   Rapporten kommer betygsättas utifrån dels utseende (teckensnittsval,
430   marginalbredd, sidnumrering), innehåll (styckeuppdelning, förlopp, hur
431   lätt det är att slå upp saker i den), informationsförmedling (vad
432   berättas i rapporten), och slutligen kommer även stavfel,
433   särskrivningar, meningsbyggnadsfel och språkblandningar in i bilden.
435   JavaDoc-sidorna kommer gås igenom och deras innehåll kommer bedömas.
437   Javakoden kommer synas så den följer konventioner och "bra"
438   programmeringsstil. Ex. på mindre bra programmeringsstil är:
439   
440   : if (a.getP() < 4)
441   :    return false;
442   :  else
443   :    return true;
444   
445   En helhetsbedömning av bl.a. ovanstående kommer poängsätta rapporten,
446   kodens dokumentation, redovisning och källkoden. Resultatet kommer
447   bli: Nivå Poäng 1 0 - 7 2 0 - 14 3 0 - 20
448   
449   Dokumentationen kommer stå för runt 1/3 av den totala poängen, så glöm
450   inte att lägga ner tid på den.
451   
452   OBS: Poängsättningen av labben kommer att ske på den först inlämnade
453   versionen. Fel som ger O på labben kommer givetvis att bidra till att
454   minska poängtalet rätt rejält.
455   
456 * Ev otydligheter i specifikationen
457   Är något otydligt i specifikationen så är det upp till er att klargöra
458   vad som gäller. Redovisa även sådana klargörande i rapporten.