
		Hierarkia - Scheme Implementation README

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


Contents
--------

1. Files
2. Required software
3. Compiling
4. Running
5. Configuration
6. User interfaces
7. Known bugs
8. Authors


1. Files
--------

Original "Hierarkia - Scheme Implementation" package contains the
following files:

README			- This README file
README-fi		- README file in Finnish
COPYING			- GNU General Public Licence
Makefile		- Makefile for compliling the source
rungame.sh		- Shell script for starting the game
hierarkia.scm		- Program source; core of the game
ngui.scm		- Program source; non-graphical user interface
mred-gui.scm		- Program source; graphical user interface
human.scm		- Program source; human player object
ai.scm			- Program source; general AI procedures
ai_plain.scm		- Program source; AI object implementation
ai_iter.scm		- Program source; AI object implementation
ai_mtd.scm		- Program source; AI object implementation
ai_imtd.scm		- Program source; AI object implementation
ai_pvs.scm		- Program source; AI object implementation
rungame.scm		- Program source; game initialization and starting
rungame-compiled.scm	- Program source; game initialization and starting
rungame-sources.scm	- Program source; game initialization and starting



2. Required software
--------------------

This program requires MzScheme interpreter and MrEd Graphical Toolbox
library of PLT DrScheme package. See <URL:http://www.plt-scheme.org/>
for downloading and manuals. Version 202 or higher should work.
PLT Mzc compiler is required for compilation.

GNU Make or similar Make implementation is needed for compilation
script. See <URL:http://www.gnu.org/software/make/make.html>. It is
not needed for running the game, however.


3. Compiling
------------

Program can be loaded to the interpreter as source code, but
compiling some of it to native code optimizes speed.
Makefile included in the package compiles sources to .so
files supported by Unix and MacOS systems.

Change your working directory where you uncompressed the package,
and run 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
(etc.)

After compiling the source code, Makefile replaces rungame.scm 
for rungame-compiled.scm so that it will load the compiled files
instead of sources.

Command 'make clean' removes compiled files and restores rungame.scm
so that it uses again the source files (ie. replaces it with 
rungame-sources.scm).

Compiler can be used also in MS Windows, but using compiled .dll
files needs some manual configuration. After compiling the .scm
files (excluding mred-gui.scm, which cannot be compiled), make a
copy of rungame.scm which will load the compiled files.


4. Running
----------

- Unix platforms:

To run the game, execute shell script rungame.sh:

% ./rungame.sh

Script requires that mred program is included in the path. It
simply starts interpreter, loads rungame.scm and after done,
evaluates expression (exit) which quits the interpreter:

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

Alternatively you can start graphical drscheme interface, load 
rungame.scm and execute it.


- Windows platforms:

Open rungame.scm either in MrEd or DrScheme program and execute it.


5. Configuration
----------------

The game can be configured by editing file rungame.scm. Commented
lines begin with semicolons (;). Here is what the file does:

1) Defines size of the board and number of units on the board

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

With these values, board size is 7 x 7 and value of the highest
unit is four.

2) Loads the game core from file hierarkia.scm or hierarkia.so.
Source file (.scm) is loaded with load procedure, compiled version
with load-extension.

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

3) Creates the game board object and initializes it:

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

After this, variable board points to initialized board object.
With example definitions of step (1) it looks like this:

B4 B3 B2 B1 -- -- --
B3 B2 B1 -- -- -- R1
B2 B1 -- -- -- R1 R2
B1 -- -- -- R1 R2 R3
-- -- -- R1 R2 R3 R4

Where '--' means an empty square and for example 'R2' means red unit 
of value four.

4) Loads player procedures from either .scm or .so files:

        (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")
OR
        (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) Loads user interface objects. File ngui.scm (or ngui.so) includes
non-graphical interface, mred-gui.scm (only .scm) graphical. Only one
of the files are not required, only the one used in next step.

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

AND/OR
        (load "mred-gui.scm")

6) Creates user interface object. First of the following creates
non-graphical interface, next one graphical. 

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

7) Starts the game with start-game procedure:

        (start-game 'human 'ai gui)

First two arguments of the procedure must be either 'ai or 'human.
(String starting with a single quote means a symbol.) First argument
is for blue player, second for red player. Arguments set players
either to AI or human players.

Third argument is user interface object created in step (6).

Default AI player uses Alpha-Beta search with search depth four.
Graphical user interface includes menus for changing AI properties.
They can also be defined in additional arguments of start-game 
procedure. Arguments are form
'(ai <player> <type> <depth> <maximum depth>),
where <player> is either 1 (blue player) or 2 (red player) and 
<type> is one of the following:

plain - default alpha-beta search
iter  - iterative deepening alpha-beta
mtd   - alpha-beta using MTD(f) algorithm
imtd  - iterative deepening alpha-beta using MTD algorithm
pvs   - alpha-beta using Principal Variation Search algorithm

Search is limited by two depths: <depth> tells how deep search
is done in quiescent (non-attack) states, <maximum depth> defines 
the maximum depth.

For example, next expression creates two AI players that use
iterative deepening alpha-beta search with depths 2 - 4 and 3 - 5:

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


6. User interfaces
------------------

Non-graphical interface is used mainly on test runs with AI players.
The expression (play <n>) plays next <n> half rounds. 'q' or 'quit'
quits the program.

Graphical interface is used with mouse. Select the unit to move with
a mouse click. After that squares that can be attacked or moved to are
shown with yellow color. Click on one of them to make the move.

In the right side of window there is a text area. Moves and information
on a running AI player is displayed there. When the last text is
"AI running...", AI is calculating its move.

In the left there are to clocks which show how much time each player
is used in seconds. The value increases also when human player is
making his move, although the clock doesn't show it.


7. Known problems
-----------------

- All AI implementations are too slow with bigger board sizes and
  greater search depths

- AI implementation using PVS has bugs. It makes worse moves than it 
  should.

- Clock display is not updated when human player makes moves.

- With some older MzScheme versions rungame.scm cannot be loaded.
  This is due to dependencies between different files. The newest 
  versions should work fine.


8. Authors
----------

Game and AI implementations were done in spring 2003 as an assignment 
work on course "Introduction to Knowledge Engineering" in Helsinki
University of Technology. The authors are:

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

Designer of the original board game "Hierarkia" ("hierarchy" in English) 
is Jyrki Parkkinen, <jyjp@cc.hut.fi>. Thanks also to Jussi Rautio for 
writing up rules and terminology of the game and submitting the game 
idea to us.
