Tetribot - An interface for Tetrinet AIs
----------------------------------------

Contents:

tclient - contains the library which allows AI's to communicate
  to the tetribot program. This library is licenced under the LGPL

tetribot - contains the tetribot program which AI's connect
  to using the the tclient library and which subsequently
  connects to a tetrinet server. Note that much of this
  code here was copied from the gtetrinet code base and everything
  in this directory is licenced under the GPL.


Note that this means that unless you plan on releasing your AI as
GPL'd software you can't use any of the code from the tetribot
directory in your AI.


Building
--------

See the individual subdirectories for further details, but you should
be able to just type make.


Using
-----

Tetribot has really only been tested against the tetrinetx server
(http://tetrinetx.sourceforge.net), and even then at this stage you
will probably notice some problems.

- Start the tetrinet server

- Start the tetribot server. By default it will attempt to connect
	to localhost, or you can pass it the name of the tetrinet server.
  ** PLEASE DO NOT USE PUBLIC TETRINET SERVERS TO TEST YOUR AI **

- Start a gtetrinet client
  - Tetribot will currently *not* start a game, so you will
    need to join manually using a client like gtetrinet
	  (http://gtetrinet.sourceforge.net) and start the game from there.

- Start your AI.

There is a simple interactive client program called test_client. It
is dynamically linked against libtclient, so you will probably
have to invoke it like:

# LD_LIBRARY_PATH=. ./test_client

By default the tetribot server will handle an arbitary number of
clients (it forks and the children handle the clients that connect).
If you want to supress this behaviour pass '-d' as a command line
argument. In this mode tetribot will only handle one client.

What works (well at least a little bit anyway)
----------------------------------------------

- Notification of information about other players
  when game starts
- Querying of
  - own and other players' fields
  - specials accumulated
  - block dropping (type/position/orientation)
  - next block (type/orientation)
- Moving/dropping blocks
- Basic tetris functionality
- Adding of lines to other players' fields when multiple lines
  are completed
- Collection and use of specials
- Playing consecutive games

What is not implemented yet
---------------------------

- Messages (retrieval/sending)
- Support for teams

Understanding block definitions
-------------------------------

tclient/tclient.h contains the bitmap images for all of the blocks.
All of the blocks are represented by a 4x4 matrix. The current block
position returned (x,y) is of the top left corner of the matrix,
regardless of whether or not the block actually has a 'bitmap block'
in the left column - they all have at least one in the top.

Note that this means that sometimes GetCurrentBlock can return an
xposition which is less than 0. For example when TC_BLOCK_0 is in the
leftmost possible column, then the xposition returned will be -1.  For
TC_BLOCK_I_1 when it is in the leftmost possible column, the xposition
returned will be 0. The initial yposition for a new block will always
be zero.

Bug reports
-----------
Please send them to:

Chris Yeoh (cyeoh@samba.org)
Jeremy Kerr (jeremy@redfishsoftware.com.au)
