(P) Yatzy¶

Alkukommentti ja palautteen kieli¶

Samoin kuin aikaisemmin tässäkin projektissa vaaditaan alkukommentti. Mallia voit katsoa ensimmäisen projektin tehtävänannosta (4.5 (P) Tammi). Riittää kirjoittaa alkukommentit niihin tiedostoihin, joihin teet muutoksia.

Kuten edellisissä projekteissa palautteen kieli valitaan palautuslaatikossa (tämän sivun lopussa). Kielivalinta määräytyy ainoastaan sen perusteella, minkä kielivalinnan olet tehnyt viimeisimmän palautuksen palautuslaatikossa.

Pelin säännöt¶

Tässä kohdassa kuvataan pelin säännöt sellaisina, kuin ne on tarkoitus toteuttaa ohjelmaan (tai on jo toteutettu koodipohjassa). Säännöt voivat poiketa oikeasta yatzy-pelistä.

Yatzy-pelissä on käytössä viisi noppaa, joita pelaajat heittävät haluamassaan järjestyksessä. Kullakin pelaajalla on aluksi kolme heittovuoroa, mutta niitä kaikkia ei ole pakko käyttää. Heittovuoroja ei ole myöskään pakko käyttää vuorotelleen, vaan pelaaja voi esimerkiksi käyttää kaikki heittovuoronsa peräkkäin (antamatta muille pelaajilla välillä vuoroa).

Pelaaja voi lukita haluamansa nopat, jolloin vain lukitsemattomat nopat heitetään uudelleen seuraavalla heittovuorolla.

Kun kaikki pelaajat ovat käyttäneet vuoronsa tai kun peli päätetään lopettaa (kesken), ohjelma kertoo, kuka voitti tai keiden pelaajien kesken tuli tasapeli.

Viiden nopan sarjoilla on seuraava paremmuusjärjestys (parhaasta huonoimpaan):

1. yatzy eli kaikilla viidellä nopalla sama silmäluku
2. neloset eli täsmälleen neljällä nopalla sama silmäluku
3. täyskäsi eli täsmälleen kolmella nopalla sama silmäluku ja myös kahdella lopulla nopalla sama silmäluku
4. suora eli silmäluvut 1, 2, 3, 4 ja 5 tai silmäluvut 2, 3, 4, 5 ja 6
5. kolmoset eli täsmälleen kolmella nopalla sama silmäluku
6. kaksi paria eli täsmälleen kahdella nopalla sama silmäluku ja myös täsmälleen kahdella muulla nopalla sama silmäluku
7. pari eli täsmälleen kahdella nopalla sama silmäluku
8. ei mitään edellä mainituista.

Edellä lueteltujen kohtien sisällä ei ole paremmuusjärjestystä, esimerkiksi 1-pari on yhtä hyvä kuin 6-pari.

Edellä kuvatusta paremmuusjärjestyksestä ei tarvitse sen enempää välittää, sillä se on valmiiksi koodattu Functions-metodin funktioihin.

Tehtävänanto¶

Tehtävänäsi on toteuttaa graafinen käyttöliittymä yatzy-peliin, jonka toimintalogiikka on annettu pohjakoodissa. Käyttöliittymäkoodi pitää toteuttaa nyt graafisesti, eli:

• heitettyjen noppien silmälukujen näyttäminen
• mahdollisuus heittää uudelleen tai antaa vuoro seuraavalle pelaajalle
• pelitilanteen näyttäminen (esimerkiksi kuka pelaaja on vuorossa ja kuinka monta vuoroa hän on käyttänyt tai montako vuoroa on jäljellä).

Näiden lisäksi pelissä pitää olla:

• mahdollisuus lukita noppia
• mahdollisuus aloittaa peli uudestaan (reset)
• ajastin, joka kertoo tähän mennessä käytetyn ajan.

Voit toteuttaa käyttöliittymän (peli-ikkunan) haluamallasi tavalla. (Peli-ikkunalla tarkoitetaan pääikkunaa, eli yksi ikkuna riittää.) Nopat voit toteuttaa esimerkiksi etiketteinä (QLabel) tai painonappeina (QPushButton) tai QGraphicsScene-ominaisuutena.

Pohjakoodin mukana saat noppien kuvat (png-tiedostoina). Voit käyttää niitä samaan tapaan kuin on tehty hedelmäesimerkissä.

Arvioinnissa kiinnitetään huomiota siihen, miten hyvin käyttöliittymäkoodi on erotettu pelin varsinaisesta toimintalogiikasta. Toimintalogiikkahan on jo (pääosin) valmiiksi toteutettu, joten periaatteessa riittää, että kirjoitat kaiken käyttöliittymäkoodin luokkaan MainWindow. Todennäköisesti tarvitset kuitenkin lisää funktioita muuallekin. Jos lisäämäsi funktiot eivät mitenkään käsittele käyttöliittymää, ne kannattaa lisätä luokkaan GameEngine. Huomaa, että koodin tulisi olla mahdollisimman lähellä sitä dataa, jota se käsittelee. Kun noudatat tätä periaatetta, voi helposti käydä niin, että jotakin toimintoa varten joudut lisäämään uuden metodin molempiin edellä mainituista luokista.

Luokan GameEngine metodeita voit tarvittaessa siirtää yksityisistä julkisista, tai voit muuttaa void-metodin palauttamaan jonkin sopivan tyyppisen arvon. Voit myös lisätä uusia metodeita ja attribuutteja tai muita muuttujia. Huolehdi kuitenkin siitä, että ei-graafinen peli toimii kuten ennenkin.

Graafisen ja ei-graafisen pelin ei kuitenkaan tarvitse toimia keskenään samalla tavalla. Tämähän ei edes voisi olla mahdollista, koska ei-graafisessa pelissä ei ole lukitusmahdollisuutta mutta graafisessa on.

Minimivaatimukset¶

Toteuttamalla minimivaatimukset voit saada työstä maksimissaan 50 pistettä. Ainakin seuraavat ominaisuudet pitää toteuttaa:

• Pelin pelaamiseksi peli-ikkuna ja heitettyjen noppien silmäluvut näytetään käyttäjälle.
  • Näiden pitää olla graafisia käyttöliittymäkomponentteja (esim. painonappeja/suorakulmioita/neliöitä/etikettejä), ei pelkästään tekstiä.
  • Riittää saada näkyviin noppien silmäluvut numeroina edellä mainittuihin käyttöliittymäkomponentteihin. Pohjakoodissa annettuja noppakuvia ei ole pakko käyttää (mutta niiden käyttämisestä saa lisäpisteitä, ks. Lisäominaisuudet).
• Pelaajien määrää pystyy säätämään, mutta riittää, että sen tekee vaihtelemalla ohjelmakoodissa olevan vakion arvoja. Muista kertoa dokumentissa, mikä tämän vakion nimi on ja mistä se löytyy.
• Käyttäjän pitää pystyä valitsemaan uusi heitto tai vuoron antaminen seuraavalle pelaajalle.
  • Tämän voit tehdä esim. painonappia klikkaamalla, näppäinkomennoilla tms.
• Käyttäjä pystyy lukitsemaan noppia.
• Pelitilanne pitää näyttää käyttäjälle (kuka pelaaja on vuorossa, kuinka monta heittoa hän on tehnyt tai kuinka monta heittoa hänellä on jäljellä).
• Pelin pystyy aloittamaan uudelleen alusta (reset). Tämän tulee olla mahdollista pelin päätyttyä ja myös kesken pelin.
• Peli kertoo käytetyn ajan sekä voittajan tai pelaajat, joiden kesken tuli tasapeli.
• Pelin toiminnallisuus pitää määritellä ja dokumentoida. Dokumentin pitää sisältää käyttöohjeet pelin pelaamiseen, esimerkiksi millaisia riippuvuuksia eri toiminnoilla on. Dokumentista pitää tulla ilmi, mitä tapahtuu ja mitä voi tapahtua eri tilanteissa. Dokumentissa pitää kuvata myös ohjelman rakenne ja tehdyt suunnittelupäätökset.

Yllä olevat kohdat on siis pakko toteuttaa jollakin tavalla toimivasti. Mitä paremmin olet toteuttanut ne ja mitä paremmalla ohjelmointityylillä, sitä enemmän saat pisteitä.

Saadaksesi enemmän pisteitä kiinnitä huomiota myös pelin käyttäjäystävällisyyteen. Voit esimerkiksi säädellä, ovatko painonapit tai muut käyttöliittymäkomponentit käyttökelpoisia vai eivät (enabled/disabled). Tähän tarkoitukseen luokassa QWidget on slotit setEnabled ja setDisabled.

Erityisen tärkeää on kiinnittää huomiota pelin vakauteen (robustness). Tällä tarkoitetaan sitä, että ohjelma toimii järkevästi (eikä esimerkiksi kaadu), vaikka käyttäjä tekisi jotakin typerää. Esimerkiksi painonappien tapauksessa voit muuttaa käyttökelvottomiksi ne painonapit, joita ei pysty järkevästi käyttämään kyseisessä tilanteessa. Yritä muutenkin etukäteen miettiä, millaisia käyttötilanteita voisi olla. Testaa ohjelmaa kuvittelemalla, että olisit pahantahtoinen vihollinen, joka haluaa saada ohjelman kaatumaan. Jos onnistut tässä, korjaa koodiasi niin, että tällainen tilanne tulee estettyä.

Myös nimeämiskäytäntöihin kiinnitetään huomiota. Tosin Qt:n automaattisesti generoimat nimet eivät aina noudata tyylisääntöjä. Esimerkiksi jos slot generoidaan automaattisesti, nimeksi voi tulla vaikkapa on_pushButton_clicked. Tämä ei ole hyvän ohjelmointityylin mukaista, koska siinä on käytetty molempia tapoja erotella sanoja: alaviivaa ja CamelCase-tyyliä. Käytä kuitenkin itse nimeämissäsi tunnisteissa yhtenäistä tyyliä.

Lisäominaisuudet¶

Kuten edellä kerrottiin, minimiominaisuudet toteuttamalla voit saada maksimissaan 50 pistettä. Toteuttamalla lisäominaisuuksia voit saada maksimissaan toiset 50 pistettä. Vain toimivista ja dokumentoiduista lisäominaisuuksista saa pisteitä, eli myös lisäominaisuudet pitää dokumentoida.

Arvioidessaan projekteja assistentit lisäävät bonuspisteet Plussan myöhempään osioon. Assistentit kiinnittävät huomiota sekä lisäominaisuuksien toimivuuteen että niiden ratkaisutapaan eli siihen, miten tyylikkäästi ratkaisu on toteutettu koodissa.

Esimerkkejä lisäominaisuuksista on lueteltu alla (suuntaa antavat maksimipisteet on kerrottu suluissa):

1. Nopat on toteutettu pohjakoodissa annetuilla png-kuvilla. (10 p.)
   • Tähän voit katsoa mallia hedelmäesimerkistä.
   • Ole tarkkana, että kuvat tulevat mukaan oikealla tavalla, sillä muuten et saa ominaisuudesta pisteitä. Ei riitä, että kuvat toimivat omalla koneellasi paikallisesti, vaan niiden pitää toimia myös assistenteilla. Voit varmistua tästä toimimalla alla olevan kohdan Noppakuvien käyttö oikealla tavalla mukaisesti.
2. Arvotut nopat eivät vain ilmesty näkyviin, vaan niiden pyöriminen on animoitu. (20 p.)
   • Tämän voit toteuttaa esimerkiksi ajastimen avulla niin, että nopat arvotaan vaikkapa kymmenen kertaa (ja viimeisin arvonta jää voimaan). Tällöin metodia, joka piirtää noppakuvat (usean eri arvonnan tuloksena), kutsutaan kymmenen kertaa. Ajastimen avulla saat hidastettua näitä metodikutsuja, jotta käyttäjä pystyy havaitsemaan noppien vaihtumisen (pyörimisen). (Tämä on eri ajastin kuin minimivaatimuksissa mainittu.)
3. Käyttäjä voi asettaa pelaajien määrän käyttöliittymässä. (5 p.)
4. Pelaajille voi antaa nimet. (5 p.)
5. Pelissä on jonkinlainen pistelasku, jonka voit itse valita. Muista dokumentoida pistelaskutapasi. (15 p.)
6. Peli sisältää tulostaulun, johon tallentuu pelaajien saamat tulokset (pisteet). Tallennetut tiedot säilyvät pelistä toiseen (eli ne tallennetaan tiedostoon). (10 p.)
7. Käyttöliittymän taustaväri vaihtuu, kun peli loppuu. Uudelleenaloituksessa (reset) taustaväri palautuu ennalleen. (5 p.)
8. Pelissä on pause-nappula, jolla ajanoton saa pysäytettyä, kun peli on käynnissä. Tällöin peli lakkaa esim. vastaamasta näppäinkomentoihin. Käyttäjälle ilmoitetaan jotenkin, että pause on meneillään. (10 p.)

Voit myös itse ehdottaa haluamaasi lisäominaisuutta. Ehdotukset on tehtävä vähintään viikko ennen työn deadlinea. Lisäominaisuutta voi ehdottaa harjoitustuntien päätteeksi tai lähettämällä viestiä kurssin sähköpostiosoitteeseen. Kurssin henkilökunnalla on oikeus hyväksyä/hylätä ehdotettu lisäominaisuus ja määrätä sille maksimipisteet.

Huomaa, että toteuttamalla kaikki edellä luetellut ominaisuudet näyttäisi siltä, että voisit ansaita enemmän kuin 50 pistettä. Kuitenkin voit enintään saada 50 pistettä, sillä jos olisit saamassa enemmän, pisteesi vähennetään 50 pisteeseen. Silti on kannattavaa yrittää toteuttaa ominaisuuksia niin paljon, kuin pystyt, sillä todennäköisesti et saa kaikista lisäominaisuuksista täysiä pisteitä. (Huomaa, että kurssin loppupuolella projektien arvostelukriteerit ovat tiukempia kuin alkupuolella.)

Noppakuvien käyttö oikealla tavalla¶

Jotta saisit noppakuvat käyttöön oikealla tavalla (eli jotta saisit pisteitä kyseisestä lisäominaisuuksista), toimi seuraavalla tavalla:

• Klikkaa projektin nimeä (yatzy_gui) hiiren oikean puoleisella napilla. Avautuvasta valikosta valitse Add New … -> Qt -> Qt Resource File.
• Add Prefix (nimeksi esim. pictures)
• Paina Add Files.

Ohjeet kuvina:

Vaihe 1

Vaihe 2

Vaihe 3

Vaihe 4

Vaihe 5

Työn testaaminen ja käyttöohje¶

Tässä projektissa olet itse päävastuussa ohjelmasi riittävän kattavasta testaamisesta. Työ pitää silti palauttaa Plussaan, jotta saisit sen arvioitavaksi. Huomaa, että ohjelman pitää toimia Linux-desktopilla.

Plussa-palautuksessa tarkistetaan, että ohjelma kääntyy, jolloin siitä saa yhden pisteen. Nollan pisteen palautus ei mene assareiden arvioitavaksi.

Luo työhakemistoon tiedosto nimeltä instructions.txt ja kirjoita siihen lyhyt käyttöohje, joka kuvaa pelin säännöt ja ohjelman toimintaa riittävällä tarkkuudella, että assistentti pystyy testaamaan työtä ja arvioimaan sen. Katso minimivaatimuksista, mitä muuta dokumentin pitää sisältää. Muista lisätä tämä tiedosto myös versionhallintaan.

Jos käytät versionhallintaa komentoriviltä, dokumenttitiedoston saa versionhallintaan kuten minkä tahansa muunkin tiedoston. Jos käytät versionhallintaa Qt:n kautta, saat lisättyä dokumenttitiedoston Qt-projektiin seuraavasti. Qt:n editointitilan vasemmalla puolella on lueteltu projektiin kuuluvat tiedostot. Klikkaa hiiren oikealla näppäimellä tiedostolistan yläpuolelta projektin nimeä ja valitse avautuvasta valikosta Add Existing Files ... (jos tiedosto instructions.txt on jo olemassa) tai Add New ... (jos olet vasta alkamassa kirjoittaa kyseistä tiedostoa).

Jos olet toteuttanut lisäominaisuuksia, mutta et ole maininnut niitä tiedostossa instructions.txt, et saa lisäominaisuuksista pisteitä.

Yleisiä vihjeitä¶

• Jotta pelissä olisi mahdollista heittää vain lukitsemattomia noppia, voit toteuttaa MainWindow-luokkaan uuden roll-metodin, vaikka sellainen onkin jo GameEngine-luokassa.

• Kannattaa tutustua tämän kierroksen esimerkkeihin. Niiden koodista löytyy useita kohtia, joita voit hyödyntää tässä projektissa.

• Kun lisäät widgettejä tiedostoon mainwindow.ui, ne eivät välttämättä asemoidu oikein suhteessa mahdollisiin koodissa luotaviin widgetteihin. Yritä sijoittaa widgetit niin, että visuaalinen ulkoasu on mahdollisimman hyvä valmiissa käyttöliittymässä.

• Vaikka lisäisitkin widgettejä Qt Designerissa (mainwindow.ui), säädä niiden ominaisuudet koodissa, sillä Qt Designerin säädöt eivät välttämättä tule näkyviin oikein ajettavassa ohjelmassa.

• Peliä toteuttaessasi joudut todennäköisesti turvautumaan Qt:n dokumentaatioon. Sieltä löytyy hyödyllisiä funktioita erilaisten ominaisuuksien toteuttamiseen.

• Kannattaa hyödyntää versionhallintaa myös kokeiluissa. Kun edellinen toimiva versio ohjelmakoodista on tallennettuna keskustietovarastoon, voit huoletta tehdä suurempiakin kokeiluita, kun tiedät, että edellisen version saa aina palautettua. Tämä onnistuu seuraavasti (kullekin muutetulle tiedostolle):

  • Qt:ssa: Tools -> Git -> Current File -> Undo Unstaged Changes / Undo Uncommitted Changes
  • Komentoriviltä: git checkout – <tiedoston nimi>

  Lisätietoa löytyy Plussan Git-kurssilta.

Erityisvaatimukset¶

Seuraavia vaatimuksia on noudatettava, mikäli haluaa työstä hyväksytyn arvosanan:

• Ohjelmassa ei saa olla muistinhallintaan liittyviä virheitä. Kannattaa siis suorittaa valgrind.
  • Jos varaat muistia komennolla new, muisti pitää vapauttaa komennolla delete, ellei vapauttaminen tapahdu parent-child -mekanismin kautta (ks. kierroksen 11 kohta Widgeteistä).
• Ohjelmassa pitää käyttää annettua koodipohjaa, eli pelin pitää perustua siihen.
• Vain STL-kirjaston säiliöt sallitaan, ei esim. Boost-kirjaston.

Arviointi¶

Jotta työ päätyisi assistenttien arvioitavaksi, se pitää palauttaa Plussaan, ja sen pitää läpäistä automaattitestit. (Tässä tapauksessa automaattitestit tarkistavat vain sen, että ohjelma kääntyy.) Jos saat automaattitesteistä 0 pistettä, myös lopullinen pistemääräsi on 0, eikä työ mene assistenttien arvioitavaksi.

Assistentti arvioi ja pisteyttää automaattitestit läpäisseistä (= 1 p) sekä tehtävänannon erityisvaatimukset täyttävistä töistä viimeisimmän Plussa-palautuksen, joka on tehty määräajan loppuun mennessä, seuraavien arviointikriteerien mukaan:

• Toteutetun ohjelman toiminnallisuus ja käyttöohje 0-10 pistettä:
  • Kaikki minimivaatimuksissa kerrotut ominaisuudet on toteutettu, ja ne toimivat.
  • Ohjelma ei kaadu.
  • Käyttöohjeessa on kerrottu pelin säännöt sekä kuvattu toteutetut lisäominaisuudet. Käyttöohje on kirjoitettu riittävän selvästi, että assistenttien on helppo sitä ymmärtää.
  • Ohjelma toimii käyttöohjeen mukaisesti.
• Ratkaisun yleisperiaate: 0-30 pistettä:
  • Tehtävän osaamistavoitteet on saavutettu.
  • Ohjelmakoodi on jaettu funktioita, luokkia ja/tai metodeita käyttäen loogisiksi kokonaisuuksiksi, jotka ovat sopivan pituisia.
  • Jos luokkia ja olioita on käytetty, ne on toteutettu olio-ohjelmoinnin periaatteita noudattaen (ks. 4-kierroksen Tyyliseikoista kohta Olio-ohjelmointi). Käyttöliittymä on erotettu pelin toimintalogiikasta.
  • Tietorakenne ei sisällä toisteista tietoa eikä turhaa tietoa. Valittuja tietorakenteita on käytetty järkevästi.
  • Ohjelmakoodi ei sisällä turhaa toisteisuutta eikä muutakaan turhaa.
  • Ohjelmakoodi ei sisällä tarpeettomia rajoitteita tai oletuksia tai muita väkinäisiä ratkaisuita.
  • Ohjelmarakenteet on toteutettu helposti ymmärrettäviksi.
  • Ohjelmakoodissa ei ole käytetty globaaleja muuttujia (globaalit const-vakiot ovat OK).
  • Ohjelman toimintaa ei lopeteta exit-funktiota käyttäen.
  • Ohjelmassa ei ole muistinhallintaan liittyviä virheitä (suorita valgrind)
• Ohjelmointityyli: -20-0 pistettä:
  • Muuttujat ja funktiot nimetty selkeästi ja kuvaavasti. Nimeämisessä on käytetty vain yhtä kieltä, ei esim. suomea ja englantia sekaisin.
  • Ohjelmassa on käytetty imettyjä vakioita taikalukujen sijasta.
  • Ohjelmakoodi on asemoitu siististi.
  • Ohjelmakoodirivit ovat enintään 80 merkkiä pitkiä.
  • Jokaisen itse kirjoittamasi/editoimasi tiedoston alussa on kommentti, josta käy ilmi tiedoston tarkoitus, nimesi, opiskelijanumerosi ja muut tarvittavat tiedot. (Tarvittaessa katso mallia ensimmäisen projektin tehtävänannosta.)
  • Jokaisen funktion/metodin alussa (otsikkotiedostossa jos sellainen on olemassa) on kommentti, joka kuvaa sen toiminnan, paluuarvon ja parametrit.
  • Kommentteja on muutenkin tarpeellisissa kohdissa.
  • Kommentit liittyvät toteutettuun ohjelmaan eivätkä johonkin sen vanhempaan versioon.
  • Kaikki kommentit on kirjoitettu samalla kielellä (fi/en), mutta kommentoinnissa saa käyttää eri kieltä kuin muuttujien ym. nimissä.
  • Kaikki muuttujat on alustettu.
  • Kääntäjä ei anna koodia käännettäessä varoituksia.
• Versionhallinnan käyttö: 0-10 pistettä:
  • Committeja on riittävä määrä.
  • Commit-viestien sisältö on selkeä ja kuvaava.

Huomaa yllä olevasta listasta, että tässä vaiheessa tyyliseikkojen oletetaan olevan opiskelijoilla hallussa. Enää et siis saa pisteitä tyylisääntöjen noudattamisesta, vaan niiden käyttämättä jättämisestä sakotetaan. Kannattaa siis tarkistaa, mitä tyyliasioista on kerrottu kierroksilla 4 ja 10.