(P) Muistipelin paluu¶

Alkukommentti ja palautteen kieli¶

Samoin kuin aikaisemmin tässäkin projektissa vaaditaan alkukommentti. Mallia voit katsoa ensimmäisen projektin tehtävänannosta (4.6 (P) Muistipeli). 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.

Tehtävänanto¶

Tehtävänäsi on toteuttaa graafisella käyttöliittymällä varustettu muistipeli, jota voi pelata (suunnilleen) muistipelin sääntöjen mukaisesti. (Tarkemmat vaatimukset kerrotaan alempana.)

Pelin pitää toimia vaihtelevalla määrällä kortteja. Korttien määrä joko kysytään käyttäjältä, tai sitä varten ohjelmassa voi olla vakio, jota muuttamalla korttien määrää voi vaihdella. Pelaajien määrä voi olla kiinteä (vähintään kaksi), tai se voi vaihdella kuten 4-projektin muistipelissä. Halutessasi voit käyttää kyseisen projektin Card- ja Player-luokkia, jos tunnet niistä olevan hyötyä. Niitä saa myös vapaasti muutella.

Pelikortit asetellaan pelilaudalle samoin kuin 4-kierroksen projektissa, eli rivien ja sarakkeiden määrien pitää olla mahdollisimman lähellä toisiaan (vrt. tehtävä 2.3.2 Läheisimmät tekijät, jonka koodi löytyy 4-kierroksen muistipelin pohjakoodista).

Kortit asetellaan pelipöydälle satunnaisessa järjestyksessä. Tarvitset siis satunnaislukugeneraattoria. Voit tehdä arpomisen samalla tavalla kuin 4-kierroksen projektissa, tai voit toteuttaa jonkin paremman tavan arpoa kortteja. (Huomaa myös vähän alempana oleva kohta Satunnaislukugeneraattorista.)

Kortteja pitää pystyä kääntämään jollakin tavalla. Tässäkin tehtävässä voit numeroida rivit ja sarakkeet, jolloin käyttäjä antaa yhteensä neljä lukua (kahden kortin “koordinaatit”). Syötteen lukemiseen voi käyttää mitä tahansa käyttöliittymäkomponenttia (QLineEdit, QSpinBox, QDoubleSponBox jne.) tai näppäinkomentoja. Ehkä luontevin toteutustapa on kuitenkin määritellä kortit painonapeiksi, jolloin kortin voi kääntää klikkaamalla sitä. Silloin sinun pitää jotenkin huolehtia siitä, että vain korkeintaan kaksi korttia saa kerrallaan olla näkyvissä.

Kortin kääntäminen tarkoittaa sitä, että sen kuvapuoli tulee näkyviin. Kuviksi riittää kirjaimet kuten 4-kierroksen projektissa. Lisäksi korttien pitää olla vähintäänkin eri värisiä eri puolilta, jolloin kääntäminen tarkoittaa myös värin vaihtumista.

Jos käännetyt kortit eivät olleet toistensa parit, ne käännetään takaisin piiloon. Jos ne olivat parit, ne poistetaan pelipöydältä, ja kyseisen pelaajan pistesaldo kasvaa. Poistaminen voi tarkoittaa sitä, että kortti oikeasti häviää tai että kortti muuttuu jotenkin näkymättömämmäksi, jolloin esimerkiksi sen väri haalistuu tai muuttuu lähemmäksi pelilaudan väriä.

Ohjelmassa korttien kääntäminen saattaa tapahtua liian nopeasti, jolloin pelaajat eivät pysty näkemään, mitkä kuvat (kirjaimet) korteissa olivat. Tästä syystä pelissä voi olla oma painonappinsa korttien sulkemista varten, jolloin pelaaja voi katsoa kortteja haluamansa ajan.

Toinen vaihtoehto on käyttää viivästystä, jolloin kortit pidetään jonkin tietyn ajan näkyvissä, ennen kuin ne käännetään taas piiloon. Tähän tarvitset ajastinta. Sen ei kuitenkaan tarvitse olla luokan attribuutti, kuten Ajastin-harjoituksessa. Yksinkertaisemmin toimintoa pystyy viivästämään seuraavalla koodilla:

QTimer::singleShot(DELAY, this, SLOT(wait()));

missä DELAY on kokonaislukuvakio, joka kertoo viivästysajan millisekunteina, ja wait on toteuttamasi slot-funktio, joka sisältää viivästetyn toiminnon. Muista laittaa slot-funktion esittely otsikkotiedostosssa kohtaan private slots. Voit myös käyttää muita nimiä kuin yllä olevassa koodissa. Huomaa, että viiveen määrälle on parempi käyttää nimettyä vakiota (kuten tässä DELAY) eikä taikanumeroa.

Pelin edetessä tai viimeistään pelin loputtua kerrotaan tilanne eli kunkin pelaajan keräämien korttien/parien määrät. Pelin edetessä tilanteen voi näyttää niin, että kun löydetyt parit häviävät pelipöydältä, ne siirtyvät pelaajan korttipinoon. Korttipinon voi piirtää esimerkiksi QGraphicsView-alueelle (ohuina/matalina) suorakulmioina vastaavalla tavalla, kuin liikkuvan ympyrän esimerkiksi piirrettiin ympyrä. Sitä mukaa kun pelaaja saa uusia pareja, hänen pinoonsa piirretään uusia suorakulmioita.

Korttien sijoittelussa joudut käyttämään hieman matematiikkaa (laskentoa). Tarvittava matematiikka on kuitenkin hyvin yksinkertaista.

Satunnaislukugeneraattorista¶

Tällä kurssilla käytetyillä satunnaislukugeneraattoreilla on sellainen ominaisuus, että (hyvin suuria siemenarvoja lukuunottamatta) ensimmäinen arvottava luku on valitun lukuvälin alaraja. Jos siis satunnaislukugeneraattori on funktion paikallinen muuttuja, ja sillä arvotaan vain yksi luku kutsukertaa kohti, arvottava luku on melkein aina sama.

Jotta satunnaislukugeneraattori toimisi paremmin, se kannattaa laittaa MainWindow-luokan attribuutiksi. Sama pätee jakaumamuuttujalle (distribuutiolle), joka määrää lukuvälin. Nämä attribuutit alustetaan rakentajassa, minkä jälkeen yksi satunnaisluku kannattaa arpoa turhaan. Näin voidaan välttää se, että ensimmäiseksi arvottava luku olisi aina sama.

Satunnaislukugeneraattorin siemenarvona voit käyttää pelkästään tietokoneen kelloa, ellet sitten halua lisätä käyttöliittymäkomponenttia, jolla käyttäjä voi antaa siemenarvon. Testaamisen aikana on hyvä käyttää jotakin tiettyä kiinteää siemenarvoa, jotta saat toistettua samanlaisen korttijaon useita kertoja.

Korttien kirjaimien arpomisen voit tehdä haluamallasi tavalla, mutta yksi mahdollinen tapa on seuraava. Merkitään korttien määrää n:llä. Ota käyttöön merkkijono, ja sijoita sille arvoksi “AABBCC…” niin, että merkkien määrä on n. Sekoita merkkijono algoritmikirjaston funktiolla shuffle, kuten näytettiin kohdassa 5.3 ja kuten mahdollisesti teit tehtävässä 5.3.1 Sekavaa tekstiä.

Minimivaatimukset¶

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

• Pelaajien määrä saa olla kiinteä, mutta sen pitää olla vähintään kaksi.
• Pelissä näkyy, kuka pelaaja kulloinkin (tai seuraavaksi) on vuorossa.
• Peliä pitää pystyä pelaamaan vaihtelevalla määrällä kortteja. Kuitenkin korttien määrällä voi olla jokin yläraja, joka saa olla vähintään 20.
  • Korttien määrä joko kysytään käyttäjältä tai ohjelmassa on vakio, jonka arvoa muuttamalla peliä voi pelata eri korttimäärillä.
• Korttien pitää olla graafisia käyttöliittymäkomponentteja (esim. painonappeja tai suorakulmioita), ei pelkästään tekstiä.
• Kortit asetellaan niin, että korttien määrät vaaka- ja pystyriveillä ovat mahdollisimman lähellä toisiaan.
• Kortteja pitää pystyä kääntämään jollakin tavalla.
• Kun kortteja käännetään, näkyvissä saa olla enintään kaksi korttia kerrallaan.
• Korttien kuviksi riittävät kirjaimet. Jokaista erilaista kuvaa/kirjainta on kaksi kappaletta. Kortin taustapuoli saa olla tyhjä, mutta kuva- ja taustapuolten pitää olla vähintäänkin eri väriset.
• Kun kaksi korttia käännetään näkyviin, niiden kuvapuolten pitää olla näkyvissä riittävän kauan.
  • Tämän voi toteuttaa joko niin, että kortit käännetään takaisin viiveellä tai että pelissä on oma painonappi sulkemista varten.
• Viimeistään pelin lopussa kerrotaan/näytetään lopputilanne.
• Pelin toiminnallisuus pitää määritellä ja dokumentoida. Dokumentin pitää sisältää käyttöohjeet, esimerkiksi millaiset säännöt pelissä on. Lisäksi 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 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 ihminen, 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ä sanottiin, 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. Pelissä on vaihteleva määrä pelaajia, ja pelaajien määrä kysytään käyttäjältä. Pelaajat voi nimetä esim. Pelaaja1, Pelaaja2 jne. (10 p.)
2. Käyttäjä voi antaa pelaajille myös nimet. (5 p.)
3. Pelitilanne esitetään graafisesti esimerkiksi niin, että pelissä on QGraphicsView-komponentti, jossa on tilaa kunkin pelaajan korttipinoille. Korttipino kasvaa sitä mukaa, kun pelaaja löytää pareja. (10 p.)
4. Sen lisäksi, että kerrotaan, kuinka monta korttia/paria kukin pelaaja on saanut, kerrotaan myös, mitkä kortit kukin pelaaja on saanut. (5 p.)
5. Pelissä käytetty aika lasketaan. Tälle on kaksi vaihtoehtoa, joista vain toinen arvostellaan:
   1. Käytetty aika ilmoitetaan käyttäjälle pelin loputtua. (5 p.)
   2. Pelin aikana kerrotaan siihen mennessä kulunut aika. (10 p.)
6. Pelin päätyttyä (tai muutenkin) peliasetelman voi palauttaa alkutilanteeseen, jolloin käyttäjä voi aloittaa uuden pelin käynnistämättä ohjelmaa uudelleen. (10 p.)
7. Peli sisältää tulostaulun, johon tallentuu pelaajan saamat pisteet. Tallennetut tiedot säilyvät pelistä toiseen (eli ne tallennetaan tiedostoon). Tulostauluun voidaan tallentaa usean eri pelaajan pisteet, joten pelin alussa käyttäjä voi (ainakin halutessaan) antaa käyttäjänimensä. (10 p.)
8. Korttien taustapuolella on kuva (kaikissa korteissa samanlainen). (10 p.)
9. Kirjainten sijasta korttien kuvapuolella on oikea kuva. (20 p.)
   • Peliähän pitää pystyä pelaamaan vaihtelevalla määrällä kortteja, mutta toisaalta korttien määrälle saa asettaa jonkin ylärajan. Tarvittavien kuvien määrä on siis yläraja jaettuna kahdella. Jos kortteja on käytössä ylärajaa pienempi määrä, käytät arvonnassa vain osan kuvista.

Jos kahden viimeisen lisäominaisuuden toteuttamisessa otat png-kuvia internetistä, varo rikkomasta tekijänoikeuksia.

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

Työn testaaminen ja käyttöohje¶

Tätä projektia ei automaattitestata, vaan olet itse vastuussa ohjelmasi riittävän kattavasta testaamisesta. Työ pitää silti palauttaa Plussaan, jotta saisit sen arvioitavaksi. Huomaa, että ohjelman pitää toimia Linux-desktopilla.

Luo työhakemisoon 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ä.

Vihjeitä¶

• 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 mahdolliseen graphicsView-widgettiin, jonka sijainti kannattaa määrätä koodissa (samoin kuin liikkuvan ympyrän esimerkissä). Yritä sijoittaa widgetit niin, että visuaalinen ulkoasu on mahdollisimman hyvä valmiissa käyttöliittymässä.

• 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 12 kohta Widgeteistä).
• 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 varoituksitta.) 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 erikoisvaatimukset täyttävistä töistä viimeisen määräajan puitteissa tehdyn commitin 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 Tyyliseikkoja kohta Olio-ohjelmointi).
  • 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, ja huomaa, että kohtaa 10.1 on päivitetty).
• Ohjelmointityyli: -20-0 pistettä:
  • Muuttujat ja funktiot nimetty selkeästi ja kuvaavasti.
  • Ohjelmassa on käytetty imettyjä vakioita taikanumeroiden 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 mahdollista) 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 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 11.