Geisha Studios

Each level needs two values: the total number of balls on the screen and the number of balls to remove. This is stored in a structure.

            
<<level structure>>=
struct Level
{
    unsigned int balls;
    unsigned int target;
};

          

Both the total number of balls and the target must be positive; it makes no sense to have less than zero balls.

Balls! has only 10 levels, for simplicity’s sake, stored in an array which I initialize with the balls and target values.

            
<<levels definition>>=
Level levels[] =
{
    // balls, target.
    { 4,  1},
    { 4,  2},
    { 8,  4},
    {15,  7},
    {25, 12},
    {30, 17},
    {30, 20},
    {30, 25},
    {30, 28},
    {30, 30}
};

          

Then, instead of hard coding the number of levels in the array, I divide the array’s size with the size of a single level to get the total number of levels. This has the advantage that to add a new level I only need to add it to the array without worrying about updating the number of levels available.

            
<<levels definition>>=
const unsigned int numLevels = sizeof(levels) / sizeof(Level);

          

Of course, the first level is 0.

            
<<levels definition>>=
unsigned int currentLevel = 0;

          

To initialize a level I create a new vector with as many balls as specified by the current level index in the array. Each ball has the same radius, but random position and color.

            
<<constants>>=
const unsigned int BALLS_RADIUS = 4;

          

            
<<initialize level>>=
std::vector<Ball> balls;
for (size_t ball = 0 ; ball < levels[currentLevel].balls ; ++ball) {
    balls.push_back(
        Ball(
            rand() % SCREEN_WIDTH,
            rand() % SCREEN_HEIGHT,
            BALLS_RADIUS, colors[rand() % colors.size()]
            )
        );
}

          

To be able to use vector I have to include its header file.

            
<<headers>>=
#include <vector>

          

The colors that can be assigned to the balls are converted from their red, green, and blue components using the screen’s surface format and are kept in a vector. With this, I can select a random color by choosing a random index for that vector.

            
<<map level colors>>=
std::vector<Uint32> colors;
colors.push_back(SDL_MapRGB(screen->format, 255,   0,   0)); // red
colors.push_back(SDL_MapRGB(screen->format,   0, 255,   0)); // lime
colors.push_back(SDL_MapRGB(screen->format,   0,   0, 255)); // blue
colors.push_back(SDL_MapRGB(screen->format,   0, 255, 255)); // aqua
colors.push_back(SDL_MapRGB(screen->format, 255, 255,   0)); // yellow
colors.push_back(SDL_MapRGB(screen->format, 255,   0, 255)); // fuchsia

          

With this approach I avoid having balls with colors that are too similar to the background color or are too similar to each other. Fortunately, in Balls! the color doesn’t have any impact on the game play.

Before I can use the random function, though, I need to set a seed value for the random generator. In this case, using the time in which the game started is good enough.

            
<<initialize random number generator>>=
srand(std::time(NULL));

          

I need to include the cstdlib header for srand and ctime for time.

            
<<headers>>=
#include <cstdlib>
#include <ctime>

          

In contrast to the balls, there are no explosions when the level starts. It is the player’s duty to add a new explosion when she sees fit and start that chain of explosions from the removed balls. Thus, I create a new vector of explosions, but I don’t add any until later.

            
<<initialize level>>=
std::vector<Explosion> explosions;

          

Besides balls and explosions, there are still two flags that the level must keep track of: one to know whether the level starter and another to know if the player already placed the first explosion on the screen.

The first flag is used to show a screen and wait for the player to click on the screen before the level starts. This is specially useful between levels, because otherwise the level would start right away after the previous level is cleared or when the player fails to meet the required target of balls to remove, in which case the message shown is slightly altered to tell the player to try again. This variable, thus, must be initialized to false.

            
<<initialize level>>=
bool levelStarted = false;

          

And is only set to true when the player clicks on the screen with the mouse.

            
<<process event types>>=
case SDL_MOUSEBUTTONDOWN:
    if (!levelStarted) {
        levelStarted = true;
    }

          

The other flag, to know whether the user placed the first explosion, is used to limit the number of explosions that the player can blow off. It is first set to the false.

            
<<initialize level>>=
bool firstExplosion = false;

          

Then, when the player clicks with the mouse button and the level has already started, this variable is set to true and a new explosion is added to the vector. If the player tries to click again, the game won’t add another explosion to the vector until this flag is set to false again, which only happens when the next level starts or the player is forced to repeat the same level.

The explosion added to the vector when the player click the mouse button is set to the cursor’s position, starting from a radius of 1 pixel and has a random color, like the balls.

            
<<process event types>>=
    else if (!firstExplosion) {
        explosions.push_back(Explosion(Vector2D(event.button.x, event.button.y), 1, colors[rand() % colors.size()]));
        firstExplosion = true;
    }
    break;

          

A ball has four attributes:

The first two attributes, radius and color, are scalar values with the radius in pixels and the color as returned by SDL_MapRGB. On the other hand, position and direction are both 2D vectors. The direction attribute is used to update the ball’s position when appropriate.

Thus, I need a 2D vector structure to hold the two coordinates, x and y, and a constructor to set the initial values of these coordinates. It would be possible to use std:pair instead, but the disadvantage of std:pair is that its two members are named first and second instead of the more familiar x and y for 2D vectors. To avoid confusion, I prefer to use a separate structure, which in this case doesn’t need to be a template because I know that I only need integer 2D vectors.

            
<<2d vector struct>>=
struct Vector2D
{
    int x;
    int y;

    Vector2D(int x, int y):
        x(x),
        y(y)
    {
    }
};

          

With this new structure is now possible to define a new Ball class with the required attributes.

            
<<Ball class>>=
class Ball
{
    public:
        <<Ball constructor>>

        <<Ball draw>>

        <<Ball update>>

        Uint32 color() const
        {
            return color_;
        }

        Vector2D position() const
        {
            return position_;
        }

        unsigned int radius() const
        {
            return radius_;
        }

    private:
        Uint32 color_;
        Vector2D direction_;
        Vector2D position_;
        unsigned int radius_;
};

          

All the ball’s initial attributes are passed as parameters to the constructor except for the direction, which is always initialized to move the ball upwards and to the left, although it would be possible to move in a random direction, for instance; it doesn’t alter the game play at all.

            
<<Ball constructor>>=
Ball(int x, int y, unsigned int radius, Uint32 color):
    color_(color),
    direction_(-1, -1),
    position_(x, y),
    radius_(radius)
{
}

          

Once set, the radius and color never change within the lifespan of a Ball object, but each time the ball is updated, its position and possibly its direction changes. The position always changes according to the direction, but the direction only changes when the ball bounces on the level’s limits. The level’s limits are are passed as parameter to the update function because the ball doesn’t have to know anything else about the level and thus avoid coupling these two objects too much.

            
<<Ball update>>=
void
update(int minX, int minY, int maxX, int maxY)
{
    position_.x += direction_.x;
    if (position_.x <= minX) {
        direction_.x = 1;
    } else if (position_.x >= maxX) {
        direction_.x = -1;
    }

    position_.y += direction_.y;
    if (position_.y <= minY) {
        direction_.y = 1;
    } else if (position_.y >= maxY) {
        direction_.y = -1;
    }
}

          

To update all the all the position of the balls in the level, thus, I to iterate the vector of balls and call their update function passing the screen’s resolution as upper limits and 0 as the lower limits, because the level uses all the screen.

            
<<update balls>>=
for(std::vector<Ball>::iterator ball = balls.begin() ;
    ball != balls.end () ; ++ball) {
    ball->update(0, 0, SCREEN_WIDTH, SCREEN_HEIGHT);
}

          

To draw a ball on the screen I have to draw a filled circle of the specified radius, with the given color, and at the current ball’s position. The surface on which to draw the ball is also passed as a parameters, because we could be drawing on a screen, on a back buffer surface, etc.

            
<<Ball draw>>=
void
draw(SDL_Surface *destination)
{
    SDL_FillCircle(destination, position_.x, position_.y, radius_, color_);
}

          

Much like updating, to draw all the balls on the screen, I iterate all the balls in the level’s vector and call the draw function. In the case of draw, though, given that I only to pass a single parameter to the function, I can use the standard for_each to iterate the all the elements in the vector and the bind2nd structure to bind the screen surface to the draw second parameter, the first being the object itself. I also need to use mem_fun_ref to call a member function of an object reference.

            
<<draw balls>>=
std::for_each(balls.begin(), balls.end(), bind2nd(std::mem_fun_ref(&Ball::draw), screen));

          

The for_each, bind2nd, and mem_fun_ref helpers are declared in the standard algorithm header that I need to include.

            
<<headers>>=
#include <algorithm>

          

An explosion also needs four attributes:

Three of the attributes are the same as the attributes for balls — color, position, and radius — but instead of moving around the screen, the explosions grows their radius up to a maximum and then shrink until the radius is zero. Whether the radius grows or shrinks is kept in the radius growth attribute, which is the number of pixels to grow or shrink the radius each update. Thus this value is a signed scalar.

            
<<Explosion class>>=
class Explosion
{
    public:
        <<Explosion constructor>>

        <<Explosion draw>>

        <<Explosion update>>

        Vector2D position() const
        {
            return position_;
        }

        unsigned int radius() const
        {
            return radius_;
        }

    private:
        Uint32 color_;
        Vector2D position_;
        unsigned int radius_;
        int radiusGrowth_;
};

          

The color and position are fixed through all the explosion’s lifetime and passed as parameters to the constructor. The initial explosion radius is also passed as parameter, because it is different if the explosion is started by the player (the initial radius is zero) or if it is due a ball exploding (the initial radius is the same as the ball’s radius.) In both cases, though, the explosion is growing and thus the growth rate is 1 pixel positive.

            
<<Explosion constructor>>=
Explosion(const Vector2D &position, unsigned int radius, Uint32 color):
    color_(color),
    position_(position),
    radius_(radius),
    radiusGrowth_(1)
{

          

As stated, when an explosion is updated it grows or shrinks depending on the sign of radiusGrowth_: if positive it grows, otherwise it shrinks. The explosion grows until it reaches a maximum radius, which passed as a parameter of update. Once it reaches this maximum radius, it then shrinks the radius until reaching 0, in which case the explosion is no longer active.

For that motive, I can’t allow the Explosion class to have an initial radius of zero, otherwise it wouldn’t grow at all. Passing a radius non-zero radius to the constructor is a caller’s responsibility and I only enforce this condition using an assert. I could also use an exception, but I don’t want to keep the condition for release build, where assert does nothing.

            
<<Explosion constructor>>=
    assert(radius > 0 && "The explosion radius can't be 0.");
}

          

The assert macro is defined in the standard cassert header file.

            
<<headers>>=
#include <cassert>

          

To update an explosion then I increment the radius as many units as specified by the radiusGrowth_ if that radius is not zero already. The maximum radius that the explosion can grow to is passed as parameter.

            
<<Explosion update>>=
void
update(unsigned int maximumRadius)
{
    if (radius_ > 0) {
        radius_ += radiusGrowth_;
        if (radius_ >= maximumRadius) {
            radiusGrowth_ = -1;
        }
    }
}

          

For Balls! I’ve decided to use the same maximum radius for all the explosions. Thus, I need to define a maximum explosion radius as a constant.

            
<<constants>>=
const unsigned int EXPLOSION_MAXIMUM_RADIUS = 30;

          

Them, I use this constant to update all the explosions inside the level’s explosions vector. If any of the explosions reaches a radius of zero, then this explosion gets removed from the vector.

            
<<update explosions>>=
for(std::vector<Explosion>::iterator explosion = explosions.begin() ;
    explosion != explosions.end() ; ) {
    explosion->update(EXPLOSION_MAXIMUM_RADIUS);
    if (explosion->radius() > 0) {
        <<check collision between explosion and balls>>
        ++explosion;
    } else {
        explosion = explosions.erase(explosion);
    }
}

          

If after updating an explosion its radius still isn’t zero, then I need to check if it collides with any of the balls bouncing on the screen. If any ball enters in contact with then explosion, I replace the ball with an explosion by adding a new explosion to the explosions vector and removing the ball balls. Unfortunately, I can’t just push_back the new explosion into the vector because if the vector needs to allocate more memory to accommodate the new element, then the iterator gets invalidated. To avoid these allocations, when starting the level I am going to reserve as many explosions as balls there are in the level, plus the explosion triggered by the user, because as the player can only start a single explosion there can’t be any other explosion. Keep in mind that this doesn’t create the Explosion objects, just reserve enough memory to hold at least as many Explosion objects as told.

            
<<initialize level>>=
explosions.reserve(levels[currentLevel].balls);

          

Without the possibility of allocations, now I can push the new explosion if a ball and explosion collides, remembering to remove the ball from the vector. The explosion’s position, color, and initial radius are the same as the ball’s.

            
<<check collision between explosion and balls>>=
for (std::vector<Ball>::iterator ball = balls.begin () ;
    ball != balls.end () ; )
{
    if (collides(*explosion, *ball)) {
        explosions.push_back(Explosion(ball->position(), ball->radius(), ball->color()));
        ball = balls.erase(ball);
    } else {
        ++ball;
    }
}

          

The collision function uses the fact that both the explosion and the ball are circles. Thus, if the distance between the centers of the two circles is less than the sum of their radius, the two are colliding. The distance between the two centers can be computed using the Pythagorean theorem, but instead of retrieving the actual distance, I am going to get the squared distance, to avoid a square root.

            
<<collision function between explosion and ball>>=
bool collides(const Explosion &explosion, const Ball &ball)
{
    unsigned int distanceSquared =
        (explosion.radius() + ball.radius()) * (explosion.radius() + ball.radius());
    return
        ((ball.position().x - explosion.position().x) * (ball.position().x - explosion.position().x) +
        (ball.position().y - explosion.position().y) * (ball.position().y - explosion.position().y)) < distanceSquared;
}

          

Finally, much like balls, to draw explosion I need to draw a filled circle at the explosion’s position, using its current radius, and with the specified color.

            
<<Explosion draw>>=
void
draw(SDL_Surface *destination)
{
    SDL_FillCircle(destination, position_.x, position_.y, radius_, color_);
}

          

Again, to draw all the explosion in the level, I am going to use for_each but the explosions are drawn in reverse order, so newer explosions are drawn under older. This is because explosions are drawn after the balls and thus appear the be on top of them. When an explosion is fired, then, it also must come from under the already existent explosions. Drawing from the beginning to the end of the vector would, then, draw the explosions backwards of what is expected.

            
<<draw explosions>>=
std::for_each(explosions.rbegin(), explosions.rend(), bind2nd(std::mem_fun_ref(&Explosion::draw), screen));

          

The game loop for Balls! is fairly typical: receive events, update entities, draw entities, update screen, limit the frame rate. This all must occur while the level is running which, which in this game means until the player placed the first explosion and all the subsequent explosion have faded off; i.e., the vector of explosions is empty again.

            
<<game loop>>=
while (!quit && (!firstExplosion || !explosions.empty())) {
    <<process events>>
    <<clear screen>>
    if (levelStarted) {
        <<update balls>>
        <<update explosions>>
        <<draw balls>>
        <<draw explosions>>
        <<draw exploded balls and target>>
    } else {
        <<draw start level screen>>
    }
    <<refresh screen>>
    <<control frame time>>
}
<<check for next level>>

          

Notice how, as I said in the section called “Levels”, if the level hasn’t started yet I do not update the balls nor the explosions and instead I show a screen that prompts the player to click a mouse button to start the level.

Also, when the level is finished, I need to check whether the player can go to the next level by checking if she has reached the target number of balls to remove.

              
<<control frame time>>=
SDL_Delay(50);

            

              
<<process event types>>=
case SDL_QUIT:
    quit = true;
    break;

            

              
<<process event types>>=
case SDL_KEYDOWN:
    if (SDLK_ESCAPE == event.key.keysym.sym) {
        quit = true;
    }
    break;

            

              
<<clear screen>>=
// The NULL rect is to fill the whole surface.
SDL_FillRect(screen, NULL, background);

            

              
<<map background color>>=
// 42 is always the answer.
SDL_Color backgroundColor = {42, 84, 126};
Uint32 background = SDL_MapRGB(screen->format, backgroundColor.r, backgroundColor.g, backgroundColor.b);

            

              
<<draw exploded balls and target>>=
unsigned int explodedBalls = levels[currentLevel].balls - balls.size();

            

              
<<draw exploded balls and target>>=
std::ostringstream levelBalls;
levelBalls << explodedBalls << "/" << levels[currentLevel].target;
draw_right_string(font, levelBalls.str(), SCREEN_WIDTH - 10, SCREEN_HEIGHT - 20,
    fontColor, backgroundColor, screen);

            

              
<<headers>>=
#include <sstream>

            

              
<<check for next level>>=
nextLevel = levels[currentLevel].balls - balls.size() >= levels[currentLevel].target;
if (nextLevel) {
    ++currentLevel;
}

            

              
<<initialize variables>>=
bool nextLevel = true;

            

              
<<check for next level>>=
finished = currentLevel >= numLevels;
if (finished) {
    quit = true;
}

            

              
<<initialize variables>>=
bool finished = false;

            

              
<<draw start level screen>>=
std::string startLevelText;
if (nextLevel) {
    startLevelText = "Click to Start Next Level";
} else {
    startLevelText = "Oops! Try Again";
}

draw_centered_string(font, startLevelText, SCREEN_WIDTH / 2,
    SCREEN_HEIGHT / 2, fontColor, backgroundColor, screen);

            

              
<<draw finished text>>=
<<clear screen>>
draw_centered_string(font, "All Levels Finished. Well Done!", SCREEN_WIDTH / 2,
    SCREEN_HEIGHT / 2, fontColor, backgroundColor, screen);
<<refresh screen>>

            

              
<<wait for exit event>>=
quit = false;
while (!quit) {
    SDL_Event event;
    SDL_WaitEvent(&event);
    quit = SDL_QUIT == event.type ||
           SDL_MOUSEBUTTONDOWN == event.type ||
           (SDL_KEYDOWN == event.type && SDLK_ESCAPE ==
               event.key.keysym.sym);
}

            

To use any function from SDL I first need to include its header. The actual directory in which the header is located at is passed to the compiler by the build system, thus including the SDL.h file (in caps, UNIX systems are case sensitive) is enough.

            
<<headers>>=
#include <SDL.h>

          

              
<<initialize SDL>>=
if (SDL_Init(SDL_INIT_TIMER | SDL_INIT_VIDEO) < 0) {
    throw sdl_error();
}

            

              
<<sdl_error class definition>>=
class sdl_error: public std::runtime_error
{
    public:
        sdl_error():
            std::runtime_error(SDL_GetError())
        {
        }
};

            

              
<<headers>>=
#include <stdexcept>

            

              
<<initialize SDL>>=
atexit(SDL_Quit);

            

              
<<constants>>=
const size_t SCREEN_HEIGHT = 320;
const size_t SCREEN_WIDTH = 480;

            

              
<<constants>>=
const size_t SCREEN_BPP = 0;

            

              
<<initialize screen>>=
SDL_Surface *screen = SDL_SetVideoMode(SCREEN_WIDTH, SCREEN_HEIGHT, SCREEN_BPP, SDL_SWSURFACE);
if (NULL == screen) {
    throw sdl_error();
}

            

              
<<refresh screen>>=
SDL_Flip(screen);

            

              
<<initialize SDL>>=
SDL_WM_SetCaption("Balls!", "Balls!");

            

              
<<process events>>=
SDL_Event event;
while (SDL_PollEvent(&event)) {
    switch (event.type) {
        <<process event types>>
    }
}

            

              
<<headers>>=
#include <SDL_ttf.h>

            

              
<<initialize SDL_ttf>>=
if (TTF_Init() < 0) {
    throw sdl_error();
}

            

              
<<initialize SDL_ttf>>=
atexit(TTF_Quit);

            

              
<<load font>>=
TTF_Font *font = TTF_OpenFont("VeraMono.ttf", 16);
if (NULL == font) {
    throw sdl_error();
}

            

              
<<draw centered string function>>=
void
draw_centered_string(TTF_Font *font, const std::string &text, int x, int y,
    const SDL_Color &foregroundColor, const SDL_Color &backgroundColor,
    SDL_Surface *destination)
{
    assert(NULL != font && "The font is NULL.");
    assert(NULL != destination && "The destination surface is NULL.");

    SDL_Surface *textSurface = TTF_RenderText_Shaded(font, text.c_str(),
        foregroundColor, backgroundColor);
    if (NULL == textSurface) {
        throw sdl_error();
    }

    // Center the surface to the given position.
    SDL_Rect pos;
    pos.x = x - textSurface->w / 2;
    pos.y = y - textSurface->h / 2;
    pos.w = 0;
    pos.h = 0;

    SDL_BlitSurface(textSurface, NULL, destination, &pos);

    SDL_FreeSurface(textSurface);
}

            

              
<<draw right string function>>=
void
draw_right_string(TTF_Font *font, const std::string &text, int x, int y,
    const SDL_Color &foregroundColor, const SDL_Color &backgroundColor,
    SDL_Surface *destination)
{
    assert(NULL != font && "The font is NULL.");
    assert(NULL != destination && "The destination surface is NULL.");

    SDL_Surface *textSurface = TTF_RenderText_Shaded(font, text.c_str(),
        foregroundColor, backgroundColor);
    if (NULL == textSurface) {
        throw sdl_error();
    }

    // Center the surface to the given position.
    SDL_Rect pos;
    pos.x = x - textSurface->w;
    pos.y = y - textSurface->h / 2;
    pos.w = 0;
    pos.h = 0;

    SDL_BlitSurface(textSurface, NULL, destination, &pos);

    SDL_FreeSurface(textSurface);
}

            

              
<<define font color>>=
SDL_Color fontColor = {255, 255, 255};

            

All the modules described above can be placed on a single source module ready to compile.

            
<<*>>=
//
// Balls! -- A simple game with balls.
// Copyright 2010 Jordi Fita <jfita@geishastudios.com>
//
<<license>>
//
<<headers>>

namespace
{
    <<constants>>

    <<level structure>>

    <<2d vector struct>>

    <<sdl_error class definition>>

    <<draw centered string function>>

    <<draw right string function>>

    <<draw filled circle function>>

    <<Ball class>>

    <<Explosion class>>

    <<collision function between explosion and ball>>
}

int
main(int argc, char *argv[])
{
    try {
        <<initialize random number generator>>
        <<levels definition>>
        <<initialize variables>>
        <<initialize SDL>>
        <<initialize screen>>
        <<initialize SDL_ttf>>
        <<load font>>
        <<define font color>>
        <<map background color>>
        <<map level colors>>


        bool quit = false;
        while (!quit) {
            <<initialize level>>
            <<game loop>>
        }
        if (finished) {
            <<draw finished text>>
            <<wait for exit event>>
        }
        return EXIT_SUCCESS;
    } catch (std::exception &e) {
        std::cerr << "Error: " << e.what() << "\n";
    } catch (...) {
        std::cerr << "Unknown error\n";
    }

    return EXIT_FAILURE;
}

          

Notice how I wrapped the “happy path” in a try catch block that catches any thrown exception. All the exceptions thrown by Balls! are considered fatal, because I can’t do anything if I can’t initialize SDL, or the font, etc. Thus, I can only show the error to the user, using cerr, and then exit with an error status code.

To be able to use the cerr, I need to include the standard iostream header.

            
<<headers>>=
#include <iostream>

          

Also, even though I don’t use arguments in this application, I declared the main function to have the standard int and argv *[] parameters, instead of using an empty parameter list, which is also a possibility in C++. I’ve done this because SDL, in Windows and Mac OS X, renames the main function, for cross-platform uniformity, to SDL_main which requires those two parameters.