Tutorial 1 – TileMap with Collision Game (Cocos2d)

This tutorial walks you through the creation of a small Cocos2d game using a scrollable TileMap. It is a little long about 90 min I think but includes creating the tilemap with Tiled and then creating the Cocos2d project from scratch.

The source code can be downloaded from the link below.

The game is created using only one class so it is not an example of how to layout the game structure but instead just illustrate how I used the tilemap in a sample game.

Here is a sneak Peak at the Game

(Since the tut video is 90 min.)

Some features of the game.

– Load a tilemap from .tmx file.

– Utilize multiple layers within the map.

– Scroll the map both on x axis and y axis.

– Use the tilemap to layout object which will be collected.

– Collision detection between tilemap and player.

– Use the tile GID to identify the tile on the map.

– Modify the tiles with the tilemap while playing the game.

As you may know if you have been following the blog, I have just begun coding for the Iphone so I had to spend a few days researching this before I had it figured out. The main problem I came across was the lack of detailed tutorials. I  had to take bits and pieces from some great blogs ad posts.

I hope that this video and source does help you out in creating a game that uses a tilemap like a 2d side scroller, and if you like it please let others know by posting on forums or linking to this tutorial.

I will try and do another tutorials on some more fun things we can do with the tilemap – like paralax scrolling and z index for you sprite between tilemap layers. But for now enjoy the tutorial!!!

TileMap Source Code Link

44 Responses to Tutorial 1 – TileMap with Collision Game (Cocos2d)

  1. Atlus says:

    I havent gotten to watch the video yet but the tutorial doesn’t compile I get 3 errors pointing to..


    just thought I would let you know

    thanks for your efforts

    • arulkarthikgd says:

      its working.few images are missing in project file.just delete the red line images and goto resource folder in project source & drag and drop the images which u r deleted , don’t select copy option.now it will works fine.

  2. Atlus says:

    also the video is sending a error page. no video sorry for the double post

    • paulsondev says:

      Video Should be working … It sometimes takes a while for it to get finalized on vimeo.

      Also for the code….not sure what the problem is??…is there a certain way to zip up a project??
      Are you running the latest version of cocos2d? Don’t know much about that problem so maybe someone else can help us out. Because when I download it it will build fine. Mystery for now but will find out!

  3. paulsondev says:

    If the video is not working for people here is the direct link.

  4. Pingback: Tutorial 2 – Parallax Backgrounds & Enemies (Cocos2d Game) « Creating Iphone Game with Cocos2d

  5. Pingback: Iphone Cocos2d Day 2 – Scrolling TileMap & JoyPad « Creating Iphone Game with Cocos2d

  6. melder says:

    When attempting to build the sample, it appears that a couple of files are missing.
    ball.png, fixed-ortho-test2.png, TileMapTest.tmx.

    They show up as red items in XCode and then provide the errors Atlus had above.

  7. Kartik says:

    Hi Paul!

    Excellent tutorials! Would you be able to post the link the Tiled Java edition for the Mac? I can’t seem to find it on their website anymore. That would be awesome!

    Thanks again!

  8. vsching says:

    hi paul, nice tutorial, but i got some problem compiling your tutorial code.
    i set both active target and executable as tilemaptutorial and use simulator 3.1.2 and this is the error i get. Anyone got any ideas about this ?

    2010-04-14 11:17:25.821 TileMapTutorial[2974:207] cocos2d: Error on XML Parse: Operation could not be completed. (NSXMLParserErrorDomain error 5.)
    2010-04-14 11:17:25.822 TileMapTutorial[2974:207] cocos2d: TMXTiledMap: Error parsing TMX file: Error Domain=NSXMLParserErrorDomain Code=5 “Operation could not be completed. (NSXMLParserErrorDomain error 5.)”
    2010-04-14 11:17:25.822 TileMapTutorial[2974:207] *** Assertion failure in -[CCTMXTiledMap initWithTMXFile:], /Developer/Tutorials/TileMapTutorial/libs/cocos2d/CCTMXTiledMap.m:58
    2010-04-14 11:17:25.824 TileMapTutorial[2974:207] *** Terminating app due to uncaught exception ‘NSInternalInconsistencyException’, reason: ‘TMXTiledMap: Map not found. Please check the filename.’

    • paulsondev says:

      I think you just have to add the resources to the project. The files are included in the zip but the project does not have them copied in.
      Or something like that….that has always been an issue and I lost the files from my computer to fix it on my end.

      So it just needs the resources added that are missing.

    • vsching, what did you do to fix that error?

  9. vsching says:

    nevermind, i figure it out..

    Try this, this should solve your problem as well

    The references to the resources folder is corrupted. Just manually add all the items at the resources folder to replace the initial 1 in the project should solve this problem.

  10. vsching says:

    lol.. you post faster than me,
    haha..thanks anyway

  11. Sohan says:

    You will find 3 items in resources folder highlighted in red,just delete those and copy once again from those main resources folder,and the problem is solved.

  12. nono says:


    Nice job

  13. Nick Vellios says:

    Found a minor bug in your tutorial. When your tilemap stops scrolling, the angle that your ball moves is effected. It’s a 45 degree angle when you are in the center of the map but not when the map hits the edge and stops scrolling. Not a big deal. Great tutorial, thank you so much!

  14. freeforce says:

    I got a question about graphics, If I’ve made an image with characters, background, objects etc in photoshop how do I make them into tiles so I can use them in Tiled?
    Do I have to save each one individually, import to zwoptex and then to Tiled?
    And finally, if I have made hills or any large object and want to split that into smaller tiles, do I make segments in Photoshop and save them into small png’s?


    • PaulsonApps says:

      This is very easy and How I did it. Set up your grid in photoshop to be whatever tile size you want to use. I used 32X32. Then with the grid turned on you just layout your images inside those grids. An image like your hill can span many grid boxes, but you just want to make sure that images dont go into another images grid box. These grid boxes are then your tiles. I hope that made sense.

      Then in Tiled you make you map with the same tile size…32X32 say…..then you import your Tiles using the photoshop png you made. In the setting you use the 32X32 size for the tiles (your photoshop grid size) and you set your margins and spacing to “0”. Now your photoshop image is automatically split into tiles.

      One tip I suggest is to save the photoshop png file into your project resources before you import your tiles in TILED. Then when you import the tiles you access them from your project resources. Now when you want to update your tiles you just modify the photoshop file, save it to the resources(overriding your current version) and then automatically your TILED project updates its tiles.

      I hope this helped.

  15. Philip says:

    hey paulsonDev, I finished the tutorial with no errors but the application will just crash just after it opens up. Any suggestions?

    • PaulsonApps says:

      You would have to look at the Console, but It is probably a missing resource. Make sure that whatever image you are using is in your Resources. If you took the code from the download link I know that some of the images where missing. You may be able to simple right click on the Resources folder and select “add existing files”. then pick the images out of the Resources folder on your hard drive.

      I hope that helps

      • Philip says:

        Thanks! Anyway, thanks for the tutorials. Is it possible to increase the map size without changing the coding in HelloWorldScene.m file (except for the boundries)?

  16. PaulsonApps says:

    I have not looked at that code in a long time but It should not be any problem to increase the map size. The way I write the code now allows things like that to change and not effect the way the code works. This should also apply to that project. I believe the code uses mapsize, layersize and tilesize instead of a hard coded number. When this is done the map can be swapped out and the game is auto updated to match your new TiledMap.

    I think that it would be a great exercise for you to try. Doing different things like that will help you understand how the code works.

  17. Philip says:

    Ok, i got the tilemap to move, but I still become stuck at the boundries. I resized the map to 30×20 instead of 20×15.

  18. Maxim Chegodaev says:

    my build stop working at
    rect.origin.x = (gid % max_x) * (tileSize_.width + spacing_) + margin_; line and i cant find ot why, any help guys

    • PaulsonApps says:

      Why are you adding spacing and Margin…..the actual tiledmap does not use this only the tiles png image within the tiled program.

      Maybe you need to clarify what this is for…and what the error is in the console.

  19. headwinds says:

    I’m using XCode with SDK 3.0. I download the source and ran the project. I got the same 3 errors about the missing pngs and added them back to the resource folder.

    Then I got an error about the info.plist not having all the required capabilities. Attempting to fix this issue in the pop up won’t do anything, instead one can open this file in text editor ( I used Text Wrangler ) and then simply delete the offending nodes – see thread about fixing a corrupted info.plist

    I downloaded three other box2D and cocos2D sample projects and your project was the only one I could get running in the simulator and my device within 20 minutes — great work! My only suggestion would be to add a brief README file about this common problem — of course this thread is even more helpful ;-D

  20. Bob says:

    Hi, I’m using the 4.0 SDK and cocos 2d 0.99.4, and when I run the project, i just get a black screen.

    I skipped the collision part because I’m actually making a totally different game based on this, and it does not require any collision.

    Any suggestions?

  21. Bob says:

    Never mind, solved the problem!

  22. I worked for 3 days on a Tiled collision code. Well, it worked, but it bugged on some corners or when the object was fast (and in my game the object will always be fast!). I almost gone to Box2D collision only until I found this code.

    I fixed a stuff here and there and now it works perfectly! I fixed two points and now it is pixel perfect (the white box is the sprite against the black tiles):

    Thanks a lot Paulson 🙂

  23. Darrell says:

    I cant seem to get the game to compile.. i get the following errors.. Im running a fairly recent cocos 2d install from a few months ago.. I just downloaded the source code and tried to compile it..

    Please help.. I tried to compile tutorial 1 and tutorial 2.. And received the same errors..


    /Developer/Library/PrivateFrameworks/DevToolsCore.framework/Resources/pbxcp failed with exit code 1

    Also i get errors saying the following resources are missing.. “tilemaptest.tmx” “ball.png” and “fixed-ortho-test2.png”

  24. Joakim says:

    Great stuff, i watched the whole video and it really rocks! Please continue your great work with your tutorials!


  25. Cacker says:


    Great tutorial!

    I went to download the Java Version of Tiled and its been replaced. Do you have a version you could make available to download or email to me ?

    Also, I cant see the graphics you are using in Cocos2d – have these changed in the more recent vesion ? Could you email these so I can follow your tutorial ?

    Many thanks and keep up the great work.


  26. Felipe Matos says:

    Hey great tutorial. Thanks!!! Just one thing. It runs fine but I get 3 unused Variable warning for the gid6-8 unsigned int. What do you suppose is the problem?

  27. Dave says:

    Hi There.

    Not sure if you still check the comments here but I wanted to let you know how incredibly useful these tutorials have been with helping me get to grips with Cocos2d – great work, thank you.

    I’ve worked through these and have the basics of a nice mario-style side scroller built up, similar to PlanetOne, and I’ve added a simple jump control for my player. I’m not using a physics engine and basically the jump just increases the players vertical velocity as they fall, until they reach a terminal velocity.

    Because of this extra speed the player sometimes ends up overlapping a collidable tile before the collision detection runs and, once they’re overlapped, all future movement is a bit screwy.

    Do you have any thoughts on how I can fix this? do I need to work out the top/side of the tile that the player has hit and just update the player position? If so, any pointers on how to go about this?

    You can see my code (not too dissimilar from your own source code) here http://www.cocos2d-iphone.org/forum/topic/16667.

    Thanks again.


  28. Barry says:

    Hey, great tutorial! I followed it all the way to the end and my project says it “succeeded” However when I build and run, it says GDB: Program received signal: “EXC_ARITHMETIC”.
    and my iphone simulator goes to the splash screen and then exits. Do you have any idea what is causing this problem ? also after the iphone simulator goes away, on my Xcode it takes me to this line of code (not on the .m or .h )and it reads
    rect.origin.x = (gid % max_x) * (tileSize_.width_) + margin_;

    If you can help me with this problem please email me at barry_wyckoff@yahoo.com

  29. KennyChong says:

    Fantastic tutorial! Appreciates your sharing that helps rookie like me! Cheers.

  30. Pingback: Tutorial 1 – TileMap with Collision Game Cocos2d « PaulsonApps Development Blog « OmNomRobot

  31. Pingback: My bookmark backup » V1.3

  32. praga says:

    Hello sir . I want to make my sprite jump on the tile map layer object ( probably brick) using cocos2d , box2d. Can u provide me any help .

  33. Nice tutorial …was looking for this one.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: