(For more resources related to this topic, see here.)

Loading XML files

I have chosen to use XML files because they are so easy to parse. We are not going to write our own XML parser, rather we will use an open source library called TinyXML. TinyXML was written by Lee Thomason and is available under the zlib license from http://sourceforge.net/projects/tinyxml/.

Once downloaded the only setup we need to do is to include a few of the files in our project:

• tinyxmlerror.cpp

• tinyxmlparser.cpp

• tinystr.cpp

• tinystr.h

• tinyxml.cpp

• tinyxml.h

Also, at the top of tinyxml.h, add this line of code:

#define TIXML_USE_STL

By doing this we ensure that we are using the STL versions of the TinyXML functions. We can now go through a little of how an XML file is structured. It’s actually fairly simple and we will only give a brief overview to help you get up to speed with how we will use it.

Basic XML structure

Here is a basic XML file:

<?xml version="1.0" ?>
<ROOT>
    <ELEMENT>
    </ELEMENT>
</ROOT>

The first line of the file defines the format of the XML file. The second line is our Root element; everything else is a child of this element. The third line is the first child of the root element. Now let’s look at a slightly more complicated XML file:

<?xml version="1.0" ?>
<ROOT>
    <ELEMENTS>
        <ELEMENT>Hello,</ELEMENT>
        <ELEMENT> World!</ELEMENT>
    </ELEMENTS>
</ROOT>

As you can see we have now added children to the first child element. You can nest as many children as you like. But without a good structure, your XML file may become very hard to read. If we were to parse the above file, here are the steps we would take:

1. Load the XML file.
2. Get the root element, <ROOT>.
3. Get the first child of the root element, <ELEMENTS>.
4. For each child, <ELEMENT> of <ELEMENTS>, get the content.
5. Close the file.

Another useful XML feature is the use of attributes. Here is an example:

<ROOT>
    <ELEMENTS>
        <ELEMENT text="Hello,"/>
        <ELEMENT text=" World!"/>
    </ELEMENTS>
</ROOT>

We have now stored the text we want in an attribute named text. When this file is parsed, we would now grab the text attribute for each element and store that instead of the content between the <ELEMENT></ELEMENT> tags. This is especially useful for us as we can use attributes to store lots of different values for our objects. So let’s look at something closer to what we will use in our game:

<?xml version="1.0" ?>
<STATES>

<!--The Menu State-->
<MENU>
<TEXTURES>
  <texture filename="button.png" ID="playbutton"/>
  <texture filename="exit.png" ID="exitbutton"/>
</TEXTURES>

<OBJECTS>
  <object type="MenuButton" x="100" y="100" width="400" 
  height="100" textureID="playbutton"/>
  <object type="MenuButton" x="100" y="300" width="400" 
  height="100" textureID="exitbutton"/>
</OBJECTS>
</MENU>

<!--The Play State-->
<PLAY>
</PLAY>

<!-- The Game Over State -->
<GAMEOVER>
</GAMEOVER>
</STATES>

This is slightly more complex. We define each state in its own element and within this element we have objects and textures with various attributes. These attributes can be loaded in to create the state.

With this knowledge of XML you can easily create your own file structures if what we cover within this book is not to your needs.

Implementing Object Factories

We are now armed with a little XML knowledge but before we move forward, we are going to take a look at Object Factories. An object factory is a class that is tasked with the creation of our objects. Essentially, we tell the factory the object we would like it to create and it goes ahead and creates a new instance of that object and then returns it. We can start by looking at a rudimentary implementation:

GameObject* GameObjectFactory::createGameObject(ID id)
{
  switch(id)
  {
    case "PLAYER":
      return new Player();
    break;
    
    case "ENEMY":
      return new Enemy();
    break;
    
    // lots more object types 
  }
}

This function is very simple. We pass in an ID for the object and the factory uses a big switch statement to look it up and return the correct object. Not a terrible solution but also not a particularly good one, as the factory will need to know about each type it needs to create and maintaining the switch statement for many different objects would be extremely tedious. We want this factory not to care about which type we ask for. It shouldn’t need to know all of the specific types we want it to create. Luckily this is something that we can definitely achieve.

Using Distributed Factories

Through the use of Distributed Factories we can make a generic object factory that will create any of our types. Distributed factories allow us to dynamically maintain the types of objects we want our factory to create, rather than hard code them into a function (like in the preceding simple example). The approach we will take is to have the factory contain std::map that maps a string (the type of our object) to a small class called Creator whose only purpose is the creation of a specific object. We will register a new type with the factory using a function that takes a string (the ID) and a Creator class and adds them to the factory’s map. We are going to start with the base class for all the Creator types. Create GameObjectFactory.h and declare this class at the top of the file.

#include <string>
#include <map>
#include "GameObject.h"

class BaseCreator
{
  public:

  virtual GameObject* createGameObject() const = 0;
  virtual ~BaseCreator() {}
};

We can now go ahead and create the rest of our factory and then go through it piece by piece.

class GameObjectFactory
{
  public:

  bool registerType(std::string typeID, BaseCreator* pCreator)
  {
    std::map<std::string, BaseCreator*>::iterator it = 
    m_creators.find(typeID);

    // if the type is already registered, do nothing
    if(it != m_creators.end())
    {
      delete pCreator;
      return false;
    }

    m_creators[typeID] = pCreator;

    return true;
  }

  GameObject* create(std::string typeID)
  {
    std::map<std::string, BaseCreator*>::iterator it = 
    m_creators.find(typeID);

    if(it == m_creators.end())
    {
      std::cout << "could not find type: " << typeID << "n";
      return NULL;
    }

    BaseCreator* pCreator = (*it).second;
    return pCreator->createGameObject();
  }

  private:

  std::map<std::string, BaseCreator*> m_creators;

};

This is quite a small class but it is actually very powerful. We will cover each part separately starting with std::map m_creators.

std::map<std::string, BaseCreator*> m_creators;

This map holds the important elements of our factory, the functions of the class essentially either add or remove from this map. This becomes apparent when we look at the registerType function:

bool registerType(std::string typeID, BaseCreator* pCreator)

This function takes the ID we want to associate the object type with (as a string), and the creator object for that class. The function then attempts to find the type using the std::mapfind function:

std::map<std::string, BaseCreator*>::iterator it = m_creators.find(typeID);

If the type is found then it is already registered. The function then deletes the passed in pointer and returns false:

if(it != m_creators.end())
{
  delete pCreator;
  return false;
}

If the type is not already registered then it can be assigned to the map and then true is returned:

m_creators[typeID] = pCreator;
return true;
}

As you can see, the registerType function is actually very simple; it is just a way to add types to the map. The create function is very similar:

GameObject* create(std::string typeID)
{
  std::map<std::string, BaseCreator*>::iterator it = 
  m_creators.find(typeID);

  if(it == m_creators.end())
  {
    std::cout << "could not find type: " << typeID << "n";
    return 0;
  }

  BaseCreator* pCreator = (*it).second;
  return pCreator->createGameObject();
}

The function looks for the type in the same way as registerType does, but this time it checks whether the type was not found (as opposed to found). If the type is not found we return 0, and if the type is found then we use the Creator object for that type to return a new instance of it as a pointer to GameObject.

It is worth noting that the GameObjectFactory class should probably be a singleton. We won’t cover how to make it a singleton in this article. Try implementing it yourself or see how it is implemented in the source code download.

Fitting the factory into the framework

With our factory now in place, we can start altering our GameObject classes to use it. Our first step is to ensure that we have a Creator class for each of our objects. Here is one for Player:

class PlayerCreator : public BaseCreator
{
  GameObject* createGameObject() const
  {
    return new Player();
  }
};

This can be added to the bottom of the Player.h file. Any object we want the factory to create must have its own Creator implementation. Another addition we must make is to move LoaderParams from the constructor to their own function called load. This stops the need for us to pass the LoaderParams object to the factory itself. We will put the load function into the GameObject base class, as we want every object to have one.

class GameObject
{
  public:

  virtual void draw()=0;
  virtual void update()=0;
  virtual void clean()=0;

  // new load function 
  virtual void load(const LoaderParams* pParams)=0;

  protected:

  GameObject() {}
  virtual ~GameObject() {}
};

Each of our derived classes will now need to implement this load function. The SDLGameObject class will now look like this:

SDLGameObject::SDLGameObject() : GameObject()
{
}

voidSDLGameObject::load(const LoaderParams *pParams)
{
  m_position = Vector2D(pParams->getX(),pParams->getY());
  m_velocity = Vector2D(0,0);
  m_acceleration = Vector2D(0,0);
  m_width = pParams->getWidth();
  m_height = pParams->getHeight();
  m_textureID = pParams->getTextureID();
  m_currentRow = 1;
  m_currentFrame = 1;
  m_numFrames = pParams->getNumFrames();
}

Our objects that derive from SDLGameObject can use this load function as well; for example, here is the Player::load function:

Player::Player() : SDLGameObject()
{

}

void Player::load(const LoaderParams *pParams)
{
  SDLGameObject::load(pParams);
}

This may seem a bit pointless but it actually saves us having to pass through LoaderParams everywhere. Without it, we would need to pass LoaderParams through the factory’s create function which would then in turn pass it through to the Creator object. We have eliminated the need for this by having a specific function that handles parsing our loading values. This will make more sense once we start parsing our states from a file.

We have another issue which needs rectifying; we have two classes with extra parameters in their constructors (MenuButton and AnimatedGraphic). Both classes take an extra parameter as well as LoaderParams. To combat this we will add these values to LoaderParams and give them default values.

LoaderParams(int x, int y, int width, int height, std::string textureID,
int numFrames, int callbackID = 0, int animSpeed = 0) :
m_x(x),
m_y(y),
m_width(width),
m_height(height),
m_textureID(textureID),
m_numFrames(numFrames),
m_callbackID(callbackID),
m_animSpeed(animSpeed)
{

}

In other words, if the parameter is not passed in, then the default values will be used (0 in both cases). Rather than passing in a function pointer as MenuButton did, we are using callbackID to decide which callback function to use within a state. We can now start using our factory and parsing our states from an XML file.

Parsing states from an XML file

The file we will be parsing is the following (test.xml in source code downloads):

<?xml version="1.0" ?>
<STATES>
<MENU>
<TEXTURES>
  <texture filename="assets/button.png" ID="playbutton"/>
  <texture filename="assets/exit.png" ID="exitbutton"/>
</TEXTURES>

<OBJECTS>
  <object type="MenuButton" x="100" y="100" width="400" 
  height="100" textureID="playbutton" numFrames="0" 
  callbackID="1"/>
  <object type="MenuButton" x="100" y="300" width="400" 
  height="100" textureID="exitbutton" numFrames="0" 
  callbackID="2"/>
</OBJECTS>
</MENU>
<PLAY>
</PLAY>

<GAMEOVER>
</GAMEOVER>
</STATES>

We are going to create a new class that parses our states for us called StateParser. The StateParser class has no data members, it is to be used once in the onEnter function of a state and then discarded when it goes out of scope. Create a StateParser.h file and add the following code:

#include <iostream>
#include <vector>
#include "tinyxml.h"

class GameObject;

class StateParser
{
  public:

  bool parseState(const char* stateFile, std::string stateID, 
  std::vector<GameObject*> *pObjects);

  private:

  void parseObjects(TiXmlElement* pStateRoot, 
  std::vector<GameObject*> *pObjects);
  void parseTextures(TiXmlElement* pStateRoot, 
  std::vector<std::string> *pTextureIDs);

};

We have three functions here, one public and two private. The parseState function takes the filename of an XML file as a parameter, along with the current stateID value and a pointer to std::vector of GameObject* for that state. The StateParser.cpp file will define this function:

bool StateParser::parseState(const char *stateFile, string 
stateID, vector<GameObject *> *pObjects, std::vector<std::string> 
*pTextureIDs)
{
  // create the XML document
  TiXmlDocument xmlDoc;

  // load the state file
  if(!xmlDoc.LoadFile(stateFile))
  {
    cerr << xmlDoc.ErrorDesc() << "n";
    return false;
  }

  // get the root element
  TiXmlElement* pRoot = xmlDoc.RootElement();

  // pre declare the states root node
  TiXmlElement* pStateRoot = 0;
  // get this states root node and assign it to pStateRoot
  for(TiXmlElement* e = pRoot->FirstChildElement(); e != NULL; e = 
  e->NextSiblingElement())
  {
    if(e->Value() == stateID)
    {
      pStateRoot = e;
    }
  }

  // pre declare the texture root
  TiXmlElement* pTextureRoot = 0;

  // get the root of the texture elements
  for(TiXmlElement* e = pStateRoot->FirstChildElement(); e != 
  NULL; e = e->NextSiblingElement())
  {
    if(e->Value() == string("TEXTURES"))
    {
      pTextureRoot = e;
    }
  }

  // now parse the textures
  parseTextures(pTextureRoot, pTextureIDs);

  // pre declare the object root node
  TiXmlElement* pObjectRoot = 0;

  // get the root node and assign it to pObjectRoot
  for(TiXmlElement* e = pStateRoot->FirstChildElement(); e != 
  NULL; e = e->NextSiblingElement())
  {
    if(e->Value() == string("OBJECTS"))
    {
      pObjectRoot = e;
    }
  }

  // now parse the objects
  parseObjects(pObjectRoot, pObjects);

  return true;
}

There is a lot of code in this function so it is worth covering in some depth. We will note the corresponding part of the XML file, along with the code we use, to obtain it. The first part of the function attempts to load the XML file that is passed into the function:

// create the XML document
TiXmlDocument xmlDoc;

// load the state file
if(!xmlDoc.LoadFile(stateFile))
{
  cerr << xmlDoc.ErrorDesc() << "n";
  return false;
}

It displays an error to let you know what happened if the XML loading fails. Next we must grab the root node of the XML file:

// get the root element
TiXmlElement* pRoot = xmlDoc.RootElement(); // <STATES>

The rest of the nodes in the file are all children of this root node. We must now get the root node of the state we are currently parsing; let’s say we are looking for MENU:

// declare the states root node
TiXmlElement* pStateRoot = 0;
// get this states root node and assign it to pStateRoot
for(TiXmlElement* e = pRoot->FirstChildElement(); 
e != NULL; e = e->NextSiblingElement())
{
  if(e->Value() == stateID)
  {
    pStateRoot = e;
  }
}

This piece of code goes through each direct child of the root node and checks if its name is the same as stateID. Once it finds the correct node it assigns it to pStateRoot. We now have the root node of the state we want to parse.

<MENU> // the states root node

Now that we have a pointer to the root node of our state we can start to grab values from it. First we want to load the textures from the file so we look for the <TEXTURE> node using the children of the pStateRoot object we found before:

// pre declare the texture root
TiXmlElement* pTextureRoot = 0;

// get the root of the texture elements
for(TiXmlElement* e = pStateRoot->FirstChildElement(); e != NULL;
e = e->NextSiblingElement())
{
  if(e->Value() == string("TEXTURES"))
  {
    pTextureRoot = e;
  }
}

Once the <TEXTURE> node is found, we can pass it into the private parseTextures function (which we will cover a little later).

parseTextures(pTextureRoot, std::vector<std::string> *pTextureIDs);

The function then moves onto searching for the <OBJECT> node and, once found, it passes it into the private parseObjects function. We also pass in the pObjects parameter:

  // pre declare the object root node
  TiXmlElement* pObjectRoot = 0;

  // get the root node and assign it to pObjectRoot
  for(TiXmlElement* e = pStateRoot->FirstChildElement();
 e != NULL; e = e->NextSiblingElement())
  {
    if(e->Value() == string("OBJECTS"))
    {
      pObjectRoot = e;
    }
  }
  parseObjects(pObjectRoot, pObjects);
  return true;
}

At this point our state has been parsed. We can now cover the two private functions, starting with parseTextures.

void StateParser::parseTextures
(TiXmlElement* pStateRoot, std::vector<std::string> *pTextureIDs)
{
  for(TiXmlElement* e = pStateRoot->FirstChildElement(); e != 
  NULL; e = e->NextSiblingElement())
  {
    string filenameAttribute = e->Attribute("filename");
    string idAttribute = e->Attribute("ID");
    pTextureIDs->push_back(idAttribute); // push into list

    TheTextureManager::Instance()->load(filenameAttribute, 
    idAttribute, TheGame::Instance()->getRenderer());
  }
}

This function gets the filename and ID attributes from each of the texture values in this part of the XML:

<TEXTURES>
  <texture filename="button.png" ID="playbutton"/>
  <texture filename="exit.png" ID="exitbutton"/>
</TEXTURES>

It then adds them to TextureManager.

TheTextureManager::Instance()->load(filenameAttribute, 
idAttribute, TheGame::Instance()->getRenderer());

The parseObjects function is quite a bit more complicated. It creates objects using our GameObjectFactory function and reads from this part of the XML file:

<OBJECTS>
  <object type="MenuButton" x="100" y="100" width="400" 
  height="100" textureID="playbutton" numFrames="0" 
  callbackID="1"/>
  <object type="MenuButton" x="100" y="300" width="400" 
  height="100" textureID="exitbutton" numFrames="0" 
  callbackID="2"/>
</OBJECTS>

The parseObjects function is defined like so:

void StateParser::parseObjects(TiXmlElement *pStateRoot, 
std::vector<GameObject *> *pObjects)
{
  for(TiXmlElement* e = pStateRoot->FirstChildElement(); e != 
  NULL; e = e->NextSiblingElement())
  {
    int x, y, width, height, numFrames, callbackID, animSpeed;
    string textureID;

    e->Attribute("x", &x);
    e->Attribute("y", &y);
    e->Attribute("width",&width);
    e->Attribute("height", &height);
    e->Attribute("numFrames", &numFrames);
    e->Attribute("callbackID", &callbackID);
    e->Attribute("animSpeed", &animSpeed);

    textureID = e->Attribute("textureID");

    GameObject* pGameObject = TheGameObjectFactory::Instance()
    ->create(e->Attribute("type"));
    pGameObject->load(new LoaderParams
    (x,y,width,height,textureID,numFrames,callbackID, animSpeed));
    pObjects->push_back(pGameObject);
  }
}

First we get any values we need from the current node. Since XML files are pure text, we cannot simply grab ints or floats from the file. TinyXML has functions with which you can pass in the value you want to be set and the attribute name. For example:

e->Attribute("x", &x);

This sets the variable x to the value contained within attribute “x”. Next comes the creation of a GameObject * class using the factory.

GameObject* pGameObject = TheGameObjectFactory::Instance()->create
(e->Attribute("type"));

We pass in the value from the type attribute and use that to create the correct object from the factory. After this we must use the load function of GameObject to set our desired values using the values loaded from the XML file.

pGameObject->load(new LoaderParams
(x,y,width,height,textureID,numFrames,callbackID));

And finally we push pGameObject into the pObjects array, which is actually a pointer to the current state’s object vector.

pObjects->push_back(pGameObject);

Loading the menu state from an XML file

We now have most of our state loading code in place and can make use of this in the MenuState class. First we must do a little legwork and set up a new way of assigning the callbacks to our MenuButton objects, since this is not something we could pass in from an XML file. The approach we will take is to give any object that wants to make use of a callback an attribute named callbackID in the XML file. Other objects do not need this value and LoaderParams will use the default value of 0. The MenuButton class will make use of this value and pull it from its LoaderParams, like so:

void MenuButton::load(const LoaderParams *pParams)
{
  SDLGameObject::load(pParams);
  m_callbackID = pParams->getCallbackID();
  m_currentFrame = MOUSE_OUT;
}

The MenuButton class will also need two other functions, one to set the callback function and another to return its callback ID:

void setCallback(void(*callback)()) { m_callback = callback;}
int getCallbackID() { return m_callbackID; }

Next we must create a function to set callbacks. Any state that uses objects with callbacks will need an implementation of this function. The most likely states to have callbacks are menu states, so we will rename our MenuState class to MainMenuState and make MenuState an abstract class that extends from GameState. The class will declare a function that sets the callbacks for any items that need it and it will also have a vector of the Callback objects as a member; this will be used within the setCallbacks function for each state.

class MenuState : public GameState
{
  protected:

  typedef void(*Callback)();
  virtual void setCallbacks(const std::vector<Callback>& callbacks) 
  = 0;

  std::vector<Callback> m_callbacks;
};

The MainMenuState class (previously MenuState) will now derive from this MenuState class.

#include "MenuState.h"
#include "GameObject.h"

class MainMenuState : public MenuState
{
  public:

  virtual void update();
  virtual void render();

  virtual bool onEnter(); 
  virtual bool onExit(); 

  virtual std::string getStateID() const { return s_menuID; }

  private:

  virtual void setCallbacks(const std::vector<Callback>& 
  callbacks);

  // call back functions for menu items
  static void s_menuToPlay();
  static void s_exitFromMenu();

  static const std::string s_menuID;

  std::vector<GameObject*> m_gameObjects;
};

Because MainMenuState now derives from MenuState, it must of course declare and define the setCallbacks function. We are now ready to use our state parsing to load the MainMenuState class. Our onEnter function will now look like this:

bool MainMenuState::onEnter()
{
  // parse the state
  StateParser stateParser;
  stateParser.parseState("test.xml", s_menuID, &m_gameObjects, 
  &m_textureIDList);

  m_callbacks.push_back(0); //pushback 0 callbackID start from 1
  m_callbacks.push_back(s_menuToPlay);
  m_callbacks.push_back(s_exitFromMenu);

  // set the callbacks for menu items
  setCallbacks(m_callbacks);

  std::cout << "entering MenuStaten";
  return true;
}

We create a state parser and then use it to parse the current state. We push any callbacks into the m_callbacks array inherited from MenuState. Now we need to define the setCallbacks function:

void MainMenuState::setCallbacks(const std::vector<Callback>& 
callbacks)
{
  // go through the game objects
  for(int i = 0; i < m_gameObjects.size(); i++)
  {
    // if they are of type MenuButton then assign a callback 
    based on the id passed in from the file
    if(dynamic_cast<MenuButton*>(m_gameObjects[i]))
    {
      MenuButton* pButton = 
      dynamic_cast<MenuButton*>(m_gameObjects[i]);
      pButton->setCallback(callbacks[pButton->getCallbackID()]);
    }
  }
}

We use dynamic_cast to check whether the object is a MenuButton type; if it is then we do the actual cast and then use the objects callbackID as the index into the callbacks vector and assign the correct function. While this method of assigning callbacks could be seen as not very extendable and could possibly be better implemented, it does have a redeeming feature; it allows us to keep our callbacks inside the state they will need to be called from. This means that we won’t need a huge header file with all of the callbacks in.

One last alteration we need is to add a list of texture IDs to each state so that we can clear all of the textures that were loaded for that state. Open up GameState.h and we will add a protected variable.

protected:
std::vector<std::string> m_textureIDList;

We will pass this into the state parser in onEnter and then we can clear any used textures in the onExit function of each state, like so:

// clear the texture manager
for(int i = 0; i < m_textureIDList.size(); i++)
{
  TheTextureManager::Instance()->
  clearFromTextureMap(m_textureIDList[i]);
}

Before we start running the game we need to register our MenuButton type with the GameObjectFactory. Open up Game.cpp and in the Game::init function we can register the type.

TheGameObjectFactory::Instance()->registerType
("MenuButton", new MenuButtonCreator());

We can now run the game and see our fully data-driven MainMenuState.