Classes | Modules | Typedefs | Enumerations | Enumerator | Functions | Variables

AESOP Client Library
[AESOP Core Libraries]


This is the reference implementation of the client side of the AESOP game protocols. More...

Collaboration diagram for AESOP Client Library:

Classes

class  aesop::ClientHost
 users of the client library must supply an object that implements this interface. More...
struct  aesop::server_info_t
 information about a remote server More...
class  aesop::Client
 class that manages local client/player state with the server More...

Modules

 Host Connection Strategy
 


Don't think of host connection as a one-time setup.


 Client/Server Motion Requests
 


How do you keep the client and server in sync on object locations? Obviously, this is a deep problem, see references such as http://gafferongames.com/2009/01/25/game-networking-resources/


 Object Synchronization
 


This module helps keep the client and server in sync about the positions, orientations, and velocities of relevant objects.


Typedefs

typedef threadsafe_map
< std::string, server_info_t > 
aesop::server_map_t
 a map of servers (key is basically a hash and should not be used for anything other than as an index into this map)

Enumerations

enum  aesop::eClientState {
  aesop::eClientState_Searching = 1,
  aesop::eClientState_Connecting = 2,
  aesop::eClientState_Connected = 3,
  aesop::eClientState_Invalid = 0
}
 

current client state (NOT player state! Just overall client state)

More...

Functions

virtual void aesop::ClientHost::requestDialog (const char *guid, int playerId, const Datahash *dialog, dialog::Host *host)=0
 we have a dialog for the given player
virtual void aesop::ClientHost::destroyDialog (const char *guid, int playerId)=0
 destroy the specified dialog
virtual void aesop::ClientHost::notifyPlayerMap (int playerId, smart_ptr< MapDynamics > &dyn)=0
 the given player is in the specified map.
virtual void aesop::ClientHost::appendGameData (xdrbuf::Output *outbuf)=0
 hook for client libraries to add custom data to outbound UDP packets
virtual void aesop::ClientHost::updateAnimation (smart_ptr< PhysicsObject > &obj, const char *animationState)=0
 host is being asked to update animation state of the given object
void aesop::server_info_t::clear (void) throw ()
bool aesop::server_info_t::isValid (void) const throw ()
virtual story::Storyaesop::Client::getStory (void)=0 throw ()
 what's the story?
virtual eClientState aesop::Client::getState (void)=0 throw ()
 current client network state?
virtual bool aesop::Client::getServer (server_info_t &server)=0
 what server are we connected to? returns false if not connected yet.
virtual const server_map_t & aesop::Client::getDiscoveredServers (void)=0
 what servers have been discovered? WARNING: you may discover thousands! Be careful how you iterate.
virtual bool aesop::Client::requestConnect (const char *serverKey)=0
 caller can ask to connect to a specific server, as specified by the server key (index into server map from getDiscoveredServers() ).
virtual float aesop::Client::tick (void)=0
 Caller must call this method repeatedly! Main network message pump.
virtual bool aesop::Client::createPlayer (int playerId)=0
 Caller can request that a new player join the game.
virtual void aesop::Client::startLocalConversation (const char *guid, int playerId, smart_ptr< converse::ConversationHost > host)=0
 Components on the client can request local conversations (system option menus, etc.
virtual bool aesop::Client::isConversationUnderway (const char *guid)=0
 is this conversation already going?
virtual void aesop::Client::newGame (int playerId)=0
 player is requesting a new game TODO: move this into the game logic, it doesn't belong here
virtual void aesop::Client::requestMove (int playerId, const point3d_t &delta, const point3d_t &euler, point3d_t &newPosition)=0
 player is asking to move by the specified amount
virtual bool aesop::Client::getPlacement (int playerId, placement_t &placement)=0
 retrieve current player position and orientation
virtual smart_ptr< PhysicsObject > aesop::Client::getPlayerObject (int playerId)=0
 retrieve object for player (can be null if player is not in map)

Variables

std::string aesop::server_info_t::publicName
netlib::address_t aesop::server_info_t::address



typedef netlib::conn_id_t aesop::conn_id_t
typedef netlib::envelope_t aesop::envelope_t
typedef netlib::MessageBuffer aesop::MessageBuffer
typedef std::map< int,
smart_ptr
< client_player_record_t > > 
aesop::player_map_t
typedef std::map< std::string,
smart_ptr< Map > > 
aesop::id_map_t
typedef std::map< std::string,
smart_ptr< converse_rec_t > > 
aesop::conversation_map_t
static const int aesop::s_maxIdLength = 32
static const int aesop::s_bigNumber = 32000
static const int aesop::s_smallNumber = 2
static int aesop::s_authCountdown = 0
static const float aesop::s_maxTimeDelta = 0.1
static const float aesop::s_minTimeDelta = 1.0e-4
static const int aesop::s_udpOutSize = 824
static const float aesop::s_minStateMessageWaitTime = 0.5
static const float aesop::s_maxStateMessageWaitTime = 3.0
static const char * aesop::s_reqIdConnect = "connect"
static const char * aesop::s_reqIdAuthorize = "auth"
virtual aesop::ClientHost::~ClientHost (void) throw ()
 you cannot delete through this interface callers must ensure that the Host object lasts as long as the Client
static smart_ptr< Client > aesop::Client::create (ClientHost *host, smart_ptr< story::Story > &story, smart_ptr< Datahash > &op_params)
static const char * aesop::getServerHashKey (const server_info_t &si, char *buffer)

Detailed Description


This is the reference implementation of the client side of the AESOP game protocols.

More than a reference, it is hoped that people building their own clients can use this common library for handling client state and server communication, and focus on their own rendering and other features.


DESIGN PRINCIPLES
The client library should be agnostic of (decoupled from) all rendering and input libraries. This way, implementers of custom clients can use these components without having to link in other third-party libraries etc.

As an example, a command-line client (no graphics etc.) should be able to use the Client Library with no problems, and use it to drive all interactions with the server.

The client library does NOT maintain any story or map state. That is left to the client host. The client just manages low-level connection state, and forwards richer details on to its host.

See the Application object for an example client host.


Typedef Documentation

Definition at line 44 of file aesop-client.cpp.

typedef threadsafe_map<std::string, server_info_t> aesop::server_map_t

a map of servers (key is basically a hash and should not be used for anything other than as an index into this map)

Definition at line 159 of file aesop-client.h.

Definition at line 45 of file aesop-client.cpp.

Definition at line 46 of file aesop-client.cpp.

typedef std::map< int, smart_ptr< player_record_t > > aesop::player_map_t

Definition at line 90 of file aesop-client.cpp.

typedef std::map<std::string, smart_ptr<Map> > aesop::id_map_t

Definition at line 94 of file aesop-client.cpp.

typedef std::map<std::string, smart_ptr<converse_rec_t> > aesop::conversation_map_t

Definition at line 113 of file aesop-client.cpp.


Enumeration Type Documentation

current client state (NOT player state! Just overall client state)

Enumerator:
eClientState_Searching 

waiting for player to select server

eClientState_Connecting 

attempting to connect to selected srvr

eClientState_Connected 

successfully connected to server

eClientState_Invalid 

Definition at line 89 of file aesop-client.h.


Function Documentation

virtual void aesop::ClientHost::requestDialog ( const char *  guid,
int  playerId,
const Datahash dialog,
dialog::Host host 
) [pure virtual, inherited]

we have a dialog for the given player

virtual void aesop::ClientHost::destroyDialog ( const char *  guid,
int  playerId 
) [pure virtual, inherited]

destroy the specified dialog

virtual void aesop::ClientHost::notifyPlayerMap ( int  playerId,
smart_ptr< MapDynamics > &  dyn 
) [pure virtual, inherited]

the given player is in the specified map.

Note that the map can be null! This means the player is not in any map.

virtual void aesop::ClientHost::appendGameData ( xdrbuf::Output outbuf  )  [pure virtual, inherited]

hook for client libraries to add custom data to outbound UDP packets

virtual void aesop::ClientHost::updateAnimation ( smart_ptr< PhysicsObject > &  obj,
const char *  animationState 
) [pure virtual, inherited]

host is being asked to update animation state of the given object

aesop::ClientHost::~ClientHost ( void   )  throw () [protected, virtual, inherited]

you cannot delete through this interface callers must ensure that the Host object lasts as long as the Client

Definition at line 64 of file aesop-client.cpp.

void aesop::server_info_t::clear ( void   )  throw () [inline, inherited]

Definition at line 142 of file aesop-client.h.

bool aesop::server_info_t::isValid ( void   )  const throw () [inline, inherited]

Definition at line 146 of file aesop-client.h.

virtual story::Story* aesop::Client::getStory ( void   )  throw () [pure virtual, inherited]

what's the story?

virtual eClientState aesop::Client::getState ( void   )  throw () [pure virtual, inherited]

current client network state?

virtual bool aesop::Client::getServer ( server_info_t server  )  [pure virtual, inherited]

what server are we connected to? returns false if not connected yet.

virtual const server_map_t& aesop::Client::getDiscoveredServers ( void   )  [pure virtual, inherited]

what servers have been discovered? WARNING: you may discover thousands! Be careful how you iterate.

virtual bool aesop::Client::requestConnect ( const char *  serverKey  )  [pure virtual, inherited]

caller can ask to connect to a specific server, as specified by the server key (index into server map from getDiscoveredServers() ).

returns true if the request was successfully queued. false means that the serverKey is now invalid, or the client is already connected, or some other internal error. Remember: a successful return does not mean the client has connected! Connecting can take a long time or fail altogether, depending on the network and server. A successful return just means the client will now try to connect.

virtual float aesop::Client::tick ( void   )  [pure virtual, inherited]

Caller must call this method repeatedly! Main network message pump.

Returns seconds elapsed since last tick() call.

virtual bool aesop::Client::createPlayer ( int  playerId  )  [pure virtual, inherited]

Caller can request that a new player join the game.

Caller provides the local ID of the new player. Returns false if player cannot be created (already exists).

virtual void aesop::Client::startLocalConversation ( const char *  guid,
int  playerId,
smart_ptr< converse::ConversationHost host 
) [pure virtual, inherited]

Components on the client can request local conversations (system option menus, etc.

)

virtual bool aesop::Client::isConversationUnderway ( const char *  guid  )  [pure virtual, inherited]

is this conversation already going?

virtual void aesop::Client::newGame ( int  playerId  )  [pure virtual, inherited]

player is requesting a new game TODO: move this into the game logic, it doesn't belong here

virtual void aesop::Client::requestMove ( int  playerId,
const point3d_t delta,
const point3d_t euler,
point3d_t newPosition 
) [pure virtual, inherited]

player is asking to move by the specified amount

Parameters:
euler euler rotation
virtual bool aesop::Client::getPlacement ( int  playerId,
placement_t placement 
) [pure virtual, inherited]

retrieve current player position and orientation

virtual smart_ptr<PhysicsObject> aesop::Client::getPlayerObject ( int  playerId  )  [pure virtual, inherited]

retrieve object for player (can be null if player is not in map)

smart_ptr< Client > aesop::Client::create ( ClientHost host,
smart_ptr< story::Story > &  story,
smart_ptr< Datahash > &  op_params 
) [static, inherited]

Definition at line 1960 of file aesop-client.cpp.

static const char* aesop::getServerHashKey ( const server_info_t &  si,
char *  buffer 
) [static]

Definition at line 124 of file aesop-client.cpp.


Variable Documentation

std::string aesop::server_info_t::publicName [inherited]

Definition at line 151 of file aesop-client.h.

Definition at line 152 of file aesop-client.h.

const int aesop::s_maxIdLength = 32 [static]

Definition at line 48 of file aesop-client.cpp.

const int aesop::s_bigNumber = 32000 [static]

Definition at line 51 of file aesop-client.cpp.

const int aesop::s_smallNumber = 2 [static]

Definition at line 52 of file aesop-client.cpp.

int aesop::s_authCountdown = 0 [static]

Definition at line 54 of file aesop-client.cpp.

const float aesop::s_maxTimeDelta = 0.1 [static]

Definition at line 56 of file aesop-client.cpp.

const float aesop::s_minTimeDelta = 1.0e-4 [static]

Definition at line 57 of file aesop-client.cpp.

const int aesop::s_udpOutSize = 824 [static]

Definition at line 60 of file aesop-client.cpp.

const float aesop::s_minStateMessageWaitTime = 0.5 [static]

Definition at line 86 of file aesop-client.cpp.

const float aesop::s_maxStateMessageWaitTime = 3.0 [static]

Definition at line 87 of file aesop-client.cpp.

const char* aesop::s_reqIdConnect = "connect" [static]

Definition at line 148 of file aesop-client.cpp.

const char* aesop::s_reqIdAuthorize = "auth" [static]

Definition at line 149 of file aesop-client.cpp.