Ylläpitodokumentti

Asdf

Helsinki 5.5.2008 Ohjelmistotuotantoprojekti HELSINGIN YLIOPISTO Tietojenkäsittelytieteen laitos Kurssi

581260 Ohjelmistotuotantoprojekti (6 ov)

Projektiryhmä Kuisma Sami Louhio Jaakko Rimpilä Raine Urtela Mika Vilhonen Vesa

Asiakas Pasanen Tomi, Teemu Saukonoja

Johtoryhmä Yrjänäinen Sampo Simola Kimmo

Kotisivu

http://www.cs.helsinki.fi/group/asdf

Versiohistoria

Versio Päiväys Tehdyt muutokset
1.0  15.4.2008 Dokumentti luotu
1.1  17.4.2008 Dokumenttia viimeistelty
1.2  2.5.2008 Lisatty Peliaulakuvauksia

Sisältö

1 Johdanto 1 1.1 Sanasto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 Ohjelmiston yleiskuvaus 3

3 Toteuttamatta jääneet toiminnallisuudet 4

4 Ohjelmiston toimintaympäristö ja käyttöönotto 5

5 Palvelin 6 5.1 Tietokanta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.2 Säikeistys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

6 Tiedonsiirto 8 6.1 JAXB, XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6.2 java.nio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6.3 Tietoliikenneprotokolla . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

6.3.1 Päivitys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 6.3.2 Kysely . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6.3.3 Vastaus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

6.4 Pokeripelissä käytetty protokolla . . . . . . . . . . . . . . . . . . . . . . 9

7 Pelilogiikka 10 7.1 Pokeripeli: GameModel . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 7.2 Pokerilogiikka . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

8 Asiakasohjelmisto 16 8.1 Peliaula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 8.2 Pelipöytä . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

9 Rajapintakuvaukset 20

Liitteet

1 Protokollakuvaukset 2 Asennusohje 3 Plugins tutorial

1 Johdanto

Asdf on Helsingin yliopiston tietojenkäsittelytieteenlaitoksen ohjelmistotuotantoprojektin 2008 kevään ryhmä, joka toteutti asiakkaan tilaaman yleiskäyttöisen pokeripalvelinohjelmiston. Tässä dokumentissa käydään läpi projektiryhmän tuottamaa ohjelmistoa, asennusta, ylläpitoa sekä ohjelmistoon liittyviä ominaisuuksia, ratkaisu- ja toteutusmalleja. Dokumentti on tarkoitettu ohjelmiston ylläpitoa varten. Projektissa keskityttiin toteuttamaan monipuolinen ja hyvin laajennettava palvelin-asiakas peliohjelmisto. Pokeripalvelin ja rajapinnat on toteutettu yleiskäyttöiseksi ja soveltuu sellaisenaan kaikkien mahdollisten vuoropohjaisten pelien tukemiseen, ja dokumentissa on painotettu ohjelmiston jatkokäyttöä sekä laajentamisen mahdollisuutta ja sen käytännön toteuttamista.

Projektin puitteissa ohjelmistoon toteutettiin palvelinohjelmisto, tietoliikenne sekä asiakasohjelmisto. Asiakasohjelmisto toteuttaa peliaulanäkymän sekä pokeripeleihin soveltuvan pelipöytänäkymän. Peliaula hakee dynaamisesti palvelimelta sinne toteutetut pelit ja mahdollistaa niihin liittymisen sekä Serverille kirjautumisen. Kaikki viestienvälitys palvelimen ja asiakasohjelmiston välillä on XML-skeemalla määritelty. Määrittelyistä luodaan pelien viestinvälityksen jälkeen pelien tarvitsemia luokkia JAXB-XML-sidontaa käyttäen.

Pokeripalvelin ohjelmiston tarkoitus on toimia yleiskäyttöisenä ympäristönä testattaessa erilaisia tekoälysovelluksia. Projektin puitteessa kuitenkin toteutettiin vain ympäristö ja rajapinnat Texas Hold’em pelaamiseen, sekä suoraviivainen toteutusmahdollisuus muille pokeripeleille. Rajapintojen suunnitteluun panostettiin erityisen paljon.

Ohjelmisto koostuu useista osajärjestelmistä, sekä useista valmiista projektissa hyödynnetyistä komponenteista. Luvussa 2 käydään läpi ohjelmiston yleiskuvaus. Luvussa 3 käydään läpi toteuttamatta jääneet toiminnallisuudet. Luvussa 4 kerrotaan ohjelmiston asennuksesta sekä käyttöönotosta. Luvuissa 5-8 käydään läpi ja kuvataan ohjelman komponentit. Komponentit on kuvattu ylläpitäjän ja/tai jatkokehittelijän tarvitsemalla tarkkuudella. Komponentteihin liittyvästä koodista löytyy yksityiskohtaiset kommentit ohjelman toiminnasta sekä Java-dokumentaatio kommentit. Luvussa 9. annetaan sanalliset kuvaukset ohjelmiston käyttämistä rajapinnoista. Liitteeksi 1. on ohjelmiston XMLprotokollakuvaukset. Liite 2. on ohjelmiston asennusohje. Liite 3 on liitännäisten kehitysohje.

Ohjelmiston Java-dokumentaatiot löytyvät osoitteesta:

texttthttp://www.cs.helsinki.fi/group/asdf/javadoc

1.1 Sanasto

Sessio - Asiakkaan yhden loogisen kommunikointitarvekokonaisuuden tunniste. Erimerkiksi peliaulalla on oma sessiotunniste, ja jokaisella pelillä johon asiakas on liittynyt on oma sessiotunniste. Pelilogiikka - Kuvaus pelitilanteesta ja sen muutoksista asiakkaiden käyttäytymisen funktiona. JAXB - Java Architecture for XML Binding. Luo Java-luokista XML-skeeman ja XMLviestistä skeeman mukaan tuo takaisin Java-luokaksi. XML - Projektissa käytetty kuvauskieli tiedonvälityksessä osajärjestelmien välillä. NIO - Ohjelmistossa käytetty Javan valmis verkko-I/O toteutus. Tulee sanoista New I/O.

2 Ohjelmiston yleiskuvaus

Järjestelmä koostuu palvelimesta, sen kanssa keskustelevista asiakkaista ja erillään palvelimesta toimivista pelilogiikkaluokista. Palvelin pitää kirjaa asiakasyhteyksistä sekä sessioista, ja lisäksi ylläpitää rakennetta käynnissä olevista peleistä. Palvelin vastaa asiakkaiden pyyntöihin ja välittää pelipyynnöt oikeille peli-instansseille. Palvelin osaa mm. luetella palvelimelta löytyvät pelityypit, ja palvelimen tuntemat aktiiviset pelit.

Asiakas on loppukäyttäjän käyttämä järjestelmä, jolla otetaan yhteys TCP/IP protokollalla palvelimeen. Asiakkaan tulee luoda itselleen käyttäjätunnus ja kirjautua sisään ennen kuin pelaaminen on mahdollista. Asiakas voi kirjautumisen jälkeen pyytää palvelimelta peliluetteloa, tai luoda uusia palvelimen tuntemia pelejä.

Pelilogiikka toimii palvelinohjelmistossa. Pelilogiikan tulee toteuttaa projektin tuottamat pelirajapinnat. Pelilogiikka ladataan dynaamisesti palvelimella eikä peli-instanssit pääse muokkaaman palvelimen tietoja.

Asiakkaan on tärkeää kyetä näyttämään pelitilanne, ja tämän vaatima logiikka on asiakkaalla tärkeää olla. Kuitenkaan pisteytystä tai lopputuloksen laskentaa ei suoriteta asiakkaalla, koska tiedot voivat väärinkäyttäjän tapauksessa olla epärehtejä, eikä niitä siksi suositella palvelimen pelilogiikassa noteeraamaan. Palvelin tallentaa pisteytykset käyttäjien tileille. Kuvassa 1. on esitetty Peliohjelmiston komponenttien yhteistoimintakuvaus.

Kuva 1: Peliohjelmiston yhteistoimintakuvaus.

3 Toteuttamatta jääneet toiminnallisuudet

• (V6) Pelaajan nimen perusteella pelihakua ei toteutettu.

• (V12) Yleinen pelihistorian tallennus.

• (V15) Pelaajatilejä ei voi poistaa muuten kuin suoraan tietokannasta.

Parannusehdotukset

Pisteyksen tallennus tietokantaan uusille peleille on hankalaa, sillä se vaatii tietokantataulujen muokkausta tai listäystä. Tähän voisi pohtia vaihtoehtoisia menetelmiä.

Peliohjelmat voisi ladata dynaamisesti palvelimelta, niin niiden levittäminen olisi helpompaa ja turvallisempaa sekä palvelimen toiminnallisuudelle, että käyttäjien mukavuudelle.

GameControllereita asiakasohjelmistossa ei poisteta poistuessa pelistä. Tämä hukkaa muistia, mikäli käyttäjällä ei ole botteja pelaamassa pelissä. GameControllerin poistaminen aiheuttaa kaikkien pelaajan lisäämien bottien kuolemisen kyseisestä pelistä, joten sitä ei pitäisi tehdä ennen kuin kaikki pelaajan agentit ovat pelistä poistettu tai poistuneet.

Tyhjien pelien poistaminen palvelimelta ei toimi GameTimer-luokassa tapahtuvan ajastimen peruuttamisen vuoksi. Tämä tulisi korjata.

Pokerilogiikan tilannepäivityksessä lähetetään tilatieto-olio, joka välittää kaiken julkisen tiedon pelitilanteesta. Tämä on verrattain raskasta, ja tietoa voisikin lähettää päivitysten muodossa, jättäen muuttumattomat tiedot lähettämättä.

Liukulukujen käyttö rahaliikenteessä on Väärin(tm). Pitäisi olla täsmäpistelukuesitys. Liukulukuvirheitä voisi myös harkita korjaavan pyöristyksillä, mikäli on kyvykkäistä ihmisistä pulaa.

4 Ohjelmiston toimintaympäristö ja käyttöönotto

Sekä palvelin että asiakas vaativat Java 6 tai uudemman toimiakseen. Käyttöjärjestelmä voi kummassakin tapauksessa olla mikä vain, jossa on Java 6 tai uudempi, mutta palvelimen tapauksessa suositus on Linux järjestelmä, eikä toiminnan eheydelle anneta mitään takeita muissa järjestelmissä.

Seuraavassa käsitellään palvelimen asentamista uuteen tietojärjestelmään, sekä asiakkaan asentamista toiseen tietojärjestelmään.

Tietokannan asennus onnistuu asentamalla PostgreSQL tietokanta mielivaltaiseen järjestelmään, johon on mahdollista ottaa TCP/IP yhteys. Lisäksi täytyy asettaa käyttäjätunnus ja osoite -kentät tietokantaa vastaaviksi server.conf tiedostoon.

Palvelimen asentaminen onnistuu purkamalla Server.zip:n sisältö haluttuun koneeseen ja käynnistämällä runServer.sh linux -järjestelmässä tai runServer.bat windows -järjestelmässä. Palvelin tarvitsee myös asennetun tietokannan (katso edellinen kohta) ja konfiguraatiotiedoston.

Asiakas löytyy Client.zip tiedoston sisältä. Pura tämä hakemiston path_from_root_to_target alihakemistoon client. Aja samaisesta kansiosta nyt runPokerClient.sh (linux -järjestelmä) tai runPokerClient.bat (windows -järjestelmä).

5 Palvelin

Palvelimen komponenttien yhteistoimintakuvaus esiteltiin luvussa 2. Seuraavassa on selitetty komponentteihin liittyviä ominaisuuksia.

• Main

Tämä luokka käynnistää Server -luokan ja asettaa lokiin kirjaamisen.

• Server

Alustaa Java.nio pistokkeet yhteyksien kuuntelemiselle ja hyväksymiselle. Luokka pyörii jatkuvassa silmukassa run-metodissa, jossa kutsutaan toistuvasti valitsijaluokan select metodia. Luokka huolehtii myös erilaisten managerien alustamisesta ja välittämisestä muille luokille. Server-luokka alustaa uuden ClientConnectionluokan jokaista uutta hyväksyttyä yhteyttä kohti.

• ClientConnection

Edustaa yksittäistä pistokeyhteyttä. Luokka tarjoaa metodit viestien lähettämiseen ja sisältää vastaanotetun viestin käsittelylogiikan. ClientConnection alustaa MessageHandlerluokan ilmentymän, joka tekee viestin korkean tason käsittelyn.

• MessageHandler

Huolehtii viestien käsittelystä. Luokka huolehtii sessiotunnisteiden käytöstä, jotta yhdistetyt asiakkaat eivät voi yrittää huijata eivätkä välitetyt viestit mene väärille vastaanottajille. MessageHandler käyttää Serverin omistamien managereiden palveluita.

• AccountManager, Account

Sisältää käyttäjätunnusten luonnin, poiston ja muutokset. Myös autentikointi on tehty tässä luokassa. Luokka käyttää tietokantaa autentikointiin. Jokaista kirjautunutta käyttäjää kohti alustetaan Account ja se talletetaan luokan ClientConnection jäsenmuuttujaan, josta se voidaan hakea kun halutaan tietää käyttäjän autentikoinnin tilanne ja mahdolliset käyttäjäoikeudet.

• SessionManager

Pitää kirjaa yhteyksien sekä sessiotunnisteiden käytöstä. tällöin voidaan tarkistaa, että yhteydet yritä käyttää toistensa sessiotunnisteita.

• GameManager

Sisältää pelien luontiin liittyvät toiminnot. Tämän luokan kautta kulkevat kaikki peleille menevät viestit. GameManagerilla on lista pelejä ja se käyttää GameFactorya uusien pelien luontiin.

• GameTimer GameTimer on peliliitännäisille tarjottu ajastinrajapinta. Luokka on hyvin samantapainen kuin Timer-luokka, jonka se perii. GameTimer synkronoi ajastettujen tapahtumien toimitukset peleille, kun palvelin saattaa olla eri säikeestä käsittelemässä peliä samaan aikaan.

• Configuration

Lukee käyttäjän asetukset server.conf tiedostosta työhakemistosta ja tarjoaa ne staattisten metodien välityksellä kysyjille.

Seuraavassa on kuvattu tarkemmin uuden pelin lisääminen palvelimelle, autentikoinnin toteutus sekä palvelimen säikeistyksestä.

5.1 Tietokanta

Palvelin käyttää autentikointiin PostgreSQL-tietokantaa. Tietokannan yhteysmerkkijono ja käyttäjätunnukset tulee määritellä server.conf tiedostoon. Autentikointitietokannan taulun voi luoda seuraavalla SQL-lauseella:

CREATE TABLE account (
name varchar(256),
password char(32),
type short,
balance decimal,
PRIMARY KEY(name)
);

Salasana-kentän sisältö on MD5-hajautusarvo käyttäjätunnuksen ja selväkielisen salasanan yhdisteestä heksadesimaalimerkkijonona.

5.2 Säikeistys

Palvelin on toteutettu kahden säikeen avulla. Ensimmäinen säie on vastuussa Java.nio luokkien yhteysoperaatioiden käsittelystä ja toinen ajastimien hallinnasta. Ajastimia tarjotaan liitännäisille. Synkronointi säikeiden välillä tapahtuu liitännäistä kutsuttaessa ja liitännäisestä ulospäin lähtevissä kutsuissa.

6 Tiedonsiirto

6.1 JAXB, XML

Asiakkaan ja palvelimen tiedonvälityksessä on hyödynnetty valmista JAXB-pakettia, joka muuntaa Java-luokkia XML-muotoiseksi informaatioksi, ja takaisin. Viestit kääritään XML Schema kielellä määriteltyihin viestiluokkiin, jotka voivat määrittelyn mukaan olla (kirjoittamisen hetkellä) kysely-, vastaus- tai tilannepäivitystyyppisiä viestejä. Nämä viestityypit taas jakautuvat erilaisiin viestityyppeihin, kuten peliviesteihin tai autentikointiviesteihin. Katsaus käytettyihin viestiluokkiin löytyy mukaan liitetystä XML-skeemasta ja Javadoc -dokumentaatioista. Viestien määrittely on hoidettu XML-skeemalla niin, että skeema jättää prosessoimatta valittujen viestityyppien tietynnimiset alielementit. Tämän avulla ohjelmiston liitännäisten avulla tehdyt laajennukset voivat määrittää omat valinnaiset viestityyppien parametrit, mutta viestin eheys pystytään kuitenkin tarkistamaan luotettavasti ennen liitännäisille luovuttamista. Jaxb työkalujen käyttöä rohkaistaan myös liitännäisten kehittelyssä sillä etuna on protokollan väärintulkitsemisen tai -käyttämisen huomaaminen jo kääntämisvaiheessa, sillä viestin käsittely tapahtuu perinteisten Javaluokkien kaltaisten metodien kutsuilla.

6.2 java.nio

Tietoliikennepistokkeiden kanssa käytetään Javan New I/O (Java.nio) luokkia. Luokat mahdollistavat asynkronisten pistokkeiden käyttämisen, jolla voidaan ehkäistä tilannetta, jossa jokaista asiakasyhteyttä varten on oma säie. Asiakkaan ja palvelimen välinen liikenne on toteutettu niin, että asiakas pitää koko session ajan yhteyttä auki palvelimeen. Yhteyden ollessa auki kumpi tahansa pää pystyy herättämään keskustelukumppanin jonkin tapahtuman sattuessa. Jatkuvasti auki olevan yhteyden takia viestinvälityksessä lähetetään ensin viestin koko ja sitten vasta itse viesti. Viestin koko lähetetään 32-bittisenä kokonaislukuna, jonka tavujärjestys noudattaa tietoliikenteessä käytettyä Big-Endian (Network Byte Order) tavujärjestystä.

6.3 Tietoliikenneprotokolla

Protokolla on jaettu kolmeen ylätyyppiin päivitys, kysely, vastaus. Seuraavassa on selitetty mihin kutakin tyyppiä on käytetty. Toteutettu protokolla löytyy liitteestä 2 tarkempine selityksineen.

6.3.1 Päivitys

Päivitys on serverin lähettämä pelitilanteen päivittämiseen käytetty viesti. Sisältävät päivitetyt tiedot pelitilanteesta, kuten pelitilanneolion, keskusteluviestit ja muun pelintilannesisältöön liittyvän tiedon.

6.3.2 Kysely

Kysely on asiakasohjelmiston pelipöytään sekä peliaulan käyttämät viestit. Sisältävät viestipyynnöt, joiden avulla asiakasohjelmisto pyytää palvelinta suorittamaan eri toimintoja. Peliaulan toimintoihin kuuluu pelilistausten ja pelitietojen pyytäminen, pelin luominen ja pelipöytään liittyminen, palvelimelle kirjautuminen sekä uusien tilien luonti. Pelipöytä lähettää keskusteluviestit, penkin varaukset sekä peliin liittymisen kyselyviestinä. Mahdollista on myös että pelilogiikka pyytää asiakkaalta kyselyä.

6.3.3 Vastaus

Palvelin käyttää vastausviestejä vastausviesteinä pelipöydän sekä peliaulan pyyntöihin. Lisäksi pelipöydästä välitettävät pelitapahtumat lähetetään palvelimelle vastausviesteinä.

6.4 Pokeripelissä käytetty protokolla

Asiakkaan ohjelmiston pokeripeli viestii palvelimella pyörivän pelilogiikan kanssa käyttämällä spesifistä pokeripeleille tehtyä protokollaa. Protokollan mukaiset viestit kulkevat yllä esitetyn prokollan mukaisten otsakkeiden alla. Viestien sisältö on sijoitettu erityiseen parametrielementiin, joka voi sisältää mitä tahansa. Viestit sisältävät pelitilanne-, päivitys-, käsikortti- sekä pelitapahtumaviestejä.

7 Pelilogiikka

Pelilogiikkamoduulit sijaitsevat palvelimella mutta ne on eroteltu itsenäisiksi moduuleiksi. Pelilogiikkamoduulien täytyy toteuttaa Game-rajapinta. Pelilogiikkamoduulit toteuttavat itse oman toiminnallisuutensa. Logiikkamoduuleilla on mahdollisuus käyttää palvelimen valittuja palveluita abstraktin Game-luokan tarjoamien metodien kautta. Ajastinpalveluita on pakko käyttää tätä kautta, jotta synkronointi toimii oikein.

7.1 Pokeripeli: GameModel

Projektin yhteydessä toteutettuun TexasHoldem peliin liittyvä peli-informaatio-objekti, joka toteuttaa gameinfo rajapinnan. GameModel sisältää pelin kaiken julkisen tiedon ja aksessorit niiden muunteluun. Aksessoreilla pelilogiikka päivittää pelitilannetta. Pelilogiikan ulkopuolelle pelitieto-olio (GameInfo) lähetetään ilman tietosisältöä muuttavia aksessoreita. Olioiden tietosisältönä on kaikki pelin esittämiseen tarvittava tilatieto. Metodeista kuvaukset löytyvät Javadoc-liitteestä.

7.2 Pokerilogiikka

Kuvassa 2 on esitelty ohjelmiston käyttämä yleiskäyttöinen pokeripelilogiikka tilakoneena. Sen lisäksi että uusia pelejä voidaan toteuttaa luomalla pelejä, jotka toteuttavat game-rajapinnan voidaan uusia pokeripelejä periä pokerilogiikasta vaihtelemalla jako-, panostus- sekä kortinvaihtokierrostilojen määrää ja järjestystä. Lisäksi uuteen peliin tulee toteuttaa voittajanlaskenta sekä potinjakoalgoritmi, mikäli kyseiset algoritmit poikkeavat valmiista toteutuksesta.

Tilakoneessa usein edellinen tila asettaa seuraavaksi toimivan pelaajan kohdalleen, jotta itseään toistavat tilat voidaan suorittaa useasti peräjälkeen.

Toimintaviestit asiakasohjelmistosta

Pokerilogiikkatilakoneen tiloihin, kuten sokkopanosten keräys, panostuskierrokset, ja korttienvaihto, liittyy vuorovaikutus asiakkaan kanssa. Edellä mainituissa tiloissa pelilogiikka pyytää palvelimelta ajastinpalvelua, jonka ajan odotellaan pelaajalta pelitilanteeseen liittyvää toimintoa. Lisäksi on viestejä jotka voivat tulla missä tahansa tilakoneen tilassa, kuten peliin liittyminen, pelistä poistuminen. Kuvassa 3 on yleiskuva viesteistä, jotka voivat tulla mihin tahansa aikaan. Lisäksi kunkin tilan kuvassa on tietoa kyseisen tilan toiminnasta ja siihen liittyvästä viestinnästä.

waitplayers

Waitplayers on tila, jossa odotellaan minimimäärä pelaajia eikä peli ole käynnissä. Aina pelin alkaessa pelaajien minimimääräksi asetetaan kaksi. Pelin alkaessa odotuksen jälkeen

Kuva 2: Pokerilogiikkatilakone Kuva 3: Pokerilogiikka: Yleiset toimintaviestit arvotaan uusi jakaja.

blind round

Blind round on tila, joka suoritetaan jokaiselle aktiiviselle pelaajalle pöydässä. Pelaajalta kysytään kuvan 4 mukaisesti maksettavia panostuksia. Lisäksi kysytään sakkopanokset tauolta palanneilta pelaajilta sekä peliin liittymiseen liittyviä panostuksia.

Kuva 4: Pokerilogiikka: blind round

new deal

Jakokierros suoritetaan pelin alussa ja aloitetaan luomalla uusi korttipakka. Korttipakasta jaetaan aktiivisille pelaajille käsikortit. Käsitiedoista paljastetaan pelaajille vain kortit, jotka ovat kyseiselle pelaajalle julkista tai henkilökohtaista tietoa. Muista korteista esitetään vain tausta. Jakokierroksen lopussa asetetaan pelitilaolion aktiiviseksi pelaajaksi panostuskierroksella ensimmäistä edellinen pelaaja.

bet round

Panostuskierroksella kerätään panoksia kuvan 5 algoritmin mukaan. Tila on iteratiivinen ja suoritetaan jokaiselle aktiiviselle pelaajalle vuorollaan kunnes päästään lopputilaan. Lopputilassa kaikki ovat joko maksaneet vaaditut panostukset, heittäneet kortit pois tai panostaneet kaikkensa. Tämän jälkeen siirrytään seuraavaan tilaan. Mikäli pelissä on vain yksi pelaaja, on sekin lopputila ja siirrytään less-than-two-players tilaan.

Kuva 5: pokerilogiikka: bet round

discard round

Discard round eli korttienvaihtokierros ei kuulu texas holdemiin, mutta pokerilogiikka toteuttaa kyseisen tilan muita pelejä varten. Tilassa käydään kaikki aktiiviset pelaajat kerran läpi ja jaetaan poisheitettyjen korttien tilalle uudet kortit. Tilan vaiheet on esitetty kuvassa 6.

Kuva 6: Pokerilogiikka: discard round

deal card round

Korttienjako -tiloissa jaetaan pöytään tai pelaajille lisää kortteja, tämän jälkeen asetetaan pelitilaolion aktiiviseksi pelaajaksi seuraavassa tilassa ensimmäisenä toimivaa pelaajaa edellinen pelaaja. Pelaajan asetuksessa huomattavaa on, että heads up tilanteessa ei ensimmäisenä toimiva pelaaja ole aina buttonista seuraava aktiivinen pelaaja.

Less than two players

Tähän tilanteeseen tulessa pelissä on vähemmän kuin kaksi pelaajaa. Tilanteeseen voidaan päästä kahdesta eri tilasta, sokkopanoskierrokselta tai panostuskierroksilta. Sokkopanoskierrokselta tultaessa joko kukaan ei ole liittynyt peliin tai pelkästään toinen sokkopanoksista on maksettu, tällöin sokkopanos palautetaan ja siirrytään eteenpäin showdown tilaan.

Panostuskierrokselta tultaessa tähän tilaan pelissä on enää yksi pelaaja joka voittaa kierroksen. Voittajaa varten asetetaan ajastin, jonka ajan hänellä on mahdollisuus näyttää tai piilottaa voittokortit muilta pelaajilta. Mikäli ajastin laukeaa, kortteja ei näytetä. Ajastimen laukeamisen tai korttien näyttämispäätöksen jälkeen siirrytään showdown tilaan.

winnings

Viiden kortin pokerikäden arvon laskemiseen on käytetty nimimerkillä ”Cactus Kev” esiintyvän henkilön kehittämää algoritmia, jonka kuvaus löytyy osoitteesta:

http://www.suffecool.net/poker/evaluator.html

Paras pokerikäsi seitsemästä kortista on laskettu sijoittamalla vuorotellen kaikki mahdolliset viiden kortin yhdistelmät algoritmiin. Kun pokerikädet on saatu, arvojärjestykseen jaetaan potti voittajien kesken kuvan 7 algoritmia käyttäen.

Kuva 7: Pokerilogiikka: kuinka voitto potti jaetaan

muck round

Voittajan ratkomisen jälkeen häviäjille suodaan vielä mahdollisuus kätkeä tai näyttää korttinsa muck-ajastimen ajan, jonka jälkeen siirrytään showdown-tilaan.

showdown

Showdown-tilassa lähetetään kaikille peliä seuraaville päivitetty pelitilanneolio ja odotetaan 4s, jotta ihmispelaajilla on aikaa omaksua lopputulos. Samalla kerätään tieto asiakasohjelmilta, ketkä pelaajista eivät osallistu seuraavalle kierrokselle.

8 Asiakasohjelmisto

Asiakasohjelmisto on loppukäyttäjän koneella pyörivä komponentti. Asiakasohjelmisto koostuu palvelimelle kirjautumisesta, peliaulasta, pelipöydästä sekä pelipöytään ja aulaan liittyvistä ohjain-olioista (GameController, LobbyController). Peliaula sekä pelipöytä toteuttavat ohjelmiston käyttöliittymän javan swing kirjastolla. Tietosisältö on upotettu Controller-olioihin, jotka kommunikoivat yleisen yhteysrajapinnan kautta palvelimen ja käyttötymä komponenttien välillä.

8.1 Peliaula

Käyttäjän kirjauduttua palvelimelle saavutaan peliaulaan. Peliaulan ylälaidassa hoidetaan uusien käyttäjienluonti, sisä- ja uloskirjautuminen sekä näytetään kuka on kirjautunut aulaan. Loput ikkunasta on jaettu kolmeen osaan. Vasemmalla sijaitsee pelivalikko palvelimella olevista pelityypeistä. Keskellä ruutua ovat pelilistaukset aktiivisista peleistä sekä listauksien tarkentamista helpottavaa ja toiminnallisuutta. Oikeassa laidassa ruutua on yksityiskohtaista tietoa valitusta pelistä. Jos yhtään peliä ei ole valittu, on oikeassa reunassa uuden pelin luontiin tarvittavat lomaketiedot. Keskellä olevaa pelilistaustietoa voidaan järjestää laskevaan ja nousevaan järjestykseen painamalla harmaan otsakerivin sarakkeiden nimiä. Lisäksi tyhjät ja täydet pöydät pystytään piilottamaan pelilistauksesta.

Oikealla laidassa sijaitsevasta yksityiskohtaisesta pelitiedosta selviää kuka pelaa valitussa pöydässä missäkin paikassa ja paljonko heillä pöydässä rahaa. Pelitietojen alla on esitetty pelin kuvaus sekä pelinliittymispainike, joka avaa valitun pelin uuteen ikkunaan. Kuvassa 8 on esitetty peliaulan graafisten komponenttien suhteet aulanhallinta-olioon sekä esitetty miten käyttöliittymäpaneelit sijoittuvat kehykseen. Kuvassa 9 on kuva itse peliaulasta.

Seuraavassa on kuvattu lyhyesti asiakasohjelmiston eri komponentit. Javadoc -dokumentaatio sisältää tarkemmat kuvaukset luokista.

• ConnectionHandler

Java NIO -kirjastoa hyödyntävä yhteysluokka. Pyörii itsenäisessä säikeessä kuunnellen sockettiin tulevaa dataa ja sockettiin lähetettävän datan pyyntöjä. Käyttää avukeseen ChangeRequest olioita ohjatakseen socketin toimintaa lukemisen ja kirjoittamisen välillä. Sisältää metodit viestien lähettämiseen ja metodin viestien kuuntelijaksi rekisteröitymiseen. Rekisteröityneille kuuntelijoille välitetään viestejä niiden sessionID:n perusteella.

• Message

Rajapinta, joka mahdollistaa ConnectionHandlerille saapuvien viestien kuuntelijaksi rekisteröitymisen. Sisältää rajapinta metodit, joiden avulla viestien välittäminen kuuntelijalle onnistuu.

• LobbyController Asiakasohjelmiston aulaa ja pelihakua hallinnoiva osio. Tämän luokan kautta kulkevat viestit käyttöliittymäluokasta LobbyFrame palvelimelle ja takaisin. Huolehtii myös peliohjelmien käynnistämisestä.

• LobbyModel

Pitää yllä aulaohjelman tietosisältöä. Tallettaa tuoreimmat päivitykset pelilistoista ja pitää yllä asiakkaan kirjautumista. Sisältää apumetodeita LobbyControllerille tietojen kaivamiseen palvelimelta lähetetyistä viesteistä. Tietoja käyttäjästä ylläpidetään luokan User avulla.

• LobbyFrame

Graafinen käyttöliittymä aulaohjelmalle. Komennot käyttöliittymästä kulkevat LobbyControllerille. Rakentuu useista osapaneeleista.

• PluginLoader

Apuluokka, joka huolehtii luokkien dynaamisesta lataamisesta. Käytetään muun muassa peliohjelmien dynaamiseen lataamiseen ja pokeripelissä tekoälypelaajien lataamiseen. Configuration luokka pitää yllä hakemistot, joista lisäosat ja tekoälypelaajat tulee ladata.

• GameController

Abstrakti yläluokka, jota laajentamalla voidaan toteuttaa uusia peliohjelmia, jotka aulaohjelma osaa ladata dynaamisesti. Sisältää useita valmiiksi toteutettuja metodeita ja abstraktit metodit, joiden avulla kommunikointi palvelimen välillä ConnectionHandler luokan kautta tulee tapahtumaan. Toteuttaa Message -rajapinnan.

Kuva 8: Peliaulan komponenttien suhteet toisiinsa.

Kuva 9: Kuvankaappaus peliaulasta.

8.2 Pelipöytä

Ohjelmistossa on toteutettu pelipöytä pokeripeleille. Pelinhallintaolio välittää ajantasaista pelitietoa käyttöliittymäkomponenteille kuvan 10 esittämällä tavalla. Pelitilanteen hallintaan liittyvät graafiset komponentit on sijoitettu Javan Layoutmanagerien avulla. Kuitenkin pelinäkymään liittyvät peli-istuimet ja niihin läheisesti liittyvät informaatiota sisältävien tietorakenteiden esitykset, kuten ajastimet, jakajanapit, kortit, paikanvarausnapit sekä panostukset on sijoitettu kerrostusruutuun (JLayeredPane). Kerrostusruudun käyttö mahdollistaa dynaamisen istuimien sijoittelun sekä pelaajille jaettavan korttimäärän vaihtelun. Myös pelikuvakkeet kuten kortit, jakajanapit, jne. skaalauntuvat peli-ikkunan koonmuutosten mukaan, mahdollistaen useamman pelipöydän sovittamisen pienellekin näytölle.

Pelipöydän käyttöliittymän alareuna on jaettu kolmeen osaan. Vasemmanlaidan valintaruudut sisältävät etukäteistietoa sokkopanosten maksusta, sitoutista sekä voittavien ja häviävien korttien pois heitosta. Vasemmanlaidan painikkeista saa peliaulan näkyviin, tai suljettua pelipöydän. Keskellä alareunassa sijaitsee keskusteluviesti-ikkuna. Oikeassa alareunassa on näkyvissä pelissä oleva potti sekä nykyisen kierroksen tarvittava panostusmäärä sekä pelitilanteeseen liittyvät toimintapainikkeet. Toimintapainikkeita liittyy panostuskierrokseen, sokkopanoskierrokseen sekä pelaajan ollessa sitout tilassa. Oikeassa laidassa sijaitsee myös valintaruudut, joilla pelaaja voi antaa etukäteistietoa miten aikoo toimia omalla kierroksellaan. Kuvassa 11 on kuva pelipöydästä Kuva 10: Pelipöydän komponenttien suhteet toisiinsa.

Kuva 11: Kuvankaappaus pelipöydästä.

9 Rajapintakuvaukset

• Game: Game -rajapinta määrittelee tavan, jolla yleisen pelin tulisi tehdä yhteistyötä palvelimen kanssa. Rajapinnan määrittelemät metodit antavat pelille mahdollisuuden käsitellä palvelimelta saapuvia viestejä ja lähettää niihin vastauksia. Lisäksi rajapinta ohjeistaa selkeällä tavalla kuinka pelaajia tulee liittymään peliin ja miten pelaajat voivat peliin vaikuttaa. Rajapinnan metodit peliohjelmoijan tulee kuitenkin toteuttaa itse.

• PokerGame: Rajapinta toteuttaa kaikkien pokeripelien haluamat toiminnot. Laajentamalla tätä luokkaa, voidaan helposti toteuttaa muita pokeripelejä.

• MessageHandler: Rajapinta, joka mahdollistaa asiakaspäässä olevien peliasiakasohjelmien kommunikoinnin palvelimen kanssa ConnectionHandler luokan kautta. MessageHandler rajapinnan toteuttavat luokat voivat rekisteröityä niille rajapinnan kautta annettuun yhteisolioon. Tällöin niille välitetään yhteys oliolle tulleita viestejä niiden sessiotunnisteen perusteella.

• GameController: Rajapinta määrittelee tavan, jolla peliaulasta voidaan käynnistää tietynpelin asiakasohjelma sekä miten viestinvälitys asiakasohjelman ja palvelimella toimivan pelilogiikan välillä tapahtuu. GameController toteuttaa MessageHandler -rajapinnan.

• PlayerInfo: Tarjoaa metodit pelaajakohtaisen julkisen tiedon pyytämiseen.

• GameModel: Tarjoaa metodit pelikohtaisen julkisen tiedon pyytämiseen.

1

Liite 1. Protokollakuvaukset

1

Liite 2. Asennusohje

1

Liite 3. Plugins tutorial