0. What is this?
------------------

This text is intended to act as an introduction for people wanting to know how Jubatu works.
It gives some very basic information to help plugin's developers get started.

1. Tips
---------

The communication management is done from an independent thread; both the main windows and the
game windows communicate with the communication thread by using python queues.

The main window only load games at starting time.

There are a logger for Jubatu's core (you can change his settings from jubatu.py) and a logger for
the communication thread (you can change his settings from juxmpp.py); furthermore, game plugins
can define his own loggers.

The chess plugin was intended to serve as a good example for developing other plugins. Take a look
at it.

Every game plugin MUST have his own ID (as returned by the id() function); you can check the chess
plugin to look for the recommended way for making the ID version-dependent (basicly, taking a hash).
If you want to debug a plugin having such a schema, you could be interested in  making the id()
function return a fixed ID. If you want to know what IDs are using your contacts, try setting the
logging verbosity of the core's logger to "DEBUG".

You can only play with other users having exactly the same plugin version (that mean: engines with
the same ID).

The communication protocol is game-dependent; basicly it's mounted over xmpp iq stanzas, and the
communication thread redirect incoming stanzas to the corresponding engines if the stanzas have a type
recognized by it ('proposal' or 'turn', as of now, but this is still preliminar). If you want to have
a better understanding on how an implemented protocol works, consider increasing the verbosity level
of the loggers.

You have some useful global objects in the application object. Check jubatu.py for details.

The selection of adversaries is intended to work this way: the user click in the corresponding gamers'
list and after it he double-click the selected buddies. Take a look at how the chess plugin manages this.

If you are developing a new plugin, you MUST provide a 'new game panel' to be loaded in the main window.
In that panel you must provide all the options neccesary for proposing a new game (list of participants,
referee/master, used colours, whatever).

There are two directories from where Jubatu looks for games: the 'games' subdirectory relative to the
'jubatu.py' file, and the 'games' from the user preferences directory ('~/.jubatu').

The include of live messaging capabilities have been delayed till seing if a future version of Panda3d
can integrate a 3d view inside a wx panel. If that happens, we could integrate the 3d windows in a
general frame containing a 'char' tab. If, after a reasonable amount of time, nothing is done with
Panda3d, we could create a separate wxFrame attached to the 3d window.

By now, Jubatu connects with negative XMPP priority, so no 'message stanzas' should be delivered to it.
