GGZ Gaming Zone Design Specification

Brent Hendricks

               <bmh@users.sourceforge.net>

   Copyright  1999, 2000 Brent Hendricks

   Design specification for the GGZ Gaming Zone. This document covers the
   internal  server  architecture  and  the  client/server  communication
   protocols.
     _________________________________________________________________

   Table of Contents
   Introduction by Brent M. Hendricks
   1. Design Requirements
   2. Client-Server Communication Protocol

        2.1. Logging in
        2.2. Requesting server information
        2.3. Rooms
        2.4. Requesting room information
        2.5. Server updates
        2.6. Table Management
        2.7. Chatting with friends
        2.8. Game Interactions

   3. Design Overview

        3.1. The GGZ server (ggzd)

              3.1.1. Interactions between ggzd and running games
              3.1.2. Interactions between ggzd and config utilities

        3.2. Individual Game Servers
        3.3. Config Utility
        3.4. Key Subsystems

              3.4.1. Options Parser
              3.4.2. Login/User Database
              3.4.3. MOTD System
              3.4.4. Player Statistics
              3.4.5. Module loading

        3.5. Data Structures

   A. Protocol Reference

        A.1. Messages sent in both directions

              SESSION -- Session start
              PING -- Lag measurement challenge
              PONG -- Lag measurement response

        A.2. Server to client messages

              ROOM -- List entry describing one room
              GAME -- List entry describing one game type
              SERVER -- Server identification
              MOTD -- Server Message of the day
              UPDATE --  Notification that the list of players or the
                      list of tables in a room has changed, or the list
                      of rooms or game types on a server.

              PLAYER --  List entry describing one player.
              TABLE --  List entry containing one table
              JOIN --  Message to indicate you've joined a table
              LEAVE --  Message to indicate you've left a table
              RESULT --  General message to indicate the result of a
                      request

              LIST --  Server response to request for list of rooms or
                      list of games

              CHAT -- Server response to chat message request

        A.3. Client to server messages

              LOGIN -- Client requested login
              LIST --  Client request for list of rooms or games on the
                      server, or of tables or players in a room

              LAUNCH -- Client request for new table launch
              JOIN -- Client request to join a table
              LEAVE -- Client request to leave table
              CHAT -- Client chat message request
              ENTER -- Request to change rooms
              CHANNEL -- Request for a direct game connection

        A.4. Messages from server to game module

              RSP_GAME_JOIN -- Response to join request
              RSP_GAME_LEAVE -- Response to leave request
              RSP_GAME_SPECTATOR_JOIN -- Response to join request of a
                      spectator

              RSP_GAME_SPECTATOR_LEAVE -- Response to spectator leave
                      request

              RSP_GAME_SEAT -- Response to player seat modification
                      request

              REQ_GAME_STATE -- Request to change game state
              MSG_LOG -- Log message

        A.5. Messages from game module to the server

              REQ_GAME_JOIN -- Request for a player to join a table
              REQ_GAME_LEAVE -- Request for a player to leave a table
              REQ_GAME_SPECTATOR_JOIN -- Request for a spectator to join
                      a table

              REQ_GAME_SPECTATOR_LEAVE -- Request for a spectator to
                      leave a table

              REQ_GAME_SEAT -- Request to modify a player seat
              RSP_GAME_STATE -- Response to game state change request

   List of Figures
   3-1. Server Architecture
     _________________________________________________________________

Introduction by Brent M. Hendricks

   At  some  point during the development of NetSpades, I realized that a
   major  rewrite  was  in  order.  I wasn't happy with the client/server
   interactions,  and  I  wanted to add some features which just wouldn't
   work  within  the  current  infrastructure.  So  I  began to formulate
   grandiose  plans  for  NetSpades  v5, but continued to work on the 4.X
   series.  A  little later, I began to contemplate adding the ability to
   play  Hearts  as well as Spades. But why stop there? Why not develop a
   general  framework  for  playing networked games? And so my plans have
   developed into what I called NetGames.

   Just  before  I was going to announce my new project on SourceForge, I
   happened  across  Rich's  announcement  and plans for an online gaming
   system.  It  was to be in the same vein as Microsoft's Internet Gaming
   Zone,  so  he  named  it the Gnu Gaming Zone(GGZ). His goals and plans
   were  so  similar  to  mine  that  I  suggested  we merge projects and
   collaborate. He readily agreed, and the GGZ was born.
     _________________________________________________________________

Chapter 1. Design Requirements

   There  are  many  planned features for GGZ. Some will take longer than
   others  to  implement.  Some  may  be  discarded  at a later date. The
   following ones are available already (not ordered yet):

     * Password-based user accounts
     * Ability to leave and then rejoin game
     * Ability to reserve games for specific users
     * Capability   for   users  to  chat  without  resorting  to  second
       port/socket
     * Basic  infrastructure  from game developers to write network games
       without having to worry about connections/login/user accounts/etc.
     * Multiple "rooms" in which to play games. These rooms may reside on
       different servers, transparent to the user.

   Planned features include (but are not limited to):

     * Persistent user statistics
     * Dynamic run-time configuration of server
     * Ability  to  add/remove  game  types from server without having to
       recompile
     _________________________________________________________________

Chapter 2. Client-Server Communication Protocol

   The  client and GGZ server will communicate via the protocol described
   here.  Individual  games  will  of  course  communicate  via their own
   protocol.  These  messages  are  transferred  on  a  separate (direct)
   connection  between  game  client and game server. While GGZ games are
   free  to  use  whatever  communication  protocol  they  like,  the GGZ
   protocol itself is currently encoded in XML.

   Interactions   are   presented  here  categorically.  For  a  complete
   reference of client-server interactions, please see the appendix.
     _________________________________________________________________

2.1. Logging in

   When  a client first connects to the server, the server will start the
   SESSION  and  respond  with SERVER, notifying the client of the server
   type,  name and protocol version number. If the server is full (ie. no
   more user logins allowed), it will indicate this. After establishing a
   connection to the server, the client may send one of three commands to
   login:

     * LOGIN  is  used  for normal player logins. The server will respond
       with  a  RESULT  tag.  There are 3 types: First-time logins (which
       result in an account to be created and a password to be assigned),
       anonymous  logins (which don't require a password), and registered
       logins.

     Note:  Clients  may  choose to send login requests immediately, not
     waiting  for  the  SERVER.  This is acceptable, provided the client
     handle  the  case where the server tells that it doesn't accept any
     more  connections  (i.e.  is  full).  It  will  receive  no further
     notification that the login has failed.

   After   a   successful   login,  the  server  may  optionally  send  a
   message-of-the-day  to  the  client  via  a  MOTD  tag. This is a text
   message,  possibly  with  embedded  color codes. For more details, see
   MOTD System.

   Any  time  after  logging  in,  the client may logout of the server by
   closing  the  session, i.e. by sending the closing part of the SESSION
   tag.  The  server  will  end its SESSION then, too. Clients should not
   simply  disconnect  from the server without logging out as player data
   and game statistics may not get written back to the database.

     Note:  A  client may only login once. At the present, if the player
     wishes  to re-login for some reason (eg. to become anonymous, or to
     switch accounts), he will have to logout and then back in again. We
     may  make  account-switching  possible  at  a  future date, once we
     implement player preferences.

                                  Warning

   Although it is not explicitly disallowed by the server, clients are
   discouraged from allowing players to logout while at a game table. The
   client should send the appropriate LEAVE request first.
     _________________________________________________________________

2.2. Requesting server information

   After  logging  in,  there are several pieces of information about the
   server which the client may request:

     * To  request  a  list  of game types which the server supports, the
       client  should  as  for the game list via the tag LIST. The server
       will then send the client the list of supported games via a RESULT
       tag  which encloses a LIST. Only games which are supported by both
       the particular client and the server may be played.
     * To request a list of the game rooms present on the server, clients
       should  send  a  LIST tag with the room parameter. The server will
       then  send  back  a  LIST  (again,  within  a RESULT tag) with the
       desired information.
     * If  the  server  has  a message-of-the-day, it will send it to the
       client  upon login (see the section on logging in). The client may
       request  to  see it again, however, by sending MOTD. If there is a
       message-of-the-day,  the  server will send it via MOTD. If it does
       not exist, the server will ignore the request.

   Some  infomration  about  the  server  may  change while the player is
   logged   in.   If   this  occurs,  the  server  will  send  an  update
   notification.
     _________________________________________________________________

2.3. Rooms

   Most  of  the  real  action on a GGZ server occurs in rooms. Each room
   supports  a  particular game type, and provides a place for players to
   chat  back  and  forth  with friends. When a client first logs in, the
   player  is not in a specific room, but in limbo. In order to chat with
   other players or join a table, the player must enter a specific room.

   Changing  rooms  is  done  via  ENTER.  The server will respond to the
   room-change  request  with  RESULT.  There is no equivalent command to
   leave  a  room since leaving the room takes place automatically when a
   player  joins  some other room (We can't have players in two places at
   once, now can we?).
     _________________________________________________________________

2.4. Requesting room information

   Once  the  player  has entered a room, he or she will no doubt want to
   know who else is there and if there are any games being played.

     * To  request  a  list  of  the players in the current room and what
       tables  the are at, a client may send LIST with type 'player'. The
       server will respond with a list of PLAYER tags.
     * Similarly,  to  request a list of the game tables in the room, the
       client  should  send LIST of type 'table'. The server will respond
       via a list of TABLE tags.

   Rooms  are  busy  places with players entering and leaving, and tables
   being  launched  and  destroyed.  To  keep  the  client from having to
   continually  resend  list  requests,  the  server  will  send periodic
   updates.
     _________________________________________________________________

2.5. Server updates

   While  the  player  is  logged  in,  information  about the server may
   change,  espeically  if  that  information  pertains to the players or
   tables in a perticular room. Rather than insist that the client send a
   new list request periodically, the server will send update messages to
   the client:

     * If  the the room list changes in any way, the server will send out
       a room UPDATE to each of the clients. Note that currently there is
       no  mechanism to change the rooms on the fly, so this message will
       never  occur. However, it is probable that this functionality will
       be added in the future.
     * If  another player enters or leaves the room, the server will send
       an UPDATE of type 'player' to all of other players in that room. A
       player will never receive a player update about himself.
     * If  the  server's  list  of supported games types changes, it will
       send  a  game  type  UPDATE  to  each  of  the  clients. Note that
       currently  there  is no mechanism to change game types on the fly,
       so  this  message  will  never occur. However, it is probable that
       this functionality will be added in the future.
     * Whenever  the list of tables in a room changes, each player in the
       room  will  receive  an UPDATE message of type 'player'. This will
       occur whenever a table is launched or destroyed, a player joins or
       leaves, or the table's state has changed.

     Note:  It should be noted that these messages are asynchronous, are
     are  sent by the server automatically without having been requested
     by the client.
     _________________________________________________________________

2.6. Table Management

   In order to play or watch a game with other players logged into GGZ, a
   player  must  be  at  a  table.  This  is  accomplished via one of two
   interactions:

     * To  join  a  player  or spectator to an existing table, the client
       should  send  JOIN. The server will respond with RESULT, notifying
       the client if the attempt to join was successful.
     * To  launch  a  new  table,  clients  must send the LAUNCH tag. The
       server  will  respond  with  RESULT,  notifying  the client of the
       status of the table launch.

     Note:  Currently  the server will automatically attempt to join the
     the  player  to  the  newly launched table. The result of this join
     will be sent to the client via a RESULT, even though the client did
     not  explicitly request a join. This behaviour may change in future
     version of the server

   At the end of a game session, the server will automatically remove all
   players  from  the table. Should a player wish to leave a table before
   the  completion of the game, however, the client may send a LEAVE. The
   server  will  then send back RESULT. Note that not all game types will
   support  leaving  in mid-game. Such games can be left when passing the
   'force' parameter, however it ends for all other players then, too.
     _________________________________________________________________

2.7. Chatting with friends

   What  fun  would playing games be if you can't taunt your opponents or
   laugh  with your friends? Similar to the "Taunt" feature provided with
   NetSpades,  the  GGZ  server  provides the ability to send messages to
   other  players via the server. The following interactions describe how
   this messaging is accomplished.

     * When  a  player  wishes  to send a chat message, the client should
       send a CHAT. Different types of chat messages are distinguished by
       the  chat  sub-opcodes  The server will respond with the status of
       the chat operation via CHAT
     * When  a  player  receives  a chat message from another player, the
       server  will  send  CHAT  to  the  client.  The  chat  sub-opcodes
       distinguish between the various chat operations

   Sub-opcodes for chat messages are as follows:

     * GGZ_CHAT_NORMAL  signifies  a "typical" chat message which is sent
       to all players in the current room.
     * GGZ_CHAT_BEEP  is a special message with no text content, which is
       sent  to  a  specific  player.  A  typical  client response to the
       receipt of this message would be to emit a beep.
     * GGZ_CHAT_PERSONAL  is  a  private  message  directed  to  a single
       player.

                                     Warning
       To discourage cheating, private messages may not be sent or received
       while the player is at a game table.
     _________________________________________________________________

2.8. Game Interactions

   Since  protocol  version  7,  direct  connections  have been in place.
   Therefore, no separate tags to embed them are needed anymore.
     _________________________________________________________________

Chapter 3. Design Overview

                               Warning

   This chapter is horribly out of date. We will be fixing it soon
   There are four parts which comprise the server side:

     * Main GGZ server (called ggzd)
     * Individual game servers
     * Run-time config utility programs
     * Meta server

   We  will  discuss  each  of these in turn, but first we'll look at the
   overall architecture.

   Figure 3-1. Server Architecture

   [server_arch.gif]
   The  GGZ  server  will  handle  incoming  connections, manage the user
   database, and keep track of all of the games being played (referred to
   as  game  tables).  Clients  are  always  in direct communication with
   control.

   Note  that  ggzd  will  not  handle  the  specifics of how to play any
   particular  game.  That  logic  is  contained  in  the individual game
   servers.  It  is expected (and hoped!) that game developers will write
   their  own games servers for use with GGZ. GGZ will attempt to provide
   a  simple framework for writing network games in which developers need
   not  worry about connections or user logins or maintaining statistics.
   All  of  that will be done by GGZ. Game developers should only have to
   concern themselves with gameplay.

   The third item is more loosely connected. We will provide some sort of
   run-time  configuration utilities for GGZ, so the main server will not
   have  to  be  restarted  (or worse.. recompiled!) in order for various
   options to be changed. The first such utility is ggzduedit, with which
   the user database can be edited.

   Some options may include:

     * Location of game servers
     * Set auto removal of inactive users
          + Set inactivity threshold
     * Set auto clearing of statistics
          + Set clearing interval
     * Log level (level of detail in server logs)
     _________________________________________________________________

3.1. The GGZ server (ggzd)

   This  is  the main brain for the server side of GGZ. It handles client
   logins  and new user registrations. It manages option negotiation with
   the  clients,  and  launches new game sessions. It maintains a list of
   running  game sessions and keeps a database of win/lose statistics for
   each  user.  It  coordinates  games,  users,  and  databases,  and  is
   responsible  for  interacting  with the client, the running games, and
   the config utility.

   Several  possible designs were being considered before settling on the
   current  one.  It  is  possible  that as GGZ develops this design will
   change  as  well.  Since  ggzd  must communicate with multiple parties
   (game  tables,  users,  etc.)  it  was decided to use a multi-threaded
   concurrent  server  where  each  connection (be it user or game table)
   gets its own thread. This avoids the situation where ggzd is servicing
   a  request  and  therefore  cannot  handle any incoming connections or
   other   requests.  Brent  chose  threads  rather  than  forking  child
   processes  because threads have a smaller overhead and it is easier to
   share memory between threads than between processes.

   Every  time  a  new user connects, ggzd creates a new thread to handle
   all  requests  for  that  user.  This  thread  is  known as the player
   handler.  If  the  user decides to launch a new game table, the player
   handler  creates  a thread to handle all requests from the game table.
   This new thread is known as the table handler. The table handler waits
   until  enough  players have joined the table and then forks a process,
   known as the game table process, in which to run the game server. (The
   reason  game  servers  are  not  run  within  a thread is so that game
   developers not be required to worry about writing thread-safe code.)

   During  the course of the game, the player thread for each player acts
   as  a  liaison between the player and the game table, passing requests
   back  and  forth transparent to the player and the game server. When a
   player logs out, the player handler thread is destroyed.
     _________________________________________________________________

3.1.1. Interactions between ggzd and running games

   Quite  a  few  game servers will be provided with GGZ, but it is hoped
   that  others  will  write  game  modules,  and  either submit them for
   inclusion  in  the  GGZ  package,  or  maintain  and  distribute  them
   separately.  The  following  API describes how ggzd will interact with
   the game processes.

     Note:  All interaction is enclosed within the ggzdmod library. Game
     developers  should  use  it  (or any of its wrappers) so they don't
     have to deal with the protocol in use directly.

   Four types of data are exchanged between ggzd and game servers:

     * chr: a 1-byte signed char
     * int: a 4-byte signed integer in network byte order
     * str:  a  multibyte  null-terminated  string preceded by its length
       (including null-termination) as an integer.
     * fd:  a  file  descriptor  passed via sendmsg() along with a single
       byte of dummy data

   The  following  is a complete list of messages between the game module
   and  the  control  section  of  the  server.  Again,  I have chosen to
   intersperse  game  module  requests  with  the  corresponding  control
   responses.

   Please  note:  the  following  is  not written stone, merely a list of
   ideas.
        REQ_GAME_LAUNCH
        int: number of seats at table
        sequence of
        int: seat assignment (-1 for OPEN, -2 for COMP, -3 RESV)
        str: name of player (if assignment >=0 or == RESV)
        fd:  file dscriptor of player (if assignment >= 0)
        RSP_GAME_LAUNCH
        chr: success flag (0 if OK, -1 if error)

        REQ_GAME_JOIN
        int: seat number
        str: name of player
        fd:  file dscriptor of player
        RSP_GAME_JOIN
        chr: success flag (0 if OK, -1 if error)

        REQ_GAME_LEAVE
        str: name of player
        RSP_GAME_LEAVE
        chr: success flag (0 if OK, -1 if error)

        MSG_GAME_OVER
        int: number of statistics
        sequence of
        int: player index
        int: number of games won
        int: number of games lost

        MSG_LOG
        int: log level mask
        str: log message

        MSG_DBG
        int: debug level mask
        str: debug message

     _________________________________________________________________

3.1.2. Interactions between ggzd and config utilities

   Since the server runs non-interactively in the background, there needs
   to  be some run-time configuration tools so that server options may be
   changed  without  restarting.  Updates  are either executed indirectly
   (e.g.  when removing a player from the database), or explicitely (e.g.
   when  changing  some  configuration  parameters  and  sending a hangup
   signal  to  ggzd).  The  latter one will be steered by a configuration
   utility as well at some point.

   Messages between ggzd and the config utilities might include:

     * Request available game types (loaded modules)
     * Add/Remove Game types
     * Remove users
     * Request list of active games
     * Clear Player statistics
     * Modify logging
     _________________________________________________________________

3.2. Individual Game Servers

   As  described  above, game servers run in their own processes, and are
   responsible for handling the gameplay of a particular game.

   There are three possibilities for game server design.

     * Compiled in. The game table process calls a startup function which
       begins  execution  of the game server. This scheme has the benefit
       that  the  server has access to ggzd's data structures at the time
       the  process  was forked. Communication between the game table and
       ggzd  can  be  via  pipes  or  a socketpair. The problem with this
       scheme  is  that to change which games are offered by a particular
       server requires a recompile. Not good.
     * Dynamically  loaded modules. Similar to the above except that game
       server exist as loadable modules which may be inserted and removed
       at  runtime.  This  allows  for  adding  new  game types without a
       recompile.  Downside  is that it requires both game developers and
       myself to know how to deal with loadable modules.
     * Exec()  separate  program.  In this scheme, GGZ acts much like the
       inet   daemon  by  handling  the  connections  and  then  doing  a
       fork()/exec()  to  launch the game server. This scheme also allows
       for adding new games at runtime and has the bonus effect that game
       servers can be written in other languages that C.

   The current design requires game servers of type three. It is possible
   however,  that  in the future GGZ will allow dynamically loaded server
   modules as well.

   Once the game server is running it is necessary that ggzd pass it some
   required  information  such as player names and file descriptors. This
   communication  occurs  over  a pipe or socketpair which is established
   prior  to  the  forking  of the process. The interactions between game
   modules and the control section are listed above in section 3.1.1.1.
     _________________________________________________________________

3.3. Config Utility

   There  is currently one such tool, namely ggzduedit. It can be used to
   access  the  player  database,  edit  permissions  and  add and remove
   registered players.
     _________________________________________________________________

3.4. Key Subsystems

   While   the   architecture   of   the   server  is  divided  into  the
   aforementioned  four  parts,  there  are  a few "subsystems" which are
   necessary.
     _________________________________________________________________

3.4.1. Options Parser

   This  is  a  two part system. One to parse the command-line arguments,
   and  one  to  parse  the  configuration file. Options specified on the
   command  line should have a higher precedence than those in the config
   file.  Additionally,  an alternate config file may be specified on the
   command line.

   At the present, the popt library is used for command-line parsing.

   The   configuration  file  parsing  is  a  three-phase  process  which
   bootstraps  itself  from  a  dark,  dreary  and  empty  server  to one
   supporting  multiple  chat  rooms, each of which can host one specific
   game:

     * Phase  One:  Read  the ggzd.conf file from SYSCONFDIR. The file to
       read can be determined at runtime with the
       --file=/path/to/conffile option. This feature is most notably used
       when testing a new configuration.
       The same line parser is used throughout the configuration process.
       It  is relatively simplistic, much like strtok(), but processes an
       entire  line  in  a single shot. It then sets two module variables
       'varname'  and  'varvalue'  to  the  appropriate contexts from the
       configuration line. The file parsers can then use these strings to
       configure various run-time variables.
     * Phase  Two:  Scan  all  the game description files and parse those
       which have been signaled as in use by the main configuration file.
     * Phase  Three:  Scan all the room description files and parse those
       which have been signaled as in use by the main configuration file.
       These  must  be  processed after the game files, as each room will
       host a game which is already loaded by phase two.

   The  actual  contents  of  the configuration files is discussed in the
   server administration documentation.
     _________________________________________________________________

3.4.2. Login/User Database

   The  server  will  need to store a database of user ID, name, password
   and  permission at the very least. This system must allow searching by
   name  or  ID,  and allow for easy addition/deletion. GGZ can use libdb
   for  this.  A  SQL database is possible too but probably not necessary
   for most installation. Both PostgreSQL and MySQL are supported at this
   point.
     _________________________________________________________________

3.4.3. MOTD System

   The  message  of  the  day  is read at initialization time from a file
   pointed to by the MOTD configuration file option. The file can consist
   of up to 80 lines (this is configurable at build via MAX_MOTD_LINES).

   The  message  of  the  day  file  can  contain  % specifiers which are
   replaced  by  the  server  before sending to the client. The following
   codes are supported:

     * %a - Server administrator's name
     * %C - Server cputype (according to last kernel build)
     * %d - Current date on server
     * %e - Server administrator's email address
     * %g - Current number of game tables
     * %G - Current number of game tables with free seats
     * %h - Server's hostname
     * %o - Server's OS name
     * %p - Port number for this server
     * %t - Current local time on server
     * %u - Current server uptime statistic
     * %U - Current numbers of users on system
     * %v - Version of running server
     _________________________________________________________________

3.4.4. Player Statistics

   Since  the  game  modules  are  dynamic,  it  makes sense to store the
   statistics  on a per-game type basis, rather than on a per-user basis.
   Statistics  are  currently  handled by ggzdmod, independent from ggzd.
   Several  types  will be supported eventually, some of them are already
   implemented, e.g. win/loss or ELO.
     _________________________________________________________________

3.4.5. Module loading

   Not written
     _________________________________________________________________

3.5. Data Structures

   There  will be an array of game_t structures on the server. This array
   will  be  initialized  at  startup,  and  may  be changed when dynamic
   loading  of  new  game  modules  occurs.  The index into this array is
   referred to as the game type index.
    game_t {
    str: short string for name of game (16 chars?)
    str: long string for description (256 chars?)
    fnc: pointer to function for launching game
    chr: allowable player numbers (2^num)
    chr: allow computer players (1 for yes)
    int: sizeof options struct in bytes
    chr: enabled flag (1 if playing this game is enabled)
    }


   There  will  be an array of game_run_t structures representing running
   games,  This  array  will  be  dynamic  since as games are started and
   finished,  entries  in  the array are created and destroyed. The index
   into this array is referred to as the game index.
    game_run_t {
    int: game type index
    int: number of player slots
    *int: array of player codes for registered players
    chr: play/wait flag (0 if waiting for players, 1 if playing)
    int: process or thread ID
    *void: pointer to options struct for this game
    *int: array of player codes for reservations
    int: number of open player slots
    int: file descriptor for communication
    chr: computer players (2^num)
    }


   There  will  also  be a large array of user_t structures, representing
   connected  users.  As soon as a user connects, an entry is created and
   the  file  descriptor  filled  in.  When  the user completes the login
   process, the user code and name are filled in. When the user launches,
   or joins a game, the game index is filled in.
    user_t {
    int: user code (unique user id number)
    str: user name
    int: file descriptor for communication
    int: game index
    }


   An  array  of  reservation_t  structures holds all of the reservations
   requested.  These are created when a game is launched with reservation
   requests.  They  may  be altered once the game has been launched. They
   are deleted when a user accepts a reservation or declines it.
    reservation_t {
    int: game index
    int: user code
    }


   The  server options are stored in a Options structure. This holds many
   run-time  configurable  options.  Note:  Not  all of these options are
   implemented at this current time.
    Options {
    str: Name of configuration file specified in --file
    chr: remove_users
    int: User inactivity time
    chr: clear_stats
    int: stat_clr_time
    int: TCP/IP port to use for communications
    str: Directory in which game description files are found
    str: tmp_dir
    str: The base configuration directory
    str: The server admin's name
    str: The server admin's email address
    int: Whether to perform hostname lookups for log files
    }


   A  chat  room  is  implemented  internally  in a RoomStruct. These are
   stored  in  a  run-time allocated array as needed. Hopefully this will
   allow on-the-fly room creation in the future.
    RoomStruct {
    str: Short room name
    str: Long room description
    int: Number of players in room
    int: Maximum number of players allowed in this room
    int: Number of active tables in room
    int: Maximum number of active tables in room
    int: The game type this room hosts
    time_t: A timestamp when the player list last changed
    time_t: A timestamp when the table list last changed
    *int: An array of player indices (players in room)
    *int: An array of table indices
    *ChatItemStruct: The tail of a linked list of chat for this room
    }


   Chat  messages  are implemented as a set of linked lists, one per chat
   room.  The  chat  room itself points to the tail of the linked list so
   that  chats  may  easily  be  tacked  onto  the end. Each player has a
   pointer  to  their  head  of the chain, which is the next message they
   expect to receive. A ChatItem is stored as follows:
    ChatItem {
    int: Number of players who have not read this chat
    str: The name of the sender of this chat
    str: The message itself
    *ChatItem: The next message in the linked list
    }


   The  message  of the day is stored internally in a MOTDInfo structure.
   It  is  read  at system initialization and will not change dynamically
   (at least yet).
    MOTDInfo {
    str: Filename where MOTD is found
    chr: Whether to utilize the MOTD (bool)
    ulong: Time the server started up (used to calc uptime)
    int: Number of lines in MOTD file
    *str: An array of MOTD text lines
    str: The server's hostname
    str: The server's system name (eg: Linux)
    str: The server's CPU identifier - this is not strictly accurate
    and depends on who compiled the kernel
    str: The port number the server is using
    }


   Logfile  options are stored separately from the main server options in
   a LogInfo structure:
    LogInfo {
    int: Have log files been initialized?  If no, we emit to stdout/err
    int: Which syslog facility to use
    uint: A bitmap of options (see err_func.h)
    str: Filename for logfile (if not syslog)
    *FILE: Stream for logfile
    uint: Log types to include in logs (see err_func.h)
    ** The following are only included if debug is on **
    chr: A flag to note that debug level was set on command line
    str: Filename for debug file (if not syslog)
    *FILE: Stream for debug file
    uint: Debug types to include in logs (see err_func.h)
    }

     _________________________________________________________________

Appendix A. Protocol Reference

   We  now  list a complete reference of messages which get passed to and
   from the GGZ server. This listing conforms to protocol version 7.

   Three types of data are exchanged between the client and the server:

     * char: a 1-byte signed char
     * int: a 4-byte signed integer in network byte order
     * string:  a multibyte null-terminated string preceded by its length
       (including null-termination) as an integer.

   Interactions   take  one  of  three  forms:  server  messages,  client
   requests,  and  server  responses.  Each interaction is prefaced by an
   opcode  identifying  it  (some  interactions  consist  solely  of  the
   opcode). The opcode (stored as an enumerated value) is sent as an int.
     _________________________________________________________________

A.1. Messages sent in both directions

   Table of Contents
   SESSION -- Session start
   PING -- Lag measurement challenge
   PONG -- Lag measurement response

SESSION

Name

   SESSION -- Session start

Synopsis

   <SESSION> ... </SESSION>

Description

   Session start tag sent from server or client

Message Data

   None

Usage

   The  SESSION  tag  is  sent  from  the  server  to  the  client upon a
   successful  connection.  It  does neither guarantee a successful login
   nor  does  it  indicate  if the client and server version match. It is
   also  sent by the client, when attempting to login, or when requesting
   a direct connection between game client and game server.

PING

Name

   PING -- Lag measurement challenge

Synopsis

   <PING ID='_id_'/>
   Data Type   Example
   ID   string 1h3k5lmfs

Description

   Periodically sent request

Message Data

   ID
          Unique identifier for this ping; it is sent back in the pong.

Usage

   The  PING  tag  is sent periodically from the server to all clients in
   order  to obtain their response (the PONG tag) for lag calculation. It
   may  also be sent by the client to the server at any time to determine
   the client's own lag time.

PONG

Name

   PONG -- Lag measurement response

Synopsis

   <PONG/>
   Data Type   Example
   ID   string 1h3k5lmfs

Description

   Response to lag measurement challenge

Message Data

   ID
          Unique identifier for this pong - the same string that was sent
          in the ping.

Usage

   The  PONG  should be sent immediately in response to the PING tag. The
   resulting  round-trip  time  can be measured to determine the player's
   lag.  When  the  server sends the ping, the lag measurement is tracked
   and  reported  to all players in the room (including that player). But
   for  a  lagging  client  -  or one that is not in a room - this is not
   helpful.  Thus  the  client  can also send a ping to determine its own
   latency.
     _________________________________________________________________

A.2. Server to client messages

   Table of Contents
   ROOM -- List entry describing one room
   GAME -- List entry describing one game type
   SERVER -- Server identification
   MOTD -- Server Message of the day
   UPDATE --  Notification that the list of players or the list of tables
          in a room has changed, or the list of rooms or game types on a
          server.

   PLAYER --  List entry describing one player.
   TABLE --  List entry containing one table
   JOIN --  Message to indicate you've joined a table
   LEAVE --  Message to indicate you've left a table
   RESULT --  General message to indicate the result of a request
   LIST --  Server response to request for list of rooms or list of games

   CHAT -- Server response to chat message request

ROOM

Name

   ROOM -- List entry describing one room

Synopsis

   <ROOM ID="id" NAME="name" GAME="game" PLAYERS="players">
   <DESC>desc</DESC> </ROOM>
   Data    Type   Example
   ID      string 0
   NAME    string TicTacToe
   GAME    int    4
   PLAYERS int    14
   DESC    string Sample TTT room

Description

   A list entry describing one room at a GGZ server

Message Data

   ID
          Unique identifier for this room

   NAME
          Room name

   GAME
          The identifier of the game associated with this room

   PLAYERS
          The number of players currently in the room. This value is sent
          in  the room list and may be periodically updated. However this
          information   is  not  updated  immediately,  so  the  client's
          knowledge  may  become  stale.  For the current room the client
          should  use  the list of players in the room as a more accurate
          value.

   DESC
          Verbose room description (sent only if requested)

Usage

   A  list  of  room  tags  is sent when requesting the list of available
   rooms on a server, typically done after logging in.

GAME

Name

   GAME -- List entry describing one game type

Synopsis

   <GAME ID="id" NAME="name" VERSION="version"> <PROTOCOL ENGINE="engine"
   VERSION="version"/> <ALLOW PLAYERS="players" BOTS="bots"
   SPECTATORS="spectator"/> <ABOUT AUTHOR="author" URL="url"/>
   <DESC>desc</DESC> </GAME>
   Data Type Example
   ID int 0
   NAME string TicTacToe
   VERSION string 0.2
   ENGINE string TicTacToe
   PLAYERS string 4
   BOTS string 1..3
   SPECTATORS string true
   AUTHOR string Anonymous Coward
   URL string http://ggz.sourceforge.net/
   DESC string My first game

Description

   A list entry describing one game at a GGZ server, which may be used in
   one or more rooms.

Message Data

   ID
          Unique identifier for this game

   NAME
          The name of the game

   VERSION
          Game   server   program   version,   and   game   server/client
          communication protocol version

   ENGINE
          Generalized game type, which is used for frontend selection

   PLAYERS
          The  number  of  players allowed in this game, in the form of a
          list  of  individual  numbers and/or a single range of numbers,
          separated by spaces. For instance '1 2 3 5..10' includes both a
          list and a range.

   BOTS
          The number of AI bots allowed at a table of this game. The form
          is that of a number list (the same as for the PLAYERS element).
          Zero bots is always allowed and will not be listed.

   SPECTATORS
          Whether  spectators  are  allowed  or  not,  either  'true'  or
          'false'.

   AUTHOR
          Name of the author or author team

   URL
          Pointer to the project homepage of the game server

   DESC
          Description for the game type offered by this server

Usage

   After  the  client requested the list of games, a LIST containing some
   game entries is sent from the server to the client.

SERVER

Name

   SERVER -- Server identification

Synopsis

   <SERVER ID="id" NAME="name" VERSION="version" STATUS="status">
   <OPTIONS CHATLEN="chatlen"/> </SERVER>
   Data    Type   Example
   ID      string GGZ-0.0.6
   NAME    string Harry's GGZ server
   VERSION int    6
   STATUS  string ok
   CHATLEN int    512

Description

   An identification message from the server

Message Data

   ID
          Server identification string (including version number)

   VERSION
          Integer version number

   NAME
          Descriptive name of that server

   STATUS
          Current server status, can be either 'ok' or 'full'

   CHATLEN
          Maximum length of chat messages

Usage

   The  SERVER  tag is sent from the server to the client right after the
   SESSION  tag. It must be examined by the client to determine whether a
   login is possible or not.

MOTD

Name

   MOTD -- Server Message of the day

Synopsis

   <MOTD PRIORITY="priority"> <![CDATA[...]]> </MOTD>
   Data     Type   Example
   PRIORITY string normal

Description

   Message of the day (MOTD) from the Server

Message Data

   PRIORITY
          MOTD priority used to determine whether to display it or not

   Data (CDATA)
          All lines of the MOTD, separated by the newline character

Usage

   The  MOTD  tag  is  sent from the server to the client upon successful
   login (ie. after the RESULT tag belonging to a LOGIN request)

UPDATE

Name

   UPDATE --  Notification that the list of players or the list of tables
   in a room has changed, or the list of rooms or game types on a server.

Synopsis

   <UPDATE TYPE="type" ACTION="action" ROOM="room" FROMROOM="from"
   TOROOM="to">
   Data     Type   Example
   TYPE     string player
   ACTION   string add
   ROOM     int    1
   FROMROOM int    2
   TOROOM   int    3

Description

   Notification  from  the server that the list of players in the current
   room has been modified since the last update, or that a table has been
   added,  removed  or changed its state, or that a room or game type has
   been added or removed.

Message Data

   TYPE
          Update  type.  Can  be 'player' or 'table' for room updates, or
          'room' or 'game' for server updates.

   ACTION
          Action  to  do.  Can  be 'add', 'delete', 'lag', or 'stats' for
          players; 'add', 'delete', 'join', 'leave', 'status', 'desc', or
          'seat'  for  tables;  'players'  for rooms. No game updates are
          possible at this time.

   ROOM
          Room  to which the update applies. Only used for types 'player'
          and 'table'.

   FROMROOM
          Room  the  player is coming from. Only used for type 'add'. The
          room may be -1 indicating "no room".

   ROOM
          Room  the  player is going to. Only used for type 'delete'. The
          room may be -1 indicating "no room".

Usage

   An  UPDATE  tag  is  sent from the server to the client if the list of
   players,  tables, rooms or games has changed since the last update. It
   is not sent upon initial entry to a room or server; the information is
   originally  sent  in a LIST. An update is sent when the information of
   that type changes.

   The  UPDATE tag contains one or more tags of type PLAYER, TABLE, ROOM,
   or GAME. The information included in the subtags depends on the ACTION
   attribute  of  the  update. For instance a "table" "desc" update would
   include  only  the  description  of  the table, while a "player" "add"
   update  includes the full information about the player. A full list of
   these dependencies is not available at this time.

PLAYER

Name

   PLAYER --  List entry describing one player.

Synopsis

   <PLAYER ID='id' TYPE='type' TABLE='table' LAG='lag' WINS='wins'
   LOSSES='losses' TIES='ties' FORFEITS='forfeits' RATING='rating'
   RANKING='rating' HIGHSCORE='highscore'/>
   Data Type Example
   ID string Grubby
   TYPE string guest
   TABLE int -1
   LAG int 1
   WINS int 7
   LOSSES int 3
   TIES int 1
   RATING int 1500
   RANKING int 3
   HIGHSCORE long 49807

Description

   List entry containing the description of one player

Message Data

   ID
          Unique identifier of this player

   TYPE
          Player type (can be 'guest', 'normal', 'admin' or 'bot')

   TABLE
          ID  number  of  table  at  which player is "sitting"; -1 or not
          present if the player is not at a table.

   LAG
          Lag  value  of  the  player,  which  ranges  from  zero  (ideal
          connection) to five (slow connection).

   WINS
          The  number of wins the player has. This will be a non-negative
          integer,  if  present. It will not be present if the player has
          no  stats  of  this  type  (for whatever reason). WINS, LOSSES,
          TIES,  and  FORFEITS  will all be either present or not present
          (as a group).

   LOSSES
          The  number  of losses the player has - a non-negative integer.
          See WINS.

   TIES
          The number of ties the player has - a non-negative integer. See
          WINS.

   FORFEITS
          The  number  of  forfeits  (abandoned games) the player has - a
          non-negative integer. See WINS.

   RATING
          If   present,  it  represents  the  player's  rating.  This  is
          generally  done  on  an  ELO scale, although the parameters may
          differ  from  those used for Chess. It will not be given if the
          player has no rating.

   RANKING
          If  present,  provides the absolute ranking of the player. This
          will  be a positive integer. It will not be given if the player
          has no ranking.

   HIGHSCORE
          If  present, provides the highest score the player has achieved
          at  the  current  game.  It  will  not  be given if there is no
          available highscore for this player.

Usage

   The  PLAYER  is contained in a list sent from the server to the client
   in  response  to  LIST  request  tag  of type 'player'. It may also be
   contained  within  the  UPDATE  tag  send  from the server when player
   information  changes.  If  sent as part of a LIST then the information
   will  be complete - and any omissions are intentional. If sent as part
   of an UPDATE then only some attributes will be present.

TABLE

Name

   TABLE --  List entry containing one table

Synopsis

   <TABLE ID="id" GAME="game" STATUS="status" SEATS="seats">
   <DESC>desc</DESC> <SEAT NUM="num" TYPE="type">player</SEAT> ...
   </TABLE>
   Data   Type   Example
   ID     int    0
   GAME   int    0
   STATUS int    1
   SEATS  int    2
   DESC   string An empty table
   NUM    int    0
   TYPE   string player
   PLAYER string Grubby

Description

   The TABLE tag describes one table with all its properties

Message Data

   ID
          Unique identifier of this table in this room

   GAME
          Associated game. Only used in updates with action 'add'.

   STATUS
          Current  status  of  the  table.  Only used within updates with
          action 'status' or 'add'.

   SEATS
          Number of seats on this table.

   DESC
          Description  of  the table. Only sent when table is being added
          to the list, i.e. in updates with action 'add'.

   NUM
          Number of a seat.

   TYPE
          Type  of  a  seat, which can be 'open', 'player', 'reserved' or
          'bot'.

   PLAYER
          Player name in case the type is either 'player' or 'reserved'.

Usage

   TABLE  tags  are  sent  in  a  list  from  the server to the client in
   response  to  LIST when LIST is of type 'table', and in UPDATE tags of
   type 'table'.

JOIN

Name

   JOIN --  Message to indicate you've joined a table

Synopsis

   <JOIN TABLE='table' SPECTATOR='spectator'/>
   TABLE     integer    1
   SPECTATOR boolstring false

Description

   Tells  the client that they have joined a table. Currently each client
   and  each  player can only be at one table at a time. The join will be
   initiated  when  the  client  sends  either  a JOIN request to join an
   existing  table  or  a  LAUNCH  request  to  launch  a  new table (and
   subsequently join it).

Message Data

   TABLE
          The  index  of  the  table that has been joined. This will be a
          non-negative  integer  corresponding  to  the index sent in the
          TABLE tag.

   SPECTATOR
          Either  "true"  if the player is a spectator or "false" if they
          are  a  normal  player. This is generally determined based upon
          the client's JOIN request.

Usage

   JOIN  is  sent  from  the  server  to  the client to inform the player
   they've joined a table. The client should take any necessary actions.

LEAVE

Name

   LEAVE --  Message to indicate you've left a table

Synopsis

   <LEAVE REASON='reason' PLAYER='player'/>
   REASON string normal
   PLAYER player jdorje

Description

   Tells the client that they have left a table. This may be initiated by
   the  player  sending  the  server  a LEAVE request, by the game server
   exiting  when  the  game  is over, by the player being booted from the
   table,  or by the game server aborting. In any of the cases the client
   should make sure the game client exits normally.

Message Data

   REASON
          The  reason  the  player  left  the  table,  currently  one  of
          "normal", "boot", "gameover", or "gameerror".

   PLAYER
          The name of the (remote) player responsible for the leave. This
          is currently only provided for the "boot" leave, where it gives
          the name of the player who initiated the boot.

Usage

   LEAVE  is sent from the server to the client to tell of a table leave.
   The client should take any necessary actions.

RESULT

Name

   RESULT --  General message to indicate the result of a request

Synopsis

   <RESULT ACTION="action" CODE="code"/>
   Data   Type   Example
   ACTION string list
   CODE   string ok

Description

   Server response to any request, embedding the answer data

Message Data

   ACTION
          The  request  type this result is referring to. Actions include
          'motd',  'list',  'enter',  'chat',  'launch', 'join', 'leave',
          'reseat', 'update', 'protocol', 'channel', 'login', and 'pong'.

   CODE
          Result  indicator:  either  'ok' or an error string. Errors may
          include 'usr lookup', 'bad options', 'room full', 'table full',
          table  empty',  launch  fail',  'join fail', 'no table', 'leave
          fail', 'leave forbidden', 'already logged in', 'not logged in',
          'not  in room', 'at table', 'in transit', 'no permission', 'bad
          xml',  'seat  assign  fail',  'no  channel', or 'too long'. The
          client  should  behave  sanely when it receives an unrecognized
          error.

Usage

   RESULT  is  sent  from  the  server to the client in response to LIST,
   ENTER, LAUNCH, JOIN, LEAVE, CHAT and LOGIN requests. Note that in some
   of  these  cases  (e.g.  LIST)  the  response  to  the request will be
   contained  within the RESULT, whereas in others it will not. The logic
   on  which  is  which  is  reasonable,  but  nonetheless  the  lack  of
   consistency may be confusing.

LIST

Name

   LIST --  Server response to request for list of rooms or list of games

Synopsis

   <LIST TYPE="type" ROOM="room"> </LIST>
   Data Type   Example
   TYPE string room
   ROOM int    1

Description

   Server response to request for list of rooms or game types

Message Data

   TYPE
          Type of list, either 'room', 'game', 'table' or 'player'

   ROOM
          The  room to which this list belongs. Only used for 'table' and
          'player'.

Usage

   The  LIST  is  sent  from  the server to the client in response to the
   client  request  named LIST, and may contain either TABLE or PLAYER or
   GAME or ROOM entries.

CHAT

Name

   CHAT -- Server response to chat message request

Synopsis

   <CHAT TYPE="type" FROM="from"> <![CDATA[...]]> </CHAT>
   Data Type   Example
   TYPE string private
   FROM string Grubby

Description

   Server response to player chat request

Message Data

   TYPE
          Type of chat message, which can be one of "normal", "announce",
          "beep", "private", or "table".

   FROM
          Player from which this message originates

Usage

   The CHAT response tag is sent from the server to client to handle chat
   message requests via the CHAT tag.
     _________________________________________________________________

A.3. Client to server messages

   Table of Contents
   LOGIN -- Client requested login
   LIST --  Client request for list of rooms or games on the server, or
          of tables or players in a room

   LAUNCH -- Client request for new table launch
   JOIN -- Client request to join a table
   LEAVE -- Client request to leave table
   CHAT -- Client chat message request
   ENTER -- Request to change rooms
   CHANNEL -- Request for a direct game connection

LOGIN

Name

   LOGIN -- Client requested login

Synopsis

   <LOGIN TYPE="type"> <NAME>name</NAME> <PASSWORD>password</PASSWORD>
   </LOGIN>
   Data Type Example
   TYPE string guest
   NAME string Gandalf
   PASSWORD string xxxx

Description

   Client requested login

Message Data

   TYPE
          Type of login, which can be one of "normal", "guest" or "first"

   NAME
          Login name

   PASSWORD
          Player  password,  which is only used for registered ("normal")
          players

Usage

   The  LOGIN  tag  is  sent  from  the client to the server to request a
   player  login. The request may come after SERVER. The client must have
   started the SESSION in advance. The server will respond to the request
   with a RESULT tag

LIST

Name

   LIST --   Client  request for list of rooms or games on the server, or
   of tables or players in a room

Synopsis

   <LIST TYPE="type" FULL="full"/>
   Data Type       Example
   TYPE string     room
   FULL boolstring true

Description

   Client request for list of rooms or game types on the server, or (when
   in a room) for list of tables or list of players

Message Data

   TYPE
          The type may be 'room' for the room list, and 'game' to receive
          the game types list. Likewise, 'player' and 'table' are used to
          retrieve room information.

   FULL
          Verbosity  flag.  Set  to  'false' for short room descriptions,
          'true'  for full descriptions. This is only used for the 'room'
          type.

Usage

   The <LIST> tag is sent from the client to the server to request a list
   of  rooms, game types, tables or players. The server will respond with
   the appropriate RESULT tag which contains a LIST. This request is only
   valid once the player has successfully logged in for 'room' and 'game'
   types  (ie.  after  the  login  RESULT), and only after the player has
   entered a room (for 'table' and 'player' types).

LAUNCH

Name

   LAUNCH -- Client request for new table launch

Synopsis

   <LAUNCH> ... </LAUNCH>   
   Data                   Type Example
   No data

Description

   Client request for new table launch

Usage

   The  LAUNCH  tag  request  a table to be launched in the current room.
   Therefore,  each  LAUNCH  request  contains one tag of type TABLE. The
   server  will  respond with a RESULT tag, followed by an UPDATE of type
   'table' upon success.

JOIN

Name

   JOIN -- Client request to join a table

Synopsis

   <JOIN TABLE="table" SPECTATOR="spectator">
   Data      Type       Example
   TABLE     int        0
   SPECTATOR boolstring true

Description

   Client request to join table

Message Data

   TABLE
          The identifier of table the player wishes to join

   SPECTATOR
          Whether  to join as spectator (when true) or not (when false or
          omitted).

Usage

   JOIN  is  sent  from client to the server to request a table join. The
   server  will respond with RESULT telling us the success of the action.
   If  the  action  was  successful  the client will also receive a JOIN,
   which  we should act upon. If the join succeeds it is likely an UPDATE
   of type 'table' will also be necessary..

LEAVE

Name

   LEAVE -- Client request to leave table

Synopsis

   <LEAVE FORCE="force">
   FORCE boolstring false

Description

   Server response to player request to leave tablet

Message Data

   FORCE
          Force  leaving  the  table even though the game doesn't support
          it. The game would then be cancelled. For spectators, this flag
          is ignored.

Usage

   LEAVE  is sent from the client to the server to request a table leave.
   The  server  will  respons  with  a  RESULT message as well as a LEAVE
   message with reason "normal" if the leave succeeded.

CHAT

Name

   CHAT -- Client chat message request

Synopsis

   <CHAT TYPE='type' TO='to'> <![CDATA[...]]> </CHAT>
   Data Type   Example
   TYPE string normal
   TO   string josef

Description

   Client chat message request

Message Data

   TYPE
          Chat   type.  Can  be  one  of  "normal",  "announce",  "beep",
          "private", or "table".

   TO
          Name  of  player  who  will  receive message. This attribute is
          needed for 'beep' and 'private' messages, but not for 'normal',
          'announce', or 'table'. The client should behave sanely if this
          contains incorrect data or is not present.

Usage

   A  CHAT  request  is  sent from the client to send a chat message. The
   server  will  respond  with  an appropriate RESULT which embeds a CHAT
   tag.

ENTER

Name

   ENTER -- Request to change rooms

Synopsis

   <ENTER ROOM="room">
   Data Type Example
   ROOM int  1

Description

   Request to change rooms

Message Data

   ROOM
          The room identifier of requested destination room

Usage

   ENTER  is sent from the client to the server to request a room change.
   It is expected that the server will respond with RESULT.

CHANNEL

Name

   CHANNEL -- Request for a direct game connection

Synopsis

   <CHANNEL ID="id">
   Data Type   Example
   ID   string Grubby

Description

   Request for a direct connection between game server and game client

Message Data

   ID
          Identifier  of the created channel. This equals the name of the
          player who launches or joins a game.

Usage

   To  obtain  a  channel,  the  CHANNEL  tag  is  sent within a separate
   SESSION.
     _________________________________________________________________

A.4. Messages from server to game module

   Table of Contents
   RSP_GAME_JOIN -- Response to join request
   RSP_GAME_LEAVE -- Response to leave request
   RSP_GAME_SPECTATOR_JOIN -- Response to join request of a spectator
   RSP_GAME_SPECTATOR_LEAVE -- Response to spectator leave request
   RSP_GAME_SEAT -- Response to player seat modification request
   REQ_GAME_STATE -- Request to change game state
   MSG_LOG -- Log message

   Messages from server to game module

RSP_GAME_JOIN

Name

   RSP_GAME_JOIN -- Response to join request

Synopsis

   RSP_GAME_JOIN
   Data   Type
   STATUS char

Description

   Indication of game server that it handled the join event

Message Data

   STATUS
          Status of the join request; if negative, an error occured

Usage

   The game server sends this message in response to REQ_GAME_JOIN.

RSP_GAME_LEAVE

Name

   RSP_GAME_LEAVE -- Response to leave request

Synopsis

   RSP_GAME_LEAVE
   Data   Type
   STATUS char

Description

   Indication of game server that it handled the leave event

Message Data

   STATUS
          Status of the leave request; if negative, an error occured

Usage

   The game server sends this message in response to REQ_GAME_LEAVE.

RSP_GAME_SPECTATOR_JOIN

Name

   RSP_GAME_SPECTATOR_JOIN -- Response to join request of a spectator

Synopsis

   RSP_GAME_SPECTATOR_JOIN
   Data   Type
   STATUS char

Description

   Indication  of  game  server  that  it  handled  the  join  event of a
   spectator

Message Data

   STATUS
          Status of the join request; if negative, an error occured

Usage

   The    game    server    sends    this    message   in   response   to
   REQ_GAME_SPECTATOR_JOIN.

RSP_GAME_SPECTATOR_LEAVE

Name

   RSP_GAME_SPECTATOR_LEAVE -- Response to spectator leave request

Synopsis

   RSP_GAME_SPECTATOR_LEAVE
   Data   Type
   STATUS char

Description

   Indication  of  game  server  that  it  handled  the  leave event of a
   spectator

Message Data

   STATUS
          Status of the leave request; if negative, an error occured

Usage

   The    game    server    sends    this    message   in   response   to
   REQ_GAME_SPECTATOR_LEAVE.

RSP_GAME_SEAT

Name

   RSP_GAME_SEAT -- Response to player seat modification request

Synopsis

   RSP_GAME_SEAT
   Data   Type
   STATUS char

Description

   Response from game server to a request to change a player seat.

Message Data

   STATUS
          Status of the procedure; if negative, an error occured

Usage

   The game server sends this message in response to REQ_GAME_SEAT.

REQ_GAME_STATE

Name

   REQ_GAME_STATE -- Request to change game state

Synopsis

   REQ_GAME_STATE
   Data  Type
   STATE char

Description

   Request to change game state

Message Data

   STATE
          New  state  of  the  game.  This  can  be  one  of:  "created",
          "waiting", "playing", "done"

Usage

   Sent  whenever  the  state  of  a  game  changes.  A RSP_GAME_STATE is
   expected in response.

MSG_LOG

Name

   MSG_LOG -- Log message

Synopsis

   MSG_LOG
   Data    Type  
   MESSAGE string

Description

   Log  message sent by the game to the server so it can be injected into
   the server's logging system.

Message Data

   MESSAGE
          The log message.

Usage

   Might be sent at any time by the game server.
     _________________________________________________________________

A.5. Messages from game module to the server

   Table of Contents
   REQ_GAME_JOIN -- Request for a player to join a table
   REQ_GAME_LEAVE -- Request for a player to leave a table
   REQ_GAME_SPECTATOR_JOIN -- Request for a spectator to join a table
   REQ_GAME_SPECTATOR_LEAVE -- Request for a spectator to leave a table
   REQ_GAME_SEAT -- Request to modify a player seat
   RSP_GAME_STATE -- Response to game state change request

   Messages from game module to the server

REQ_GAME_JOIN

Name

   REQ_GAME_JOIN -- Request for a player to join a table

Synopsis

   REQ_GAME_JOIN
   Data Type  
   SEAT int   
   NAME string
   FD   fd    

Description

   Request to join a game

Message Data

   SEAT
          Seat number of the joining player

   NAME
          The name of the affected player

   FD
          File descriptor used for communication with the player

Usage

   Sent  every time a player joins a game. In response, the server should
   send RSP_GAME_JOIN.

REQ_GAME_LEAVE

Name

   REQ_GAME_LEAVE -- Request for a player to leave a table

Synopsis

   REQ_GAME_LEAVE
   Data Type  
   SEAT int   
   NAME string

Description

   Request to leave a game

Message Data

   SEAT
          Seat number of the leaving player

   NAME
          The name of the affected player

Usage

   Sent  whenever  a  player  leaves  a game. The game is responsible for
   removing  the  player  from  its  data,  and  send a RSP_GAME_LEAVE in
   response.

REQ_GAME_SPECTATOR_JOIN

Name

   REQ_GAME_SPECTATOR_JOIN -- Request for a spectator to join a table

Synopsis

   REQ_GAME_SPECTATOR_JOIN
   Data Type  
   SEAT int   
   NAME string
   FD   fd    

Description

   Request to join a game

Message Data

   SEAT
          Spectator number of the joining spectator

   NAME
          The name of the affected spectator

   FD
          File descriptor used for communication with the spectator

Usage

   Sent  every  time  a  spectator  joins a game. In response, the server
   should send RSP_GAME_SPECTATOR_JOIN.

REQ_GAME_SPECTATOR_LEAVE

Name

   REQ_GAME_SPECTATOR_LEAVE -- Request for a spectator to leave a table

Synopsis

   REQ_GAME_SPECTATOR_LEAVE
   Data Type  
   SEAT int   
   NAME string

Description

   Request to leave a game

Message Data

   SEAT
          Spectator number of the leaving spectator

   NAME
          The name of the affected spectator

Usage

   Sent  whenever  a spectator leaves a game. The game is responsible for
   removing    the    spectator    from    its    data,    and   send   a
   RSP_GAME_SPECTATOR_LEAVE in response.

REQ_GAME_SEAT

Name

   REQ_GAME_SEAT -- Request to modify a player seat

Synopsis

   REQ_GAME_SEAT
   Data Type  
   SEAT int   
   NAME string
   FD   fd    

Description

   Request to modify a player seat

Message Data

   SEAT
          Number of the seat to be altered

   NAME
          Name  of  the  new  player,  if  the  seat  is  a  player  or a
          reservation

   FD
          Contains the file descriptor if the seat is a player

Usage

   REQ_GAME_SEAT  gets  sent if a seat is to be changed. In response, the
   server expects a RSP_GAME_SEAT from the game.

RSP_GAME_STATE

Name

   RSP_GAME_STATE -- Response to game state change request

Synopsis

   RSP_GAME_STATE
   Data Type
   none

Description

   Response from game server to a request to change a player seat.

Message Data

   None

Usage

   The server sends this message in response to REQ_GAME_STATE.
