=================================================================
          xpexeso -- the game with 64 picture cards
=================================================================
July 1999                                              Petr Olsak

The winner is usually the player with a better "short" memory. You have to
remember the position and contents of cards. The program xpexeso emulates
the classical game PEXESO, which is widely played by children. The program
is implemented for X Window System.

The rules of the game
=====================

The game is for two or more players. If the xpexeso program is used, some
player(s) can be substituted by computer. The game includes 64 picture
cards coupled into pairs. There are 32 pictures (the same picture on each
pair). The backside of all cards is common for all cards.

The cards are mixed and all cards are dealt to the table backside up into
8x8 rectangle on the start of the game. The players change periodically
with his playing. The playing of one player consists from one or more
moves. One move is turning out of two arbitrary cards. The move is
successful if and only if these two cards have the same picture. In this
case, the player removes this pair from the table and adds one point to his
score. The player continue with next move until his moves are successful.
If the move is not successful, the player have to turn back the two shown
cards on the same place where they were before this move. Then the next
player starts his playing. If the table is empty the game is over. The
winner is the player with maximum of points (it means with maximum of
successful moves during the game). The players cannot do any notices about
cards into "external memory" during game. They have to store all
information only in his own memory.

The program description
=======================

The program randomizes and deals all cards on graphics window at the start
of program or when the button "new game" is pressed. Default players are
two: you and computer. The list of players may be changed in "setting"
dialog window. The computer-player works with the memory different from
memory of routine, which shows the values of chosen cards on the window. It
means, the computer-player does not sharp. You can set the capacity of
memory of computer-player. This brings the computer-player at the near to
human player. If the capacity of memory is set to 100 moves (say), many
people cannot win over the computer.

You can set the names of all players in "setting" dialog window. The
names are separated by space. If the name begin with the "@" or "*"
character, this player will be substituted by computer. These
"computerized" players can be more than one. But all computer-players
of one type (@ or *) work with the same memory with the same capacity
setting. Example (two human and two computer players):

John @Hall9000 Mike @Robot

You can set only one self-player too. In this case you can ask how
many moves you need to end of game.

Who is currently playing is shown (including the number of points) in the
upside of the main window. The player can pass his move (this is an
extension from the classical game rules). He can click on the button of
next player. If you click to another player button before computer-player
starts his move, you can break the playing of the computer-player too.

The human player have to click to two cards. If the move is not successful,
he/she have to click to these cards secondly to turn they back. It means,
he/she can see the contents of these cards arbitrary long time. If the
computer player is playing, it turn out first card after "pretimewait",
second card after "timewait", delay "longtimewait" with two cards shown,
then turn back first card and turn back second card after "timewait". You
can set the parameters "pretimewait", "timewait" and "longtimewait" in
"setting" dialog window.

The "New game" botton gives you the possibility to choose the new
picture set. The default picture set is "Vecernicek". All picture sets
are configured in pexet-eng file and are stored in xpm graphics format.
You can make new picture set. Read the pexset-eng file for more
information.


How behaves the computer player
===============================

You can set the memory capacity of computer player by two parameters in
"setting" dialog window. First parameter "number of exactly remembered
moves" gives the number of moves. If some card was shown only in a move
older than this value, the computer does not know exactly about it.
Computer can know about this card approximately, if this move fall within
the interval from "number of exactly remembered moves" + 1 to "number of
all remembered moves". If the move is older than the value of second
parameter, the computer totally does not know about this card. If the
computer know about some card only approximately, then he can try to turn
out this card in probability 1/4, he turn out the neighboring card with
probability 1/8 and he turn out the diagonal neighboring card with
probability 1/16. The probability is greater, if some cards are missing or
are remembered by computer exactly. If you set the "number of exactly
remembered moves" greater than "number of all remembered moves", the second
parameter is set to maximum of both. You can try to set both parameters to
zero (computer generates all moves randomly) or to 100 (you will not able
to win). Notice: The parameters describe only the number of unsuccessful
moves because it is no reason to remember the cards from successful moves.

Example: "number of exactly remembered moves" = 3 and "number of all
remembered moves" = 10. The computer remembers 3 moves back exactly. It
means 6 (no necessary different) positions and values of cards from these
moves. Computer remembers the cards only approximately in 7 more moves
back. This setting is default and it gives possibility to human player to
win the game.

You can set for computer player two game strategies: open playing and
spiteful playing. This setting influences turning out of the second card in
the case if the pair card for the first one is not known by the computer.
Computer can turn the second card as not known card, but this move can by
helpful for the next player. This is the open strategy. On the other hand,
computer can turn out the second card as well-known card in order to
suggest nothing for next player (spiteful strategy). If the spiteful
strategy is set, the computer player saves his memory because the second
well-known card is remembered in special memory independent on standard
computer-player memory. Thus the computer have to remember only one card
from this move. This is comparable with one half of common move.

You can set the talk level for the computer. The option "silent" means
that computer write nothing about its and your playing. The option
"names" causes that all names of used cards will be shown.  The option
"comment" means that computer writes the notices about its own playing
("I know both cards", "I guess both cards", "I am lucky", "I choose
randomly", "I guess second card", "I known second card", "Just my
luck", "I was not successful") The option "kibitz" means that computer
write notices about its playing and on the top of it notices about
human playing ("I know second card", "I don't know second card", "It
was shown before", "I guess second card", "I have known this", "I have
guessed this", "I have not known this", "This is a new card").
This kibitz-computer uses memory of computer-player of type @.
You can leave this player out of game (but kibitz) and play with
computer type * with another memory settings.

The program can write the log file with detail information about all moves
in the game and about memory state of computer player. You can set the
name of log file on command line only. The memory dump is used by 
@ type computer player.

The delay parameters are set in tenth of seconds. All three delay
parameters "pretimewait", "timewait" and "longtimewait" was mentioned in
previous section.


The command line options
========================

You can use common X11 options (for example -fn font). In addition, you can
use following special program options:

-log filename ... the log is written into filename
-log -        ... the log is written on standard output
-set filename ... the configuration file for list of picture sets.
-defaultset number ... the number of default picture set 
                  (default: 1, it means the first set in pexset-eng).
                  If -defaultset 0, the default is randomized.
-doc filename ... the documentation is read from filename

-cards CxR    ... You can set another number of cards than default 8x8
                  by this option. (C is number of columns and R number
                  of Rows here). Example: -cards 16x8 

The maximum of cards is set in config.h by MAXPOCETKARET parameter to
128. No all pic-sets will work in this case because more picture data
files are needed (the "Vecernicek" is mixed with "Animals from Africa"
and the "Flowers filed" includes sufficient number of pictures).  If
the number of cards is odd, one card is no in pair a this card stay on
the table during whole game. The picture of this stand-alone card is
generated randomly.

-picgeometry WxH ... you can fix the width and height of all
                  pictures in all pic-sets by this parameter.
                  Example for low resolution screens:
                  -picgeometry 50x56

Next command line options may be used for setting another than default
values of basic parameters used in program. User can do more change of all
this values in "setting" dialog window.

-players "list of players" .. the players (default: "You @Computer")
-m1 number ... number of exactly remembered cards of @ (default: 3)
-m2 number ... number of all remembered moves of @ (default: 10)
-close-game .. the spiteful game strategy of @ (default: open)
-second    ... the following -m1 -m2 -close-game set * instead @
-t1 number ... pretimewait (default: 8 tenth of seconds)
-t2 number ... timewait (default: 4 tenth of seconds)
-t3 number ... longtimewait (default: 35 tenth of seconds)
-talk level .. the talk level (0 = silent, 1 = names, 2 = comment, 
               3 = kibitz, default: 0)
-no-move-out . leave the cards after successful move on the table
               (default: move these cards from the table)


The history of program
======================

This is my first program for X Window System. I am sure that the task is
possible to solve by special library more comfortable and with more fine
result, but I have bad experience with programs dependent on some special
(still in developing) libraries. These programs are very complicated to
compile they on various platforms. The newer version of libraries is needed
to compile before building the programs. I suggested to use only the old
and everywhere present X Toolkit and X Athena in my program. The pictures
are read by Xpm. No more.

The idea to write the PEXESO program came from my son Mirek (8 year old).
I said: If you draw 32 pictures using Gimp then I write this program.
Unfortunately, he has drawn the pictures during few days. This was a
reason why I have started with study of textbook by Ales Limpouch
(Programming in X Window System) and I started with writing my work.
The fact that the PEXESO was implemented by Petr Blaha for svgalib library
was not usable for me, because we need the program for X. His source code
was not employed and I wrote all code once again. To write the
platform  independent algorithms and to implement the "human behavior"
of computer-player was the more simple task. In version for text 
terminal (without pictures) was the game written and tested during 
one day. Next two weeks, I struggled with widgets, events and similar 
objects of X Athena.

Many of distributed picture sets were made by brothers Petr and Pavel
Matula in 1994. These sets are distributed with their program pexeso
for MS DOS. This program is free and available without source codes on
http://www.fi.muni.cz/~pam/pexeso/. The implementation of graphics is
famous because the old DOS machines were assumed thus only 16 colors
are used for all pictures all-together. Every picture is placed only in
56x56 pixels square. These sets are distributed in xpexeso program
with kind permission of Pavel Matula.

If you make a new interesting picture set, I like to include it into
xpexeso distribution. We have many power tools for making pictures now
(Gimp for example) and we are not limited to 16 colors only.

Copyright
=========

This work has been as "labor of love" and the program can be distributed
under the same conditions as is written in GNU General Public License. The
scanned pictures are not a subject of this license and are not a part of
this program in this meaning. The program works without these pictures too.
You can draw his own pictures or use Mirek's pictures.
