[Freeciv-Dev] [RFC] New event handling

[Raimar Falke <hawk@xxxxxxxxxxxxxxxxxxxxxxx>]

Hi,

These are our ideas for the new event handling.

Overview
========

The following data is required by a client which is used by a human:
 - the localized format string
 - int arguments
 - string arguments
    * strings which maybe modified (city names, player names)
      [maybe translated or not, e.g. city names possibly will get
       translatable by client option]
    * strings which stay equal and are translatable (names from the ruleset)

A non human client needs:
 - a non-ambiguous way to identify a certain message
 - the category of this message; the categories should be organized
   hierarchically
 - int arguments
 - string arguments

There are certain ways to sent this data to the client. We (Dirk and
Raimar) came to the following conclusions:
 - the server sends the untranslated (english) format string; the
   client will translate the string using gettext() to get the
   localized format string
 - int arguments aren't a problem
 - strings which are changable: the server sends the type (city, player),
   the verbatim name and the id of the city or player (the id is
   required for the non-human client)
 - strings which stay unchanged: the server sends the type (unit,
   government, improvement,...) and the id; the client will lookup the
   string (using "find_*(id)->name") and translate it with gettext()
 - the non-ambiguous way of identification is the untranslated format
   string
 - the hierarchical category will be coded into an integer

Server side
===========

The call would change from:

  notify_player_ex(pplayer, punit->x, punit->y, E_NOEVENT,
                   _("Game: %s unit has no moves left to add to %s."),
                   unit_name, pcity->name);

to (slightly changed to be more salutary)

  notify_player_ex_new(pplayer, punit->x, punit->y, 
                       make_category(CAT_FAILURE, CAT_UNIT, CAT_MOVE, 
E_NOEVENT),
                       N_("Game: %s unit has no moves left to add to %s."),
                       AT_UNIT_NAME(punit->id),
                       AT_CITY_NAME(pcity->id));

So the event type will be exchanged with a call to
make_category(). The format string is unchanged. All arguments will
have to be wrapped in this AT_* (ArgumentType) macros. There will be:
AT_INT, AT_CITY_NAME, AT_PLAYER_NAME, AT_UNIT_NAME,
AT_GOVERNMENT_NAME, AT_WONDER_NAME, ... , AT_MALE_RULER_NAME,
AT_FEMALE_RULER_NAME.

The macros will expand to a magic number, the type (roughly same as
the AT_* macros) and the argument. Using the magic number it can be
ensured that every argument has a proper type attached.

To get the number of arguments the format string has to be searched
for '%' format identifiers (excluding %%).

Network
=======

Basically the arguments to the above method after expanding the AT_*
macros get transfered. For city and player names also the name is
transfered verbatim. The packet will be of variable length and the
strings will not use a static length. An extra serial field will be
added.

/* This is a bit of pseudo-code, as the message itself cannot be
expressed as c-structure and mostly consists of variable length
char field. Text length is determined by zero-char. */
struct packet_new_generic_message {
  int x,y;
  int message_id; /* created by make_category */
  char numargs;
  char[numargs] argtype; /* from AT_xxx() macro */
  char[...] format string;
  depending on argtype for each arg:
    a) int data /* id or value, most often used */
    b) int id; char[...] data; /* city names, player names */
  [ c) char[...] data; /* we don't know any type requiring this! */]
};

Client
======

The client will prepare the arguments, retrieve the localized format
string and will vsnprintf it. There has to be some va_list magic.

The category will be used to decide if and where to display the
message. The ai will use the category to select a broad set of
messages or the format string to pinpoint one:

  if(is_category(msg_cat,CAT_INFO,CAT_CITY))
     handle_city_info();
  /* or */
  if(strcmp(format_str,"Your city %s grows to size %d.")==0)
     handle_city_grown();

Using the format-string should be necessary in very rare cases only
(or the category system must be redesigned).

Help with the category design is welcome (AI designers, this is your task)!

        Raimar & Dirk

-- 
 email: rf13@xxxxxxxxxxxxxxxxx
  "Heuer's Law: Any feature is a bug unless it can be turned off."