AI Module Creation Tutorial

Contents

• Introduction
• AI Module Base Class
• Writing Your AI Module Header
• Writing Your AI Module Implementation

Introduction

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

AI Module Base Class

The easiest and quickest way to create an AI module is to use the CAIModule base class. The class contains much of the message processing and filtering needed for an AI module. The CAIModule class in the header file AIModule.h contains function headers describing what each of the pure virtual functions are to do.

Ex.

// NewGame
//
// @description Initalizes the game board.
//
// @return void
//
// @limitations NONE
//
virtual void NewGame()=0;

All classes that derive from CAIModule must implement the NewGame function. The function should initialize the game board and set the m_curPiece variable so that it contains the data about the first player. There are a number of pure virtual functions that are documented similarly. For more information see AIModule.h.

Writing Your AI Module Header

Let's start writing our AI module for Tic-Tac-Toe. The class will be derived from the CAIModule base class. Below is a code listing for the CTicTacToeAI class definition.

#include "Caffeine.h"
#include "AIModule.h"
#include "TicTacToe.h"

class CTicTacToeAI: public CAIModule
{
public:
 CTicTacToeAI();
 ~CTicTacToeAI();

 CEID GetCEID() const;

protected:

 void NewGame();
 void Play(const CPiece* p);
 void PlayMove(const CMove* m);
 bool CheckMove(const CMove* m);
 void SetPlayerPiece(const CPiece* p);
 void InvalidMoveProcessing(const CMove* p);
 void SetPlayerDescription();

 list<CTicTacToeMove> GenerateMoves();

private:

 CTicTacToePiece m_playerPiece;
 CTicTacToePiece m_board[3][3];
};

The first thing to do is include the needed files. In the case of an AI Module the includes will most likely be Caffeine.h, AIModule.h, and the game header file. The Caffeine.h header file contains some important structures in the Caffeine Framework as well as the cross-platform typedefs for data types. It is best to use these type instead of the built-in types to insure that they are the proper size (Eg. use int32 instead of int and uin32 instead of unsigned int.)

The class is fairly straight forward. Lets look a little more closely at the class definition.

class CTicTacToeAI: public CAIModule
{
public:
 CTicTacToeAI();
 ~CTicTacToeAI();

 CEID GetCEID() const;

Figure 1.1

Not a whole lot going on here. The function GetCEID is the only mystery. The structure CEID, which stands for Caffeine Entity Identifier, contains data unique to each individual Caffeine entity (Game modules, AI modules, GUIs) and unique to each instance of that entity. The function simply returns this structure.

protected:

 void NewGame();
 void Play(const CPiece* p);
 void PlayMove(const CMove* m);
 bool CheckMove(const CMove* m);
 void SetPlayerPiece(const CPiece* p);
 void InvalidMoveProcessing(const CMove* p);
 void SetPlayerDescription();

Figure 1.2

The next set of functions are protected functions of the class. All of these functions are pure virtual functions of the CAIModule class. They will be called by the CAIModule base class in response to messages received from the game module and other players.

  list<CTicTacToeMove> GenerateMoves();

private:

 CTicTacToePiece m_playerPiece;
 CTicTacToePiece m_board[3][3];
};

Figure 1.3

The last part of the class contains the one specific Tic-Tac-Toe function, which will be used to generate moves. The two variables are this AIs piece and the game board respectively.

The last thing that needs to be done in the header file is to write the body of the GetCEID function.

inline CEID CTicTacToeAI::GetCEID() const
{
 return m_PlayerInfo.m_PlayerID;
}

Figure 1.4

This function is simple enough to be created inline. The function needs to return the m_PlayerID variable of the m_PlayerInfo structure. This variable will be set in the CTicTacToeAI::SetPlayerDescription function.

Writing Your AI Module Implementation

On to the meat of the AI module, the implementation. Lets start with the with the simple part first.

CTicTacToeAI::CTicTacToeAI()
{
 m_curPiece = new CTicTacToePiece();
 m_curMove  = new CTicTacToeMove();

 SetPlayerDescription();
}

CTicTacToeAI::~CTicTacToeAI()
{
}

Figure 2.1

Here is the constructor and deconstructor for the class. The constructor contains the initialization of m_curPiece and m_curMove variables. These two variables are members of the CAIModule class. They are of the type CPiece and CMove which are generic base classes from which CTicTacToePiece and CTicTacToeMove are derived (See Game Piece & Move Structures for move details). The m_curPiece variable will contains the piece of the player who is currently taking their turn. The m_curMove variable will hold the current move of this AI. The SetPlayerDescritption function must be called in the constructor of your AI module class to correctly set the friendly description and game ID for your game, if this is not set properly the game module will reject your AI, because it will believe it was made for a different game.

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

Figure 2.2

The NewGame function is simple for Tic-Tac-Toe. Just initalize the 3x3 board to all empty spaces.

Next comes the fun part, the Play function.

void CTicTacToeAI::Play(const CPiece*)
{
 list<CTicTacToeMove> moveList = GenerateMoves();
 list<CTicTacToeMove>::iterator iter;
 int32 numMoves = moveList.size();
 int32 moveNumber = CMTRand::GetRand() % numMoves;

 iter = moveList.begin();
 for(int32 i=0; i<moveNumber; i++)
  iter++;
 
 CTicTacToeMove* curMove = (CTicTacToeMove*)m_curMove;

 m_board[(*iter).GetX()][(*iter).GetY()] = m_playerPiece;

 curMove->SetLocation((*iter).GetX(), (*iter).GetY());
 curMove->SetPiece(m_playerPiece);
}

Figure 2.3

In this function the AI will determine the next move it is to make and play it. For simplisity sake, we only do a random player. First, we generate all the possible moves. Then, we select and random one using the CMTRand class to generate a thread-safe random number.

The CPiece parameter to this function is used in stochastic games in order to receive the stochastic information (Eg. die roll, card hand, etc.) The function also updates the AI's board object with the move that was selected.

In order to set the value of the m_curMove variable it must first be cast as a CTicTacToeMove. Remember, we created the m_curMove variable in the constructor, but that the variable itself is of the CMove type. Once cast the appropriate variables are set.

Lets look at the move generation function.

list<CTicTacToeMove> CTicTacToeAI::GenerateMoves()
{
 list<CTicTacToeMove> moveList;
 CTicTacToeMove curMove;

 curMove.SetPiece(m_playerPiece);
 for(int32 i=0; i<3; i++)
 {
  for(int32 j=0; j<3; j++)
  {
   curMove.SetLocation(i,j);

   if(CheckMove(&curMove))
    moveList.push_back(curMove);
  }
 }

 return moveList;
}

Figure 2.4

Move generation for Tic-Tac-Toe consists of finding all the empty spaces. This is done even more simple by searching through all the board squares and checking each possible move with the CheckMove function.

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

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

Figure 2.5

The PlayMove function is only concerned with playing a particular move. The move has already been checked for validity using the CheckMove function. The only thing left to do is to place the piece on the board. First the CMove parameter must be cast to the proper type, in this case CTicTacToeMove. Then the board can be updated.

Checking the validity of a move is done using the CheckMove function

bool CTicTacToeAI::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 2.6

The CMove parameter must once again be cast into the proper type ( Are you seeing a trend here? ;-) The CTicTacToeMove class contains the piece and location of the move which are retrieved. If the location variables are within range, just check that the board space is empty. No need to worry about checking to see if the right person is making a move as it was already checked by the Game Module.

On thing that is important to know is what your piece is for this game.

void CTicTacToeAI::SetPlayerPiece(const CPiece* p)
{
 CTicTacToePiece* piece = (CTicTacToePiece*)p;

 m_playerPiece = piece->GetType();
}

Figure 2.7

The SetPlayerPiece function is called when the Game Module sends the AI Module a message with its piece information. The piece parameter is cast as a CTicTacToePiece and its value is saved to the m_playerPiece variable of this class.

The processing of invalid move messages is required by the CAIModule, but we don't need to do anything about it. Just leave its body blank, unless you want to report something to the console screen.

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

void CTicTacToeAI::SetPlayerDescription()
{
 //Description of the TicTacToe AI Module
 m_PlayerInfo.SetAuthor("Matt Bruns");
 m_PlayerInfo.SetDesc("TicTacToe Tutorial AI Module");
 m_PlayerInfo.SetTitle("TicTacToe AI");
 m_PlayerInfo.m_PlayerID.s_playerType = PLAYER_TYPE_AI;
 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.SetVersion(0,0,1);
}

Figure 2.8

This function sets the m_PlayerInfo structure of the base class. This structure is used to declare the identity of this player. The constant TICTACTOE_GAME_GUID is provided in the TicTacToe.h header file. Update the rest of the information with the correct data.

Finishing Your AI Module

The last task in creating an AI Module is to create the DLL entry point functions. These functions were implemented in the TicTacToeAIModule.cpp file.

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

#include "TicTacToeAI.h"

using namespace caffeine;

MODULE_FUNCTION_HEADER
void* Create()
{    
    return (void*)(new CTicTacToeAI());
}

Figure 2.9

The Library.h include file contains the function prototypes for the 3 functions that need to be implemented. The first function is the Create function. It is called by the DLL loading classes to create an instance of your AI. Just create a new instance of the AI class and return it cast as a void pointer.

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 next function is very similar.

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

    delete (CTicTacToeAI*) module;
}

This function will destroy the AI class object that was created with the Create function. All memory that is created by a DLL must be deleted in that DLL. This function has to be used to delete the memory created by using the Create function. First check that the paramter is valid and then delete the memory after casting the pointer.

The last function is used to set some module information.

MODULE_FUNCTION_HEADER
CLibraryInfo* GetInfo()
{
    CLibraryInfo* info = CLibraryInfo::GetInstance();
    
    strncpy(info->description, "Tic-Tac-Toe AI Module", sizeof(info->description));
    strncpy(info->title, "Tic-Tac-Toe AI 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;
}

This function is used to retrieve information about a library. Set the information accordingly.

You should now have a fully function AI Module that can be used by the Caffeine client.

---

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