 #========================================================================#
 #                   GoMoku++ readme file (Version 2.1)                   #
 #                                                                        #
 #  Copyright (C)  Valer Canda 1997                 All rights reserved.  #
 #========================================================================#


 --------------------------------------------------------------------------
 Contents
 --------------------------------------------------------------------------
   1. What is GoMoku++
   2. Rules of the game
   3. The main window
   4. Menu commands
   5. General dialogue windows
   6. Computer players
   7. Properties of the players


 --------------------------------------------------------------------------
 1. What is GoMoku++
 --------------------------------------------------------------------------
 GoMoku++ is a strategy game playing program that was written as part of my
 graduation project:  "Computer implementation of strategic  games" for the
 Slovak Technical University in Bratislava. (Slovak Republic)

 The main purpose  of the project was not to  write a perfect go-moku game.
 Instead, it was  to demonstrate how computers can  play strategy games, to
 analyze  the algorithms  that strategy   games use,  and to  compare these
 algorithms to  determine the similarities  and differences. An  additional
 objective was to  determine how a strategy game  player could be simulated
 by a computer. Hopefully, these goals  and objects have been fulfilled and
 the GoMoku++ computer simulated players are reasonably good.

 This application is  written using MS Visual C++ 4.0.  It is optimized for
 Pentium processors but also runs on  486 and some 386 based computers with
 Windows 95, Windows NT 3.51+, and later operating system versions.

 This version of GoMoku++ is FREEWARE. However, I will not complain, if you
 decide to appreciate my work in any way...


 --------------------------------------------------------------------------
 2. Rules of the game
 --------------------------------------------------------------------------
 Two  players alternate  moves on  a square  board with  a  19 x 19  square
 playing field. All squares are empty at  the start of the game. One of the
 players  uses  the  sign  O  (circle)  and  his  or  her opponent uses the
 X (cross) to  indicate their moves.  When making a  move, the Player  must
 place his sign on  one of the empty fields. The winner  is the player that
 managed to occupy 5 adjacent fields in  one line. In the case that none of
 the players can meet the winning requirements and all squares on the board
 are occupied, then  the game is a draw.  Even in a game where  none of the
 players has a chance to build a 5 square line, the game is a draw.


 --------------------------------------------------------------------------
 3. The main window
 --------------------------------------------------------------------------
 The main window  of the GoMoku++ program consists  of several areas. Let's
 have a  short look at  them, starting from  the top and  moving toward the
 bottom of the main window.


 A) Title bar

    You can find here the name of the currently active game. If no name has
    been  assigned yet  to the  current  game,  the name  is identified  as
    "Untitled". The system menu is positioned to the left side of the title
    bar. The  minimize and close icons  are positioned to the  right of the
    title bar.


 B) Menu bar

    All commands  of GoMoku++ can  be reached via  menus located here.  All
    menu items are described in section 4 of this document.


 C) Toolbar

    The most frequently used commands can also be invoked through the icons
    on the toolbar. If you are not  sure which command is represented by an
    icon,  just pause  the mouse  pointer above  an icon.  A small  tooltip
    window appears  in a few seconds  providing a the name  of the command.
    Additionally, a short description appears on the status bar.


 D) Playing board

    Moves are made  on the playing board. When  it is time to make  a move,
    just take a look  at the mouse pointer. If it has  the form of a circle
    or cross, it's your move. If  the pointer looks like hourglass,then the
    the computer  is analyzing its move  and is currently thinking.  If the
    shape of  the pointer is  an arrow, then  the game is  over. No further
    play can occur.


 E) Status bar

    The  Status  consists  of  three  parts.  The  left  most part contains
    a context  sensitive description of  the currently active  control. The
    middle part displays  the status of the game.  You can find information
    there about whose turn it is and  whether the game has ended. The right
    most part of the status bar displays the progress of the analysis while
    computer  is  thinking  and  the  number  of  the  move, when a move is
    expected from you.


 --------------------------------------------------------------------------
 4. Menu commands
 --------------------------------------------------------------------------
 There are  five menus in the  main menu bar. Each  of them groups commands
 that are similar or related.


 A) File Menu

    This menu  contains commands that work  with the Go-Moku game.  In this
    context, a GoMoku game is treated  as a file. Also, the general options
    of GoMoku++  can be set here.  The application can be  exited from this
    menu too.

    * New
        Start a new game. Opponents taking part in the new game will be the
        players that were previously chosen  in the Who Plays dialogue from
        the last game.

    * Open...
        Open a saved  game. The standard Open File  dialogue box of Windows
        appears. You  will be able to  browse the files and  to choose one,
        that  should  be  loaded.  Only  valid  GoMoku++  *.gam  files  are
        accepted.

    * Save
        Save the currently opened game. You cannot save an empty game which
        has had  no moves made.  If you are  saving the game  for the first
        time, then you will be prompted for the filename.

    * Save As...
        Save the open game with a new name. The standard Save File dialogue
        box of Windows appears for you to enter the new filename and choose
        the directory for the file.

    * Options...
        Set up the general options  for GoMoku++. Further information about
        the Options dialogue box appears in section 5 of this document.

    * Recently used files
        At the  end of the  File menu  appears  the names of  the last four
        saved  games that  were most  recently opened  by GoMoku++. You can
        quickly  re-open any  of them  by clicking  on the appropriate menu
        item.  If you  haven't saved/opened  four games  yet, there will be
        less (or none) items in this part of the menu.

    * Exit
        Quit GoMoku++ by clicking on this menu item.


 B) Players Menu

    The  Players  Menu  contains  a  group  of  commands  related to player
    management and the assignment of the players to the game.

    * Who Plays...
        Select and set up players for  the current game. See description of
        the Who Plays dialogue for more information.

    * Switch Sides
        Switch  players that  are currently  taking part  in the  game. The
        player playing as O will become X and vice-versa.

    * Autoplay
        Set the expert computer player for  both sides. Game will be played
        automatically until the end or until  you break it. See the Options
        dialogue for information about setting up the expert player.

    * Opponent's Settings...
        Set up  parameters of your current  computer opponent. The detailed
        description of the  player properties can be found  in section 7 of
        this document.

    * Edit Players...
        Browse, add, or remove computer  players and edit their properties.
        See  the  description  of  the   Edit  Players  dialogue  for  more
        information.


 C) Action Menu

    The Action Menu contains commands  for controlling the game, especially
    browsing through all played moves.

    * Move Back
        Undo the last  played move. Or, in other words,  go to the previous
        position of  the game. You  cannot undo a  move, if you  are on the
        first position (empty board).

    * Move Forward
        Replay the next move of the game. A move can be replayed only if at
        least one move has been undone before.

    * Undo All Moves
        Return to the start of the game.

    * Redo All Moves
        Go to the last position of the current game in play. Redo all moves
        that have been undone.

    * Replay Game
        Replay all moves played in the  current game. The delay between the
        replayed moves can be set in the Options dialogue.

    * Stop Thinking
        Interrupt the current computer action.  It can be interrupted while
        thinking, autoplaying, and replaying.


 D) View Menu

    The  View Menu  commands influence  the appearance  of GoMoku++ and its
    components.

    * Tool Bar
        Show or hide the toolbar. This menu item is checked, if the toolbar
        is shown. The same is true about the status bar and the log window.

    * Status Bar
        Show or hide the status bar.

    * Log Window
        Show or  hide the Log  Window. See section  5 of this  document for
        more information regarding this window.

    * All Examined fields
        Switch ON or OFF marking of  all examined fields. Fields are marked
        only when a player derived from CMiniMaxPlayer, CAlphaBetaPlayer or
        CExtensivePlayer is  taking part in  the game. Examined  fields are
        marked  with  the  dark  gray  color  on  the  board. See the Field
        Reduction  radio buttons  of the  properties dialogue  box for more
        information about this topic.

    * Currently Examined Field
        Toggle marking of the currently examined field. The marked field is
        sunken.  Currently examined  fields are  marked only  when a player
        derived  from CMiniMaxPlayer,  CAlphaBetaPlayer or CExtensivePlayer
        is  thinking.  See  the  Move  Ordering  radio  buttons for further
        information related to this topic.

    * Worth Of Fields
        Display or hide the worths of fields of the board. These worths are
        used for evaluation of the field and position quality. The worth of
        field is the main indicator for  choosing the best move for players
        derived from  CLightPlayer and CMediumPlayer. The  sum of the field
        worths is the fundamental indicator  for evaluation of the position
        quality    used   in    players   derived    from   CMiniMaxPlayer,
        CAlphaBetaPlayer and CExtensivePlayer.

    * Follow Side On Move / Side Not On Move / Maximum Of Both
        Select  whose worths  of fields  will be  displayed. You can follow
        worths  of fields  that are  valid for  side on  move, or  for it's
        opponent, or the maximums of these  two values. You can switch this
        menu item only when the Worth Of Fields menu item is checked.


 E) Help Menu

    The  Help Menu  contains commands   that can  give you  some additional
    information related to the game and GoMoku++.

    * Advice
        You can  let the computer  expert suggest your  next move. See  the
        Options  dialogue box  for  information  about choosing  the expert
        player. The recommended move will be announced in a message box and
        the appropriate field will be sunken.

    * User Guide...
        Display this readme file.

    * About GoMoku++...
        Display a brief information about the program.


 --------------------------------------------------------------------------
 5. General dialogue windows
 --------------------------------------------------------------------------
 This section provides a short description  of most of the dialogue windows
 in GoMoku++. The properties windows of the players are described later.


 A) Options

    Some basic settings of the GoMoku++ can be set up here.


    * "Ask before closing unsaved game" check box.

      If you check this control, you will  be asked by a message box if you
      wish to save  the changed game, whenever you try  to open another one
      or to quit the GoMoku++.


    * "Default computer player (Expert)" combo box.

      You  can choose  one of  available players  as expert.  This computer
      player will play for both sides,  when you select the "Autoplay". The
      player will  also give advice to  you, whenever you will  ask for it.
      And, the same player will be  used as your initial opponent after the
      start of GoMoku++.


    * "Thinking thread priority" radio buttons.

      Analysis  of  the  game  tree   performed  by  players  derived  from
      CMiniMaxPlayer, CAlphaBetaPlayer or CExtensivePlayer can take a quite
      long time. To  avoiding a blocked application (ie.  not responding to
      any  inputs  from  mouse  or  keyboard)  during  this  analysis,  the
      algorithm runs in a separate thread. (Look for some information about
      multithreading,  if  you  don't  understand,  what  a thread is.) The
      priority  of this  parallel thread  can be  adjusted here. The higher
      priority  you choose,  the more  CPU  time  will be  assigned to  the
      analyzing thread and  the faster the thinking will  be. But the other
      applications  (also the  main thread  of the  GoMoku++) will get less
      performance.  If you  want to  work in  some other application, while
      some lengthy analysis runs in the  GoMoku++, choose a low priority to
      be not slowed down by your work.


    * "Pause for replaying" slider control.

      When you start the replaying of the  game, all moves of the game will
      be  replayed with  the lapse  that is  set up  here. The  shorter the
      delay, the faster the replaying.


 B) Who Plays

    This dialogue allows you to choose  the players that are taking part in
    the game. You can also set up  the properties of the players here. Both
    sides taking part in the game  have been assigned equal groupboxes that
    contain information about the names  of the players, their classes, and
    their short descriptions. The properties  window of the selected player
    can be invoked by pressing the "Properties..." button. The sides of the
    players can be switched via the "Switch Sides" button.


 C) Edit Players

    All players  can be browsed  and edited here.  New players can  also be
    defined here. The  created players can be removed  in the same dialogue
    window. Note,  you must leave  this window by  the "OK" button,  if you
    want to activate  the changes that you made here.  If you leave through
    the "Cancel" button,  all your changes will be  discarded. (The same is
    true about the close icon in the title bar.)


    * "Available Players" list box.

      All available players are listed here.  You have to select the player
      that you want to edit or remove in this list box.


    * "Properties" group box.

      The name, the  base class, and the short  description of the selected
      player are displayed here. You can edit the name and the description.
      The base class is entered when the new player is created.


    * "Add New..." button.

      If you  want to define  a new player,  push this button.  You will be
      prompted for  the name and  the base class  of the new  player. After
      creation, the new  player appears on the bottom of  the list, and you
      can edit his/her properties, if you wish.


    * "Remove" button.

      All players  that have been created  by you can also  be removed. The
      first 7 players cannot be removed, because they build a "player base"
      for GoMoku++.


    * "Settings..." button.

      By pressing  this button, you can  edit the settings of  the selected
      player.  Players  based  on  the  CRandomPlayer  class don't have any
      settings.  See  section  7   for  further  information  about  player
      properties.


 D) Log Window

    The Log Window collects information  about the game. The information is
    cleared each time, when a new game  is starting. You can find here, not
    only the names of the players  and their moves, but also some statistic
    information that  describes their thinking.  Only players derived  from
    CMiniMaxPlayer,  CAlphaBetaPlayer  and  CExtensivePlayer  provide these
    statistics. The collected  log information can be saved  to a text file
    via the "Save..." button.

    Let's describe the arrows of numbers, that you can find here.

    * SeenPos
      Number of positions  that have been examined before  deciding to play
      the move.

    * Time ms
      Duration of the analysis in milliseconds.

    * Pos/sec
      Speed of the analysis. [positions per seconds]

    * Branch
      Average branch factor.  How many moves had to be  examined in a usual
      position.

    * MaxDepth
      The maximal depth in "halfmoves"  (ply) that have been reached during
      the analysis.

    * Breaks
      Number of  breaks that occurred  during the analysis.  How many times
      a branch in the game tree has been pruned.

    * SavedWork
      How many positions were skipped (did not need to be examined) because
      of the pruning.

    * Score
      Evaluation  of the  current position.  Zero means  an equal position,
      positive  values  are  considered  to  be  good  for  the player, the
      negative ones for  the opponent. Values above 800  signal victory and
      values below -800 defeat.

    * Remark
      Some  players can  attach a   short comment  here. For  example, when
      thinking was interrupted or when a victory is assumed etc.


 --------------------------------------------------------------------------
 6. Computer players
 --------------------------------------------------------------------------
 I'm  sorry,  but  you  won't  find  here  an  explanation  of the minimax,
 alpha-beta-pruning,  or  other  algorithms  used  by  the  players  of the
 GoMoku++. These  topics are out  of scope of  this document. You  can find
 them in many books of artificial intelligence or on the web.

 This  version of  GoMoku++ contains  6 classes  of computer players. These
 are: CRandomPlayer, CLightPlayer, CMiniMaxPlayer, CAlphaBetaPlayer and the
 CExtensivePlayer. Each of the classes  uses a different algorithm. A short
 description of  all classes follows  in this section.  Further information
 about parametrisations (properties) of all players can be found in section
 7 of this document.


 A) CRandomPlayer

    A  player  that  doesn't  think  at  all.  S/He  just  puts the sign on
    a randomly chosen empty field. If you  won't be able to beat him/her in
    5 moves, then don't even try to play against the other players... :)


 B) CLightPlayer

    A  player  that  examines  the  fields  of  the  current  position, and
    depending on their  worth, chooses the best one  for his/her next move.
    S/He also detects  some double attacks and uses  them, if possible. The
    simple  algorithm,  used  by  this  player,  makes the CLightPlayer the
    quickest one of all non-random computer players.


 C) CMediumPlayer

    This player  also examines only  fields in their  current position, but
    uses  an advanced  evaluation strategy,  which enables  him /her  exact
    detection  of all  double attacks.  Thus, s/he  is able  to predict his
    victory up to 3 moves. (Even if s/he doesn't scan the game tree.)


 D) CMiniMaxPlayer

    This is  the first player that  doesn't scan the fields  of the current
    position.  Instead, it  scans all   possible sequences  of moves  up to
    a specified depth. To this depth, all positions are evaluated, not only
    their single fields. Values of the positions are propagated back up the
    tree, and the best move is  chosen according to these evaluations. This
    is a usual minimax algorithm.


 E) CAlphaBetaPlayer

    This  player  uses  the  alpha-beta-pruning  method.  It  is  a similar
    algorithm  to the  minimax, but  is much  more efficient.  Its speed is
    increased  by pruning  the non-perspective  branches in  the game tree.
    Thus,  the  alpha-beta-method  manages  to  examine  the  game  tree to
    a greater depth than the minimax in the same period of time.


 F) CExtensivePlayer

    This   is   the   most   sophisticated   player   and   uses  both  the
    alpha-beta-pruning  and  an  extensive  heuristic. Extensive heuristics
    detect  some  positions  in  terminal  depth  that  should  be examined
    a little deeper. This strategy  makes possible to detect some victories
    in such a depth that could  not be examined by the alpha-beta-method in
    a reasonable time.


 --------------------------------------------------------------------------
 7. Properties of the players
 --------------------------------------------------------------------------
 The characterists and qualities of the players can be influenced radically
 through their settings.  Most of the settings are  the parametrisations of
 used algorithms. The  power and speed of several  players derived from the
 same class vary depending on the  settings. The settings of any player can
 be reached through the "Settings..." button of the "Edit Players" dialogue
 window.  (Only  players  derived  from  the  CRandomPlayer  don't have the
 settings.)


 A) CHumanPlayer

    The only  thing you can  set up  for  this player is  the input device.
    Usually both the keyboard and mouse are enabled. If you want to let two
    people play, then you can enable only the mouse for the first, and only
    the keyboard for the second one. This way, the players cannot interfere
    with each others moves.


 B) CLightPlayer

    Defender, normal, or  attacker can be chosen as  the playing style. The
    quality of the  evaluation can be primitive, sensible  or fanatic. Only
    the defender and attacker support the fanatic evaluation. The primitive
    version doesn't  distinguish many double  attacks and is  simplified in
    comparison with the  normal one. The fanatic tries  to defend (attack),
    even if it's not necessary.


 C) CMediumPlayer

    This  class  of  players  can   use  defensive,  normal  or  aggressive
    evaluation. It is similar to the previous class, but it doesn't support
    the  evaluation adjustment,  which only  would decrease  the quality of
    this player. (See the section 6C for an additional information)


 D) CMiniMaxPLayer, CAlphaBetaPlayer

    These  two  players  examine  the  game  tree,  and  both have the same
    parametrisations. Explanation of these follows.


    * Maximal depth

      The maximal depth  of the examination of the game  tree. The depth is
      entered in halfmoves  (plies). A depth of one  means: "examine all my
      sensible moves",  depth two: "examine  all my sensible  moves and for
      each of  them all my  opponent's sensible answering  moves", etc. The
      dependency between depth and time needed for analysis is exponential.
      It means,  that you probably won't  be willing to wait  for more than
      a   depth   of   3   by   CMiniMaxPlayer   and   a   depth  of  5  by
      CAlphaBetaPlayer... ;)


    * Reduce branch factor.

      The branch factor expresses how many  moves have to be examined in an
      average position.  Reducing the branch  factor in this  way may cause
      a  serious decrease  in game  quality. I  suggest that  you use  this
      choice only  with selected "Absolute  best first" move  ordering, and
      not to use  a smaller branch factor reduction than  20. If the branch
      factor is not reduced, all reasonable moves (see the field reduction)
      will be examined in each position.


    * Type of field reduction

      Not all possible moves make sense  in a position. Here you can choose
      how  these  moves  will  be  selected.  You  can  visualize the field
      reduction by  checking the menu  item /View/All examined  Fields. "No
      reduction" means that  all fields will be examined.  Each of the next
      reductions is stricter. (going from top to bottom)


    * Type of move ordering

      Moves chosen  for examination will be  examined in the order  that is
      selected here.  For example, "My  best first" means  that fields with
      the highest  worth for the side  making the move are  examined first.
      When "Absolute  best first" is selected,  moves are ordered according
      to their  higher worth (for  the side on  move or opponent).  You can
      visualize   move   ordering   by   checking   the   View   menu  item
      View/Currently Examined Field.


    * Aging

      Aging  provides  a  small  improvement  for  the detection of winning
      positions. When aging is on, all  winning values will be decreased by
      1 by  each propagation up  the game tree.  This makes it  possible to
      identify the shorter path to victory from longer ones.


    * Attack

      Normal  evaluation function  (function that  evaluates the positions)
      considers  the difference  between a   players sum  of worths  of the
      fields  and the  opponent's sum  of worths  of the  fields. When this
      option  is  checked,  the  difference  between  the  numbers  of  the
      player's possible  attacks and the  opponent's attacks is  considered
      also.


 E) CExtensivePlayer
    Most of the settings for this player are similar to the settings of the
    CMiniMaxPlayer  and  CAlphaBetaPlayer  players.  Some  new settings are
    described here.


    * Maximal full search depth

      This extensive player examines the game  tree to this fixed depth and
      then chooses  some of non-quiet  positions for the  next examination.
      These  positions  can  be  examined  up  to  the "Maximal total depth
      including  extensive  search".  This  technique  (extension)  enables
      detection of deep combinations without wasting the time of a full and
      deep examination. Some  examples of good choices for  depths would be
      3 for the full depth and 6 or 8 for the total depth.


    * Weighted

      A weighted evaluation function will be used  instead of a linear one,
      when this option is checked.


 Well, that'll be all. I wish you pleasant playing with GoMoku++.

 Valer
 <canda@vadium.sk>

 --------------------------------------------------------------------------
 End of file.
 --------------------------------------------------------------------------