{!!!#- {id="Dixsjg7NbllG" .huomautus .hidden-print visible="%%'ohj1s19d11vika'|belongs%%" nocache="true"} **HUOMIO!** [Olen laittanut sinulle sähköpostia otsikolla: Ohj1: täydennä d11 kuntoon tai ota yhteyttä]{.red}. Laitathan kuntoon tai otat yhteyttä! !!!}

Jypeli Androidilla

Siirtämällä kurssilla tehdyn pelin Android puhelimeen, saa 1 op kurssille:

  • ITKP106 Ohjelmointi 1, mobiili

  • mikäli saa sovelluksen julkaistua kauppapaikassa, saa +1op.

  • kurssin suoritus: peli siirretään puhelimelle ja näytetään ohjaajalle että peli toimii puhelimessa.

  • lisä op:ta varten näytetään vastaavasti että pelin voi ladata kauppapaikasta

  • ohjelman koodit versionhallintaan kuten Ohj1-kurssilla vaikkapa

     tunnus/branch/android

    haaran alle.

Tässä dokumentissa kerrotaan, miten asennetaan Android-kehitystyökalut ja käännetään jo valmis Jypeli-projekti Androidille. Oletuksena on, että aiemmin kurssilla käytetyt kehitystyökalut (esim. Visual Studio 2017) ovat jo asennettuna. Ohjeet ovat toistaiseksi vain Windowsille.

Jypelin ajaminen Androidilla vaatii vähintään Android-version 4.4.2 (KitKat). Tämän voisi olettaa löytyvän ainakin kaikista vuoden 2014 ja sitä uudemmista Android-puhelimista; Androidin version voi yleensä tarkistaa puhelimen asetuksista. Jypelistä ei ainakaan toistaiseksi ole iOS-versiota.

Google Play vaatii Android 8.0 (API level 26) tai suurempaa, joten kannattaa asettaa (Target Framework) vähintään tuoksi. Google Playhin rekisteröityminen maksaa noin 25 euroa, joka suoritetaan kertamaksuna.

1. Työkalujen asentaminen

Suorita alla olevat kohdat yksi kerrallaan Android-kehitystyökalujen asentamiseksi.

Alla olevat ohjeet käyttävät hyvin vanhaa Jypelin versiota. Uudesta Jypelistä ei vielä ole mobiiliversiota.

1.1 Visual Studion mobiilikehitystyökalut

Jos et kurssin alussa asentanut Visual Studion mobiilikehitysosaa (luultavasti et, jos noudatit ohjeita), niin se täytyy nyt asentaa.

  1. Käynnistä Visual Studion asentaja avaamalla Ohjauspaneeli -> Ohjelmat ja toiminnot -> etsi ja valitse Microsoft Visual Studio 2017 -> Muuta
    • Windows 10:llä onnistuu myös Asetukset -> Sovellukset kautta
  2. Asentajassa paina Modify, joka löytyy Visual Studio Community 2017-kohdan alapuolelta
  3. Vieritä alemmas Mobile & Gaming -osioon, ja laita sieltä rasti kohtaan Mobile Development with .NET.
  4. Paina oikealta alhaalta Modify. Et voi käyttää Visual Studiota asennuksen aikana. HUOM! Jos asentanut VisualStudio 2019 ja monoGamen jo aiemmin kurssia varten, mobiililisäosa vaatii vain n. 4GB. Muuten asennus voi myös vaatia useita kymmeniä gigatavuja vapaata levytilaa ja asennus voi kestä jonkin aikaa, mahdollisesti useamman tunnin..

1.2 MonoGame

  • Lataa ja asenna MonoGame 3.6 osoitteesta
  • Valitse sivulta MonoGame 3.6 for Visual Studio.
  • Asennuksen yhteydessä varmista, että asennat projektimallit Visual Studio 2017:sta (Visual Studio 2017 Templates)

1.3 Android-API

Käynnistä Visual Studio. Mene ylhäältä valikosta Tools -> Android -> Android SDK Manager. Etsi avautuvan ikkunan listasta Android 4.4.2 (API 19), laita rasti ruutuun ja paina Install packages...

2. Pelin kääntäminen Androidille

Tässä osiossa käydään läpi, miten jo olemassaoleva Jypeli-projekti käännetään Androidille.

2.1 Projektin luonti

  1. Avaa Visual Studio
  2. Luo uusi MonoGame Android-projekti (File -> New -> Project... -> MonoGame -> MonoGame Android Project). Työn yksinkertaistamiseksi kannattaa laittaa projektin nimeksi sama kuin aiemman, alkuperäisen pelisi nimi (tätä varten projekti pitää kuitenkin laittaa eri kansioon kuin alkuperäinen pelisi).
  3. Lataa Jypeli.dll ja Jypeli.Physics2D.dll -kirjastot osoitteesta ja tallenna ne levylle. Lisää nämä referensseiksi juuri luomaasi projektiin.
  4. Uudelleennimeä projektin Game1.cs -tiedosto vastaamaan alkuperäisen peliluokkasi nimeä.
  5. Avaa uudelleennimeämäsi -tiedosto (alunperin Game1.cs) ja korvaa kaikki sen koodi alkuperäisen pelisi koodilla.
  6. Avaa Activity1.cs -tiedosto ja muuta rivillä 21 oleva luokka oman luokkasi nimeksi, jos saat virheen. Muuta myös rivillä 14 oleva ScreenOrientation = ScreenOrientation.Landscape, jos haluat puhelimesi olevan vain sivusuunnassa.
  7. Aseta Android-API:n versio: mene ylhäältä valikosta Project -> <projektin nimi>Properties. VaihdaCompile using Android version` -kohdan alasvetovalikosta versioksi uusin versio.
  8. Luo Android Manifest tiedosto: mene ylhäältä valikosta Project -> <projektin nimi>Propertiesja valitseAndroid Manifest. Luo Android Manifest tiedosto ja muuta sovelluksenApplication name,Package nameja muutaminimum Android version` sopivaksi, vaikka Android 4.4.
  9. Yritä kääntää peliä (Build -> Build Solution). Jos uuden projektisi nimi ei täysin täsmää alkuperäisen pelisi projektin nimeen (eli et antanut kohdassa 1 projektille samaa nimeä kuin alkuperäiselle pelillesi), on yleensä tarpeellista muokata luokan ja namespacen nimeä joko pelisi pääkooditiedostossa tai sitten projektin MainActivity.cs -tiedostossa. Saatat myös joutua poistamaan joitain using-lauseita ja Mouse / Keyboard.ListenOn -kutsuja pelisi koodista. Tämän jälkeen pelisi pitäisi kääntyä.

Tästä puuttuu AndroidManifestin tekeminen, Android 4.4 (19) SDK:n asentaminen ja MainActivityn muokkaaminen (melkein pakollinen)

29 Aug 18

SDK:n asentaminen on kerrottu luvussa 1.3.

Muilta osin tässä ohjeessa on joitain puutteita juuri activityyn yms. liittyen, jotka tullaan korjaamaan ennen tulevan syksyn ohj1-kurssin HT-vaiheen päättymistä.

29 Aug 18

Uusimmassa tänä aamuna ladatussa MonoJypelissä projektimallit sisältävät AndroidManifest-tiedoston.

31 Aug 18

ScreenOrientation = ScreenOrientation.Landscape Ei toimi. Kuva pyörii tästä huolimatta pienestäkin liikkestä

26 Nov 19

2.2 Sisällön tuonti peliin

Sisällön (kuvien, äänien yms.) tuominen peliin tapahtuu Androidille hieman eri tavalla kuin Windows-Jypelille.

  1. Mene Windowsin resurssienhallinnassa (Explorer, huom. ei IE) edellisessä kohdassa luomasi projektin kansioon, ja sieltä Content-alikansioon. Content-alikansiosta avaa tiedosto Content.mgcb.
  2. Eteesi pitäisi avautua MonoGame Content Pipeline. Lisää pelisi sisältö avautuneesta ikkunasta painamalla vasemmalta yhtäältä löytyvää Content-kohtaa hiiren oikealla näppäimellä, ja sitten kontekstivalikosta Add -> Existing Item.... Navigoi alkuperäisen pelisi sisältötiedostojen luokse ja lisää ne kaikki peliin.
  3. Jos MonoGame Pipeline Tool varoittaa lisäämisen yhteydessä, että tiedostot on eri kansiossa kuin kohdekansiossa, käske sen kopioida tiedostot

Huomioita:

  • Esim. tasohyppelypelien kentät joutuu toistaiseksi toteuttamaan string[] -taulukoina sen sijaan, että ne ladattaisiin tekstitiedostoista. Ks luento 13.
  • Huomaa, että tiedostojen nimet pitää Androidissa täsmätä koodiin myös kirjainten koon osalta! Jos esim. koodissa on kutsu LoadImage("pallo") ja sisältötiedoston nimi on Pallo.png eikä pallo.png, niin ohjelmasi kaatuu kun sitä ajetaan puhelimella!

Onko kenttien toteuttamiseksi string[]-taulukkona olemassa jotain ohjetta?

VL: ne demot, jossa tehtiin AngryLegoa, ja toki myös Jypelin ohjeissa.

24 Nov 17 (edited 24 Nov 17)

2.3 Pelaajan syötteen käsittely

Mobiilialustalla ei yleensä ole käytössä hiirtä taikka näppäimistöä, joten pelaajan syötteen käsittely pitää hoitaa eri tavalla. Tässä auttavat TouchPanel-luokan metodit. Esimerkiksi Jypelin Norsupeli-tasohyppelypelipohja toteutettuna Androidilla käyttää TouchPanel.ListenOn -metodia Widget-luokan kanssa:

3. Pelin ajaminen Android-puhelimella

Ajaaksesi pelin Android-puhelimella tulee puhelin asettaa kehitystilaan ja liittää tietokoneeseen. Miten se täsmälleen tapahtuu voi riippua mallista, mutta seuraavien ohjeiden pitäisi päteä melko hyvin suurimmalle osalle Android-laitteista. Visual Studio kannattaa sulkea tämän asennuksen ajaksi.

3.1 Puhelimen asettaminen kehitystilaan

Katso myös Android/debug.

  1. Mene puhelimessa Settings -> About phone -> Software information -sivulle ja näpäytä Build Number -kohtaa 7 kertaa.
  2. Siirry takaisin Settings-valikkoon. Mikäli edellinen kohta onnistui, niin sieltä (mahdollisesti System-kategorian alta) pitäisi löytyä Developer Options -kohta.
  3. Varmista kehitysasetuksista, että USB Debugging on päällä.

3.2 Puhelimen liittäminen tietokoneeseen

Littääksesi puhelimen tietokoneeseen täytyy sinun asentaa USB-ajurit. Mene aluksi Windowsin resurssienhallinnan avulla kansioon C:\Program Files (x86)\Android\android-sdk\tools\, ja sieltä suorita tiedosto android.bat.

Tämän jälkeen USB-ajurit täytyy ladata puhelimesi valmistajan sivuilta ja sitten asentaa. Androidin kotisivuilta löytyy linkit eri puhelinvalmistajien latauspalveluihin: https://developer.android.com/studio/run/oem-usb.html#Drivers

HUOM! Jos käytät Googlen Galaxy Nexus-puhelinta, ajurit asennetaan Android SDK Managerin kautta. Seuraa tällöin seuraavia ohjeita kohdasta “Install USB Drivers” eteenpäin: https://developer.xamarin.com/guides/android/getting_started/installation/set_up_device_for_development/

Huawei puhelimia varten asenna HiSuite.

Minulla on Huawei-laite, mutta noilta sivuilta en löytänyt latauslinkkiä kysesiin OEM ajureihin.

19 Nov 17

Koita asentaa Huawei HiSuite, jos sinulla ei ole sitä vielä asennettuna. Ehkä ajurit on bundlattu sen mukana, muuten en löytänyt Huawein sivuilta mitään järkevän näköistä ladattavaa.

Netistä myös löytyi sivuja jotka tarjoilivat Huawei-ajureita eri laitteille, mutta niiden kanssa saa luonnollisesti olla äärimmäisen tarkkana ettei asenna haittaohjelmia.

19 Nov 17 (edited 19 Nov 17)

Tämän jälkeen voit yksinkertaisesti vain kytkeä puhelimesi tietokoneeseen USB-kaapelilla, sallia puhelimessa USB-debuggaamisen, käynnistää Visual Studion ja ladata aiemmin luomasi Android-projektin. Visual Studiossa pitäisi tällöin näkyä ylhäällä vihreän nuolen oikealla puolen laitteesi malli (missä tietokonesovelluksissa on lukenut Debug). On myös mahdollista, että kohdassa lukeekin jotain Visual Studioon ja/tai emulaatioon liittyvää. Tällöin avaa kyseisen nimen vieressä olevasta nuolesta alasvetovalikko ja katso, löytyykö puhelimesi listasta. Jos löytyy, valitse se.

Nyt voit painaa Visual Studiosta F5 ja pelisi pitäisi käynnistyä puhelimellasi, ainakin jos se ei ole lukitussa tilassa ja koodissa ei ole virheitä.

3.3 Mahdollisia ongelmia

Jostain syystä pelin debuggaaminen Visual Studiolla ei aina onnistu, kun peliä suoritetaan puhelimessa. Virheen tapahtuessa Visual Studio ei välttämättä esimerkiksi aina näytä virhettä suoraan, vaan poikkeuksen tapahtuessa näytetään vain “The application is in break mode” -ruutu. Tällöin täytyy painaa ylhäältä Continue -näppäintä kahdesti, jolloin ohjelma sammuu. Tämän jälkeen voit vaihtaa Visual Studiossa tyypillisesti vasemmalta alhaalta Output-ikkunaan, josta voi yleensä lukea pelin kaataneen poikkeuksen tiedot.

3.4 Linux erikoisuudet

Ubuntulle openJDK löytyy ainakin pakettijakelusta. Android SDK:n saa ladattua zip-pakettina, jonka saa purkamisen jälkeen ajettua linuxilla.

Puhelimessa debuggaus onnistuu siten, että julistetaan manifestiin applicationin sisään android:debuggable=“true”. Lisäksi Output-ikkunan lokiin voi tulostaa Android.Util.Log käskyillä. Molemmat pitää kuitenkin muistaa poistaa julkaisuvaiheessa.

USB:n ajurit voi testata Android SDK:n mukana tulevalla adb ohjelman käskyllä adb devices, joka listaa yhdistetyt puhelimet. Linuxilla voi tarvita/etc/undev/rules.d/51-android.rules tiedoston tekemisen lukuoikeuksilla ja rivillä SUBSYSTEM=="usb", ATTR{idVendor}=="04e8", MODE="0666", GROUP="plugdev" sikäli kun valmistaja on Samsung (04e8).

4. Julkaiseminen

5. Huomioita

  • Kun Android-laittella sammuuttaa pelin, peli siirretäänkin vain taustalle. Tämä käyttäytyminen tulee MonoGamen puolelta. Jostain syystä peliä ei tällä hetkellä tosin yleensä voi palauttaa takaisin aktiiviseksi ikkunaksi, vaan ikkuna pitää tappaa manuaalisesti ja sitten avata sovellus uudestaan.

Näytön käännön lukitseminen toimi kun avasin pelin Activity1.cs tiedoston ja vaihdoin (minulla rivi 14) ScreenOrientation = ScreenOrientation.Landscape. Saa myös lukittua Portrait asentoon milloin näyttö on aina pystyssä.

23 Apr 18

These are the current permissions for this document; please modify if needed. You can always modify these permissions from the manage page.