Cocos2D iPhone/Objective C Documentation

Is there any place remaining on the internet where the Cocos2d 3.4/3.5 for iPhone/Objective-C documentation exists on the internet still ?

I can access the /docs section of the old website using
but it seems the link to the documentation has not been archived.

Somewhere out there there was a migration guide between 2.x and 3.x too - if anyone knows where that might exist I would also appreciate it.

I am looking to upgrade my Cocos2d 2.x app to support iPhone X resolution… I can’t seem to see anywhere on the internet that confirms that 3.x supports @3x resolution. If anyone can confirm whether this is the case or not I would be most appreciative!

I don’t know actually. Let me reach out to the previous folks and see if they have any materials that we can host on our docs server.

Many thanks!

I reached out to the previous maintainer and he doesn’t have the old materials. I apologize.

No worries. Thanks for trying!

The good news is I have tried doing iPhone X support using the cocos2d 2.x version that I am on and it turns out that in the absence of @3x assets looks like the iPhone reverts to @2x assets, so seems like supporting iPhone X will be possible! Great news!

Hi @chopsalot, I am in a similar situation as you… I have an app in the app store built with cocos2d-iphone v2.x that I really need to update to fix bug, but I have totally neglected supporting all the ridiculous resolutions / device sizes that apple offers, and I really need to tackle this.

I just started looking into what it would take to modify the cocos 2.x CCDirector to be device agnostic, so I was wondering how your progress has gone so far and if you’d like to work together to get this done as soon as possible… ?

Hi @patrick99e99, well the good news is all I had to do was just to add the launch image for the devices I wanted to support and it just supported the screen resolution automatically! Obviously the scene still looked massively broken because I didn’t program it in a dynamic way the first time around, but now that I’ve reprogrammed the scene to me a lot more relative and lose the magic number bs I had in there its all good. I have now gone ahead and adapted my app to work on every device with no problem. My biggest concern was that devices that require @3x resolution would have all the sprites appearing 50% the size that they should be (i.e. using the 2x assets with a 3x density). Looks like iOS is smart enough to work all that out though and when using 2x assets it upscales them sensibly automatically.

If you did want to support @3x images, I found this stackoverflow post by someone who successfully modded their cocos2d 2.x to use 3x assets . I didn’t use it myself as I am happy to just use 2x stuff, but looks like a handy resource if you wanted to go the full distance.

1 Like

Hi @chopsalot, that is interesting because I am not experiencing things just magically working. I actually just setup a launch image storyboard to see if that would help, but it did not… I actually would prefer to not support @3x, so if I don’t have to, that is ideal.

Do you do anything in your app delegate for content scaling? I think that is what is all messed up for me. For example, if I choose iPhone6, all my art is huge and off the screen, it’s as if the iphone viewport is zoomed into the center of the app… If I choose iPhone6 Plus, then all of my art looks like garbage-- as in the coordinates for sprites are somehow not being adjusted for the device scaling or something… Have you seen anything like this?

What are you using for a design resolution and what size is your art made for?

Also what version of cocos2d are you using? I am on Cocos2d 2.2 according to my cocos2d.h file

Hmmm, that is interesting. I actually met another guy using cocos2d 2.x who also reported a similar issue with his graphics on the Plus size just looking garbage. I wonder what could be so different about my version? I am happy to zip the cocos2d directory inside my project to see if that would help - I dont think I’ve particular edited the source although just did a search on my project and looks like I have added a few things in in the past to do with bugs I found and solutions pasted from stackoverflow… Not sure that would be significant though.

Are you using sprite sheets? What software are you using to pack them? Are you using -hd prefix etc?

There is no concept of “design resolution” in cocos2d-iphone v2.x.

I have 1x and 2x versions of my art.

Previously when I released my app, I was trying to support ipad retina, iphone5, 6, 6+, so I wrote my own custom classes that inherited from CCDirector and had hard coded winSize and projections to make them work for those devices. I also had subclassed CCSprite, CCSpriteBatchNode, CCNode, etc so that they all used those custom directors to offset positions based off of device types…

Once Apple started releasing more devices with different screen sizes, it became obvious that my approach was going to be a maintenance nightmare, so since I need to update my app and am being forced to support iPhone X, then I decided to throw away all that custom code, and just want to support a simple 4:3 aspect ratio and scale it on the devices (black borders).

However, removing all my custom director code, I am back to where I was before where nothing works as-is in cocos2d except iPad…

@patrick99e99 I have zipped the contents of my projects ‘lib’ directory that has all the cocos2d files in it. I have uploaded it to my dropbox here

You could try using that and see what happens. If you search for ‘//Dave’ I think I have marked all places I made any additions with that comment tag.

Very odd that mine would just be working and yours not I think. Let me know if you have any luck.

Oh you just made me realize the reason for the garbage… I forgot, I had modified cocos2d to support 3x images, and since I ended up not actually using them in my game, the scaling for sprite sheets was set for 3x… So reverting that commit fixed that problem.

But… The problem still remains, no matter what device I use, all my art is HUGE and going off the screen… Are you doing anything anywhere to change/set CCDirector’s winSize?

That’s the part I am trying to figure out how to do… I need to project this 768x1024 scaled to fit the device’s screen so that it’s always 4:3 in portrait mode…

Here is a cut down version of my AppDelegate initial method too, just incase I’m doing anything different. That ‘isInForeground’ method called at the bottom is just if the app is opened in the background it stops it from trying to stuff until the app is foregrounded (otherwise it was crashing).

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
     // Create the main window
    window_ = [[UIWindow alloc] initWithFrame:[[UIScreen mainScreen] bounds]];
    // Create an CCGLView with a RGB565 color buffer, and a depth buffer of 0-bits
    CCGLView *glView = [CCGLView viewWithFrame:[window_ bounds]
                                   pixelFormat:kEAGLColorFormatRGB565    //kEAGLColorFormatRGBA8
                                   depthFormat:0    //GL_DEPTH_COMPONENT24_OES
    glView.multipleTouchEnabled = YES;
    director_ = (CCDirectorIOS*) [CCDirector sharedDirector];
    director_.wantsFullScreenLayout = YES;
    // Display FSP and SPF
    [director_ setDisplayStats:NO];
    // set FPS at 60
    [director_ setAnimationInterval:1.0/60];
    // attach the openglView to the director
    [director_ setView:glView];
    // for rotation and other messages
    [director_ setDelegate:self];
    // 2D projection
    [director_ setProjection:kCCDirectorProjection2D];
    //    [director setProjection:kCCDirectorProjection3D];
    // Enables High Res mode (Retina Display) on iPhone 4 and maintains low res on all other devices
    if( ! [director_ enableRetinaDisplay:YES] )
        CCLOG(@"Retina Display Not supported");
    // Default texture format for PNG/BMP/TIFF/JPEG/GIF images
    // It can be RGBA8888, RGBA4444, RGB5_A1, RGB565
    // You can change anytime.
    [CCTexture2D setDefaultAlphaPixelFormat:kCCTexture2DPixelFormat_RGBA8888];
    // If the 1st suffix is not found and if fallback is enabled then fallback suffixes are going to searched. If none is found, it will try with the name without suffix.
    // On iPad HD  : "-ipadhd", "-ipad",  "-hd"
    // On iPad     : "-ipad", "-hd"
    // On iPhone HD: "-hd"
    CCFileUtils *sharedFileUtils = [CCFileUtils sharedFileUtils];
    [sharedFileUtils setEnableFallbackSuffixes:NO];                // Default: NO. No fallback suffixes are going to be used
    [sharedFileUtils setiPhoneRetinaDisplaySuffix:@"-hd"];        // Default on iPhone RetinaDisplay is "-hd"
    [sharedFileUtils setiPadSuffix:@"-ipad"];                    // Default on iPad is "ipad"
    [sharedFileUtils setiPadRetinaDisplaySuffix:@"-ipadhd"];    // Default on iPad RetinaDisplay is "-ipadhd"
    // Assume that PVR images have premultiplied alpha
    [CCTexture2D PVRImagesHavePremultipliedAlpha:YES];
    navController_ = [[UINavigationController alloc] initWithRootViewController:director_];
    navController_.navigationBarHidden = YES;
    // set the Navigation Controller as the root view controller
    [window_ setRootViewController:navController_];
    // make main window visible
    if ([self isInForeground]) {
        [window_ makeKeyAndVisible];
        makeWindowVisibleRun_  = YES;
    else {
        makeWindowVisibleRun_  = NO;
    return YES;

Are you doing anything anywhere to change/set CCDirector’s winSize?

The code that sets the winSize is in the app delegate in my code above where it refers to [window_ bounds] … see below

CCGLView *glView = [CCGLView viewWithFrame:[window_ bounds]
                                   pixelFormat:kEAGLColorFormatRGB565    //kEAGLColorFormatRGBA8
                                   depthFormat:0    //GL_DEPTH_COMPONENT24_OES

Ok, so I made a new github repo which demonstrates my problem:

  1. I made a background image for retina and non-retina: “cat.png” (768x1024) and “cat-hd.png” (1536x2048)

  2. I made a retina and non-retina version of a foreground image “headshot.png” (125x125) and “headshot-hd.png” (250x250)

So, if you build this with an iPad, you will see it looks correct.

However if you build with an iPhone (I tried iPhone 6 and iPhone X) the image is huge and off the screen.

What I want is for that the aspect ratio 4:3 to be applied to scale up/down whatever the device’s screen size is so that the content will fit the screen.

So in other words, I need it so that if a CCSprite’s position to be ccp(768, 1024) and its anchor point is ccp(1, 1), then the image will be in the bottom right corner, and if CCSprite’s position to be ccp(0, 0) and its anchor point is ccp(0, 0) then it will be in the top left corner-- no matter what device is or what its screen resolution is.

How can I do this?

Ok, so your project won’t compile, looks like its missing cocos2d but not immediately sure how to get that to work.

Looking at your code however, assuming I am understanding you correctly, I’m not sure how you are expecting this to happen? You are using static coordinates so Its doing exactly what you are telling it to do. Why not do this:

-(instancetype)init {
    if (self = [super init]) {
        self.offset = self.headshot.contentSize.width * 0.5;
        self.velX = 1.0f;
        self.velY = 1.0f;
        self.speed = 1000;

        CCSprite *background = [CCSprite spriteWithFile:@"cat.png"];
//instead of using magic numbers, use a more dynamic reference`
        background.position = ccp(self.contentSize.width/2, self.contentSize.height/2); 
        background.anchorPoint = ccp(0.5, 0.5);

//If you care about the aspect ratio, you can do this
background.scale = MAX(  self.contentSize.width / background.contentSize.width , self.contentSize.height / background.contentSize.height) ;

//Else you could just set the X and Y scales indepently
 background.scaleX = self.contentSize.width / background.contentSize.width;
 background.scaleY = self.contentSize.height / background.contentSize.height;

        [self addChild:background];
        [self addChild:self.headshot];
        [self scheduleUpdate];
    return self;

-(CCSprite *)headshot {
    if (!_headshot) {
        _headshot = [CCSprite spriteWithFile:@"headshot.png"];
        _headshot.position = ccp(self.contentSize.width/2, self.contentSize.height/2); //again... you want it to be in the middle of the screen... so tell is so
        _headshot.anchorPoint = ccp(0.5, 0.5);
    return _headshot;

Is this want you mean’t? Or have I misunderstood?

You can also use a macro like this to get the screen size at any time:

#define SCREEN_SIZE [[UIScreen mainScreen] bounds].size

@chopsalot, sorry! I forgot I had added cocos as a submodule so that’s why it didn’t get into the repo… I made another commit and added it in, so you can pull and get it if you want.

So, yes, your code does do what I want---- BUT… I don’t want to have to do it that way, as that will be an absolute nightmare! To do it that way would require me to setScale on every single thing in my app and do division in every single call to setPosition…

I am looking for a way to alter the actual projection of the game so that (768, 1024) will ALWAYS be the bottom right edge of the 4:3 constrained screen area, no matter what the device’s actual resolution is… This is what I believe the modern Cocos2d is doing with the concept of “design scale”… I need a simple way to make ALL positioning affected without having to individually do math in every single call to set the position for my sprites.

Ahh I see. Unfortunately I don’t know enough about the inner workings of cocos2d to be able to give you any advice on altering the projection. I did think maybe you could override some of the core methods of CCNode to auto update position, contentSize etc. I tried this with position, and yes it works… but you’re still going to run into a lot of issues I think

-(void) setPosition: (CGPoint)newPosition
    CGSize screenSize = [[UIScreen mainScreen] bounds].size;
    CGSize refSize = CGSizeMake(768.0 , 1024.0);
    CGFloat desiredAspect = refSize.width / refSize.height ;
    CGFloat actualAspect = screenSize.width / screenSize.height ;
    CGFloat actualHeight = screenSize.height;
    CGFloat actualWidth = screenSize.height * desiredAspect;
    if (actualWidth > screenSize.width) {
        actualWidth = screenSize.width;
        actualHeight = actualWidth / desiredAspect;
    CGPoint offsetPos = ccp( (screenSize.width - actualWidth)/2 , (screenSize.height - actualHeight)/2 );
    CGPoint scaledPos = ccp( offsetPos.x + (newPosition.x * (actualWidth/refSize.width)) , offsetPos.y + (newPosition.y * (actualHeight/refSize.height)) );
    //printf("orig Position: x= %.2f  y= %.2f   newPos x= %.2f  y= %.2f  actualW = %.2f h= %.2f  offset x= %.2f  y= %.2f  screen w= %.2f  h=%.2f  \n",newPosition.x,newPosition.y,scaledPos.x,scaledPos.y,actualWidth,actualHeight,offsetPos.x,offsetPos.y,screenSize.width,screenSize.height);
	_position = scaledPos;
	_isTransformDirty = _isInverseDirty = YES;

Another thing to consider though is this, human interface guidelines for the notch state that:

Don’t mask or call special attention to key display features. Don’t attempt to hide the device’s rounded corners, sensor housing, or indicator for accessing the Home screen by placing black bars at the top and bottom of the screen. Don’t use visual adornments like brackets, bezels, shapes, or instructional text to call special attention to these areas either.

So even if you did manage to preserve the aspect ratio leaving bars at the top and bottom, would it even pass Apple review?