(The Unofficial) PopCap Framework Developer Board
February 21, 2018, 04:24:13 AM CET *
Welcome, Guest. Please login or register.

Login with username, password and session length
  Home   Forum   Help Calendar Contact Login Register  
Pages: [1] 2 3   Go Down
Author Topic: PopCap Breakout Tutorial: Part 1  (Read 45789 times)
0 Members and 1 Guest are viewing this topic.
« on: May 28, 2007, 08:21:43 AM CEST »

Hello everyone and welcome to my PopCap game development tutorial.  My name is Donald May and I am the author of this 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.

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:

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

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 latest SDK that you can get.

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

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

PopCap 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.
« Last Edit: May 30, 2007, 08:43:14 PM CEST by vortex » Logged
« Reply #1 on: May 28, 2007, 08:22:55 AM CEST »

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.

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.

Click OK and then you will see this dialog:

Now click Application Settings and select Windows Application and check Empty Project
« Reply #2 on: May 28, 2007, 08:23:44 AM CEST »

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:

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:


#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 hInstanceHINSTANCE hPrevInstanceLPSTR lpCmdLineint 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.
GameAppanApp = 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;


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.

Now in this header file add the following code:

#ifndef __GAMEAPP_H__
#define __GAMEAPP_H__

#include "SexyAppFramework/SexyAppBase.h"

namespace Sexy

GameApp : public SexyAppBase




virtual ~GameApp();

virtual void

virtual void

virtual void



// __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.
« Reply #3 on: May 28, 2007, 08:24:22 AM CEST »

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

#include "GameApp.h"
#include "Board.h"
#include "SexyAppFramework/WidgetManager.h"
#include "SexyAppFramework/Common.h"

using namespace Sexy;

mProdName "BareBones";

mProductVersion "1.0";

mTitle StringToSexyStringFast("SexyAppFramework: " mProdName " - " mProductVersion);

mRegKey "PopCap\\SexyAppFramework\\BareBones";

mWidth 640;
mHeight 480;

mBoard NULL;

delete mBoard;

void GameApp::Init()



void GameApp::LoadingThreadProc()


void GameApp::LoadingThreadCompleted()

//Load stuff here

if (

mBoard = new Board(this);



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:

#ifndef __BOARD_H__
#define __BOARD_H__

#include "SexyAppFramework/Widget.h"

namespace Sexy


Board : public Widget





virtual ~Board();

virtual void Draw(Graphicsg);

virtual void Update();



#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:

#include "Board.h"
#include "SexyAppFramework/Graphics.h"

#include "SexyAppFramework/Color.h"

#include "SexyAppFramework/Point.h"

using namespace Sexy;

mApp theApp;


void Board::Update()
//Your update code here!

void Board::Draw(Graphicsg)
g->SetColor(Color(0,0,0)); //Set black color
g->FillRect(00mWidthmHeight); //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.

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.  

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.

Our BareBones project now depends on SexyAppBase! This adds all of the framework code into our solution and allows us to use it.
« Last Edit: May 28, 2007, 08:36:07 AM CEST by vortex » Logged
« Reply #4 on: May 28, 2007, 08:24:54 AM CEST »

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:

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

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:

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:

« Reply #5 on: May 28, 2007, 08:25:27 AM CEST »

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

Make sure your Linker tab looks like mine:

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:

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:

Testing it out!

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

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).
« Reply #6 on: May 28, 2007, 08:26:41 AM CEST »

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

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!

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.

PS: I noticed I can attach files, so I am attaching BareBones.zip. Oh and the post size/image limitation is a pain!

Part Two
Continue to Part 2
« Last Edit: May 28, 2007, 11:13:02 PM CEST by vortex » Logged
« Reply #7 on: May 28, 2007, 11:13:00 AM CEST »

Holy crap. This is awesome.
« Reply #8 on: May 30, 2007, 07:11:02 AM CEST »

well done vortex, I was toying with the idea of doing a tutorial like this on my blog but you've got so much detail here I don't think it needs doing anymore!
« Reply #9 on: May 30, 2007, 10:17:59 AM CEST »

Thank you for your praise but don't let my tutorial stop you from creating your own if you feel the need!

The way I see it is that knowledge is something that should be shared Wink.
« Reply #10 on: May 31, 2007, 04:04:47 AM CEST »

"You rock!"  If you had published the book I would have been near the front of the line when the store opened to get it.  So, will you autograph my copy of this post?  :-)

« Reply #11 on: May 31, 2007, 09:03:56 PM CEST »

I'm doing cart-wheels vortex, This is astounding! You even used the Express edition of VS, thanks a million!
« Reply #12 on: June 07, 2007, 09:30:53 PM CEST »

Adjustment to be made:

Everyone already has a copy of the right version of bass.dll

You can find it in source/demos

So all they need to do is put it in the right place.

« Reply #13 on: June 07, 2007, 10:06:22 PM CEST »

Ah good to know. I will make a note of it in the tutorial as soon as I get a chance.

Thanks Smiley.
« Reply #14 on: June 08, 2007, 09:03:09 AM CEST »

I was a little confused when you choose console app for the new project type and then changed to windows app in the application settings.  I must have missed it the first time through because I ended up getting a linker error on the main function when I ran it at the end.

Anyway I'm working with VS2003 and and ran into a few gotchas there.  In the end I found it easiest just to open up the properties for demo1 and my project side by side and copy the settings that way.  Everything is working fine now though.  

Looks to be a well written tutorial though.  I look forward to finishing it.  Also, if you'd like VS2003 version of the barebones project for the tutorial I'd be happy to provide it.
Pages: [1] 2 3   Go Up
Jump to:  

Powered by MySQL Powered by PHP Powered by SMF 1.1.19 | SMF © 2013, Simple Machines Valid XHTML 1.0! Valid CSS!
SimplePortal 2.3.3 © 2008-2010, SimplePortal