
Copyright (c) Dale E. Parson, Ph.D., June, 2008.

Please read the content of LICENSE.txt.

JULY 15, 2008: Assuming you are running manytones.ck or chorusmanytones.ck in
ChucK (4 banks of 64 oscillators each, although chorusmanytones.ck uses
Chorus effect which may have bugs and which hangs miniAudicle -- use command
line ChucK), then to start the most up-to-date plugin from within the
chess/chess/ directory (after setting and exporting PYTHONPATH as explained
below), in two separate Bash command windows in chess/chess/:
        
        ./gamestart
        ./guistart      [ IPADDR ]

IPADDR is the optional IP address of the machine running 'gamestart' (the
game server) if they are on different machines.

Bash entails running Cygwin on XP. If you don't have bash, just do
what these two files do:

        python -i startgame.py
        python -i startgui.py [ IPADDR ]

--------------------------------------------------------------------

Please read PROTOCOL_2.txt to learn about the UDP protocol used to
send note events to Max/MSP, ChcuK and Supercollider. There are
max/, chuck/ and sc/ subdirectories with example sound generators.

1. Install Python 2.4.4 or later -- Python 2.5.x may work, I don't know.
Python must have the Tkinter module available for the GUI. Try this:

$ python
Python 2.4.4 (#71, Oct 18 2006, 08:34:43) [MSC v.1310 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import Tkinter

If it fails you will get a message like this:

ImportError: No module named Tkinter

You can download Python and Tkinter at http://www.python.org/

2. I have been running under Cygwin on Windows XP, and I have tested
under OSX as well. Under Cygwin I have my env set up and exported as:

export PYTHONPATH=c:\chess;c:\gcs

also PATH includes python at /cygdrive/c/Python24

3. I install this stuff at C:/chess, and run it from directory
c:/chess/chess. You have to run the Python scripts from the lower chess/
directory just above avatars/ (cd to there), but PYTHONPATH has to be set
to the upper chess/ directory above that.

4. Start your Max/MSP, ChucK or Supercollider sound generator to 
receive UDP datagrams from this program and generate sounds.
There are example patches in the Max, chuck/ and sc/ subdirectories.
The sound program must listen on UDP port 57120; this number is hard coded
at present, but it will go into a config file later.
See PROTOCOL_2.txt for more details.

5. In one terminal window from chess/chess/ do

    python
    from chess.chessgame import *
    testd()

This starts the chess server, and informs you of the server's IP address.

testd() uses the aheadSineInterpreter.py plugin for music generation.
simpleSineInterpreter.py, polySineInterpreter.py and shuffleSineInterpreter.py
are predecessors of aheadSineInterpreter.py that you can ignore.

EDIT, July, 2008: There are now teste() and testf() as well, that use
sustainSineInterpreter.py and echosustainSineInterpreter.py respectively.
At present these must run with Chuck program manytones.ck, which has 4 banks
of 64 oscillators each. The testa() through testd() scripts use
2 banks of 32 oscillators each; chuck program chesstones.ck or the scripts
under max/ and sc/ currently supply 2 banks of 32 oscillators each
(July 6 sc/ updated for 4 x 64).
To see the full OSC game protocol in action try out testf() with
echosustainSineInterpreter.py.

You can also invoke testf() with a parameter that supplies an alternative
"chord chart" file to the default 'transformsbasic' in file transformsbasic.py.
More on that below.

EDIT August, 2008 for electro-music 2008: testh() is the latest plugin
driver. It runs stutterPannerSustainInterpreter.py and works with
chuck/chorusmanytones.ck or sc/chess_music.scd. I haven't gotten to test it
with Max/MSP, but it "should" work!

6. From the same or different machine(s), start another Python process in
the chess/chess/ directory:

    python
    from chess.chessboard import *
    start('IPADDR')

where IPADDR is the IP address of (4) in quotes. You can also add two optional
arguments:

    start('IPADDR','black')

starts you as black instead of white. You can always flip this at run time
using the GUI's "Switch Sides" button. You will have to switch sides if
both people are playing from the same machine. You can have multiple
chessboard client sessions for one chessgame server session.

    start('IPADDR',debug=1)

Let's you move black while playing as white or vice versa. The reason to
run in non-debug mode is to disallow another player from moving your
pieces and vice versa. This came out in home user testing.

7. I recommend Toggling the Graph Trace to ON early in the game and watching
the pretty arrows. There is no indicator to tell you whether you are in
trace mode until the arrows appear.

8. OCCASIONALLY THE GUI PROCESS LOCKS UP and stops updating the display.
If you click a piece to move (don't try drag-and-drop, just fully click a
piece to move, and then fuly click its destination square), and the piece
doesn't arrive and the display locks up, just "Exit GUI" and start another
GUI as in step 5. So it goes. The game state will not be lost.

9. The other window shows some music generation config parameters for
the plugin of testd() or testf(), aheadSineInterpreter.py or
echosustainSineInterpreter.py. You can highlight one of
these and paste it using the buttons, or just type it in, to see its
effect. I recommend playing with lookaheadlimit values of 1 .. 10.
Watch the arrows and listen to the sound changes after you do this.

NOTE: The sustain related parameters work only with
echosustainSineInterpreter.py.

EDIT, July, 2008: There are now sliders and checkboxes for the more
useful config parameters. 

10. Hitting the "Exit GUI" button kills the GUI process, but to kill the server
type control-D or control-Z or whatever your EOF character is into the
Python server terminal.

UPDATE JULY, 2008: You can now run testf() instead of testd(), which uses
ChucK file manytones.ck, which uses 4 banks of 64 oscillators each,
with the odd numbered banks for conflict. Tests testa() througth testd()
continue to work with chesstones.ck as well as the sc/ and max/ tone
generators.

You can record moves by setting the 'recordfile' variable from the GUI or
invoking start_record('FILENAME') from the server console, where
FILENAME is the name of a file to capture. Set recordfile in the GUI to as
empty assignment, or invoke stop_record(0 from the console to stop.
You must invoke play_record('FILENAME') from the server console to
play a file back.

A final extension hook is the series of auto-transforms that occur when
the game gets "bored" waiting for a player (i.e., the delay2alterseq
parameter times out). Consult file 'transformsbasic.py' to see the default
set of auto transforms. To change this set, copy transformsbasic.py to
mytransformsbasic.py (for example), and add or delete or move entries
from this comma separated list, keeping the Python list syntax intact.
Transforms act as follows:

    'up5th',        transposes up a Just 5th
    'down5th',      transposes down a Just 5th
    'upmin3rd', 'downmin3rd', 'up3rd', 'down3rd', 'up4th', 'down4th',
    'up5th', 'down5th', 'up6th' and 'down6th', 'upoctave', 'downoctave'
                    are similar for those degrees in the Just scale.
    'warble',       adds some varying modulation to each note
    'ahead',        performs look-ahead in a 'virtual game' in which it makes
                    audible but invisible moves, until a real player makes a
                    real move; these moves do not affact the real game
    'retro',        applies retrograde to the current phrase

    The paired up/down transforms and retro/retro are complementary, i.e.,
    they bring you back to the same place. Generally the overall list should
    bring you back to the same note and octave by applying pairs of
    (not necessarily adjacent) complementary transforms.

HAVE FUN!
-----------------------------------------------------------------
THE CODE AND DOCUMENTATION IN THIS DIRECTORY AND BELOW ARE OPEN
SOURCE ACCORDING TO THE TERMS OF THE FOLLOWING LICENSE. PLEASE READ:
-----------------------------------------------------------------------------
ESST (Embedded System Software Tools) License
-----------------------------------------------------------------------------

SOFTWARE LICENSE

This software is provided subject to the following terms and conditions,
which you should read carefully before using the software. Using this
software indicates your acceptance of these terms and conditions. 
If you do not agree with these terms and conditions, do not use the software.

Copyright (c) 2008 Dale E. Parson, Ph.D. (a.k.a. Acoustic Interloper)
All rights reserved.

Redistribution and use in source or binary forms, with or without
modifications, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice,
this list of conditions and the following Disclaimer in comments in the code
as well as in the documentation and/or other materials provided with the
distribution.
* Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following Disclaimer in the documentation
and/or other materials provided with the distribution.
* Neither the name of Dale E. Parson, nor the names of the contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.

Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, INFRINGEMENT AND THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
ANY USE, MODIFICATION OR DISTRIBUTION OF THIS SOFTWARE IS SOLELY AT THE
USER'S OWN RISK. IN NO EVENT SHALL Dale E. Parson OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, INCLUDING,
BUT NOT LIMITED TO, CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-----------------------------------------------------------------------------

