From GPWiki
Jump to: navigation, search


Hello everyone and welcome to the PopCap game development tutorial.


A while ago I promised a book on PopCap game development. However due to certain factors, this book will probably never be released or completed. I still wanted to give back to the community for helping me so much when I was a novice, and as a result I decided to write this tutorial.

My goal for this tutorial is to share with the audience the process of creating a very simple game from start to finish in the PopCap framework. Hopefully this will help people get past some of the hurdles they are facing and will inspire more development using this wonderful framework.

During the development of this tutorial I struggled with the decision of what game to create and after much thought I decided on a breakout game. Pong has been done to death and I wanted something that would show some other elements involved in game design.


This tutorial is about making the game Breakout using the PopCap game framework. I don’t assume a lot of familiarity with the PopCap framework, but I do expect the user of this tutorial to have an ok understanding of C++ and Object Oriented design concepts. There are many tutorials and books available for teaching C++ and I am not going to rehash those concepts here.

If you are familiar with C++ and OOP concepts then please read on!

My Qualifications

I have over six years C++ experience and over ten years of game development experience. I am the programmer responsible for Speedy Solitaire which was created in the PopCap framework. It is because of this experience that I feel that I am qualified to write this course.

Getting Started

There are a number of things you will need in order to start using the PopCap framework.

The first is a C++ compiler. PopCap uses Visual C++ and the latest versions no longer support Visual C++ 6.0. Luckily Visual C++ 2005 Express is free and as such that is the version we are going to be using in this tutorial.

You can download Visual C++ 2005 Express from:


The next thing that you will need is the Platform SDK. You can find detailed instructions for downloading and setting up the Platform SDK from:


Then you will need the DirectX SDK available from:


Microsoft likes changing the links for it’s software all of the time so if any of the links are dead just run a Google search and make sure to download the full DirectX SDK.

Configuring the DirectX SDK

To configure the DirectX SDK with Visual C++ 2005 Express, you must tell Visual C++ 2005 Express where to find the Lib and Include directories.

From the main menu go to Tools->Options

You will see a dialog appear that looks like this:

PopCap Tutorials Options1.jpg

Look to the left of this dialog and locate the Projects and Solutions text. Click the little box with a plus in it to expand this item and then click Visual C++ Directories

PopCap Tutorials VisualDir.jpg

The first thing you will want to do is tell the compiler where to find the include directories. Look to the top of the dialog and in the combo box that reads Show directories for choose Include files.

I am using the October 2006 SDK (mainly because I am too lazy to upgrade to the latest version) but you will want to get the August 2007 SDK as it is the most recent DirectX SDK that supports DirectX 7.

GUITutorial warn.gif Notice
As of August 2, 2008 the PopCap framework still only supports DirectX 7. A revision is underway to support DirectX 9 but we are waiting on PopCap to release it to the general public.

PopCap Tutorials IncludeDir.jpg

Create a new entry in this list and add the directory of your SDK include path. Mine is C:\Program Files\Microsoft DirectX SDK (October 2006)\Include and yours will probably be something similar.

Now repeat this process for the library files and add that directory. My library directory is C:\Program Files\Microsoft DirectX SDK (October 2006)\Lib\x86

PopCap Tutorials LibDir.jpg

Downloading the PopCap framework

Now that we hopefully have the DirectX SDK configured, we can download the PopCap SDK from:

PopCap Framework Downloads

At the time of this writing the PopCap framework is in version 1.3 and so that is the version of the PopCap framework that I am going to use for this tutorial.

Once you have the SDK downloaded, extract the folders to a directory on your computer. I chose C:\PopCap2 because it seemed like a good directory to store the files. You can call this directory anything you like.

The first thing to do is go to the \osframework\source\demos directory and open the osfd VS2005.sln solution. Try to compile and run the various demos presented in the framework.

To change the currently active project in order to try out all of the demos what you can do is right click a project such as Demo1 and from the resulting menu select Set as Startup project.

PopCap Tutorials StartupProject1.jpg

You can then run a project by hitting F5, pressing the green arrow on the toolbar, or by going to Debug->Start Debugging.

If they work then you have configured everything correctly and you are on your way! If they don’t work then refer to the troubleshooting tips at the end of this document.

PopCap Tutorials Demo1.jpg

So far we have gotten our Visual C++ 2005 Express compiler installed, installed the Platform SDK, installed the DirectX SDK, and downloaded and extracted the PopCap framework. We are now ready to begin our own project!

Creating your first PopCap project

An area that I struggled with when I started with the PopCap framework was how to create my own project. The demos were cool, but I wanted to be able to create something of my own! Well what we are going to do will involve creating a new project in Visual C++ 2005 Express of our choosing, configuring it properly, adding the SexyAppBase, and adding all of the files that we need. As this process is a lot of work, a wise idea would be to create a BareBones project that you can copy for all of your projects later on. This will save you a ton of time and allow you to experiment quickly.

Open Visual C++ 2005 Express and go to File->New Project. Select Win32 under Project types and select Win32 Console Application as the template.

Navigate to your PopCap source directory and enter BareBones as the name of your project.

PopCap Tutorials NewProj.jpg

Click OK and then you will see this dialog:

PopCap Tutorials AppWizard.jpg

Now click Application Settings and select Windows Application and check Empty Project

PopCap Tutorials AppWizard2.jpg

Click Finish and your project will be created.

Adding the source files

Now that you have a blank project we need to start adding code to it. The thing I did was I went through and basically copied Demo1 in my project but I removed all of the stuff specific to Demo1.

For the sake of this tutorial I am going to provide the exact code I am putting in each source file.

Create a new source file by going to Project->Add New Item.

You will now see the Add New Item Dialog:

PopCap Tutorials AddMain.jpg

In the dialog select C++ File and enter main as the name. When your dialog matches mine then click the Add button.

Now the file you just added will be open for editing. Copy and paste the following code into Main.cpp:

// main.cpp

  1. include "GameApp.h"

// The SexyAppFramework resides in the "Sexy" namespace. As a convenience, // you'll see in all the .cpp files "using namespace Sexy" to avoid // having to prefix everything with Sexy:: using namespace Sexy;

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpCmdLine, int nCmdShow) {

   // Make sure to set this. Some classes, like the exception handler and custom cursors
   // will need to use it.
   gHInstance = hInstance;
   // Create and initialize our game application.
   GameApp* anApp = new GameApp();
   // Starts the entire application: sets up the resource loading thread and 
   // custom cursor thread, and enters the game loop where the application
   // will remain until it is shut down. You will most likely not need to
   // override this function.

   delete anApp;
   return 0;


WinMain is the Windows API equivalent of the main function in C++ console programming. This function just creates a new instance of our GameApp class and basically starts our entire program running.

Now we will add a header file. Go to Project->Add New Item again, but this time select Header File and for the name enter GameApp.

PopCap Tutorials AddGameApp.jpg

Now in this header file add the following code:

  1. ifndef __GAMEAPP_H__
  2. define __GAMEAPP_H__

  1. include "SexyAppFramework/SexyAppBase.h"

namespace Sexy {

   class Board;

class GameApp : public SexyAppBase {

       Board*        mBoard;    

       virtual ~GameApp();
       virtual void    Init();
       virtual void    LoadingThreadProc();
       virtual void    LoadingThreadCompleted();



  1. endif // __GAMEAPP_H__

This code prototypes our GameApp class which inherits from SexyAppBase. The reason for not using SexyAppBase directly is that by making the GameApp class, we can define our own code in the various methods. If you are not familiar with the concept of inheritance then this would be a good time to stop and learn C++ as this tutorial is over your head!

The reason I removed the massive amount of commenting that is available from this same code in the demos, is that if you intend to use this code in your future projects then eventually such comments will just get in the way. The idea is to provide a clean framework from which to build your projects, so if you are looking for an explanation as to what all of these functions do then I would recommend checking out the included demos.

Now we continue on and add a new source file GameApp.cpp and add the following code to it:

  1. include "GameApp.h"
  2. include "Board.h"
  3. include "SexyAppFramework/WidgetManager.h"
  4. include "SexyAppFramework/Common.h"

using namespace Sexy;

GameApp::GameApp() {

   mProdName = "BareBones";
   mProductVersion = "1.0";
   mTitle = StringToSexyStringFast("SexyAppFramework: " + mProdName + " - " + mProductVersion);
   mRegKey = "PopCap\\SexyAppFramework\\BareBones";
   mWidth = 640;
   mHeight = 480;
   mBoard = NULL;


GameApp::~GameApp() {

   delete mBoard;


void GameApp::Init() {



void GameApp::LoadingThreadProc() {


void GameApp::LoadingThreadCompleted() {

   //Load stuff here
   if (mLoadingFailed)
   mBoard = new Board(this);
   mBoard->Resize(0, 0, mWidth, mHeight);


Here we define the GameApp class that we prototyped in the GameApp header. In the constructor we have set a number of variables for our project such as the name of the project and the width and height of the window. Later on we are going to explore these variables and alter them.

PopCap uses something called a Widget. A Widget is a self contained unit that has it’s own update, drawing, and input processing methods. These widgets are managed by something called a Widget Manager which allows us to manage multiple widgets at one time. In the GameApp destructor you see that we are removing something called the Board widget from our widget manager and in the LoadingThreadCompleted method we are creating this widget, sizing it to the window size, and adding it to our widget manager. This Board widget is where our game will take place, but later on we can add other widgets for title screens and menus.

We will now add the code for our Board widget.

Let’s create the Board.h header and add the following code to it:

  1. ifndef __BOARD_H__
  2. define __BOARD_H__
  1. include "SexyAppFramework/Widget.h"

namespace Sexy { class Graphics;

class GameApp;

class Board : public Widget {

       GameApp*    mApp;
       Board(GameApp* theApp);
       virtual ~Board();
       virtual void Draw(Graphics* g);
       virtual void Update();



  1. endif // __BOARD_H__

This code prototypes our Board class and inherits from the Widget class. This means tht our Board class is a widget and where we get the term Board Widget from. Currently our Board widget will let us override the Draw and Update methods, but later on we will expose more methods that we can define.

Now we add the Board.cpp source file and give it the following code:

  1. include "Board.h"
  2. include "SexyAppFramework/Graphics.h"
  1. include "SexyAppFramework/Color.h"
  1. include "SexyAppFramework/Point.h"

using namespace Sexy;

Board::Board(GameApp* theApp) {

   mApp = theApp;


Board::~Board() { }

void Board::Update() {

   //Your update code here!


void Board::Draw(Graphics* g) {

   g->SetColor(Color(0,0,0)); //Set black color
   g->FillRect(0, 0, mWidth, mHeight); //Fill screen with current color
   //Draw here


This code defines all of the methods for our Board widget that were prototyped in Board.h. The thing to note here is the Draw method which fills the screen with a black color. Later on we will expand both the Update and Draw methods.

The good news is that all of the code that we need for our BareBones project is now implemented, but the bad news is that we still have to configure our project! We have made progress but we still have a good ways to go so now would be a good time to save your work.

Adding SexyAppBase

The next thing we should do is add the SexyAppBase to our solution and make our project dependant on it. This is a very important step and a reason that a lot of beginners experience errors.

GUITutorial warn.gif Notice
Failure to follow this step will result in build errors. If you are experiencing a lot of errors when building your project then ensure that you have followed these steps correctly.

Right click the solution in the Solution Explorer and from the resulting menu select Add->Existing Project.

Navigate to your Source\SexyAppFramework folder and locate the SexyAppBase VS2005.vcproj file. Select this file and click Open.

PopCap Tutorials SelectSexy.jpg

Now that this project is added to our solution, right click' our Barebones project and select Project Dependencies from the resulting menu.

In the Depends on list, check SexyAppBase and click OK.

PopCap Tutorials Depends.jpg

Our BareBones project now depends on SexyAppBase! This adds all of the framework code into our solution and allows us to use it.

Configuring the properties

The final step in creating a PopCap framework project is to configure the properties. This is a very tedious task so try to follow the directions exactly.

Go to Project->BareBones properties.

You should see this dialog:

PopCap Tutorials BareBoneProps.jpg

Make sure the General tab is selected and change Use Unicode character set to Use Multi-Byte character set.

PopCap Tutorials BareBoneGen.jpg

Make sure your general properties are similar to mine.

Next locate the C\C++ entry and expand it. For the Additional Include Directories edit it so it reads ..\;..\.. and change the Program Database for Edit and Continue to Program Database

Make sure the C/C++ tab looks like mine:

PopCap Tutorials BareBoneC.jpg

Now click the Code Generation tab and change Enable Minimal Rebuild to No. Then change the Runtime Library to Multithreaded Debug

Make sure your Code Generation tab looks like mine:

PopCap Tutorials-BareCodeGen.jpg

Now click and expand the Linker entry. Change Enable Incremental Linking to No

Make sure your Linker tab looks like mine:

PopCap Tutorials Linker.jpg

Now switch to the Input entry and in Additional Dependencies change it to winmm.lib wsock32.lib gdi32.lib advapi32.lib shell32.lib

Make sure your Input tab looks like mine:

PopCap Tutorials InputTab.jpg

Next switch to the Debugging entry and change Generate Map File to Yes . change Map File Name to BareBones.map, and change Map Exports to Yes.

Make sure your Debbuging tab looks like mine:

PopCap Tutorials DebugTab.jpg

Testing it out

Now try pressing F5 to see the result of all of your hard work! If you see an error message like:

PopCap Tutorials Error.jpg

That means that you don’t have Bass.dll on your system. Either download it or in the GameApp constructor add the following code:


This will remove the need for Bass.dll and allow you to see the result of your work (although if you want sound you will need to change this later). I recommend that you build this no sound needed thing into your BareBones project so that you can build simple demos and share them with your impressed friends and family without the need to have them download Bass.dll (It has happened to me quite a few times before).

This is how your hard work should look when it is all working:

PopCap Tutorials Success.jpg

Now that you have seen just how hard it is to create a PopCap framework project, you can understand why I told you to make it once and reuse it!

Now if you wanted to add Release functionality to your projects in your BareBones project then just duplicate the Release settings for Demo1 in the Demos like I did for Debug mode in this tutorial. Just be careful as it is really easy to screw something up or miss something! Check everything to make sure the settings are the same.

For the truly lazy

For the lazy people out there, I have zipped my BareBones project which has Release mode configured and it is downloadable here:


The code should work fine but you may need to readd the SexyAppBase project as it might be relative to my computer.

Until next time

Well this concludes part one of my PopCap tutorial! I hope you enjoyed what I have written so far. In the next tutorial we are going to start using the project template that we just created! Go to Part 2

Legal stuff

I take no responsibility what so ever for any damages or liabilities from the code and/or information presented in this tutorial. This tutorial is provided AS-IS with no warranty what so ever.