Suunnitteludokumentti

Asdf

Helsinki 25.2.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  18.2.2008 ensimmäinen versio
1.1  24.2.2008 Sekvenssikaaviota lisätty

Sisältö

1 Johdanto 1 1.1 Sanasto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Dokumentin rakenne . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

2 Arkkitehtuurikuvaus 2 2.1 Arkkitehtuurikaavio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.2 Osajärjestelmät . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.3 Ohjelman päätoiminnallisuuksien kuvaukset . . . . . . . . . . . . . . . . 3

2.3.1 Pelilistauksen etsiminen . . . . . . . . . . . . . . . . . . . . . . 3 2.3.2 Peliin siirtyminen . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.3.3 Pelitapahtuman välitys . . . . . . . . . . . . . . . . . . . . . . . 5 2.3.4 Uudenpelin luonti . . . . . . . . . . . . . . . . . . . . . . . . . 6

3 Komponentit 7

3.1 Asiakas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1.1 Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.2 GameController . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.3 GameModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.4 AbstractPlayer . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.5 Ourplayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.6 Botplayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.7 GameView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.8 Lobby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.1.9 LobbyModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1.10 LobbyView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1.11 Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1.12 ConnectionHandler . . . . . . . . . . . . . . . . . . . . . . . . . 9 3.1.13 TexasHoldemConnection . . . . . . . . . . . . . . . . . . . . . . 9 3.1.14 LobbyConnection . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2 Palvelin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.1 Game . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2.2 AbstractGame . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.3 Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.4 Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.5 PokerActions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.6 TexasholdemActions . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.7 Search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.8 CardGame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.9 PokerGame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.10 TexasHoldem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 3.2.11 Place . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.12 Deck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.13 Card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.14 GameServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.15 ConnectionInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.16 ConnectionListener . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.17 Account, Statistics . . . . . . . . . . . . . . . . . . . . . . . . . 12 3.2.18 GameFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

4 Käyttöliittymä 13 4.1 pelipöytä . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.2 peliaula . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 XML-schema protokolla 15

1 Johdanto

Asdf on Helsingin yliopiston tietojenkäsittelytieteen laitoksen ohjelmistotuotantoprojektin ryhmä. Tämä on ryhmän toteuttaman pokeripalvelin-ohjelmiston suunnitteludokumentti. Dokumentissä esitellään järjestelmän kompponentit, rajapinnat, sekä kuvataan käyttöliittymä.

Projektiin liittyvää materiaalia tulee olemaan saatavilla ryhmän kotisivulla osoitteessa:

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

1.1 Sanasto

Sana  Selitys
GUI  Graphical User Interface, graafinen käyttöliittymä

JAXB Ohjelmiston toteutuksessa käytettävä valmis komponentti, jota käytetään muuntamaan xml-schema protokollat java-olioiksi sekä toisinpäin.

Meerkat Poker Academyn tarjoama rajapinta, joka yleistää kommunikaation asiakkaan ja palvelimen välillä texas holdem -pelissä sekä mahdollistaa pokeriohjelmiston peluuttaa valmiita tietokonebotteja, jotka kyseisen rajapinnan toteuttavat. Ohjeliston komponentit, jotka rajapinnan toteuttavat sisältävät pelitilannetietoa sekä pelitoiminnallisuutta texas holdem peliin. Ohjelmisto tulee käärimään ja purkamaan xmlschema viesteistä JAXB-kompponetin avulla meerkat rajapinnat toteuttavia pelitilanne- sekä pelaajaolioita.

1.2 Dokumentin rakenne

Tässä luvussa on lyhyt kuvaus projektista, dokumentin rakenne sekä sanasto. Luvussa 2 on esitelty ohjelmiston arkkitehtuuri. Lisäksi luvussa 2 on esitetty ohjelmiston toiminnallisuutta sanallisesti ja sekvenssikaavioilla. Luvussa 3 on ohjelmiston asiakas- ja palvelinkomponentit esitetty luokkakaavioina ja sanallisin kuvauksin. Luvussa 4 on esitetty ohjelman käyttöliittymä. Luvussa 5 on esitetty xml-schemalla välitettävien viestien muoto.

2 Arkkitehtuurikuvaus

Tässä luvussa esitellään ohjelmiston arkkitehtuuri sekä esitellään osajärjestelmät. Lisäksi esitetään sekvenssikaavion ja sanallisesti ohjelmiston toimintoa.

2.1 Arkkitehtuurikaavio

Kuva 1: Arkkitehtuurin korkean tason näkymä.

2.2 Osajärjestelmät

Ohjelmisto koostuu asiakas- ja palvelinohjelmistosta, ohjelmistot kommunikoivat keskenään xml-viesteillä, joista kerrotaan tarkemmin luvussa 5. Ohjelmisto voidaan jakaa vielä osajärjestelmiin palvelin, pelilogiikkamoduulit, tietokanta, peliaula, pelipöydät sekä tekoälypelaajat. Tietokanta toteutetaan vasta seuraavassa iteraatiovaiheessa.

Palvelin luo peleistä ilmentymiä ja välittää peliviestejä pelilogiikkailmentymien ja (tekoäly)pelaajien kesken. Palvelin tallentaa myös tilastotietoa ja käyttäjätiedot. Pelilogiikka on toteutettu itsenäisillä komponenteilla, joille palvelin tarjoaa yleisen rajapinnan ottamatta kantaa niiden toteutukseen.

Asiakasohjelmisto on loppukäyttäjän koneella pyörivä graafinen komponentti. Asiakasohjelmisto muodostuu peliaulasta sekä pelipöydistä. Molemmat kommunikoivat yleisen yhteysrajapinnan kautta palvelimen kanssa. Peliaula toteuttaa: sisäänkirjaantumisen, uusien pelien luonnin, pelien selaamisen sekä pelipöytiin siirtymisen. Pelipöytä toteuttaa: jonkin pelilogiikan pelin pelaamisen tarvittavan graafisen ympäristön johon pelaaja voi liittyä tai liittää tietokonepelaajia.

2.3 Ohjelman päätoiminnallisuuksien kuvaukset

Seuraavassa on käyty läpi pokeriohjelmiston toiminnallisuuksien läpivientiä sekvenssikaavion.

2.3.1 Pelilistauksen etsiminen

Kuva 2: Pelilistauksen hakeminen.

2.3.2 Peliin siirtyminen

Kuva 3: Peliin siirtyminen:asiakas.

Kuva 4: Peliin siirtyminen: palvelin.

2.3.3 Pelitapahtuman välitys

Kuva 5: Pelitapahtuman välitys: asiakas

Kuva 6: Pelitapahtuman välitys: palvelin.

2.3.4 Uudenpelin luonti

Kuva 7: Uudenpelin luonti: asiakas.

Kuva 8: Uudenpelin luonti: palvelin.

3 Komponentit

Luvussa käydään läpi ohjelman komponentit. Komponenteista on annettu kuvaus, luokkakaavio sekä lyhyet luokkien kuvaukset.

3.1 Asiakas

Asiakas on loppukäyttäjän koneella pyörivä graafinen komponentti. Asiakaskomponentin avulla loppukäyttäjä voi tehdä, poistaa ja pelata pelejä. Käyttöliittymä toteuttaa myös tekoälypelaajien hallinnoinnin ja pelauttamisen. Käyttöliittymäkomponenttien arkkitehtuurissa on pyritty soveltamaan Model-View-Controller suunnittelumallia, jonka tarkoituksena on käyttöliittymän erottaminen sovellusaluetiedosta.

3.1.1 Table

Peliohjelmien yläluokka, jossa kaikissa peleissä toteutettava yhteinen toiminnallisuus.

3.1.2 GameController

Aulasta käynnistetty ilmentymä texasholdem pelipöydästä. Keskittää toiminnot mallin ja yhteysrajapinnan välillä. Ylläpitää pelitilannetta GameModel-oliossa, ja vastaa bottipelaajien pelikyselyihin sekä tarjoaa graafiselle käyttöliittymälle tiedon pelitilanteesta. Lisäksi meerkat rajapintojen kautta aktivoi tietokone- ja ihmispelaajia ja kerää tilannetietoja.

3.1.3 GameModel

Meerkat gameinfo rajapinnan toteuttava tieto pelitilanteesta. Lisäksi muuta tietoa pelitilanteesta, kuten varatut paikat. GameModel sisältää kaiken tarpeellisen tiedon pelitilanteen esittämiseen.

3.1.4 AbstractPlayer

Meerkat pelaaja rajapinnat toteuttava yläluokka pelaajista.

3.1.5 Ourplayer

meerkat rajapinnat toteuttava pelaajaolio, joka istuu tässä pöydässä.

3.1.6 Botplayer

Meerkat rajapinnat toteuttava tekoälytietokoneohjelma, joita voidaan käynnistää pelaamaan pöytään. Viestii ja kommunikoi pelin kanssa TexasHoldemClient-komponentin kautta GameControllerin viestien mukaan.

3.1.7 GameView

Asiakasohjelman graafiset käyttöliittymä komponenttien yläluokka yhdelle pelipöydälle, toteuttaa erillaisten panelien avulla näkymän pelipöydästä ja pelitilanteista, kts. kuva X käyttöliittymäkuvauksesta.

3.1.8 Lobby

Ilmentymä aulasta, joka käynnistetään haluttaessa käyttää ohjelmistoa, luo näkymän aulasta ja sen kautta lähdetään liittymään peleijin ja hakemaan pelejä.

3.1.9 LobbyModel

Tilannetieto peliaulasta.

3.1.10 LobbyView

Asiakasohjelman graafinen käyttöliittymä komponenttien yläluokka peliaulalle, toteuttaa paneelien avulla, pelin hakemisen, pelilistat, yksityiskohdat pelistä sekä uuden pelin luomisen.

3.1.11 Connection

Rajapintaluokka joka kuvaa yhteydenpitoon palvelimelle asiakkaan tarjoamat palvelut.

3.1.12 ConnectionHandler

Välittää xml-pohjaiset viestit palvelimelle sekä kuuntelee palvelimelta tulevia tietoja ja välittää ne eteenpäin headerin mukaan connection rajapinnan toteuttaviin luokkiin, kuten LobbyConnection ja TexasHoldemConnection.

3.1.13 TexasHoldemConnection

THC piilottaa viestien parsimisen ja tarkistamisen yksityiskohdat. Tarjoaa rajapinnat viestin lähettämiselle ja vastaanottamiselle. Luokka käyttää JAXB kirjastoilla automaattisesti generoitua parseria XML viestien muodostamiseen ja lukemiseen. Toteuttaa connection rajapinnan.

3.1.14 LobbyConnection

THC:n tavoin LC piilottaa viestien parsimisen ja tarkistamisen yksityiskohdat. Tarjoaa rajapinnat viestin lähettämiselle ja vastaanottamiselle. Luokka käyttää JAXB kirjastoilla automaattisesti generoitua parseria XML viestien muodostamiseen ja lukemiseen. Toteuttaa connection rajapinnan.

3.2 Palvelin

Palvelin huolehtii pelilogiikoiden toiminnallisuudesta. Palvelin välittää viestit peli-ilmentymien sekä pelaajien kesken. Palvelin tarjoaa rajapinnat peli-ilmentymille sekä huolehtii niiden eheydestä.

3.2.1 Game Rajapintaluokka, joka kuvaa yleiset pelien tarjoamat palvelut.

3.2.2 AbstractGame Kaikkien pelien yläluokka. Kaikkien pelien yhteiset ominaisuudet, pelin kuuntelijat.

3.2.3 Client Pelin kuuntelijoiden yleiset tiedot palvelinta varten.

3.2.4 Actions Kaikkiin peleihin liittyviä toimintoja.

3.2.5 PokerActions Kaikkiin pokeripeleihin tarvittavat meerkat rajapinnan mukaiset toiminnot.

3.2.6 TexasholdemActions Pelkästään Texasholdem liittyvät pelitoiminnot.

3.2.7 Search Käytetään pelikohtaisten hakuehtojen toteutukseen. Luokka alustetaan hakuehdot sisältävällä XML-viestillä. Tarjoaa metodin, joka palauttaa vastaako parametrina annettu peli hakuehtoja.

3.2.8 CardGame Abstrakti yläluokka korttipeleille.

3.2.9 PokerGame Abstrakti yläluokka pokeripeleille.

3.2.10 TexasHoldem Luokka toteuttamaan ilmentymä texas holdem pelistä. Peli alustetaan odottamaan minimi määrä pelaajia pöytään ja sen jälkeen peli jatkuu kunnes pelillä ei ole yhtään seuraajaa. Pelin alettua peli etenee jakamalla aktiivisille pelaajille piilokortit, panostuskierros, flop, panostuskierros, turn, panostuskierros, river, panostuskierros, showdown, potinjako. Mikäli panostuskierroksen lopussa on vain yksi pelaaja kierros loppuu siihen. TexasHoldem odottaa panostuskierroksilla aikarajan verran pelitoimintatietoa aktiivisilta pelaajilta, pelitoimintatieto tallennetaan Placeen. Kaikki pelitoiminta lähetetään kaikille peliä seuraaville Clienteille, Piilokortit lähetetään vain kortin omistajalle sekä superkäyttäjille.

3.2.11 Place

Place toteuttaa pokeripaikan pöydässä. Paikkoja varataan ja niihin sioitetaan pelaajia. Paikka ylläpitää tilatietoa sijoitetun pelaajan pöytään tuomista rahoista sekä pelissä olevasta rahasta. Paikka ottaa vastaan ja ylläpitää tietoa pelaajan peliin liittyvistä toiminnoista (muck,sitout,action)

3.2.12 Deck

Kokoelma korteista, pelipakka josta voidaan jakaa kortteja peleihin.

3.2.13 Card

Card toteuttaa yksittäisen (pokeri)kortin. Parametreina on väri, arvo sekä jaetaanko kortti näkyviin.

3.2.14 GameServer

Pelipalvelin, joka pyörittää pelejä ja ottaa vastaan asiakkaita ja välittää viestit peli-ilmentymille.

3.2.15 ConnectionInfo

Yhteystiedot asiakkaista.

3.2.16 ConnectionListener

Kuuntelee uusia yhteyksiä palvelimelle. Avaa yhteyden asiakkaan ja palvelimen välille, kun tulee uusi yhteys.

3.2.17 Account, Statistics

Account hoitaa Käyttäjän hallinta tiedot, tunnukset ja salasanat. Statistics tilastotiedon. Molemmat korvataan tietokannalla viimeistään toisessa iteraatio vaiheessa.

3.2.18 GameFactory

Luo parametrien mukaan annetun ilmentymän halutusta pelistä.

4 Käyttöliittymä

4.1 pelipöytä

Kuva 9: Pelipöytä

Kuvassa 9 on esitetty asiakasohjelmiston texas holdem pelipöydän alustava käyttöliittymähahmotelma.

Käyttöliittymän alareuna on jaettu kolmeen osaan, vasemmalla sijaitsee yleisiä pelitilanteesta riippumattomia nappeja, keskellä chatti-ikkuna. Oikeassa reunassa näkyy pelissä oleva potti sekä nykyisen kierroksen tarvittava panostusmäärä sekä aktiivisen pöydässä istuvan pelaajan ollessa vuorossa pelitilanteeseen liittyvät napit: call,fold,check,raise, sekä panoksen määrittely valikko.

Käyttöliittymän yläosa näyttää pöytäkortit sekä potin sekä vaihtelevan määrän pelaajaistuimia pelistä riippuen. peli-istuimen läheisyyteen on toteutettu näytettävää tietoa kyseisestä pelaajasta, varattu istuin, tai tyhjä istuin. Näytettävään tietoon pelaajasta kuuluu jakajanappi, onko pelaajalla kortit, kierroksen sanallinen toiminto, pelaajan nimi, rahamäärä, paljonko rahaa potissa, ja aktiivisen pelaajan kohdalla aikarajan kulumista näyttävä palkki.

4.2 peliaula

Kuva 10: Peliaula, valittu peli.

Kuvassa 10 on esitetty asiakasohjelmiston peliaulan alustava käyttöliittymähahmotelma.

Peliaulan ylälaidassa hoidetaan sisään- sekä uloskirjautuminen ja näytetään kuka on kirjaantuneena. Loput ikkunasta on jaettu kolmeen osaan. Vasemmalla sijaitsee pelivalikko palvelimella olevista pelityypeistä. Keskellä ruutua on pelilistaukset aktiivisista peleistä ja listauksien tarkentamista helpottavaa ja järjestävää toiminnallisuutta. Oikeassa laidassa ruutua on yksityiskohtaista tietoa valitusta pelistä. Mikäli yhtään peliä ei ole valittu on oikeassa reunassa uuden pelin luontiin tarvittavat lomaketiedot (kuva11).

Keskellä olevaa pelilistaustietoa voidaan järjestää laskevaan ja nousevaan järjestykseen painamalla harmaan otsakerivin sarakkeiden nimiä. Pelilistoja voidaan myös etsiä pelaajan tai pelin nimen perusteella. Hakuehtojen rajoitukseen on tarjottu alalaidassa täysien ja tyhjien pöytien piilotukset sekä pelaajamäärien ja panostuksen rajoittamista. Hiiren tuplaklikkaus valitussa pelissä avaa kyseisen pelin pelipöydän uuteen ikkunaan.

Oikealla laidassa sijaitsevasta yksityiskohtaisesta pelitiedosta selviää kuka pelaa pöydässä missäkin paikassa ja paljonko heillä on käyttörahaa pöydässä, sekä onko kyseessä tietokone- vai ihmispelaaja. Pöydän tietojen alla on esitetty pelin kuvaus sekä nappi, joka avaa valitun pelin uuteen ikkunaan.

Kuva 11: Peliaula, uuden pelin luonti.

5 XML-schema protokolla

Viestit on määritelty XML schemalla. Tämä mahdollistaa helpon parserin ja viestien validoinnin. Viestinmäärittelyssä on ideana, että viestin ulkokuori on yhtenäinen kaikille viesteille, mutta viestiin voidaan laittaa täysin mielivaltaista XML sisältöä tiettyihin kohtiin, jotta voidaan toteuttaa minkä tahansa pelin vaatima viestinvälitys. Alla olevaa XML schema dokumenttia käytetään suoraan JAXB työkalujen avulla parserin generoimiseen.

<?xml version="1.0"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="message">
<xs:complexType>
<xs:choice>
<xs:element name="create" type="requireParameters"/>
<xs:element name="delete" type="optionalParameters"/>
<xs:element name="join" type="optionalParameters"/>
<xs:element name="part" type="optionalParameters"/>
<xs:element name="action" type="requireParameters"/>
<xs:element name="info" type="requireParameters"/>
</xs:choice>
<xs:attribute name="gameID" type="xs:unsignedLong" default="0"/>
<xs:attribute name="gameType" type="xs:string" default="Game"/>
</xs:complexType>
</xs:element>

<xs:complexType name="requireParameters">
  <xs:sequence>
     <xs:element name="parameters" type="parameters"/>
  </xs:sequence>
</xs:complexType>
<xs:complexType name="optionalParameters">
  <xs:sequence>
     <xs:element name="parameters" type="parameters" minOccurs="0"/>
  </xs:sequence>
</xs:complexType>
<xs:complexType name="parameters">
  <xs:sequence>
     <xs:any processContents="skip" maxOccurs="unbounded"/>
  </xs:sequence>
</xs:complexType>
</xs:schema>