--------------------------------
 Mancala README file
 Kevin Riggle
 http://cmancala.sourceforge.net
 $Revision: 1.15.2.3 $
 $Date: 2004/01/17 20:18:06 $
--------------------------------

To compile the Mancala program itself, cd into 'src' and type 'make'.
To compile the ai-test program, type 'make ai-test-normal'.  ('make recurse' 
and 'make ultimate' compile the mancala with the recursive and "ultimate" ai 
modules, respectively.)


DEV-LOG:

01-17-04: A lot of work has happened on the graphical branch without much in 
the way of updates here.  I would in no way call the code "production ready" --
it's a game, for crying out loud, and I'm in high school.  It is in a lot better
shape now, however.  There's still a memory leak somewhere, and valgrind is
segfaulting on me (grr), but it more-or-less works and looks good doing it, so
I'm releasing version 0.1.0 of the graphical Mancala in C today. :)  Projects
for later include making it work with autoconf/automake/etc., fixing the
remaining bugs, adding some configurability, and making it compile on Windows.
I spent about five hours trying to get everything in place, and I'm still
getting Blue Screens of Death.  At least it works on Linux, and I can show it
to my teacher for a grade.  Happy compiling!

01-07-04: The graphical version is getting off the ground, though the current
code looks like barfed-up ramen.  Bugger.  Once I decided I didn't like the
random stone placement look, I had an established code structure that forced
me to do the drawing a certain way.  It's proving to be a real pain in the ass,
since it's more logical to draw the entire board at once, but I'd rather not
pass half my environment to a function.  I may have to, since the alternative
is putting it all in main(), which is nasty, or dividing it up somehow, which
just doesn't make any sense at all.  I think my first impulse (before random
stones) was right -- all the board-drawing code goes in a function in
graphics.c, and no more messing around with half-a-dozen intermediate surfaces.
Oh, and I'm also keeping something of a development log at the Mancala in C
webpage (http://cmancala.sourceforge.net) *and* the day-to-day changes in the
ChangeLog, so I may be updating this less frequently than I used to.

12-28-03: Well, well, well.  Looks like I may write a graphical version of
mancala after all!  I've cleaned up the source code tree as well, using several
other notable projects (*cough*Linuxkernel*cough*) as models.  I've also
learned a bit about CVS in the process and how it handles branches.  Grrr...
At any rate, this should be fun to watch. :)

12-04-03: Progress continues.  Taking a small break from the ultimate algo, 
(stealing homework time, too, but -- hey, this is homework too).  Redid the 
Makefile a little more so you can make mancala and ai-test with any of the
three routines, plus wrote *another* wrapper function because the copy-the-
boards-and-set-up-the-logs code was being duplicated in -recurse and -ultimate.
I'm proud to say that my first attempt at passing function pointers worked
without a single hitch.  I love C... <sigh> :)

12-01-03: Made good progress over Thanksgiving break.  SSH works pretty well,
even over my grandmother's feeble dial-up connection.  Work is starting on the
"ultimate" algorithm, which may or may not be "ultimate," but will certainly
improve on the recursive algorithm, which doesn't have any concept of 
"strategy" or not letting me have a huge capture.  Thankfully the memory
requirements don't seem too overwhelming (c'mon, Kev, you really expected a
couple pitiful little integer tables would bring a modern computer to its
knees?)  If this comes along as quickly as it is seeming to, I may have time
to write a GUI before Christmas.  Oh, and I removed Makefile.bsd because I
figured out how to make one work for *both* UNIXes I use.

11-22-03: Getting better at CVS every day.  Set up a separate branch for the
new ai-test stuff (-r ai-test-headless), which lets me test the ai without
entering each value manually.  Instead, it grabs it from a file, which allows
me to, say, use AskIgor (http://www.st.cs.uni-sb.de/askigor/) to debug the ai.
Once I've got the code tightened up, all I need to do is release my working
directory and run "cvs co -j ai-test-headless mancala", resolve conflicts, and
commit.  Sweetness. :)

11-21-03: from the its-not-a-bug-its-a-feature dept.:  Turns out the ai-test 
program was balking because I entered the human board as all zeroes, so it
thought the game had been won.  Silly me.  Anyhow, 0.2.0 is in good shape
and I'm starting on the ultimate algo now.  Nothing more to see here, move
along... 

11-19-03: Not sure *why* I can't squash the bug, but I need to step away and 
we're due for a release anyway, so prepare for mancala-0.2.0!  This should
include the bugfixes I came up with to the original ai lo these many years ago,
and should otherwise prove that, yes, Virginia, I really am doing something.
The old AI beats the recursive one *anyway*, so it isn't really a big deal.
Now to refresh my memory about game theory so I can write THE ULTIMATE AI...
MUAHAHAHAHA...  sorry. 

11-12-03: Made a good start on squashing the bug I talked about two days ago.
Still getting some confusing results (ai-test="0 1 2 0 0 0 0"), but it is 
obvious we're getting the information we need without passing more pointers
with each recursion.  I should be able to ditch *ptCount, too -- I love 
abstraction, which lets me mess with the function definitions without making
me rewrite the call in main.c too. :)  

11-10-03: Almost have the recursive algorithm licked.  Looks like there's only 
one major bug left, namely the "i have no idea how many stones i got when i
recursed" bug.  Discovered that the algorithm had no idea if we'd won the
game, and so would loop infinitely trying to find a move that didn't exist.
Also changed the Makefiles so that they will clean up the logs the program 
and the recursive algo generate.  Code needs some clean-up, commenting, and
pretty exhaustive documentation (preferably step-by-step) just so I can say
I'm doing *something* in my independent study, but is otherwise pretty close.

10-29-03: Okay, added the select-a-random-move-if-we-don't-have-a-good-
alternative code to the recursive algo -- need to check the main program
logic to discern why the computer won't take its extra turns.  This may
be why the recursive algorithm seems "worse" than the heiuristic one,
when in fact they should play almost identically except in certain
special cases (ie. where taking the extra turn destroys an opportunity
for a larger gain, eg. a good capture).  Prepping a nicely-commented
version for MIT.
-----
Bah.  Tested the instance I mentioned above and discovered that when my
function actually recurses beyond one or two levels, it ends up getting
stuck somewhere. Bah.

10-28-03: And now it comes to me why I don't use my lovely rand_btw
function in my heiuristic AI...  it doesn't work (or rather, it puts the
"pseudo-" in "pseudo-random").  Research needed on a better and more
random random-function, though its current form will work well enough
for the version of the recursive algo I send to MIT (they won't see that
code anyway :).  It's in mancala.c now, and extern'd.

10-27-03: Well, the recursive algorithm now a) compiles and b) runs,
though it doesn't play terribly well.  There are also several noticable
bugs that need to be fixed (eg. if the AI cannot make a move that gains
it points, it does not move at all), but by in large I'm happy that I've
at least reached this juncture.  I'm also hoping to send the recursive
algorithm to MIT with my application as an example of extra things I do
in my spare time, so it's a good thing it's coming along so nicely.

10-16-03: Taking a little longer than expected -- needing to get a development
environment set up on SDF takes more time and money (!) than I initially thought
it would.  At any rate, it's all set so I should be making some more progress
now.  Added the two new ai modules (recursive and "ultimate") and started 
updating the makefile to allow for that.  Nothing actually works yet, but
it's in process now.  We'll see how far I get...

09-21-03: Wow, it's really been a while.  The code is in SourceForge CVS 
(finally) because I'm doing a little work on it for an independent-study at school -- learning about recursion and working with pointers.  At any rate, I'm
making progress, and may even have a GUI in the works.  We'll see if I can
learn to stomach graphics programming. :)

07-10-02: Getting this ready to post to SourceForge.

07-07-02: Coded the game loop plus neccessary game modules (mostly 
mancala.c:move), integrating the AI.  The by far biggest bug in the AI (aside
from the fact that it always loses against me) is that the 'random move'
algorithm often picks piddly little moves that don't get it any points -- say
moving one or two stones when there are ten in another hole.  The AI also needs
a true random-number generator (probably a whole new algorithm).  I'm going to
have to con a family member or three into sitting down and playing against this
thing.  Since I *programmed* the dang thing, I have some insight into how it
works.  (Which I stupidly revealed tonight, though they'll hopefully a. forget
it, or b. not know what to do with the knowledge.)  I must say, if the program
*I* design beats *me*, using just these pitiful hueristic methodss and not some
fancy-schmancy neural-net-cum-expert-system-cum-kitchen-sink, it wouldn't say
much for my skill at Mancala or the difficulty of the game.  (In short, it 
would be *really* embarrassing!)  Not that I'm worried, mind you. ;-)

07-04-02: Worked on instructions and game setup.  Also morphed common.h into
mancala.[ch], containing the same game-wide symbolic constants plus most of
the core game modules like move() and gameWon().

07-03-02: Began the main program module by coding in support for command-line
options.  Not sexy work, but necessary.  I also revised the Makefile to get
rid of the *~ files EMACS sometimes leaves behind.

06-29-02: Not only does it work, but I've fixed the remaining bugs in the AI
module, so it's time to code the UI/game modules!

06-28-02 (later): IT WORKS! (That thunking you hear is the sound of brain cells
being violently beaten to death.  I forgot to dereference the pointers.  Shit.)
AI code, at least with the minimal testing I've done, gives the expected 
result.  This project may go quicker than I thought it would! :-)  Mad props to
Peder Skyt of povray.off-topic for pointing out my error.

06-28-02: Posted a query to povray.off-topic RE: the segfault/"scanf-needs-a-
pointer" conundrum.  Gah.  Entered my code for the AI module itself.  No way to
test it out (obviously), but it compiles so I'm happy.  Updated the Makefile
(again) to compile with debugging, and introduced common.h to store standard
symbolic constants (BOARD_MAX, INITIAL_STONES, etc.).

06-27/28-02: Tried to code the bulk of ai-test.  Didn't work.  It's the ai-test
module, now with SEGFAULTs!  I know it's a stupid problem, I *know* I've seen
it before, but I can't. make. it. work! <grrrr>  Also updated the Makefile to 
reflect the way GNU make *actually* works, not the way I think it does. :-)

06-27-02: Well, just getting this project off the ground... set up a Makefile
and put basic 'Hello, world!'-ish stubs in to test it out, set up a
basic structure, etc. etc. etc. and checked it into CVS.  We'll see how this
turns out... :-)
