High Level API Design for GNE

First Draft, August 2, 2005

Table of Contents

1. Introduction
   1. Definitions
2. Requirements
3. ChannelProvider
4. High-Level Server Design (external link)
5. ObjectBroker (external link)

Back to Main GNE Page

Introduction

There are several parts to GNE. This document will describe the high-level GNE API. First I will briefly describe the layers of a program made with GNE, as viewed from a purely network engine perspective:

1. OS Layer
2. Low-level Networking API abstraction (GNE uses HawkNL)
3. Mid-level GNE API (connections, bandwidth management, packet serialization, support APIs (Threads, Console, etc.) ).
4. High-level GNE API, as denoted by this document.
5. Application-level specific instantiation of GNE (through C++ inheritance).
6. Application-level logic code (if it is really a game, then this will be the game logic engine code).

The high-level API will deal with higher-level multiplayer concepts, and it will be built entirely as an extension on top of the mid-level GNE, and thus will be an optional part of using GNE. Because of my experience, the API will be designed to a server-client game architecture. I do not know enough about peer-to-peer (if there is even a single, dominant method to do p2p) to implement a clean enough API for it. As of this time of the first draft, I'm still working on the requirements for the high-level API and what should be included in it, so your comments are very welcome.

However, the user-code can pick and choose to use the three parts (Server/Client, ChannelProvider, and ObjectBroker) together, seperately, or not at all if some or all of the high-level API is not suitable for its game. The Server/Client and ObjectBroker APIs are suitable mostly only for a server-client type of game where the server is authoritative. The ChannelProvider should be useful for any type of game where the user-code will want to group connections to together into lists to perform actions on the whole group at a time.

Definitions

Unlike the GNE Protocol specification document, server and client are used in this document to mean more than a listener and a connector. A Server is a process, thread, or piece of code on a machine that is charge of coordinating a group of clients. A client is a process, thread, or piece of code that connects to a server. Based on these definitions, a client and server could even reside in the same program, and this may be the case on a machine acting as a client and a server -- in this case the client part of the program will "connect" to the server part of the program.

Ther term user is used in this document not to refer to the player of a game (that person is called the "player"), but instead the user is the user of GNE -- the person who codes the game using GNE. From GNE's perspective, the game author's code is the only entity using the library, thus he or she is called the user.

A Player is the intelligence driving the client's actions in the game. A player would normally be a human, as AI players would mostly likely be implemented in the game logic code on the server.

GNE tries to be as transparent as possible to the client/server architecture style (for example, the server may need not serve as an authoritative role in the game logic).

Back To Top

Requirements / Introduction to Problem

In the server-client model, there will be a single well-known server, and a group of 0 or more clients. If the server is not well-known, the user-code is responsible for discovering the server. After the completion of the high-level API and resources (namely, programming time) permit, work will begin on a generic game meta-server a user could deploy to provide a simple match-making service for their game.

The server may be responsible for some the following list of common game server tasks:

1. Listening for, and gathering a number of clients between some minimum and maximum number for a game to begin (it must make sure that no more than n clients make it into the game, by using a "gate").
2. Depending on game parameters, the server may need to accomodate for players entering and leaving during game play (and still enforce the maximum players exactly).
3. Providing time synchronization for the clients, to try to bring all clients to a common clock.
4. Providing one or more "channels" of communication to relay packets such as object replications or text communications between players.
5. Relaying and/or processing game data packets between the clients -- the ChannelProvider.
6. If the game server is authoritative in the game play, it may send unsolicited update packets to a player, using a unicast functionality.

Back To Top

ChannelProvider

GNE's high-level API has three main parts that address the problems encountered by a networked game: The ChannelProvider, the ObjectBroker, and the Server/Client API. The ChannelProvider is arguably the simplest of the three parts, and is tied the closest to the mid-level API.

The ChannelProvider allows the user-code to create groups of Connections to which they can send ChannelPackets. The ChannelPackets In its stand-alone form, the ChannelProvider simply provides broadcast capabilities to a set of Connections.

The ChannelProvider becomes most useful when combined with the Server/Client API (which also uses the ObjectBroker). In this case, the Server maintains a list of clients, and can route broadcast packets automatically inside of the GNE code, so for example the user-code on the server can specify 3 channels, one channel for each of two opposing teams, and a channel containing all of the players. Once the channels can been specified, GNE will handle the routing of packets between players on the channels, so a good use for this would be to create channels meant for sending ChatPackets, so when each player sends out a packet to their team's channel, GNE will route the packets so all of that player's teammates will see the message. Additionally, the server can use the channels to easily replicate objects to all players or to groups of players, since the ObjectBroker is also integrated with the Server/Client API.

Back To Top