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 (IN const char *guid, IN int playerId, IN const Datahash *dialog, IN dialog::Host *host)=0
	we have a dialog for the given player
virtual void	aesop::ClientHost::destroyDialog (IN const char *guid, IN int playerId)=0
	destroy the specified dialog
virtual void	aesop::ClientHost::notifyPlayerMap (IN int playerId, IN smart_ptr< MapDynamics > &dyn)=0
	the given player is in the specified map.
virtual void	aesop::ClientHost::appendGameData (IN xdrbuf::Output *outbuf)=0
	hook for client libraries to add custom data to outbound UDP packets
virtual void	aesop::ClientHost::updateAnimation (IN smart_ptr< PhysicsObject > &obj, IN 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::Story *	aesop::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 (OUT 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 (IN 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 (IN int playerId)=0
	Caller can request that a new player join the game.
virtual void	aesop::Client::startLocalConversation (IN const char *guid, IN int playerId, IN smart_ptr< converse::ConversationHost > host)=0
	Components on the client can request local conversations (system option menus, etc.
virtual bool	aesop::Client::isConversationUnderway (IN const char *guid)=0
	is this conversation already going?
virtual void	aesop::Client::newGame (IN 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 (IN int playerId, IN const point3d_t &delta, IN const point3d_t &euler, OUT point3d_t &newPosition)=0
	player is asking to move by the specified amount
virtual bool	aesop::Client::getPlacement (IN int playerId, OUT placement_t &placement)=0
	retrieve current player position and orientation
virtual smart_ptr< PhysicsObject >	aesop::Client::getPlayerObject (IN 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 (IN ClientHost *host, IN smart_ptr< story::Story > &story, IN smart_ptr< Datahash > &op_params)
static const char *	aesop::getServerHashKey (IN const server_info_t &si, IO 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

typedef dword_t aesop::conn_id_t

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.

typedef netlib::envelope_t aesop::envelope_t

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

typedef netlib::MessageBuffer aesop::MessageBuffer

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

typedef std::map<int, smart_ptr<client_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

enum aesop::eClientState

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	(	IN const char *	guid,
		IN int	playerId,
		IN const Datahash *	dialog,
		IN dialog::Host *	host
	)			[pure virtual, inherited]

we have a dialog for the given player

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

destroy the specified dialog

virtual void aesop::ClientHost::notifyPlayerMap	(	IN int	playerId,
		IN 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

(

IN xdrbuf::Output *

outbuf

)

[pure virtual, inherited]

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

virtual void aesop::ClientHost::updateAnimation	(	IN smart_ptr< PhysicsObject > &	obj,
		IN 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

(

OUT 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

(

IN 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

(

IN 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	(	IN const char *	guid,
		IN int	playerId,
		IN 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

(

IN const char *

guid

)

[pure virtual, inherited]

is this conversation already going?

virtual void aesop::Client::newGame

(

IN 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	(	IN int	playerId,
		IN const point3d_t &	delta,
		IN const point3d_t &	euler,
		OUT point3d_t &	newPosition
	)			[pure virtual, inherited]

player is asking to move by the specified amount

Parameters:

euler

euler rotation

virtual bool aesop::Client::getPlacement	(	IN int	playerId,
		OUT placement_t &	placement
	)			[pure virtual, inherited]

retrieve current player position and orientation

virtual smart_ptr<PhysicsObject> aesop::Client::getPlayerObject

(

IN int

playerId

)

[pure virtual, inherited]

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

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

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

static const char* aesop::getServerHashKey	(	IN const server_info_t &	si,
		IO 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.

netlib::address_t aesop::server_info_t::address [inherited]

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.