=========================================================================
                                                                   README
=========================================================================

GNECT - A FOUR IN A ROW GAME FOR GNOME

Gnect is really two different pieces of software working together -
my user interface plus Giuliano Bertoletti's Velena Engine. So, this
file contains two main sections:


    1: THE GNECT README
    2: THE VELENA ENGINE README


Please check the INSTALL file for Requirements and Gnect specific
installation information, and the TODO file for bugs and plans.


=========================================================================
1: THE GNECT README
=========================================================================

CONTENTS

    - The Object of the Game
    - The Velena Engine
    - Velena Engine Source (Changes, etc.)
    - Gnect's Menus and Toolbar
    - The Preferences Dialogue
    - Command Line Options
    - Custom Tile Sets and Themes
    - Questions, Updates and Bug Reports
    - Troubleshooting
    - Contacting Me
    - Acknowledgements
 


THE OBJECT OF THE GAME

    Gnect is a Four in a Row game for GNOME. The object is to build a
    line of four of your counters while trying to stop your opponent
    (human or computer) building a line of his/her/its own. A line can be
    horizontal, vertical or diagonal.

    Here's a very good spot on the WWW for related information, software
    and links:


      http://www.pomakis.com/~pomakis/c4/



THE VELENA ENGINE

    Gnect's main computer player is Giuliano Bertoletti's public domain
    Velena Engine, a very sophisticated piece of software using "AI"
    techniques rather than "brute force" alone. If set to its highest
    skill level, and if it makes the first move in a new game, it will
    not lose. Even if it doesn't make the first move, it's still
    extremely hard to beat.

    For detailed information about the Velena Engine, please visit
    Velena's homepage:


      http://www.ce.unipr.it/~gbe/velena.html


    Please don't hassle Giuliano with questions or bug reports about
    Gnect - he's not responsible for Gnect or any problems you might
    experience with Gnect.



VELENA ENGINE SOURCE (Changes, etc.)

    I've tweaked the Velena Engine source code slightly to get it running
    with Gnect and vice versa. Therefore, you should download Giuliano's
    original Velena Engine source if you want to see it "untouched".
    Here's what's different in the Velena Engine code that comes with
    Gnect:

    - Parts of two files behave differently: connect4.c and error.c
    - This file has been replaced: wc.c
    - All files have had // .... replaced by /* .... */
    - gets() replaced by fgets() and a few unused variables commented out,
      just to shut gcc up.
    - Velena Engine's log file has been disabled. (The variable named
      doVelengLogfile in gnect.c flags this.)
    - I've added a note below Giuliano's copyright note in each source
      file. My addition reads as follows:

          The author, Giuliano Bertoletti, has kindly granted
          permission to distribute this software under the
          terms of the GNU General Public License. (Please see
          the COPYING file for details). Note that these files
          have been hacked a bit for inclusion with gnect. The
          original Velena Engine source can be found here:
          
          http://www.ce.unipr.it/~gbe/velena.html

          - Tim Musson, yyyy.mm.dd

    - The following source files belong to the Velena Engine:

         src/bintree.c     src/cmdline.c      src/pbsolver.c
         src/proto.h       src/con4vals.h     src/dummy.c
         src/heurist.c     src/playgame.c     src/rules.h
         src/connect4.c    src/error.c        src/heurist.h
         src/pnsearch.c    src/connect4.h     src/evaluate.c
         src/ia_main.c     src/pnsearch.h     src/adjmtrx.c
         src/buildob.c     src/database.c     src/offsets.h
         src/wc.c

      Also, the opening book file (data/white_ob.cn4) was supplied
      with the Velena Engine source.

      I have not pruned out the bits not relevant to Gnect, so some
      of the included Velena Engine code is redundant.

    - The following source files are Gnect's:

         src/gnect.c      src/gnect.h         src/dialog.c
         src/dialog.h     src/prefs.c         src/prefs.h
         src/theme.c      src/theme.h         src/gui.c
         src/gui.h        src/gfx.c           src/gfx.h
         src/sound.c      src/sound.h         src/file.c
         src/file.h       src/brain.c         src/brain.h
         src/main.c       src/main.h



GNECT'S MENUS AND TOOLBAR

    Only a couple of items deserve notes...

	"Undo" (in the Games menu and on the toolbar) can undo more than just
    the last move - it can take you right back to an empty board. If
    you're playing against the computer, the undo function assumes it's
    _your_ last move you want to undo - it's therefore forced to undo the
    computer's last move before undoing yours. If a computer player made
    the very first move, that first move will not be undone.

	"Draw grid" (in the Settings menu) toggles the drawing of a grid over
    the background image. This only affects themes that use full-window
    background images.



THE PREFERENCES DIALOGUE

     Player Selection

       + The "Player One" and "Player Two" options let you select who's
         playing. Making changes here will end a game in progress.
         The computer player named "Gnect" originally served as a place
         holder - but, since it's a pretty nice level for young kids,
         I've kept it around.
       + "When starting a new game, who moves first?" What these options
         do is pretty jolly obvious.

     Appearance

       + The Theme menu is where you select... a theme. Just below it
         you'll see the short descriptions Gnect will use to refer to
         players in status bar messages and on the score board. In
         human vs computer games, Gnect ignores these descriptions and
         uses "Me" vs "You" instead.
       + "Enable animation" ...I forget what this toggle does.
       + "Animated wipes" toggles the way Gnect clears the board before
         starting a new game. If checked, it'll pick a wipe at random.
         If unchecked, these wipes are disabled. This option is only
         available if animation itself is enabled.

     Miscellaneous

       + The Sound menu lets you choose between No sound, Speaker beeps
         or GNOME sound events. Before using the GNOME souund events
         option, you'll have to set the sound events up (no sound files
         come with Gnect). You can do this via the GNOME Control Center.
       + The Keyboard boxes let you arrange keyboard control to your
         liking. Select an action then press the key you'd like to
         perform it. 



COMMAND LINE OPTIONS


     --debugging

           Causes Gnect to display information that might help if
           you're troubleshooting or just bored.


     --seed=ARG

           Seeds the random number generator with the value you specify
           with ARG, rather than letting Gnect seed it using the system
           clock. (Either way, the --debugging option will show you the
           seed used.


     -xARG and -yARG

           Specify the position of Gnect's window on the desktop.



     As with other GNOME apps, the --help option will list more options.



CUSTOM TILE SETS AND THEMES

     Gnect's tile sets (I suggest PNG format) contain six tiles of equal
     size, lined up horizontally. From left to right:


       1.Player one's counter as it'll appear on the main board
       2.Player two's counter as it'll appear on the main board
       3.Main board background
       4.Top row background
       5.Player one's counter as it'll appear on the top row
       6.Player two's counter as it'll appear on the top row


     Gnect automatically calculates the tile dimensions:


         tile height = tile set height
         tile width  = tile set width / 6


     That is, your tiles can be square or rectangular - and any size you
     like. Most of the tile sets that come with Gnect use tiles measuring
     40x40 pixels ("small"), 45x45 ("medium") and 50x50 ("large").

     Try to stick to certain colours for each player - not always
     possible, but anyway - it helps people adjust when meeting a new tile
     set for the first time. Here's the system I've used so far:


         Player one: Red, Orange, Green, Dark 
         Player two: Blue, Purple, Yellow, Light 


     You can save your tile sets in either ~/.gnect/pixmaps/ (which you'll
     have to create yourself) or the pixmap directory created when Gnect
     was installed (probably either /usr/share/pixmaps/gnect/ or
     /usr/local/share/pixmaps/gnect/).
         

     Before Gnect can use your new tile set, you'll need to write a theme
     file for it. It's just a plain text file with a .gnect extension.
     Here's an example: buttonshop_50x50.gnect

         #
         # This is an example Gnect theme file.
         #

         # This theme's title (required)
         Title = Button Shop

         # The tile set (required)
         Tileset = tileset_50x50_buttonshop.png

         # A short description of player
         # one's counter (required)
         Player1 = Green

         # A short description of player
         # two's counter (required)
         Player2 = Yellow

         # Details (optional)
         Tooltip = A tribute to button makers everywhere
         

     Save buttonshop_50x50.gnect in either ~/.gnect/themes/ or the data
     directory created when Gnect was installed (probably either
     /usr/share/gnect/ or /usr/local/share/gnect/).
         

     Next time you run Gnect it'll find the new theme and, assuming the
     pixmap exists, you'll be able to select Button Shop via preferences. 

     So, what if you want a full-window background image, rather than just
     one small tile repeated over the background? First, decide on the
     tile set you want to use. Work out the dimensions of a 7 column by
     7 row background image using that tile set (eg., a 240x40 tile set
     is based on 40x40 pixel tiles - so a full-window background would
     measure 280x280 pixels). Add the following lines to a theme file:


        # Full-sized background image (optional)
        Background = bg_50x50_buttonshop.jpg


     You can use pretty much any file format you like for the background
     image. Save it in the same location as your tile set files.

     If the tile set you use with that background uses transparency, the
     background will show through the transparent bits. Also, the third
     and fourth tiles (ie. the background tiles) in the tile set will not
     be drawn if you specify a background image.

     If you want a grid of a specific colour (the default is black) drawn
     over your background image, add a line like this to your theme file:


         # Draw a grid of this colour (optional)
         GridRGB = RGB:FF/FF/FF


     You can specify the grid colour in other formats, too. For example:


         GridRGB = white


     If you _don't_ want a grid (say, your background image has one built
     in), add the NoGrid keyword (it needs no value).


         # Never draw a grid with this theme (optional)
         NoGrid


     Note that Gnect can only draw a grid if the theme uses a background
     image.



QUESTIONS, UPDATES AND BUG REPORTS

     To see if you have the most recent version, please visit Gnect's
     homepage. If you'd like to complain about a bug, or if you have a
     question or suggestion, feel free to email me.


         http://homepages.ihug.co.nz/~trmusson/gnect.html


     Please read the file named TODO for plans and bug information.

     Extra themes can be found on Gnect's homepage.



TROUBLESHOOTING

     If Gnect stops working for no apparent reason, your best bet is to
     delete your Gnect preference file (probably ~/.gnome/gnect). Gnect
     should build a new one, leaving out anything troublesome. If that
     doesn't work, make sure there's at least one theme file in Gnect's
     data directory (see above: Custom Tile Sets & Themes) and that it
     names a tile set that really does exist in Gnect's pixmap directory.
     If that doesn't work, email me and complain.



CONTACTING ME

       Tim Musson - trmusson@ihug.co.nz

       If IHUG goes bankrupt, try timothym@clear.net.nz



ACKNOWLEDGEMENTS

       + Thanks to Giuliano Bertoletti for permission to incorporate the
         Velena Engine and distribute the result under the GPL. If Gnect
         is a worthwhile program (and it is!) then 99.9 percent of that
         worth is in Giuliano's Velena Engine. 
       + Thanks to David Neary, who suggested the Velena Engine would
         make an excellent computer player for Gnect and basically got
         me enthusiastic again. Gnect would probably have died without
         his idea and encouragement. David has also put a lot of work into
         Gnect's event handling - an area I was having big problems with.
       + Thanks to Alex Duggan of http://www.astrolinux.com/ for supplying
         the RedHat7.0 RPMs available on Gnect's homepage.
       + Thanks to Diego Restrepo for supplying the RedHat6.x RPMs
         available on Gnect's homepage.
       + Havoc Pennington, George Lebl, Tony Gale and Ian Main: excellent
         GTK and GNOME tutorials. (This is my first GUI-based program,
         as you might've guessed.) You'll find the tutorials at
         http://www.gnome.org/



LICENSE

     Gnect is released under the GNU General Public License. Please see
     the file named COPYING for details - or visit:


         http://www.gnu.org/copyleft/gpl.html




=========================================================================
2: THE VELENA ENGINE README
=========================================================================

Velena Engine Source Code V1.00  (written by Giuliano Bertoletti)
Copyright (C) 1996-97 Giuliano Bertoletti & GBE 32241 Software PR

Released 27/07/1997
=========================================================================

This is a Connect 4 AI core engine. Please download Velena for the whole 
documentation.

Velena can be found at the following adresses via Internet:

http://www.ce.unipr.it/~gbe/velena.html  (official homepage)

ftp://x2ftp.oulu.fi/pub/msdos/programming/ai/velenaXX.zip
   where XX is the current version of Velena (now is 18).

=========================================================================

Acknoledgements

Velena Engine Source Code is free software; you can redistribute it and/or
modify it under the following conditions:


1 - If you make a derived work, the full source code must be distributed
    and placed in public domain.

2 - You must not charge a fee for this software nor for any derived work
    in which this software is included.

3 - You must not delete the copyright notices in the source code
    (but of course you can make your own layout for graphics and copyright notices on
    the screen, provided it's clearly expressed that you used the Velena Engine Source
    Code and that's a derived work).



Disclaimer

This software is distributed in the hope that it will be useful, but
without any warranty; including but not limited to implied warranties
of merchantability or fitness for a particular purpose with respect to
the software and accompanying written materials.
The author takes no responsibility for use or misuse of this software.
Although every effort has been made to produce a solid and efficient product
the author cannot assure that the operation of the software will be
uninterrupted and error free. The user takes every risk.

Actually the source code has been tested under Watcom C/C++ V10.0 and
Linux gcc compiler. The default makefile is for linux. If you want to
compile the code under watcom use makefile.wcc



Greetings

During Velena development I have been helped by many persons:

This program is based on the knowledged approach of L.Victor Allis which
designed and  implemented a sophisticated AI engine in a program called
Victor. Velena is basically the same, except that even newer concepts and
techniques were introduced in order to reduce the problem complexity (of
solving the game) to a more tractable factor of magnitude. Moreover Velena
is available to anyone, while Victor (currently) is not. I thank L.Victor
Allis for his support while I developed Velena and for the theory he made
for solving Connect Four. Without him this program wouldn't have come to light.

I also thank Filippo Ghilardi who helped me to build the opening book data base
which took several days of work on his Pentium 133 computer, and Davide Mazza
who created the Velena intro logo (MSDOS version).

===============================================================================

                                                       The author:
                                                       Giuliano Bertoletti
                                                E-mail gbe@ce.unipr.it
                                                       gbe@netsis.it

===============================================================================
END
