
		Hierarkia - Scheme Implementation README in Finnish

README-fi v1.0 2003-09-05
Copyright 2003 Sami Virpioja and Ilari Lhteenmki

This file is written by Sami Virpioja. Questions, comments or anything
related to the program can be send by e-mail to <svirpioj@cc.hut.fi>.

See file README for English instructions.


Sislt
-------

1. Tiedostot
2. Vaadittavat ohjelmat
3. Kntminen
4. Ajaminen
5. Asetukset
6. Kyttliittymt
7. Tunnettuja ongelmia
8. Tekijt


1. Tiedostot
------------

Alkuperinen "Hierarkia - Scheme Implementation" -paketti sislt 
seuraavat tiedostot:

README			- README-ohjetiedosto englanniksi
README-fi		- Tm ohjetiedosto
COPYING			- GNU General Public Licence -lisenssi
Makefile		- Makefile lhdekoodin kntmiseen
rungame.sh		- Komentoriviskripti ohjelman kynnistmiseen
hierarkia.scm		- Ohjelmakoodi; pelin ydin
ngui.scm		- Ohjelmakoodi; tekstikyttliittym
mred-gui.scm		- Ohjelmakoodi; graafinen kyttliittym
human.scm		- Ohjelmakoodi; ihmispelaajaobjekti
ai.scm			- Ohjelmakoodi; yleisi tekolyn proseduureja
ai_plain.scm		- Ohjelmakoodi; AI-pelaajatoteutus
ai_iter.scm		- Ohjelmakoodi; AI-pelaajatoteutus
ai_mtd.scm		- Ohjelmakoodi; AI-pelaajatoteutus
ai_imtd.scm		- Ohjelmakoodi; AI-pelaajatoteutus
ai_pvs.scm		- Ohjelmakoodi; AI-pelaajatoteutus
rungame.scm		- Ohjelmakoodi; pelin alustus- ja kynnistysrutiinit
rungame-compiled.scm	- Ohjelmakoodi; pelin alustus- ja kynnistysrutiinit
rungame-sources.scm	- Ohjelmakoodi; pelin alustus- ja kynnistysrutiinit


2. Vaadittavat ohjelmat
-----------------------

Peli vaatii PLT DrScheme -pakettiin kuuluvan MzScheme-tulkin ja 
MrEd-grafiikkakirjaston. Lisksi knnettess tarvitaan Mzc-kntj.
Ohjelmat ovat saatavilla osoitteesta <URL:http://www.plt-scheme.org/>. 
Ohjelman pitisi toimia ainakin versiolla 202 ja uudemmilla. 

Ohjelman automaattiseen kntmiseen tarvitaan GNU Make tai vastaava.
<URL:http://www.gnu.org/software/make/make.html>


3. Kntminen
--------------

Tiedostot voi lukea tulkkiin mys suoraan lhdekoodeista, mutta 
natiivikoodiksi kntminen nopeuttaa hieman toimintaa. Paketin
sisltm Makefile knt koodin Unix:ien ja MacOS:n kyttmiksi
.so -tiedostoiksi.

Siirry hakemistoon johon purit paketin ja knn tiedostot 
komennolla make:

% make

mzc ai.scm ai_mtd.scm ai_plain.scm ai_pvs.scm ai_iter.scm ai_imtd.scm \\
human.scm ngui.scm hierarkia.scm
MzScheme compiler (mzc) version 202, Copyright (c) 1996-2002 PLT
(jne.)

Kntmisen jlkeen rungame.scm korvataan rungame-compiled.scm:ll,
joka lataa so-tiedostot lhdekoodien sijasta.

Komennolla 'make clean' voi poistaa knnetyt tiedostot ja palauttaa
rungame.scm:n kyttmn lhdekoodeja (kopioi rungame-sources.scm:n
sen plle).

Windowsissakin kntminen onnistuu, mutta vaatii tll hetkell
omatoimisuutta. Knn tiedostot erikseen dll:ksi Mzc:ll ja tee uusi 
rungame.scm joka lataa ne .so tai .scm -tiedostojen sijasta. Huomaa,
ett graafisen kyttliittymn sisltv mred-gui.scm: ei voi knt.


4. Ajaminen
-----------

- Unix-ympristt:

Ohjelma kynnistyy oletusasetuksilla ajamalla kynnistysskripti
rungame.sh:

% ./rungame.sh

Skripti vaatii ett Mred-tulkki lytyy polusta. Se yksinkertaisesti 
kynnist tulkin komentoriville, ajaa rungame.scm -tiedoston ja 
suorituksen loputtua ajaa komennon (exit), joka poistuu tulkista: 

% mred -z -f rungame.scm -e '(exit)'

Vaihtoehtoisesti voit avata rungame.scm -tiedoston drscheme 
-ohjelmointiympristn ja ajaa ohjelman siell:

% drscheme rungame.scm &


- Windows-ymprist:

Avaa rungame.scm joko MrEd tai DrScheme -ohjelmassa. Edellisess se
ajetaan automaattisesti, jlkimmisess valitse lataamisen jlkeen
"execute".


5. Asetukset
------------

Ohjelman asetuksia voi st rungame.scm -tiedostosta. Kommentoidut
rivit alkavat puolipisteell (;). Tiedosto tekee seuraavat asiat: 

1) Mrittelee pelilauden koon ja nappuloiden mrn:

        (define board-size 7)
        (define max-rank 4)

Nill asetuksilla pelilauta on 7 x 7 ja korkeimman nappulan
arvo on nelj.

2) Lataa pelirungon, joka on hierarkia.scm -tiedostossa. Vastaava
knnetty versio on hierarkia.so. Knnetty versio ladataan
load-extension -komennolla, lhdekoodi komennolla load: 

        (load-extension "hierarkia.so")
TAI
        (load "hierarkia.scm")

3) Luo pelilaudan ja alustaa sen:

        (define board (make-board))
        (init-board! board)

Tmn jlkeen muuttujassa board on pelilauta, joka esimerkiksi kohdan
(1) arvoilla nytt seuraavalta:

S4 S3 S2 S1 -- -- --
S3 S2 S1 -- -- -- P1
S2 S1 -- -- -- P1 P2
S1 -- -- -- P1 P2 P3
-- -- -- P1 P2 P3 P4

4) Lataa pelaajatiedostot joko .scm tai knnetyist .so -tiedostoista
(katso kohta (2)):

        (load-extension "human.so")
        (load-extension "ai.so")
        (load-extension "ai_plain.so")
        (load-extension "ai_mtd.so")
        (load-extension "ai_pvs.so")
        (load-extension "ai_iter.so")
        (load-extension "ai_imtd.so")
TAI
        (load "human.scm")
        (load "ai.scm")
        (load "ai_plain.scm")
        (load "ai_mtd.scm")
        (load "ai_pvs.scm")
        (load "ai_iter.scm")
        (load "ai_imtd.scm")

5) Lataa kyttliittymkirjastot. Tiedosto ngui.scm (tai .so) sislt
komentorivikyttliittymn, mred-gui.scm graafisen. Vain toisen lataaminen 
riitt. Huom! mred-gui.scm:st ei ole knnetty versiota.

        (load "ngui.scm")
TAI
        (load-extension "ngui.so")

JA/TAI
        (load "mred-gui.scm")

6) Luo kyttliittymobjektin. Seuraavista ensimminen luo
komentorivikyttliittymn, jlkimminen graafisen (oikeat 
kirjastotiedostot tulee olla ladattuna edellisen kohdan mukaisesti):

        (define gui (make-ngui))
TAI
        (define gui (make-gui board-size max-rank board))

7) Kynnist pelin start-game -proseduurilla:

        (start-game 'human 'ai gui)

Proseduurin kaksi ensimmist argumenttia saavat olla joko symbolit
'ai tai 'human. Ensimminen asettaa sininisen (aloittavan) pelaajan,
jlkimminen punaisen. 'ai tarkoittaa tietokonepelaajaa, 'human
ihmispelaajaa. Kolmas argumentti on kohdassa (6) luotu
kyttliittymobjekti.

Oletuksena tietokonepelaaja kytt alfa-beta -hakua neljn
hakusyvyydelle. Graafisessa kyttliittymss on oma valikko
tietokonepelaajan ominaisuuksien sdlle. Ominaisuudet voidaan
mys mritt suoraan start-game:n lisargumenteissa.
Lisargumentit ovat muotoa 
'(ai <pelaaja> <tyyppi> <hakusyvyys> <suurin hakusyvyys>),
miss <pelaaja> on joko 1 (sininen) tai 2 (punainen) ja 
tyyppi joku seuraavista: 

plain - normaali alfa-beta -haku
iter  - iteratiivisesti syvenev alfa-beta
mtd   - MTD-algoritmia kyttv alfa-beta
imtd  - iteratiivisesti syvenev MTD-algoritmia kyttv alfa-beta
pvs   - PVS-algoritmia kyttv alfa-beta

Hakusyvyys kertoo kuinka syvlle haku oloittuu rauhallisissa
tiloissa, suurin hakusyvyys kuinka syvlle maksimissaan, jos
siirrot ovat hykkys- tai lyntitiloja.

Esimerkiksi seuraava luo kaksi tietokonepelaajaa, jotka kyttvt
iteratiivisesti syvenev alfa-beta -hakua, ensimminen
hakusyvyyksill 2 ja 4, toinen 3 ja 5:

        (start-game 'ai 'ai gui '(ai 1 iter 2 4) '(ai 2 iter 3 5))


6. Kyttliittymt
------------------

Komentorivikyttliittym on tarkoitettu lhinn tietokonepelaajien
vlisiin testiajoihin. Komennolla (play <n>) peli pyrii seuraavat
<n> puolisiirtoa. 'q' tai 'quit' poistuu ohjelmasta.

Graafinen kyttliittym ei tuottane ongelmia: valitse siirrettv
nappula hiirell, jonka jlkeen kone nytt keltaisina ne ruudut
joihin voit siirty tai hykt. Paina hiiren nappulaa halutun ruudun
kohdalla niin siirto tapahtuu. Oikeassa reunassa olevaan tekstialueeseen 
kirjoitetaan pelaajien siirrot ja tietoa tietokonepelaajan toiminnasta. 
Kun viimeisen rivin lukee "AI running...", tietokone on laskemassa 
siirtoaan.

Vasemmassa laidassa ylhll ja alhaalla pyrivt kummankin pelaajan
kellot. Valitettavasti ihmispelaajan vuorolla kellon aikaa ei pivitet 
jatkuvasti, vaan vasta kun siirto on tehty.


7. Tunnettuja ongelmia
----------------------

- Kaikki teklyt toimivat liian hitaasti isoilla pelilaudoilla tai
  suurilla hakusyvyyksill.

- PVS-tekolyn toiminnassa on ongelmia. Toisin sanoen se tekee joskus
  huonompia siirtoja kuin pitisi.

- Peliajan kulumista ei nytet ihmispelaajan pelivuorolla.

- Joillakin vanhoilla MzSchemen versiolla kynnistminen ei onnistu 
  johtuen tiedostojen keskinisist riippuvuuksista. Kyseiset versiot
  vaativat ett yksittisess ladattavassa tiedostossa ei ole kytetty
  mrittelemttmi muuttujia.


8. Tekijt
----------

Peli tekolytoteutuksineen tehtiin kevll 2003 harjoitustyn
Teknillisess korkeakoulussa kurssille Tietmystekniikan perusteet.
Tekijt ovat:

Sami Virpioja, <svirpioj@cc.hut.fi>
Ilari Lhteenmki, <ilahteen@cc.hut.fi>

Hierarkia-lautapelin suunnittelija on Jyrki Parkkinen, <jyjp@cc.hut.fi>.
Kiitokset mys Jussi Rautiolle, joka kirjoitti yls pelin sen hetkiset 
snnt ja terminologian ja ehdotti peli harjoitustyn aiheeksi.
