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, vaikka samaan repositorioon uuteen kansioon.

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 2022) ovat jo asennettuna. Ohjeet ovat toistaiseksi vain Windowsille, mutta ovat helposti sovellettavissa Macilla ja Linuxilla.

Google Playhin rekisteröityminen maksaa noin 25 euroa, joka suoritetaan kertamaksuna. Rekisteröityminen vaaditaan vain jos haluat julkaista pelisi kauppapaikassa.

1. Työkalujen asentaminen ja projektin valmistelu

Aloita avaamalla Visual Studio Installer, ohjelma löytyy sinun tietokoneelta jos olet asentanut kurssin työkalut.

Valitse Visual Studio Community 2022 kohdalta Modify. Jos ilmoittaa että päivitys on saatavilla, asenna myös se.

Lisää ruksi kohtaan .NET Multi-platform App UI development.

Paina Modify ja odota.

1.0.1 Android lisäosa .NETtiin

Kun Visual Studion asennus on valmis, avaa komentorivi ja kirjoita komento

dotnet workload install android

Tämä asentaa vielä tarvittavat Android-kirjastot käytettäväksi. Tässä kestää hetki.

1.0.2 Jypeli projektin pohja

Luo projekti Visual Studiossa kuten normaalisti, valitse Android Fysiikkapeli-projektimalli.

1.0.3 Sisällön tuonti peliin

Sisällön tuonti tapahtuu hyvin samalla tavalla kuin "työpöytäJypelissä". Laita tiedosto Content-kansioon, mutta nyt sille pitää antaa asetus Build Action -> AndroidAsset. Build Action listan valinnat eivät (jostain kumman syystä) ole aakkosjärjestyksessä. Build Action-asetus löytyy Properties-ikkunasta, kun tiedosto on valittu Solution Explorerissa.

Copy to output... asetusta ei tarvitse laittaa.

1.0.4 Android SDK 34 tuelle workaround

Jotta Jypeli-android projekti toimii Android SDK versiolla 33 ja uudemmilla, tulee meidän tehdä pieni muutos siihen, miten Xamarin käsittelee Androidin receivereitä, kun Jypeli ja Xamarin eivät ole ajan tasalla.

Lisää MainActivity luokkaan seuraava koodi:

public override Intent RegisterReceiver(BroadcastReceiver receiver, IntentFilter filter)
{
    if (Build.VERSION.SdkInt >= BuildVersionCodes.Tiramisu)
    {
        return base.RegisterReceiver(receiver, filter, ReceiverFlags.NotExported);
    }
    return base.RegisterReceiver(receiver, filter);
}

Tämä lisää kaikkiin ohjelman tekemiin RegisterReceiver()-kutsuihin Android SDK 33:n ja sitä uudempien vaativan parameterin.

Jos saat käynnistysvaiheessa seuraavan virheen, ylempi todennäköisesti puuttuu tai on väärin sovellettu:

Java.Lang.SecurityException: 'com.jyujanip.heitetaantikkaa: One of RECEIVER_EXPORTED or RECEIVER_NOT_EXPORTED 
should be specified when a receiver isn't being registered exclusively for system broadcasts'

1.1 Android-API

• Visual Studiossa valitse ylävalikosta Tools -> Android -> Android SDK Manager.
• Etsi listasta Android SDK Platform 34, avaa lisävalinnat +-merkistä, laita rasti ruutuun kohtaan Android SDK Platform 34
• Paina Apply changes.

2. Pelin ajaminen emulaattorissa

Testaamisen nopeuttamiseksi on suositeltavaa käyttää emulaattoria pelin ajamiseen, eikä välttämättä oikeaa puhelinta.

Voit luoda uuden virtuaalisen puhelimen Visual Studiosta Tools > Android > Android Device Manager.

Ei ole erityistä väliä minkä puhelimen luot. Oleellisin ero Base Device asetuksella on puhelimen fyysinen koko, eli minkä kokoinen ja resoluutioinen näyttö siinä on. Ainakin Pixel 5 SDK versiolla 34 toimii ohjelman ajamiseksi.

Prosessor asetuksena kannattaa pitää oletus, eli todennäköisesti x86 64.

OS kohdassa kannattaa ottaa API 34, mutta tälläkään ei ole erityisen suurta merkitystä, kunhan se on kuitenkin kohtuullisen uusi versio.

Muihin asetuksiin ei kannata koskea ellei tiedä mitä tekee.

Nyt Visual Studion Run nappulassa näkyy että millä laitteella peli ajetaan. Voit vaihtaa laitetta siinä olevasta pienestä alaspäin osoittavasta nuolesta.

Ensimmäisen kerran kun käynnistät virtuaalipuhelimen, siinä kestää hetki. Aivan kuten oikealla puhelimellakin.

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ä.

Tämän jälkeen voit yksinkertaisesti vain kytkeä puhelimesi tietokoneeseen USB-kaapelilla, sallia puhelimessa USB-debuggaamisen, käynnistää Visual Studion ja avata 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ä.

4. Vinkkejä ja ohjeita

4.1 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.

https://tim.jyu.fi/view/kurssit/jypeli/ohjaimet/ohjainten-lisays#puhelimen-kosketusn%C3%A4ytt%C3%B6

4.2 Peli vaakatasoon

Muokkaa MainActivity-luokan Activity-atribuuttia: ScreenOrientation = ScreenOrientation.Landscape

4.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.

4.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).

5. Julkaiseminen Google Play:hin

ks. Julkaiseminen kauppapaikassa

5.1 Peli ladattavaksi muille Play Storen kautta

Pelistä/ohjelmasta/appistä täytyy ensin tehdä testiversio Play Storeen, ennen kuin Google sallii sen julkisen jakamisen (julkaisun).

1. Kopioi linkki testiin liittymiseen: "How testers join your test"-otsikon alta, kun selaat Play Consolessa "Test and release" -> "Testing" -> "Internal testing" ja sieltä "Testers"-tabi.

2. Tämän lisäksi salli lataaminen kenelle vain, joilla on linkki: "Test and release" -> "Testing" -> "Internal app sharing" ja sieltä "Manage testers"-otsikon alta, "Anyone you shared the link with can download"

3. Nyt kaikki, jotka ovat liittyneet testiin Google-käyttäjällään kopioidun linkin kautta, voivat ladata pelin.