Framework.dox

Framework Documentation

Contents

Introduction

The Caffeine Framework is a cross-platform generic message routing framework designed for facilitating of AI programming. The framework at its core is a message routing system that can be used to deliver any number of messages to a particular entity or all entities attached to the system. This allows for a generic way for entities to communicate with each other.

Another core part of the framework is the cross-platform dynamic-linked library (DLL) loading functionality. This allows for the creation of DLLs that contain game rules and AI players that can be dynamically plugged into the system.

Through the use of these two core components and all of the base classes that have been created, the Caffeine Framework can accommodate nearly all turn based multi-player games, including stochastic and partially observeable games.

Cross-Platform Compatibility

The Caffeine Framework was written to be cross-platform from the beginning. All platform specific code was written in a way as to provide a generic interface to the functionality. The core cross-platform components are the DLL loading, threading, and networking classes. Each of these components was written so that it would be compatible with Microsoft Windows and Linux.

Another aspect of cross-platform compatibility is the use of typedefs for the built-in variable types. Each of the built-in variables types was typedef'ed so that they will be the same across all platforms. This way if you need an unsigned 32-bit integer you know that uint32 is what you need and you don't need to worry that it will not be a unsigned 32-bit integer on another platform.

The Caffeine Framework was written for compatibility with Microsoft Windows and Linux. Compatibility with other operating systems can be added with minimal effort to the framework.

Message Classes

Message Routing

DLL Loading

Networking

Networking in the Caffeine Framework is done through the use of the CBSock class. The CBSock class is a cross-platform buffered socket class that uses TCP/IP sockets to send data across the network. The class allows for the sending of messages derived from the CMessage class or the CMessage class itself. The buffer inside of the CMessage class is also sent across the network directly after the message, to reduce the number of derived message classes that need to be created. The messages are guaranteed to be sent in order by the TCP/IP protocol.

Game Modules

Game Modules are dynamic-linked libraries that used to facilitate in the playing of games. Game Modules are responsible for telling players whose turn it is as well as any other information they need to know to play their turn (Eg. dice rolls, cards, etc.) Game Modules are based on the CPlayer class to provide interoperability with our message routing system.

In order to ease the creation of Game Modules the CGameModule abstract base class was created. The Game Module base class handles all of the message processing and makes calls to pure virtual functions that are implemented in derived classes. It is highly suggested to use the CGameModule base class so that you don't have to recreate all of the message processing routines.

It is possible to write a Game Module just based on the CPlayer class. The Game Module would then have direct access to the message routing system for ultimate control over the game. This should only be attempted by expert users of the system.

For informatino on creating a Game Module Module for the Caffeine Framework see the Game Module Creation Tutorial

AI Modules

AI Modules are dynamic-linked libraries that are used to play games using the Caffeine Framework. AI Modules are responsible for playing moves in the game when it is there turn. AI Modules are based on the CLocalPlayer base class to provide interoperability with out message routing system.

In order to ease the creation of AI Modules the CAIModule abstract base class was created. The AI Module base class handles all of the message processing and makes calls to pure virtual functions that are implemented in derived classes. It is highly suggested to uses the CAIModule base class so that you don't have to recreate all of the message processing routines.

It is possile to write an AI Module just based on the CLocalPlayer class. The AI Module would then have direct access to the messages that are sent to it by other players and the game module. If the Game Module was written so that it did not make use of the CGameModule base class, then you will most likely also have to write the AI Module without the use of the CAIModule class. This should only be attempted by expert users of the system.

For informatino on creating a AI Module for the Caffeine Framework see the AI Module Creation Tutorial

Graphic User Interfaces

The Graphic User Interfaces for use with the Caffeine Framework were written using the Qt toolkit made by TrollTech (http://trolltech.com). Qt was chosen for its ease of use and cross-platform compatibility. It was not used originally to create the backend of the framework due to the licensing cost for compatibility with the Microsoft Windows Operating System at the time the project was started.

For information on creating a GUI for the Caffeine Framework using Qt is the Graphic User Interface Tutorial .

Tournaments

Pitfalls

One of the major pitfalls that was encountered during the creation of the Caffeine Framework was a problem with the deletion of memory. Any and all memory that is created by a DLL must be deleted by that DLL. This includes all of the Message objects and the Game and AI module objects as well. In order to overcome this hurdle, the mailbox class does not delete the memory of the messages when the messages are read. It waits until the Cleanup function is called so that the memory can be deleted from the correct object.

Another issue is the sending of complex types using the buffer of the CMessage class. A complex type is defined as an object which contains a pointer to dynamic memory in it (Eg. the CPlayerPiece class.) Thus in order to send an object of this type is must be packed into an array and then unpacked on when it is read. The deletion of this unpacked memory can cause problems, so be sure to cast the pointer as a int8* before deleting it. See the deconstructor of the CPlayerPiece for more information.