This is a post by special contributor Andreas Loew, the creator of TexturePacker and PhysicsEditor.
Create this vertical scrolling platformer with Cocos2D!
In Part One on the tutorial series, we introduced the MonkeyJump! game design, created the sprite sheets and shapes we needed, and began coding the game.
In Part Two, we added our hero to the game, made him move and jump, and added some gameplay.
In this third and final part of the series, we will add some performance improvements, add a HUD Layer, and yes – kill the monkey! :]
We’ll be starting with the project where we left off last time. If you don’t have it already, grab the source code for this tutorial series and open up 5-MonkeyJumpAndRun.
All right, time to stop monkeying around and wrap up this tutorial! :]
Too Many Objects!
Playing our game for a while, you’ll see that it gets slower and slower, until it becomes completely unplayable.
There’s a reason for this – as objects continue to fall from the sky, one after another, they bump into the objects already lying around. All of these collisions have to be handled by Box2d. If there are n objects, there are n*(n-1) possible collisions to handle. Box2d uses hashes to make things faster, but you can imagine how dramatically the number of collisions increases as the number of objects increases.
If you watch a statue drop, you’ll see that nearly the entire stack below moves and bounces from impulses passed from the statue down through the stack from one object to another.
To improve the situation, we’re going to convert objects which are some distance below the monkey into static objects. These static objects will still let other objects pile up above them, but they’ll no longer react to the impact. As a result, a falling statue will only affect the top of the stack instead of the complete pile.
Box2d allows objects to go to sleep when they aren’t touched by other objects for some time. We will use this feature to improve performance.
GB2Engine has an iterate method that can be used to iterate all objects with a block. We will use it to create a routine that checks the y-coordinates of all objects and puts to sleep any that are a certain distance below the monkey.
Add the following code to the end of the update selector in GameLayer.mm:
// 10 - Iterate over objects and turn objects into static objects
Compile and test. Note that there are still some situations where things won’t work as expected. For example, if a group of objects pile up like a tower, and the monkey climbs onto the pile, it might happen that a dropping object reaches the pruneDistance and is converted into a static object in mid-air.
The solution is quite simple: only convert objects to static if their speed is low. Change the second if condition in the above code to:
if((y < prune) &&
Compile and test. Looks good, doesn’t it?
Caught in a Trap
There’s still an issue though – the monkey might still get caught under a pile of objects. Items pile up around him, and he’s not strong enough to break free if there are too many objects above him.
There are several ways to deal with this situation. One is to simply let him die if he’s stuck. Another solution is to “teleport” the monkey above the objects and let him go on playing. That sounds fun, let’s do that!
To make this work, we must be sure that the monkey teleports above all objects. Otherwise, his position might place him directly inside another object and he’ll never break free!
Go into GameLayer.h and add a member variable:
float highestObjectY; // y position of the highest object
And make it a property by adding the following line above the “scene” method declaration:
@property (nonatomic, readonly) float highestObjectY;
Now switch to GameLayer.mm and synthesize the object by adding this line just below the “@implementation” line:
Then, replace section #10 in update with the following:
// 10 - Iterate over objects and turn objects into static objects
The new code determines the highest object location by resetting the highestObjectY with every new check. Note that it only checks active objects. Otherwise, the highest object will always be the object that is waiting to drop.
Switch to Monkey.h and add a new member:
int stuckWatchDogFrames; // counter to detect if monkey is stuck
Now let’s teleport the monkey above the highest object’s position if he’s been stuck with an object above his head for a certain amount of time. Aadd the following to the end of the updateCCFromPhysics selector:
// 8 - Check if monkey is stuck
Compile and run. That’s much better! Now, if the monkey is caught in a trap and he can’t push his way out, he will be magically freed.
There are other ways to detect if the monkey is caught. For example, we could check how high the objects are piled, or if the monkey’s speed is low for a certain amount of time. Feel free to try out other detection methods to see which one works best for you.
Putting the Pain on Our Hero
Play the game for a bit and you’ll realize that there isn’t much challenge to this game – the monkey climbs but doesn’t take any damage. Let’s change that.
Open Monkey.h and add a new variable called health to the Monkey class.
Also add properties to access the health level and to detect if the monkey is dead:
@property (readonly) float health;
Finally, add a define for the maximum health, at the top of the file below the import statements:
#define MONKEY_MAX_HEALTH 100.0f
Now switch to Monkey.mm and synthesize the health property:
Implement the isDead property by adding the following code above the walk method :
As you’ll notice, we decide if the monkey is dead or not based on if his health is less than 0 or not.
In the init selector, initialize the health with the maximum value by adding this below the game layer storage code:
// set health
Now let’s put the hurt on the monkey by modifying the section with the head collision in beginContactWithObject:
else if([fixtureId isEqualToString:@"head"])
Basically, the monkey should get hurt when an object collides with his head. Calculate the damage using the object’s vertical velocity and mass, and reduce the monkey’s health by that amount. This causes damage from fast-dropping objects, but doesn’t harm the monkey if an object is resting above his head. Notice that I also added a hurtFactor so that you can adjust how much the monkey is hurt.
If the monkey dies, he should drop from the scene. In this case, we’ll simply delete all the monkey’s collision flags except for the floor. This will make the monkey fall dead on the floor. We’ll release the rotation lock to let him lie on the floor, and change the monkey’s sprite to dead.png.
Dead monkeys can’t jump – so change the code in the monkey’s jump selector to ignore screen taps if the monkey is dead:
Disable the updateCCFromPhysics contents by changing section #1, as well:
Compile and run, and now you can bring out your evil side – kill the monkey! :]
Restarting the Game
Now the monkey dies, but the objects keep falling and there’s no way to restart the game.
I would suggest restarting two seconds after the monkey’s death. Usually, we’d go to a high score table after a game ends, but that’s too much for this tutorial. A simple restart will suffice.
Add a new variable to GameLayer.h to hold the restart timer:
ccTime gameOverTimer; // timer for restart of the level
And add these lines to the beginning of update inside GameLayer.mm:
In case of a restart, we simply remove all objects from the GB2Engine and replace the current scene with a new GameLayer.
Compile and run. The level should now restart two seconds after the monkey’s death.
The HUD Layer – Health
Yes, the monkey dies, but no one knows when it’s going to happen! That’s too realistic for me and most other players. Let’s add a health display so that we can keep track of the monkey’s health.
We’re going to represent the monkey’s health with 10 banana icons. Each banana represent 10 points of health.
Create a new file with the iOS\Cocoa Touch\Objective-C class template. Name the class Hud, and make it a subclass of CCSpriteBatchNode. And don’t forget to change the .m extension to .mm. Replace the contents of the Hud.h file with the following:
The HUD display uses the sprites from the jungle sprite sheet, so we have to derive the HUD from CCSpriteBatchNode in order to have access to the jungle sprite sheet sprites. Additionally, the HUD needs to keep track of the current health (which we will need later) and the sprite representing each point of the monkey’s health. We also need a method to change the current health.
Switch to Hud.mm and replace its contents with the following:
Here, we initialize the HUD’s CCSpriteBatchNode super class with the sprite sheet.
Then, we iterate through the number of health tokens and create sprites for each of the bananas. We also increase the x-position of each banana to lay it out next to the previous banana.
Finally, add the method to update the health to the end of Hud.mm:
-(void) setHealth:(float) health
In this method, we need to determine the number of bananas to display, make the ones to display visible, and clear the invisible ones. It’s possible for sections #3 and #4 to be implemented with only one loop, but we’re going to extend this code later and so will have that as two separate loops.
Next we need to add the new HUD to the GameLayer. Switch to GameLayer.h and add the predeclaration of the HUD class:
Then, add a member variable for the HUD to the GameLayer class:
Switch to GameLayer.mm and import Hud.h at the start of the file:
Init the HUD inside the init selector:
// add hud
Finally, update the HUD from inside the update selector by adding this code to the very end:
// 11 - Show monkey's health in bananas
Compile and test. It works, but I don’t quite like the visuals – I don’t think the bananas should appear and disappear so abruptly. I want them to fade in and out. I also think the monkey’s health should drop over time rather than instantly.
Since setHealth gets called every frame, it won’t be hard to adjust the displayed health level over time.
Open Hud.mm and change the setHealth selector’s section #1 with the following:
// 1 - Change current health
Compile and test. Now the HUD adjusts more slowly, but the bananas still disappear way too quickly. Let’s make them fade and scale in and out.
Replace sections #3 and #4 in setHealth with the following code:
// 3 - Set visible health tokens
To fade a banana into view, we check if the banana is already visible. If it’s not, we set it to visible, set the scale to be smaller than the actual size and opacity to 0, and then run an action scaling the banana to 1.0 and fading it in. If the banana is already visible, we’ll do nothing since an action might already be running on it.
To fade a banana out of view, we need a sequence action: first scale and fade out, and then set it to invisible using the CCHide action.
Since we can’t use the visible flag to determine if the banana is fading out, we’ll check the number of animations running on the banana. If the number isn’t zero, that means an animation is already running, so we won’t run another one.
Compile and run. Watch for the bananas to fade in on start and fade out when the monkey gets hurt.
The HUD Layer – the Score
Now let’s add a score display to the HUD. For the score, I suggest using the highest point the monkey has reached while standing on an object.
Switch to Monkey.h and add a new variable and property:
@property (nonatomic, readonly) float score;
Switch to Monkey.mm and synthesize the score property at the beginning of the file:
Add the following lines to the end of updateCCFromPhysics:
// 9 - update score
Note that we update the score only if it is higher than the current score because sometimes the monkey might drop down to a lower position after climbing higher. We also scale the monkey’s y-value by 10. Otherwise the score increases are fairly low and not very motivating.
Switch to Hud.h. Add a define for the number of score digits:
#define MAX_DIGITS 5
Add variables to keep the digit sprites and to cache the CCSpriteFrame pointers:
CCSprite *digits[MAX_DIGITS]; // weak references
Add a method definition to set the score:
-(void) setScore:(float) score;
Now switch to Hud.mm. The first thing to do here is cache the lookup of the digit sprites. Add the following lines to the end of the init method:
// 2 - Cache sprite frames
Here, we use the CCSpriteFrameCache and request the frame for each digit. We’ll store the frame data in the digitFrame array. Then we create sprites for each digit to display and initialize each one to frame 0.
Add the following method to the end of the file – it prints the current score in a character buffer and adjusts the digits displayed according to the digits in the buffer:
-(void) setScore:(float) score
Finally, switch to GameLayer.mm and add this code to the end of the update method:
// 12 - Show the score
Compile and test. Check if the score is updated when the monkey climbs higher. The monkey starts with a score of 9 – this is because the floor’s height already adds to the monkey’s score. If you want you can reduce 9 from the score so it starts at 0.
All of the code up to this point is available in the folder 6-Hud.
Currently, the monkey gets hurt by the falling bananas but I want them to restore his health when he consumes them.
To enable this, we’ll create a subclass of Object called ConsumableObject. This class gets a bool variable that keeps track as to whether the object was already consumed.
I usually prefer using one file for each class, but since these classes are quite small, I’m going to add it to the end of Object.h (after @end):
@interface ConsumableObject : Object
Similarly, derive Banana and BananaBunch classes by adding the following code after the definition of ConsumableObject:
@interface Banana : ConsumableObject
Now implement the consume method for ConsumableObject in Object.mm. It’s important to add the code below the @end that closes the @implementation for Object:
The consume method checks to see if the object was already consumed. If it wasn’t consumed, then scale the object to 0 and fade it out, and finally, delete the object from the game.
To do this, we create a CCSequence action with a parallel action of CCFadeOut and CCScaleTo, followed by a CCCallFunction. This CCCallFunction calls the deleteNow selector. This selector removes a GB2Node object from the world, both in graphics and physics.
Now, switch to Monkey.h and add the new restoreHealth method:
Next, switch to Monkey.mm and implement the method at the end of the class:
Here, we simply add the new health value, ensuring that it does not exceed the maximum. Just setting the health is enough as the HUD take care of animating the health bar.
We’ll also play a small gulp sound when the monkey swallows the item. To do this, import Monkey.h at the beginning of Object.mm:
Then, implement the beginContactWithMonkey for the Banana and BananaBunch classes below the implementation for ConsumableObject in Object.mm:
We simply check if the object was already consumed, and if not, call restoreHealth on the Monkey object. The banana restores 20 points, while the banana bunch restores 60 points.
Compile and run. Hey – what’s that? It’s not working!
The reason for failure? Bananas and banana bunches are still created as Object classes. The factory method we use in Object.mm does not yet create our new Banana and BananaBunch objects.
Go back to Object.mm and change the randomObject selector to produce Banana and BananaBunch objects:
Compile and test. Nice!
The only thing that bothers me is that the monkey stops when hitting a banana and the bananas bounce off the monkey.
Box2d has two phases during the stepping of its world: a presolve phase and a collision phase. During the presolve phase it is possible to disable collisions between objects. The collision callbacks will get called, but the objects won’t bounce off.
GBox2D wraps this into a selector called presolveContactWith* that can be called on the colliding objects. Within this selector, you can disable the contact.
Add the following selector to ConsumableObject in Object.mm (before the @end marker) – it will fix the collisions for Banana and BananaBunch:
Compile and test. Check if the monkey can eat the banana without getting disturbed or having the banana bounce off him.
Our game is looking awesome! But I still have a few more improvements for you.
The game is a bit unfair right now: the monkey is on the scene and BAM! – a statue kills him instantly. It is a game that can be won more by chance than by skill.
To make the gameplay a bit more even, we’re going to add a drop indicator. It will be a small red bar that shows the position of the next object drop.
Go to GameLayer.h and add the following variable for the drop indicator:
CCLayerColor *objectHint; // weak reference
Then, add the following initialization code to the very end of the init method of GameLayer.mm:
// object Hint
We create a semi-transparent red box as the drop indicator and set the box dimensions to 10×10 pixels. We’ll resize it later to match the dropping object’s size.
Next, scroll down to just above section #8 in the update selector and add the following code:
if(nextDrop < dropDelay*0.5)
If the nextDrop is less than half of the dropDelay, we set the objectHint to visible and its width to the dropping object’s width. We also set its position centered below the object’s x coordinate.
Compile and run! Check if the object hint appears below the position of the next drop.
One last addition – the theme music! Import SimpleAudioEngine.h at the beginning of GameLayer.mm, if you haven’t done so already:
Add the following lines to the end of the init selector. The music resources have already been added to the project:
Compile and run.
The final version of this project is in the folder called 7-done.
Where to Go From Here?
If you don’t have it already, here is all of the source code for this tutorial series.
Congratulations – you finished the tutorial. Looking back, you’ve learned a ton of things:
- Using TexturePacker to create your sprite sheets
- Using PhysicsEditor to create your collision shapes
- Building a physics-based game with collision detection and sound using Box2d
- Building a HUD layer to display the health and score
I hope you have enjoyed this tutorial! I’d love to hear what you think of the game and the products we used to make it, so keep the questions and comments coming.
This is a post by special contributor Andreas Loew, the creator of TexturePacker and Physics Editor.