[GNE]High Level GNE API

[Jason W. <gi...@ma...>]

I'm currently designing the high-level GNE API, but I'm running into 
some tough choices, because I want to offer enough flexibility so that 
any time of game can be made in the way the author desires, but I want 
to make programming the commonalities between games as simple as 
possible, but unfortunately these two ideas are often at odds.

If I move a piece of functionality into GNE, then I am making some sort 
of assumption about the target application.  This makes programming the 
games simpler, but reduces flexibility.  Where I can I've tried to make 
some features optional, and others extendable by inheritance.

What I am stuck on right now is how to handle players in the Server 
class.  There are some choices I can follow.  Keep in mind, this entire 
high-level API is built upon the mid-level one, and therefore is 
optional, so what I did in the mid-level is keep it so that it's 
suitable for 99.999% of games, but for the high-level I want it suitable 
for the most common set of games.

The ultimate amount of flexibility comes from a system where the game 
author manages all player lists.  GNE provides a couple of utility 
functions, and a way of obtaining unique player IDs from a function it 
can then use to assign to a player.  I'm not really fond of that choice 
because handling players and player lists is pretty common to all games.

My second choice is to let GNE manage simple player objects including 
IDs, and let the game author attribute a packet type to be tied to the 
objects.  GNE will create the new players and get their player data 
packet.  This simple method will allow a good level of functionality but 
without having to worry about designing the GNE API to allow the user to 
derive their own classes.  If more than a single packet is needed to 
describe a player, the author will have to handle that functionality on 
their own.  It is intended that the player data packet contain things 
like ping time, score, etc, and the players' avatars are handled 
separately.  The disadvantage of this system is that if other 
information is needed then the author has to make a list of players 
external to GNE but mirroring the GNE list to contain the additional 
data.  Also it prevents the author from using the same class to describe 
the player from a network perspective and the player from the game's 
perspective.

I'm trying to think of a way the author can create their own classes 
that GNE will use, similar to what is done on the mid-level API with the 
Packet and ConnectionListener classes.  The big problem with this is 
trying to come up with a way to effectively allow the author to create 
their own class to extend GNE's.  Also in the current high-level design 
I am considering right now, the data about the player resides in a 
different place from where the player gets his events.  I'm trying to 
see how to resolve that issue, though.  One thing I am thinking is to 
have a custom pointer in GNE's player class to the author's specific 
player class, so that they are stored in the list together and managed 
at the same time with the same API.  The disadvantage to allowing the 
author to extend the GNE class is that the author's classes become more 
dependant on the underlying design of the GNE, and additionally the API 
will be more complicated as a result, because unlike the mid-level API 
where the author's code runs to make their listeners, the connection 
process is handled mainly in GNE code, which makes designing generic 
code more difficult.  The advantages is that there is additional 
flexibility offered through this system.

In the latter 2 systems I'm still trying to decide how to handle the 
user data.  It may be possible that when a client joins, the server does 
not like its data (ie the client has a non-unique name).  How do I 
handle this situtation generically in GNE?  I could have the client 
present its data, and then the server can either refuse the client's 
connection, or present a revised copy of the data, and finish the connect...

Any insights you can give would be helpful.  Mostly what I'm looking for 
is the kinds of games you think are common, and what are the most usual 
ways of dealing with players, and the most usual attributes.  Knowing 
that may help me decide what choices to make, and what 
limitations(assumptions) are acceptable to apply for the sake of greatly 
simplifying game author code.

Jason