Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages
GM Tutorial.dox

Game Module Creation Tutorial

Contents

Introduction

This section of the manual is dedicated to the creation of Game Modules. As a tutorial, we will build the Game module for Tic-Tac-Toe.

Game Piece & Move Structures

The first step in creating a game module is to create the classes that will be used to represents pieces and moves in the game. These classes are generally stored in a header file which is named the same as the game. For Tic-Tac-Toe, the CTicTacToePiece and CTicTacToeMove classes are contained in the TicTacToe.h header file.

Lets look at how the CTicTacToePiece and CTicTacToeMove classes are constructed.

Game Piece & Move Structures

Each game that is written for the Caffeine Framework needs to have piece and move objects. If you are using the base classes for the Game Module, AI Module, and GUI Controller, then you must have piece and move classes that are derived from CPiece and CMove. Typically these classes are put in a header file named with the same name as the game.

In our case, lets look at the TicTacToe.h header file.

#include "Piece.h"
#include "Move.h"

const CaffeineGUID TICTACTOE_GAME_GUID = CaffeineGUID(0xe3464ec3, 0x1a9f, 0x44fa, 
     0xab, 0x04, 0x62, 0xb9, 0xfa, 0xca, 0xfe, 0xaf);

const CVersion TICTACTOE_GAME_VERSION = CVersion(0,0,1);
Figure 1.1

The first thing to do is to include the CPiece and CMove header files. The next two constants are used to verify that the correct game and version are being played. The CaffeineGUID class represents a Globally Unique Identifier for the game. To generate this number, run the program uuidgen from the console on Windows and the terminal on Linux. Then, following the pattern above copy the generated number into the file. The version number can be set based on whatever versioning scheme you setup.

class CTicTacToePiece : public CPiece
{
public:
 enum TYPE { EMPTY=0, X=1, O=2 };

public:
 CTicTacToePiece();
 CTicTacToePiece(const CTicTacToePiece&);
 CTicTacToePiece(TYPE);
 ~CTicTacToePiece();

 bool operator == (const CTicTacToePiece&) const;
 bool operator == (const TYPE&) const;
 bool operator != (const CTicTacToePiece&) const;
 bool operator != (const TYPE&) const;

 void operator = (const CTicTacToePiece&);
 void operator = (const TYPE&);

 void SetType(TYPE);
 TYPE GetType() const;

private:

 TYPE m_pieceType;
};
Figure 1.2

The CTicTacToePiece class is derived from the CPiece class. Lets take a more close look at this class definition.

public:
 enum TYPE { EMPTY=0, X=1, O=2 };

public:
 CTicTacToePiece();
 CTicTacToePiece(const CTicTacToePiece&);
 CTicTacToePiece(TYPE);
 ~CTicTacToePiece();
Figure 1.3

The enumeration represents the different states that a Tic-Tac-Toe board square could hold. It is important to make sure that the enumeration is in a public section so that we can access it outside of the class. The first grouping of functions are the varying constructors and the deconstructor. It is helpful to send a little bit of time in writing the piece and move structures so that they contain easy accessor functions. For this reason, not only do we have a simple constructor, but also a copy constructor and a constructor that only takes a variable of the enumeration TYPE.

 bool operator == (const CTicTacToePiece&) const;
 bool operator == (const TYPE&) const;
 bool operator != (const CTicTacToePiece&) const;
 bool operator != (const TYPE&) const;
Figure 1.4

The next group of functions are comparison functions. Writing these functions now will save a lot of time later. It will be handy to be able to comparisons using the TYPE enumeration, so we wrote comparison functions for them as well.

 void operator = (const CTicTacToePiece&);
 void operator = (const TYPE&);

 void SetType(TYPE);
 TYPE GetType() const;
Figure 1.5

The first 3 functions are all assignment functions. The last function will return the type of this piece. Nothing special going on here.

private:
 TYPE m_pieceType;
Figure 1.6

The only member variable of the class is a variable of the enumeration TYPE, which describes the state of the piece.

The implementation of the CTicTacToePiece class is straight-forward.

inline CTicTacToePiece::CTicTacToePiece()
{
 SetSize(sizeof(*this));
 m_pieceType = EMPTY;
}

inline CTicTacToePiece::CTicTacToePiece(const CTicTacToePiece& other)
{
 SetSize(sizeof(*this));
 m_pieceType = other.m_pieceType;
}

inline CTicTacToePiece::CTicTacToePiece(CTicTacToePiece::TYPE type)
{
 SetSize(sizeof(*this));
 m_pieceType = type;
}

inline CTicTacToePiece::~CTicTacToePiece()
{
}
Figure 1.7

All of the functions of the CTicTacToePiece class are simple, so we made them inline for simplicity. The first three functions are the 3 constructors. The most important part is the call to the SetSize function. The SetSize function is used to save the size of the piece object. All of the base class for the Game Module, AI Module, and GUI Controller operate on the level of the CPiece base class. So, in order to copy the piece, they need to know the size of the object without needing to know the derived class.

The size of the object is determined by calling the sizeof operator on the dereferenced this pointer (NOTE: make sure you dereference the this pointer or the sizeof operator will return the size of a pointer and not the size of the object.) This needs to be done in each of the constructors.

Next, the m_pieceType variable is set appropriately and the deconstructor has nothing to do.

inline bool CTicTacToePiece::operator ==(const CTicTacToePiece& other) const
{
 return (m_pieceType == other.m_pieceType) ? true : false;
}

inline bool CTicTacToePiece::operator ==(const CTicTacToePiece::TYPE& other) const
{
 return (m_pieceType == other) ? true : false;
}

inline bool CTicTacToePiece::operator !=(const CTicTacToePiece& other) const
{
 return (m_pieceType != other.m_pieceType) ? true : false;
}

inline bool CTicTacToePiece::operator !=(const CTicTacToePiece::TYPE& other) const
{
 return (m_pieceType != other) ? true : false;
}
Figure 1.8

The next group of functions are the comparison operators. Since we only have a single member variable of the class, these functions become quite trivial. They are still very handy later and will make your code more readable.

inline void CTicTacToePiece::operator =(const CTicTacToePiece& other)
{
 m_pieceType = other.m_pieceType;
}

inline void CTicTacToePiece::operator =(const CTicTacToePiece::TYPE& other)
{
 m_pieceType = other;
}

inline void CTicTacToePiece::SetType(CTicTacToePiece::TYPE type)
{
 m_pieceType = type;
}
Figure 1.9

Next, are the assignment operators. Even though the SetType really isn't an assignment operator per se, since we only have one member variable it might as well be one.

Lastly, we write the get accessor function.

inline CTicTacToePiece::TYPE CTicTacToePiece::GetType() const
{
 return m_pieceType;
}
Figure 1.10

That completes the CTicTacToePiece class. Now we can move on to the move class CTicTacToeMove.

class CTicTacToeMove : public CMove
{
public:
 CTicTacToeMove();
 CTicTacToeMove(const CTicTacToeMove&);
 ~CTicTacToeMove();

 void SetLocation(uint32 x, uint32 y);
 uint32 GetX() const;
 uint32 GetY() const;

 void SetPiece(CTicTacToePiece piece);
 CTicTacToePiece GetPiece() const;

private:
 uint32          m_x;
 uint32          m_y;
 CTicTacToePiece m_piece;
};
Figure 1.11

This class doesn't need quite as many functions are the piece class. As we don't usually do move comparisons, the comparison operators are left out. We also have more variables, so the need for more constructors is decreased.

A move in Tic-Tac-Toe only consists of a location on the board and the piece in which to play. The class contains accessor functions for each of these variables.

Lets take a quick look at their implementation.

inline CTicTacToeMove::CTicTacToeMove()
{
 SetSize(sizeof(*this));
 m_x = 0;
 m_y = 0;
}

inline CTicTacToeMove::CTicTacToeMove(const CTicTacToeMove& m)
{
 SetSize(sizeof(*this));
 m_x     = m.m_x;
 m_y     = m.m_y;
 m_piece = m.m_piece;
}

inline CTicTacToeMove::~CTicTacToeMove()
{
}
Figure 1.12

Once again these functions are simple enough to be inline. You will notice that the SetSize function is also used here. It is needed for the same reason that it was needed in the piece class. Make sure to set the size of the move object in each of the constructors (NOTE: make sure you dereference the this pointer argument of the sizeof operator.) Once again the deconstructor has nothing to do.

inline void CTicTacToeMove::SetLocation(uint32 x, uint32 y)
{
 if(x >= 0 && x < 3 &&
  y >= 0 && y < 3)
 {
  m_x = x;
  m_y = y;
 }
}

inline void CTicTacToeMove::SetPiece(CTicTacToePiece piece)
{
 m_piece = piece;
}
Figure 1.13

These two functions are the set accessor functions for the class. We do a simple check in the SetLocation function to make sure the arguments are within the proper range.

The get accessor functions are even simplier.

inline uint32 CTicTacToeMove::GetX() const
{
 return m_x;
}

inline uint32 CTicTacToeMove::GetY() const
{
 return m_y;
}

inline CTicTacToePiece CTicTacToeMove::GetPiece() const
{
 return m_piece;
}
Figure 1.14

Nothing special happening here. We are now finished creating the classes we need to represent pieces and moves in Tic-Tac-Toe. We can now move on to creating the Game Module.

Game Module Base Class

The easiest and quickest way to create a Game Module is to use the CGameModule base class. The class contains much of the message processing and filtering needed for a Game Module. The CGameModule class in the GameModule.h header file contains function headers that describe the pure virtual functions that need to be implemented in each derived class.

Ex. 

// NewGame
//   
// @description Initalizes the game board and sets the m_curPiece value to
// the first player that should play.
//
// @return void
//
// @limitations NONE
//
virtual void NewGame()=0;
Figure 2.1

The NewGame function must be implemented in each of the classes derived from CGameModule. As you can see, the NewGame function needs to initialize the game board and set the value of the m_curPiece variable. The m_curPiece variable is of the CPlayerPiece type defined in the GamePackage.h header file. The rest of the required functions are described in a similar way.

Writing Your Game Module Header

Now we can start writing the Tic-Tac-Toe Game Module. The Game Module will be derived from the CGameModule base class. Below is the class definition.

#include "Caffeine.h"
#include "GameModule.h"
#include "TicTacToe.h"

class CTicTacToeGM : public CGameModule
{
 enum { MAXPLAYERS = 2 };

public:
 CTicTacToeGM();
 ~CTicTacToeGM();

 CEID GetCEID() const;
 uint32 GetMaxNumberPlayers() const;
 uint32 GetMinNumberPlayers() const;
 uint32 GetNumberPlayers() const;

protected:

 void NewGame();
 void PlayMove(const CMove* m);
 bool CheckMove(const CMove* m);
 bool CheckForWin();
 void InvalidMoveProcessing(const CMove* m);
 void UpdateCurrentPlayerPiece();
 void SetPlayerDescription();
 void AddPlayer(CDescription desc);
 void RemovePlayer(CDescription desc);
 void TimeElapsed(const CPlayerPiece* piece);

 bool CheckForPieceWin(CTicTacToePiece p) const;

private:

 struct PLAYERINFO
 {
  CEID            s_id;
  CTicTacToePiece s_piece;
 };

 PLAYERINFO m_playerList[2];
 uint32 m_uiNumPlayers;
 CTicTacToePiece m_board[3][3];
};
Figure 3.1

That is a bit of code to digest at once, so lets step through it a bit.

First off we have the included header files.

#include "Caffeine.h"
#include "GameModule.h"
#include "TicTacToe.h"
Figure 3.2

The first two files will be included in every Game Module created using the CGameModule base class. The Caffeine.h header file should be included in all of the files that are to operate with the Caffeine Framework. That header files includes many helpful definitions include cross-platform typedefs for the built-in variable types. These typedefs should be used in place of the built-in types to ensure cross-platform compatibility (Eg. use int32 instead of int and uint32 instead of unsigned int.)

The last included header file contains the move and piece structures for Tic-Tac-Toe.

class CTicTacToeGM : public CGameModule
{
 enum { MAXPLAYERS = 2 };

public:
 CTicTacToeGM();
 ~CTicTacToeGM();
Figure 3.3

This is the start of the class definition. The unnamed enumeration is used to declare the maximum number of players in the game. There is nothing else special going on here.

Next, is a set of public functions that must be implemented.

 CEID GetCEID() const;
 uint32 GetMaxNumberPlayers() const;
 uint32 GetMinNumberPlayers() const;
 uint32 GetNumberPlayers() const;
Figure 3.4

These functions are required by the base classes. The GetCEID function returns the Caffeine Entity Identifier (CEID) for this object. The CEID is a structure that contains information specific to this game and version. It is unique to every caffeine entity and each instance of that entity.

The other 3 functions are straightforward, as they return just what the function names say they do.

protected:
 void NewGame();
 void PlayMove(const CMove* m);
 bool CheckMove(const CMove* m);
 bool CheckForWin();
 void InvalidMoveProcessing(const CMove* m);
 void UpdateCurrentPlayerPiece();
 void SetPlayerDescription();
 void AddPlayer(CDescription desc);
 void RemovePlayer(CDescription desc);
 void TimeElapsed(const CPlayerPiece* piece);
Figure 3.5

These functions make up the bulk of the functionality of the Game Module. All of these functions are required by the CGameModule base class to be implemented. We will go though each of these functions in more detail in the implementation of them. For more information on what each of these functions should do, see the function headers in the GameModule.h header file.

bool CheckForPieceWin(CTicTacToePiece p) const;
Figure 3.6

The last function is specific to the CTicTacToeGM class. It is used to check for a win condition of a given piece.

Next comes the private variables of the class.

private:

 struct PLAYERINFO
 {
  CEID            s_id;
  CTicTacToePiece s_piece;
 };

 PLAYERINFO m_playerList[2];
 uint32 m_uiNumPlayers;
 CTicTacToePiece m_board[3][3];
Figure 3.7

In the private section of the class, we create a private structure that contains the CEID and piece of a player. We make an array of two of these structures. The array will hold the information of the first and second player of the game. We also have a variable to hold the current player count and an array to hold the game board. This concludes the Tic-Tac-Toe Game Module class definition.

Writing Your Game Module Implementation

Now, we get down to the real meat of the Game Module, the implementation. We will start simply with the constructor and deconstructor.

CTicTacToeGM::CTicTacToeGM()
{
 m_uiNumPlayers = 0;

 m_playerList[0].s_piece = CTicTacToePiece::EMPTY;
 m_playerList[1].s_piece = CTicTacToePiece::EMPTY;

 SetPlayerDescription();
}

CTicTacToeGM::~CTicTacToeGM()
{
}
Figure 4.1

Not much going on in these two functions. We need to initialize the number of current players to 0 and set the player pieces to empty in the player array. The SetPlayerDescription function must be called in the derived class to correctly set the friendly description and game id. Once again, nothing to do in the deconstructor.

void CTicTacToeGM::SetPlayerDescription()
{
 //Description of the TicTacToe Game Module
 m_PlayerInfo.SetAuthor("Matt Bruns");
 m_PlayerInfo.SetDesc("TicTacToe Tutorial Game Module");
 m_PlayerInfo.SetTitle("TicTacToe GM");
 m_PlayerInfo.m_PlayerID.s_playerType = PLAYER_TYPE_GAME_MODULE;
 m_PlayerInfo.m_PlayerID.s_gameID = TICTACTOE_GAME_GUID;
 m_PlayerInfo.m_PlayerID.s_randNum = CMTRand::GetRand();
 m_PlayerInfo.m_PlayerID.s_stuID = 0;
 m_PlayerInfo.m_PlayerID.s_version = TICTACTOE_GAME_VERSION;
}
Figure 4.2

This next function sets the description structure for the Game Module. The m_PlayerInfo structure is a member of one of the base classes. Make sure to set the player type to PLAYER_TYPE_GAME_MODULE and the game ID to the one in the TicTacToe.h header file that we created earilier. The rest of the information is logical enough.

We can then move on to the NewGame function.

void CTicTacToeGM::NewGame()
{
 for(int32 i=0; i<3; i++)
 {
  for(int32 j=0; j<3; j++)
  {
   m_board[i][j] = CTicTacToePiece::EMPTY;
  }
 }

 m_curPiece->SetPiece(&m_playerList[0].s_piece);
 m_curPiece->SetCEID(m_playerList[0].s_id);
}
Figure 4.3

In this function we need to initialize the game board and set the m_curPiece variable to the first person to play. The m_curPiece variable is of the CPlayerPiece type, so we need to set not only the player's piece but also their CEID. This is where that PLAYERINFO structure comes in handy. The first player of the array is designed to be the first player to play, so just use it to set the m_curPiece variable.

void CTicTacToeGM::PlayMove(const CMove* m)
{
 CTicTacToeMove* pMove = (CTicTacToeMove*)m;

 m_board[pMove->GetX()][pMove->GetY()] = pMove->GetPiece();
}
Figure 4.4

Playing a move in Tic-Tac-Toe is very easy. Just set the piece at the position on the board. No need to check for the validity of the move, as it was already checked in the base class using the CheckMove function. We just need to cast the move object to a CTicTacToeMove and then play the move.

Speaking of the CheckMove function, here it is:

bool CTicTacToeGM::CheckMove(const CMove* m)
{
 bool rv = false;
 CTicTacToeMove* pMove = (CTicTacToeMove*)m;
 uint32 x = pMove->GetX();
 uint32 y = pMove->GetY();

 if(x >= 0 && x < 3 &&
  y  >= 0 && y < 3)
 {
  if(m_board[x][y] == CTicTacToePiece::EMPTY)
  {
   rv = true;
  }
 }

 return rv;
}
Figure 4.5

To check the move we first need to cast the move as a CTicTacToeMove. Then, check that the move variables are within the proper range. Finally, make sure that the board square is empty. No need to check tha the piece is of the correct type. It is already checked in the base class.

The next function we need to create is the CheckForWin function.

bool CTicTacToeGM::CheckForWin()
{
 bool rv = false;

 if(CheckForPieceWin(CTicTacToePiece::X))
 {
  m_winningMsgLength = 50;
  m_winningMsg = new int8[m_winningMsgLength];

  strncpy(m_winningMsg, "<h2>X Wins!!!</h2>", m_winningMsgLength);

  rv = true;
 }
 else if(CheckForPieceWin(CTicTacToePiece::O))
 {
  m_winningMsgLength = 50;
  m_winningMsg = new int8[m_winningMsgLength];

  strncpy(m_winningMsg, "<h2>O Wins!!!</h2>", m_winningMsgLength);

  rv = true;
 }
 else
 {
  bool bAllFull = true;
  for(int32 i=0; i<3; i++)
  {
   for(int32 j=0; j<3; j++)
   {
    if(m_board[i][j].GetType() == CTicTacToePiece::EMPTY)
    {
     bAllFull = false;
    }
   }
  }

  if(bAllFull)
  {
   m_winningMsgLength = 50;
   m_winningMsg = new int8[m_winningMsgLength];

   strncpy(m_winningMsg, "<h2>Tie Game!!!</h2>", m_winningMsgLength);
   rv = true;
  }
 }

 return rv;
}
Figure 4.6

There are a number of ways that a Tic-Tac-Toe game can be won. To ease this calculation, the function CheckForPieceWin was written. If neither piece has won, the game could still be over. We need to check the board and see if there are any pieces still empty. If there are no pieces empty, then the game is over.

If the game is over, we need to set the variables m_winningMsgLength and m_winningMsg appropriately. This is easily and safely done with strncpy. Qt supports embedded HTML tags in their displaying of text strings, so we add the 

 <h2>
tags to jazz up the output a little.

Lets look at the CheckForPieceWin function.

bool CTicTacToeGM::CheckForPieceWin(CTicTacToePiece p) const
{
 bool rv = false;

 if(p == CTicTacToePiece::EMPTY)
  return false;

 if(m_board[0][0] == p)
 {
  if(m_board[0][1] == p && m_board[0][2] == p)
  {
   //First Column Down
   rv = true;
  }
  else if(m_board[1][0] == p && m_board[2][0] == p)
  {
   //First Row Across
   rv = true;
  }
  else if(m_board[1][1] == p && m_board[2][2] == p)
  {
   //TopLeft-BottomRight Diagonl
   rv = true;
  }
 }
 else if(m_board[0][1] == p && m_board[1][1] == p &&
  m_board[2][1] == p)
 {
  //Second Row Across
  rv = true;
 }
 else if(m_board[0][2] == p && m_board[1][2] == p &&
  m_board[2][2] == p)
 {
  //Third Row Across
  rv = true;
 }
 else if(m_board[1][0] == p && m_board[1][1] == p &&
  m_board[1][2] == p)
 {
  //Second Column Down
  rv = true;
 }
 else if(m_board[2][0] == p)
 {
  if(m_board[2][1] == p && m_board[2][2] == p)
  {
   //Third Column Down
   rv = true;
  }
  else if(m_board[1][1] == p && m_board[0][2] == p)
  {
   //BottomLeft-TopRight Diagonal
   rv = true;
  }
 }

 return rv;
}
Figure 4.7

First of all, we need to return false if the piece passed into the function was the empty piece. Next we check all the different winning possiblities for Tic-Tac-Toe (Eg. Across, Down, and Diagonal).

void CTicTacToeGM::UpdateCurrentPlayerPiece()
{
 CTicTacToePiece* p = (CTicTacToePiece*)m_curPiece->GetPiece();

 if(p)
 {
  if(p->GetType() == m_playerList[0].s_piece.GetType())
  {  
   m_curPiece->SetPiece(&m_playerList[1].s_piece);
   m_curPiece->SetCEID(m_playerList[1].s_id);
  }
  else if(p->GetType() == m_playerList[1].s_piece.GetType())
  {
   m_curPiece->SetPiece(&m_playerList[0].s_piece);
   m_curPiece->SetCEID(m_playerList[0].s_id);
  }

  delete p;
 }
}
Figure 4.8

The UpdateCurrentPlayerPiece function does exactly that. First we need to retrieve the current player piece from the m_curPiece object. Remember that the m_curPiece variable is of the CPlayerPiece type, so we need to call the function GetPiece. The GetPiece function returns a new copy of the the piece, so we must delete that memory when we are done with it. (NOTE: if the deletetion of the memory causes an error, try casting the pointer to an int8* pointer when deleting it.)

In Tic-Tac-Toe we just alternate players, so check to see which player is currently moving and set the m_curPiece variable to the other player.

The next function is called when an invalid move is made or one of the player's declares and invalid move.

void CTicTacToeGM::InvalidMoveProcessing(const CMove* m)
{
 CTicTacToeMove* pMove = (CTicTacToeMove*)m;

 CTicTacToePiece p = pMove->GetPiece();

 if(p == CTicTacToePiece::X)
 {
  m_winningMsgLength = 50;
  m_winningMsg = new int8[m_winningMsgLength];

  strncpy(m_winningMsg, "<h2>O Wins!!!</h2>", m_winningMsgLength);

  m_bGameOver = true;
 }
 else if(p == CTicTacToePiece::O)
 {
  m_winningMsgLength = 50;
  m_winningMsg = new int8[m_winningMsgLength];

  strncpy(m_winningMsg, "<h2>X Wins!!!</h2>", m_winningMsgLength);

  m_bGameOver = true;
 }
}
Figure 4.9

First, we need to get the the piece of the person who made the invalid move. Then we can declare the other person a winner by setting the variable m_bGameOver tp true and setting teh m_winningMsgLength and m_winningMsg variables appropriately.

The next two functions deal with adding and removing players from the game.

void CTicTacToeGM::AddPlayer(CDescription desc)
{
 if(m_uiNumPlayers < MAXPLAYERS)
 {
  if(m_playerList[0].s_piece == CTicTacToePiece::EMPTY)
  { 
   m_playerList[0].s_piece = CTicTacToePiece::X;
   m_playerList[0].s_id    = desc.m_PlayerID;

   AssignPlayerPiece(m_playerList[0].s_id, &m_playerList[0].s_piece);
   m_uiNumPlayers++;
  }
  else if(m_playerList[1].s_piece == CTicTacToePiece::EMPTY)
  {
   m_playerList[1].s_piece = CTicTacToePiece::O;
   m_playerList[1].s_id    = desc.m_PlayerID;

   AssignPlayerPiece(m_playerList[1].s_id, &m_playerList[1].s_piece);
   m_uiNumPlayers++;
  }
 }

 if(m_uiNumPlayers == MAXPLAYERS)
  m_bReadyToStart = true;
}

void CTicTacToeGM::RemovePlayer(CDescription desc)
{
 if(m_playerList[0].s_id == desc.m_PlayerID)
 {
  m_playerList[0].s_piece = CTicTacToePiece::EMPTY;
  m_uiNumPlayers--;
  m_bReadyToStart = false;
 }
 else if(m_playerList[1].s_id == desc.m_PlayerID)
 {
  m_playerList[1].s_piece = CTicTacToePiece::EMPTY;
  m_uiNumPlayers--;
  m_bReadyToStart = false;
 }
}
Figure 4.10

These two functions will only be called if a game is not already in progress. In the AddPlayer function we need to first check that we don't already have enough players. If we still need more players, add the player to an empty space in the player array. We then use the AssignPlayerPiece function of the Game Module base class to assign that player their piece. We also need to increment the current player count variable m_uiNumPlayers. If the there are enough players to start playing the game, then set the m_bReadyToStart variable to true.

The RemovePlayer function acts a reverse way. Check to see which slot that the player occupied in the player array. Set the piece type of that slot to empty so that we know that we can add that player. Decrement the current player count and set the m_bReadToStart variable to false, since we are no longer able to start the game.

The last function that needs to be implemented is the TimeElapsed function.

void CTicTacToeGM::TimeElapsed(const CPlayerPiece* piece)
{
 CTicTacToePiece* p = (CTicTacToePiece*)piece->GetPiece();

 if(p)
 {
  if(p->GetType() == CTicTacToePiece::X)
  {
   m_winningMsgLength = 50;
   m_winningMsg = new int8[m_winningMsgLength];

   strncpy(m_winningMsg, "<h2>O Wins!</h2>", m_winningMsgLength);

   m_bGameOver = true;
  }
  else if(p->GetType() == CTicTacToePiece::O)
  {
   m_winningMsgLength = 50;
   m_winningMsg = new int8[m_winningMsgLength];

   strncpy(m_winningMsg, "<h2>X Wins!</h2>", m_winningMsgLength);

   m_bGameOver = true;
  }

  delete p;
 }
}
Figure 4.11

The TimeElasped function is called when a player runs out of time. The argument passed into this function is of the CPlayerPiece type, so we first need to get the CTicTacToePiece object. Then check the type of the piece and declare their opponent the winner. We declare the person a winner by setting the m_bGameOver variable to true and setting the m_winningMsg and m_winningMsgLength variables appropriately.

There are two more base class functions you may need to override for your specific game. These are the RelayMove and the OnGameSpecificMessage functions.

Lets look at the RelayMove function first. 












virtual CMove* RelayMove(CEID playerID, CMove* pMove);
Figure 4.12

This function needs to be overridden when you're writing your game module for a partially observable game (i.e. a game where you cannot see all of the board all the time, such as BattleShip). This function is used to determine what parts of the move a given player can see. The first argument to the function is a CEID of the player the game module is going to next send the move to. The second argument is the move just played. This function will return a pointer to a CMove derived class which contains just the information which that player with CEID playerID is allowed to see. You do not need to worry about the deletion of this CMove pointer as the Game Module base class handles that for you. Since Tic-Tac-Toe is a game of full information we do not need to override this function. The Game Module base class's implementation of this function simply forwards the whole move to each player.

The final function you may need to override is the OnGameSpecificMessage function. 











virtual void OnGameSpecificMessage(const CGameMessage* pMsg);
Figure 4.13

Since different games have different requirements all game messages which are not handled by the Game Module base class are forwarded to this function. This allows you to create games which require more information then our simple Tic-Tac-Toe example, such as Stratego where each player must set up his or her initial board state. Lets look at a typical instance of this function in a derived class.

void CStrategoGM::OnGameSpecificMessage(const CGameMessage *pMsg)
{
 switch(pMsg->GetGameMsgType())
 {
 case GAME_INIT:
  int8* p = pMsg->GetMsgBody();
  if(p && pMsg->GetMsgBodySize() > 0)
  {
          INITBOARD* tmpBoard = (INITBOARD*)p;
   PIECECOLOR c = tmpBoard->s_color;
   if(c == RED)
   {
    m_redInitBoard = tmpBoard;
    m_uiPlayerInitCount++;
   }
   else if(c == BLUE)
   {
    m_blueInitBoard = tmpBoard;
    m_uiPlayerInitCount++;
   }
  }

  if(m_uiPlayerInitCount == 2)
  {
   // Both playes have sent their initial board setups
   // time to start the game.
   m_bGameOver = false;
   NewGame();
              PostInitMessage();
  }
  break;
 };
}
Figure 4.14

The code in Figure 4.14 was taken from a Stratego Game Module class. As stated above both players in playing Stratego need to send there initial board setups before the game can begin. This function only handles the GAME_INIT game message type which is used for sending and receiving initialization information from players and game modules. Each Stratego player sends a GAME_INIT message to the game module. Upon reciept of the GAME_INIT message the game module retrieves the inital board state from the game message using the GetMsgBody function of CMessage. In this case the message body holds an INITBOARD structure, but could hold any arbitrary struture needed for your game. The piececolor of the player sending their inital boards is the retrieved and stored apporpriatley. The m_uiPlayerInitCount variable stores how many players have sent there inital boards. As soon as this count reaches two, meaning both initial boards have been recieveds, a new game is created and PostInitMessage function of the derived class is called and the game begins. Once again this function does not need to be overridden for our Tic-Tac-Toe example.

We have not completed the creation of the CTicTacToeGM class. There is still one last thing that needs to be done in order to finish the Game Module.

Finishing the Game Module

We still need to create the entry points for the DLL. Lets take a look at how this is done in the TacTacToeGameModule.cpp file.

#include "Caffeine.h"
#include "Library.h"

#include "TicTacToeGM.h"

using namespace caffeine;

MODULE_FUNCTION_HEADER
void* Create()
{    
    return (void*)(new CTicTacToeGM());
}
Figure 5.1

The one include file that might be confusing is the Library.h header file. You may have noticed that we are not creating a header file for these functions. The prototypes for all the functions in this file are in the Library.h header file. These functions are need to allow the DLL loading class to create, destroy and get information about the module.

The MODULE_FUNCTION_HEADER macro is defined in the Library.h file and is needed so that these functions become DLL entry points. This is done as a macro because the implementations are different for different platforms.

The first function that must be created is the Create function. This function creates and object of the CTicTacToeGM type, casts it as a void pointer, and returns it.

The next function is the compliment to the Create function, the Destroy function.

MODULE_FUNCTION_HEADER
void Destroy(void* module)
{
    if(module == NULL)
    {
        return;
    }

    delete (CTicTacToeGM*) module;
}
Figure 5.2

The destroy function deletes an object of the CTicTacToeGM type. We first check that this pointer is valid, then cast it as a CTicTacToeGM before we delete the memory. This function is need because all memory created by a DLL must be deleted by that DLL. Do not try to delete the memory created by the Create function or your program will crash. You must use the Destroy function.

The last function that needs to be implemented is the GetInfo function.

MODULE_FUNCTION_HEADER
CLibraryInfo* GetInfo()
{
    CLibraryInfo* info = CLibraryInfo::GetInstance();
    
    strncpy(info->description, "Simple Board Game", sizeof(info->description));
    strncpy(info->title, "TicTacToe Game Module", sizeof(info->title));
    strncpy(info->version, "0.0.1", sizeof(info->version));
    strncpy(info->author, "Matt Bruns", sizeof(info->author));
    info->type = 0;

    return info;
}
Figure 5.3

This function sets some information about the library. Fill in the information appropriately.

You have now completed the creation of the Tic-Tac-Toe Game Module.

Copyright (c) 2005 Matt Bruns, Pat Hammond, Kevin Markussen, Travis Service, Brain Shaver

SourceForge.net Logo