THE June, 2008 PROTOCOL_2: 

0. The current protocol is simple OSC/UDP, see
http://archive.cnmat.berkeley.edu/OpenSoundControl/OSC-spec.html.

The beginning of the UDP datagram is:

"list\0\0\0\0,"

as specified by OSC. The address pattern "list"  should actually start with
a "/" character to conform to OSC, but the current game protocol uses "list"
to be compatible with Msx/MSP. This protocol also has been tested on
ChucK and Supercollider. There are example sound generator in the
max/ chuck/ and sc/ subdirectories.

Following the above are OSC type tags "i" and "f" followed by 4-byte values
for the following fields. These are simple OSC datagrams, with no support
for timestamped bundles, because Max does not support them. There may be
another "long distance protocol" added later that includes timestamped
bundles, but the current protocol assumes UDP over a LAN.

The chess program sends these UDP datagrams to destination port 57120,
which is compatible with Supercollider. This number is currently hard
coded, but will become a parameter in a config file at some point.

FIELDS IN EACH OSC DATAGRAM ARE:

1. bank(int) As currently defined, a bank of sound generators.
Currently only 0 and 1 are used for the chess game. 

The proposed protocol will allow optional additional banks.
Also, any even numbered bank (l.s.bit == 0) signifies a support relationship
in the game, an odd bank (l.s.bit == 1) signifies a conflict relationship.
A bank number can exceed a sound generator's available banks, in which case
the sound generator can either A) map the bank into one of its own banks
(e.g., by setting realbank = bank MODULO numberOfBanksInSoundGenerator,
or some other mapping), or the sound generator can
B) silently discard the message. 

2. oscindex(int) As currently defined, an offset into bank of sound generators.
Currently 0 through 31 are used for the chess game. This value can be higher
than the number supported by the sound generator, in which case it can either
A) map it to a valid oscindex using modulo or similar, or B) discard.
See similar comments for the bank number. 

3. frequency(float) in Hz or -1.0 to signify "ramp down the oscillator to
0 amplitude without changing the frequency." The -1.0 value is deprecated at
this point, since it is redundant with a pair of amplitude fields equal to 0.0. 

4. phase(float) between 0.0 and 1.0 inclusive, or -1.0 (deprecated) similar
to frequency. -1.0 occurs for both fields only on zero total amplitude. 

5. left amplitude(float) between 0.0 and 1.0 inclusive. A pair of left/right
amplitudes of 0.0 signify ramping the oscillator down to 0.0 amplitude and
then freeing its resources if appropriate in the sound generator environment.
A given oscillator in a bank may be reused repeatedly, with or without being
zeroed in between. In general changes in amplitude should be ramped in order
to avoid glitchy noise -- there may be a lot of rapid changes and oscillator
use/zeroing/reuse from a game -- but this is up to the sound module designer.
Maybe they want noise. 

6. right amplitude(float) between 0.0 and 1.0 inclusive.
Comments for left amplitude also apply here. 

NOTE: Fields 7 through 11 are ordered so you can praed protocol dumps:

BLACK PAWN SUPPORTS BLACK QUEEN
BLACK PAWN ATTACKS WHITE QUEEN
BLACK PAWN ISSUPPORTEDBY BLACK QUEEN
BLACK PAWN ISATTACKEDBY WHITE QUEEN

GAME_INDENDENT INTERPRETATION:

PLAYER PIECETYPE RELATIONSHIP OTHER_PLAYER OTHER_PIECETYPE
adjective noun verb noun

7. player(integer, use optional) 0 through highest player-1 inclusive,
in chess 0 for white and 1 for black. Value -1 is reserved for no player.
This is the player moving piece field 8. These values could go higher for
other games, so a sound generator must map "illegal" values into its valid
range, or discard such sounds, as for other extensible fields defined in the
protocol. A sound generator can also ignore this optional field and generate
sounds based on other fields in the message. 

8. piece type(integer, use optional) from 0 through top piece in the game, the
INITIATOR of the relationship is being played.
For the chess game these values are: 

-1 - unknown or does not apply to the tone
 0 - pawn 
 1 - knight 
 2 - bishop 
 3 - rook 
 4 - queen 
 5 - king 

These values could go higher for other games, so a sound generator must map
"illegal" values into its valid range, or discard such sounds, as for other
extensible fields defined in the protocol. Values in general should ascend,
based on the value of a piece, move, or board configuration in a game.
A sound generator can also ignore this optional field and generate sounds
based on other fields in the message. 

For example, generating sounds from a Scrabble(tm) game might pass the index
of the highest letter, 'A' through 'Z' as 0 through 25, of a player's move,
or perhaps to the highest score on a played letter tile. Alternatively,
it might map the score value of a move into a range of buckets 0 .. N-1
giving a mapping of the overall value of the move. 

9. relationship(integer, use optional) of this tone. The chess program,
and likely other future game programs, generate tones based on relationships
of a piece being moved. For chess these relationships are: 

-2 - no relationship
 0 - I support another piece 
 1 - I attack another piece 
 2 - I am supported by another piece 
 3 - I am attacked by another piece. 

Odd values (l.s.bit == 1) always signify a conflict relationship, similar to
the bank number. Even values signify support. These values could go higher for
other games, so a sound generator must map "illegal" values into its valid
range, or discard such sounds, as for other extensible fields defined in the
protocol. A sound generator can also ignore this optional field and generate
sounds based on other fields in the message. 

10. player(integer, use optional) 0 through highest player-1 inclusive,
in chess 0 for white and 1 for black. Value -1 is reserved for no player.
This player is the RECIPIENT of the relationship represented by field 9.
See additional comments for field 7, which also apply here.

11. piece type(integer, use optional) from 0 through top piece in the game, the
RECIPIENT of the relationship initiated by field 9. Values and comments for
field 8 also apply to this field. It's value is -1 when there is no other piece.

12. move number(integer, use optional) move number is 0 if unknown or
unimplemented, otherwise it starts at 1 for the first player's move and
increments for every player thereafter. These numbers are not guaranteed to
come in order. For example, some variations of the chess game start a
"virtual game" that generates sounds while waiting for a human player to move.
The move numbers in a virtual game could get ahead of the human game.
The move number does provide some measure of move time in that all
adjacent arriving messages with the same move number would have been
generated, together, at the same move time.

Note that the Python chess program internally uses the piece types, player and
relationship values in generating the preceding fields bank .. right amplitude,
which is one reason why use of these fields is optional and they were not in
the original protocol. The fields are present in the UDP datagram and must be
extracted, but their use in the sound generator is not required. Where used,
the even versus odd mapping for support versus conflict of the bank number and
relationship fields can be used to select pleasant versus harsh timbre or
effects. Mapping of the optional fields is always at the discretion of the
sound module designer. 

END OF PROTOCOL_2 DESCRIPTION.
