Tillbaka till lektionslistan

Mobila applikationer med Android: Inlämningsuppgift 5

I den här uppgiften ska vi skriva en mobil klient till det GPS-baserade spelet Örebro Zombie Horror. Vi kommer att använda:

Uppgift

Vi ska skriva en klient till det GPS-baserade spelet Örebro Zombie Horror.

Här är ett utkast till hur den skulle kunna se ut:

En zombie-klient i Android

Den inloggade spelaren tompa syns i mitten. Två andra spelare, alpha och bravo är zombier. Spelaren charlie är människa.

De krav som klienten ska uppfylla finns beskrivna längre ner.

Spelet

En hemsk sjukdom har brutit ut i Örebro: människor blir zombier! Zombierna är mycket smittsamma, men lyckligtvis går de att bota så att de blir människor igen.

Regler:

Spelet är uppbyggt av klienter och en server. Klienterna körs på Android-apparater, och varje klient fastställer spelarens position med hjälp av GPS. Klienten rapporterar in positionen till servern, och servern skickar ut positionen till de andra klienterna. Servern håller också reda på vilka som är zombier och vilka som är människor, och det är servern som bestämmer när spelarna förvandlas från människor till zombier eller tvärtom.

Kommunikationsprotokollet

Klienten kopplar upp sig med en socket mot serverns port 2002. Servern svarar då med "ZombieServer version", till exempel "ZombieServer 0.2".

Här är de kommandon som klienten kan skicka till servern, tillsammans med de svar som servern kan skicka. Alla data mellan klient och server skickas som strängar, med varje kommando och varje svar på en egen rad. (Undantaget är kommandot LIST-VISIBLE-PLAYERS, där svaret kan bestå av flera rader.)

Det nummer som skickas före varje kommando är bara ett löpnummer, som servern skickar tillbaka. Om servern har mycket att göra kan det hända att den inte hinner svara direkt på ett kommando, och då kan klienten använda löpnumret för att veta vilket kommando ett serversvar hör ihop med. Servern använder inte det löpnumret till något, förutom att skicka tillbaka det, och förmodligen behöver du inte använda det heller. Det får vara samma hela tiden, men det måste vara med.

(Observera att servern dessutom ibland skickar ut meddelanden till klienterna på eget bevåg, så kallade asynkrona meddelanden. Dessa meddelanden börjar med ordet ASYNC, och beskrivs i en annan tabell längre ner.)

Klienten skickar Servern svarar Exempeldialog
nummer REGISTER namn lösenord nummer REGISTERED spelarnummer
nummer ERROR BAD-ARGUMENTS
nummer ERROR NAME-ALREADY-REGISTERED
Klienten: 133 REGISTER kalle
Servern: 133 ERROR BAD-ARGUMENTS
K: 134 REGISTER olle apa
S: 134 REGISTERED 56
K: 135 REGISTER olle apa
S: 135 ERROR NAME-ALREADY-REGISTERED
nummer LOGIN namn lösenord nummer WELCOME spelarnummer
nummer ERROR BAD-ARGUMENTS
nummer ERROR UNKNOWN-PLAYER
nummer ERROR WRONG-PASSWORD
nummer ERROR THIS-CLIENT-ALREADY-LOGGED-IN
nummer ERROR THAT-PLAYER-ALREADY-LOGGED-IN
K: 17 LOGIN olle
S: 17 ERROR BAD-ARGUMENTS
K: 18 LOGIN ollefoo apa
S: 18 ERROR UNKNOWN-PLAYER
K: 19 LOGIN olle apafoo
S: 19 ERROR WRONG-PASSWORD
K: 20 LOGIN olle apa
S: 20 WELCOME 565
K: 21 LOGIN olle apa
S: 21 ERROR THIS-CLIENT-ALREADY-LOGGED-IN
nummer LOGOUT nummer GOODBYE
nummer ERROR BAD-ARGUMENTS
nummer ERROR NOT-LOGGED-IN
K: 899 LOGOUT
S: 899 GOODBYE
K: 900 LOGOUT
S: 900 ERROR NOT-LOGGED-IN
K: 901 LOGOUT jo jag vill
S: 901 ERROR BAD-ARGUMENTS
nummer I-AM-AT latitud longitud nummer OK
nummer ERROR BAD-ARGUMENTS
nummer ERROR NOT-LOGGED-IN
K: 171 I-AM-AT 63.1225 15.494938388
S: 171 OK
K: 172 I-AM-AT -10 -20
S: 172 OK
K: 173 I-AM-AT 63.1225
S: 173 ERROR BAD-ARGUMENTS
K: 174 I-AM-AT 63.1225 181
S: 174 ERROR BAD-ARGUMENTS
K: 175 LOGOUT
S: 175 GOODBYE
K: 176 I-AM-AT 63.1225 15.494938388
S: 176 ERROR NOT-LOGGED-IN
nummer WHAT-AM-I nummer YOU-ARE HUMAN
nummer YOU-ARE ZOMBIE
nummer ERROR BAD-ARGUMENTS
nummer ERROR NOT-LOGGED-IN
K: 1 WHAT-AM-I
S: 1 YOU-ARE HUMAN
K: 2 WHAT-AM-I really?
S: 2 ERROR BAD-ARGUMENTS
nummer WHERE-AM-I nummer YOU-ARE-AT latitud longitud
nummer ERROR BAD-ARGUMENTS
nummer ERROR UNKNOWN-POSITION
nummer ERROR NOT-LOGGED-IN
K: 177 WHERE-AM-I
S: 177 YOU-ARE-AT -10.0 -20.0
K: 178 I-AM-AT -10 -20.1
S: 178 OK
K: 179 WHERE-AM-I
S: 179 YOU-ARE-AT -10.0 -20.1
K: 180 WHERE-AM-I foo
S: 180 ERROR BAD-ARGUMENTS
nummer SET-VISIBILITY avstånd nummer OK
nummer ERROR BAD-ARGUMENTS
nummer ERROR NOT-LOGGED-IN
K: 66 SET-VISIBILITY 190
S: 66 OK
K: 67 SET-VISIBILITY -9
S: 67 ERROR BAD-ARGUMENTS
nummer LIST-VISIBLE-PLAYERS nummer VISIBLE-PLAYERS avstånd antal
(följt av spelarnas positioner, en per rad)
nummer ERROR BAD-ARGUMENTS
nummer ERROR UNKNOWN-POSITION
nummer ERROR NOT-LOGGED-IN
K: 4711 LIST-VISIBLE-PLAYERS
S: 4711 VISIBLE-PLAYERS 100000.0 3
S: 4711 PLAYER olle HUMAN 30.1 30.1
S: 4711 PLAYER charlie HUMAN 30.2 30.2
S: 4711 PLAYER delta ZOMBIE 30.3 30.3
K: 4712 LIST-VISIBLE-PLAYERS 1000
S: 4712 ERROR BAD-ARGUMENTS
K: 4713 SET-VISIBILITY 1000
S: 4713 OK
K: 4714 LIST-VISIBLE-PLAYERS
S: 4714 VISIBLE-PLAYERS 1000.0 1
S: 4711 PLAYER olle HUMAN 30.1 30.1
nummer TURN status nummer OK
nummer ERROR BAD-ARGUMENTS
nummer ERROR CANNOT-TURN
nummer ERROR NOT-LOGGED-IN
K: 67 TURN ZOMBIE
S: 67 OK
K: 68 TURN ZOMBIE
S: 68 ERROR CANNOT-TURN
K: 69 TURN ZOMBIE ZOMBIE ZOMBIE
S: 69 ERROR BAD-ARGUMENTS
K: 70 TURN HUMAN
S: 70 OK
nummer något-annat-kommando nummer ERROR UNKNOWN-COMMAND K: 189 SHUTDOWN
S: 189 ERROR UNKNOWN-COMMAND
något annat ERROR MALFORMED-COMMAND K: hej hej
S: ERROR MALFORMED-COMMAND

Det flesta kommandona är ganska självförklarande, utom kanske TURN och LIST-VISIBLE-PLAYERS:

Servern skickar ibland ut meddelanden till klienterna på eget bevåg, så kallade asynkrona meddelanden. Dessa meddelanden börjar med ordet ASYNC, och beskrivs i tabellen nedan. Klienten ska inte svara på dessa meddelanden.

Servern skickar Exempel
ASYNC YOU-ARE ZOMBIE ASYNC YOU-ARE ZOMBIE
ASYNC YOU-ARE HUMAN ASYNC YOU-ARE HUMAN
ASYNC PLAYER namn status latitud longitud ASYNC PLAYER olle HUMAN 30.0 30.0
ASYNC PLAYER anna HUMAN 30.001 30.002
ASYNC PLAYER anna ZOMBIE 30.001 30.002
ASYNC PLAYER namn GONE ASYNC PLAYER olle GONE

När en spelare förvandlats till människa eller zombie, får den spelaren ett asynkront YOU-ARE-meddelande.

När en spelare förvandlats till människa eller zombie, eller flyttat på sig, skickas asynkrona PLAYER-meddelanden ut till alla spelare. GONE-varianten av PLAYER-meddelandet används när en spelare inte längre syns (för att hon loggat ut, eller kommit längre bort än synlighetsgränsen).

En dumhet: Observera att i protokollet skickas alltid latituden först, följt av longituden. Kommandot geo fix till emulatorn tar däremot longituden först, följt av latituden.

Ett tillägg i version 0.3 av serverprogrammet är kommandot LIST-ALL-PLAYERS, som främst är avsett för administration och felsökning av servern. Det listar alla registrerade spelare, oavsett om de är inloggade eller har någon position. Det kommandot kräver att man skickar med ett lösenord, som först ska ha angetts som argument när man startade servern.

Förslag på arbetsgång

  1. Börja med att ladda hem och provköra servern: ZombieServer-0.3.zip
    Installera och kör servern på din egen maskin. Kör servern i ett separat fönster, och koppla upp dig mot den med först en och sen flera klienter.
  2. Det finns en särskild desktop-klient (se nedan) för att koppla upp sig mot servern, och man kan också använda programmet telnet och skriva kommandon direkt. Undersök hur spelet fungerar, och hur protokollet mellan klient och server ser ut.
  3. Jag kommer att köra en server på basen.oru.se. Under utvecklingen kan det vara praktiskt att provköra mot en egen, lokal server, men den färdiga klienten ska koppla upp sig mot basen-servern.
  4. Skapa därefter en Android-app som kopplar upp sig mot servern.

Krav på klienten

Nödvändiga krav:
  1. Klienten ska kunna koppla upp sig mot servern och logga in.
  2. Klienten ska rita upp en karta med spelarna, där man ser sig själv och de andra spelare som är inom synhåll. Det ska gå att se vilka av spelarna som är zombier och vilka som är människor.
  3. Klienten ska hela tiden tydligt visa om spelaren är människa eller zombie.
  4. Klienten ska uppdatera kartan när asynkrona meddelanden om positionsändringar och människa/zombie-ändringar tas emot.
  5. För att det ska gå att rita kartan måste klienten kontinuerligt bestämma sin postion med GPS, och rapportera in postionen till servern.
Det här bör man också ha med för att klienten ska bli användbar, men det är inte ett krav för godkänt:
  1. Gör så att det går att ange namn och lösenord för den spelare man vill logga in som.
  2. Gör så att det går att registrera nya spelare, och då ange namn och lösenord.
  3. Rita ut en kartskala, så man ser hur långa avstånden är.
  4. Skriv ut namnen på spelarna.
  5. Undvik onödig kommunikation med servern. Man behöver inte begära en hel lista med kommandot LIST-VISIBLE-PLAYERS annat än första gången man ska rita kartan. Därefter använder servern asynkrona meddelanden för att skicka ut ändringar som man behöver ta hänsyn till.
Förslag på utvidgningar, om man vill:
  1. Gör det möjligt att ändra gränsen för hur långt bort spelare ska synas (kommandot SET-VISIBILITY).
  2. Anpassa den visade kartans storlek efter synlighetsgränsen, och de spelare som visas.
  3. Visa en riktig karta, med hus och vägar! (Jag har hört att Google har kartor.)
  4. Om telefonen har inbyggd kompass (med magnetiska sensorer eller GPS), så orientera kartan efter telefonens läge. Rita ut norr.
  5. Vid inloggning skickas lösenordet i klartext. Laga detta allvarliga fel. (Det kräver naturligtvis också att man ändrar i servern.)

Desktop-klienten

När man jobbar med utvecklingen kan man hämta inspiration (och kanske en del Java-kod) från klienten ZombieDesktopClient, som är skriven för vanliga skrivbords-Java. Man kan ladda hem den här: ZombieDesktopClient-0.3.zip

Den här desktop-klienten körs alltså inte på Android, utan på en vanlig dator. Den har ett huvudfönster, där man bland annat kan logga in, och skriva in (simulerade) kartkoordinater:

Desktop-klientens huvudfönster

Om man klickar på knappen Show map, visas en karta, som påminner om den karta som det ingår i uppgiften att skapa, men då alltså under Android:

Desktop-klientens kartfönster

Med knappen Show com log kan man få fram ett fönster där kommunikationen mellan klienten och servern visas:

Desktop-klientens logg-fönster

Här kan vi se hur klienten skickat kommandot LIST-VISIBLE-PLAYERS, och fått ett svar med VISIBLE-PLAYERS om att det finns 4 spelare inom synhåll, som är 1000 meter. Sen listas de fyra spelarna, och den första av dem, tompa, är den inloggade spelaren själv.

Efter att vi fått detta svar från servern, har det kommit två asynkrona meddelanden från servern med nya positioner för spelaren bravo. Om en synlig spelare flyttar sig, eller förvandlas mellan zombie och människa, får man alltid asynkrona meddelanden om det. Om man låter klienten komma ihåg den mottagna informationen, slipper man därför skicka en ny VISIBLE-PLAYERS varje gång man ska rita upp kartan.

Tips

  1. Man kan återanvända en del av koden från desktop-klienten.
  2. Man kan hämta vissa Android-specifika lösningar från chat-klienten man gjorde i uppgift 4.
  3. Man kan köra flera instanser av skrivbordsklienten samtidigt, så ser man kanske tydligare hur meddelanden från en klient påverkar de andra.
  4. Bli inte förvånade om ni hittar buggar i servern eller i desktop-klienten. Rapportera dem.
  5. Kända buggar i servern:

Redovisning

Packa ihop hela Android Studio-projektet (eller motsvarande) som en Zip-fil (eller motsvarande) och skicka den med e-post till läraren. APK-filen (Androids kompilerade installationsfil) ska vara med. Den finns normalt i underkatalogen app/build/outputs/apk. Döp om Zip-filen från nånting.zip till exempelvis nånting.info (inte nånting.txt) för att överlista överambitiösa virusfilter.

Det behövs ingen formell labbrapport, men om det är något som inte framgår direkt, till exempel hur man använder den inskickade appen eller vad utmatningen betyder, behövs det någon form av beskrivning. (Och underskatta inte min förmåga att inte begripa.)

Om samarbete: Varje student ska göra en egen lösning, och skicka in den, men det är inte förbjudet att samarbeta eller fråga andra studenter om hjälp. Däremot ska man i så fall tydligt ange vilka som man samarbetat med.

Skriv gärna i ärenderaden på brevet vilken kurs det handlar om, till exempel "Android-uppgift 5", och inte bara "Uppgift 5".

Tillbaka till lektionslistan


Thomas Padron-McCarthy (thomas.padron-mccarthy@oru.se), 25 november 2015