[Freeciv-Dev] Re: Communications Protocol

[Reinier Post <rp@xxxxxxxxxx>]

On Sun, Jul 15, 2001 at 12:01:09AM +0200, Pete Sergeant wrote:
> Hi there,
> 
> I want to write a Perl module that can act as a client to a civserver, to
> allow me, and anybody else who wants to, AI clients, using Neural Nets.
> 
> My stumbling block is the communication between the server and client. I had
> naively assumed it would be plaintext, but, of course, it isn't. My C is
> weak (as is my Java, because freeciv-java implements it too), and I really
> can't grok how it works from the source.
> 
> I was wondering if anybody would explain to me how the packets are
> constructed, and perhaps write a small piece of documentation on it, as I'm
> sure others would find it useful.

It isn't very hard.  The general idea is documented in the
'freeciv hackers guide' in the top directory.

There is a permanent two-way connection between client and server.  The
protocol is not synchronous (where the client calls the server and
waits for the answer) but asynchronous: both the client and the server
listen for incoming packets and upon receiving a packet, call the
appropriate packet handler.  That is, they are both structured like this:

  set up;
  WHILE another packet arrives
  DO
    call the appropriate packet handler on it
  OD

A packet handler may cause the loop to be terminated (the end-game packet
for instance) and of course in the process it may send packets to the
other end.  Packets will be handled in a FIFO queue.

The asynchronous protocol allows parallelism.  It is used to great
benefit in the client, which doesn't only listen for network packets,
but also for user interface events.  This is what makes Freeciv
playable on a poor connection: many orders can be placed even when the
server connection is down or lagging, e.g., individual orders to move
each of your 160 units.  Only when information from the server is
required, interaction will block, until the server packet containing
the information arrives and its handler routine makes it proceed.
The client caches some information about the game, but the whole game
state is only known to the server, so you can't really do too much in
advance.

The server could use more parallellism than it does.  In particular,
the AI code, which exists entirely in the server, isn't event based
at all, and doesn't interleave with client-side action requests.

Packets are typed: within the code, they are typed statically, as C structs.
Within the code, you can see calls to the various send_packet routines,
one for each type of packet; within the two listening loops, you can
see a case statement for the packet type, calling the packet handler of
that type.

A technical problem with C, explained in the hacker's guide, is the
fact that you have to choose a type for the actual packets to be
sent/received on the connection, and it must be capable of holding all
the different C structs.  What is more, the receiving end must be
able to recognise the packet type, so it must be encoded into the
packet explicitly.  This is why a whole section of Freeciv code,
common/packets.c, is devoted to explicitly converting statically typed
C structs to/from the dynamically typed packet type used in actual
transmission.  (I've argued on the list that all C structs in Freeciv
should really be replaced with such dynamically typed structures,
but I don't intend to do anything about it.  Object oriented C programs,
such as X, demonstrate that C can be used in that way.)

(If this message duplicates others, it's because mail server problems
at our end have caused me to be thrown off the Freeciv lists, and I
can't find out how to rejoin.)

-- 
Reinier