[Maitretarot-devel-fr] protocole

[Yves Mettier]

Petit oubli: voila le protocole de Jerome.
A voir avec perldoc.
Desole pour la mise en forme: y'a un petit bug de mozilla-1.3 qui m'embete :(
Yves


=head1 Abstract

This document describes the client/server protocol used by the
Games::Tarot module.


=head1 Description

The Games::Tarot module is in fact a client/server module, that
handles a Tarot game. Clients can connect and play, as long as they
follow and respect the protocol of the module.

This protocol is designed to be simple to implement, and easy to
parse. Let's see its basics:

=over 4

=item o

TCP server. The server is a TCP one, that is, a connected server. This
way, we have reliability for nothing: the transport layer takes care
of everything for us.

=item o

ASCII based protocol. Each frame used in the client/server dialog is
written in ASCII. This allows us to get rid of endian-ness of integers
(ok, sorry EBCDIC folks! :-) ), plus it eases the tasks of humans that
are writing clients: everyone should be able to read the trace of a
client/server dialog.

=item o

Each frame begins with a five letters word that tells unambiguously
what frame should comes next. This allows easier parsing. Parameters
of the frame comes after the keyword. Errors all begin with C<E->
followed by three digits (thus we have also a five letters
identifier), the end of the frame is a text describing the error (not
really useful for an AI, but could be interesting for players or while
debugging).

=item o

Each frame should be newline terminated. This way, we do not have
bufferisation issues, and once again it's easier for humans to follow
the traces.

=back



=head1 Game progress

The game is made of several parts.

Once started, the server loops, accepting connexions and serving
them. When all the clients are in, the server deals the cards. It then
prompts every client for its announce, as many times as needed. Then
the client that will lead the game should take the discard and make
its own. Finally, the clients play the game, one card at a time, when
it's their turn.

Let's take a closer look at this.


=head2 Client connexion

When a client connects to the server, the server can reply two things
whether its state:

=over 4

=item o

B<E-001 Server is full.>

As you could have guessed, this means that the game already has its
content of players, and therefore, it's no need to try to connect. The
client is then disconnected from the server.

=item o

B<IDTFY E<lt>nb-of-playersE<gt>>

The I<identify yourself> frame is sent, followed by the number of
players that will play the game. This could be either 3, 4 or 5 (as
the Tarot can be played only by three, four or five players).

B<Be careful>: the C<nb-of-players> is the number of players that will
compete, not the number of players currently connected.

=back

Once a client got the C<IDTFY> frame, it should answer:

=over 4

=item B<HELLO foo bar baz>

This frame tells the server that client is really willing to play, and
wil compete under the name "foo bar baz". Client can send whatever he
wants for his name, it will only be used for GUI.

=back



protocol

  Client             Server
  ------             ------

=head1 Summary

=head2 Connexion

                 <  E-000 Unknown command.

  connex         >
                 <  IDTFY 3               # game of 3 players.
  HELLO foo      >
                 <  E-001 Already connected.
                 <  E-002 Server is full.

                 <  HELLO #3              # you are the 3rd player
                 <  NEWPL #1 bar          # first player
                 <  NEWPL #2 baz          # second player
                 << NEWPL #3 foo          # third player



                 << RUOK?
  IMOK!          >
                 <  E-003 Uh-oh. Looks like we're not in the same timezone...
                 <  E-004 Yes, you already said that.
  IMOK!          >
  IMOK!          >
  IMOK!          >
                 <  CARDS 0 23 34 .. 66   # number of cards suited
                 <  CARDS 1 2 3 .. 77     # number of cards suited
                 <  CARDS 5 7 9 .. 76     # number of cards suited

                 << SPEAK #1
  ANSWR 0        >                        # passe
                 << ANSWR #1 0
                 << SPEAK #2
  ANSWR 1        >                        # prise
                 << ANSWR #2 1
                 << SPEAK #3
  ANSWR 2        >                        # pousse
                 << ANSWR #3 2
                 << ANSWR #1 0
                 << SPEAK #2
  ANSWR 0        >                        # passe
                 << ANSWR #2 0
                 << ADONE #3 2            # #3 will play a pousse

                 << DISCD 4 12 .. 37      # the discard
                 << DISCD none            # discard not shown
  READY          >
                 << READY #1
  READY          >
                 << READY #2
  DISCD 5 ..     >
                 <  ERROR can't discard trump / oudler / king
                 <  ERROR you don't own this card
  DISCD 5 ..     >
  DISCD none     >
                 << READY #3

  HAND= 75 ..    >
                 <  ERROR you don't have a hand
                 << HAND! #0
                 [...]
                 << HAND= 75 ...

  POOR!          >
                 <  ERROR you are not poor
                 << POOR! #0

                 << WAIT4 #1 1             # #1 plays the 1st card

  PLAY! 0        >                         # playcard
                 << PLAYD #1 0             # #1 played the card 0
                 << WAIT4 #2 2             # #1 plays the 1st card
  PLAY! 36       >
                 << ERROR can't play this card
                 << WAIT4 #2 2             # #1 plays the 1st card
  PLAY! 3        >
                 << PLAYD #2 3

                 << FINAL #1 37 0 2 4 ..      # team #1 (taker) has 37
points with
cards...
                 << FINAL #1 54 0 2 4 ..      # team #1 (taker) has 54
points with
cards...


  BREAK          >
                 << BROKN #1
=cut


-- 
- Homepage - http://ymettier.free.fr - http://www.cmg.com -
- GPG key  - http://ymettier.free.fr/gpg.txt              -
- MyAM     - http://www.freesoftware.fsf.org/myam         -
- GTKtalog - http://www.freesoftware.fsf.org/gtktalog     -