Creating a repeating background/infinite parallax effect in cocos2d

I’m working on an iPhone game and thought I’d share some code for a infinite parallax class I made. I’m aware of CCParallaxNode, I’ve named mine CCParallaxScrollNode and it greatly simplifies the task of creating a repeating background with parallax effects. It does all the dirty work for you, essentially. Here’s the info and link, and a sample project. Remember to change the Base SDK in the project settings to the latest you have.

CCParallaxScrollNode on GitHub

Download Sample Project

CCParallaxScrollNode for cocos2d, Created by Aram Kocharyan
http://ak.net84.net/

Easy to use parallax scroll class, with ability to create infinite/repeating parallax effects (like in the cartoons). Add sprites and it'll do the rest. Uses CCSpriteBatchNode for more efficient rendering when using a lot of sprites, if you want it to.

For infinite parallax, the idea is to have two seamless (can be repeated) CCSprite objects. When one moves
off the screen, it is placed behind the second object, this continues and creates the effect of an endless
background etc. Preferably, each image should be at least as wide as the screen, but this class lets you
use as many CCSprites as you like, so you could have 10 if you like... The minimum number to pull off the
trick is 2 images at least as wide as the screen, but this restriction isn't enforced.

Note that this class can be used just for a repeating background, it would be parallax if you had 
another set of CCSprites on top that moved at a different speed ratio.

// EASY WAY FOR INFINITE PARALLAX

    // Uses CCSpriteBatchNode for more efficient rendering when using a lot of sprites
    parallax = [CCParallaxScrollNode makeWithBatchFile:@"parallax"];

    // Create sprites (this refers to frames loaded by CCParallaxScrollNode, used for CCSpriteBatchNode)
    CCSprite *clouds1 = [CCSprite spriteWithSpriteFrameName:@"clouds1.png"];
    CCSprite *clouds2 = [CCSprite spriteWithSpriteFrameName:@"clouds2.png"];

    // Easier way, the X in ScrollX means we will be moving in X axis, so line up sprites left to right
    [parallax addInfiniteScrollXWithZ:0 Ratio:ccp(0.5,0.5) Pos:ccp(100,100) Objects:clouds1, clouds2, nil];
    
    // Add to layer, sprite, etc.
    [self addChild:parallax z:-1];


// MANUALLY - MORE CONTROL

    // Doesn't use CCSpriteBatchNode
    parallax = [CCParallaxScrollNode node];
    
    // Create sprites from file
    CCSprite *clouds1 = [CCSprite spriteWithFile:@"clouds1.png"];
    CCSprite *clouds2 = [CCSprite spriteWithFile:@"clouds2.png"];
    
    // Create 2 sprites, as one leaves screen, it is placed behind the other.
    // This is what easy way does using addInfiniteObjects.
    float totalWidth = 2 * clouds1.contentSize.width;
    // Manually specify offset once the sprite moves off screen (e.g. to move it behind next object)
    [parallax addChild:clouds1 z:0 Ratio:ccp(0.5,0.5) Pos:ccp(0,100) ScrollOffset:ccp(totalWidth,0)];
    [parallax addChild:clouds2 z:0 Ratio:ccp(0.5,0.5) Pos:ccp(clouds1.contentSize.width,100) ScrollOffset:ccp(totalWidth,0)];
    
    // Add to layer, sprite, etc.
    [self addChild:parallax z:-1];


// MOVING THE PARALLAX

    This part's the whole point. You need to tell the parallax to move, you can use:

        float myVelocity = -4;
        [parallax updateWithVelocity:ccp(myVelocity, 0) AndDelta:dt];

    in your update method, with -4 meaning move left. You can change the velocity to anything to speed up
    or slow down the parallax!


// FUNCTIONS DEFINITIONS

There are several functions included for adding, removing CCSprite children, as well as creating infinite parallax, which was the point of this class to begin with. Here's what everything means.

Ratio: When updating velocity of the parallax, by what ratio should the CCSprite move in X and Y?
       This controls the magnitude of the parallax effect for each object. Make closer objects with
       higher (X,Y) ratios (moving quickly) and distant objects with lower values.
       
Pos:   The starting (X,Y) position of a CCSprite. If doing it manually, you'll want the second image starting
       behind the first etc.
       
Dir:   This tells the helper function addInfiniteScrollWithObjects:Z:Ratio:Pos:Dir: where to place the 
       second and subsequent images (on the left/right and top/bottom) of the first. For a left moving
       parallax, this would have the direction as ccp(1,0) so the second CCSprite will be placed to the
       right of the first. ccp(-1,0) would have it to the left, and would also look exactly the same.
       What matters is the direction it is travelling in (due to the velocity in X and/or Y), which should
       not be confused with the "Dir:" parameter. If using the helper functions:
           addInfiniteScrollX...   or   addInfiniteScrollY...
       you won't need to specify the Dir.

Z:     The z-index.

CCParallaxScrollNode for cocos2d, Created by Aram Kocharyan

http://ak.net84.net/

Easy to use parallax scroll class, with ability to create infinite/repeating parallax effects (like in the cartoons). Add sprites and it'll do the rest. Uses CCSpriteBatchNode for more efficient rendering when using a lot of sprites, if you want it to.

For infinite parallax, the idea is to have two seamless (can be repeated) CCSprite objects. When one moves

off the screen, it is placed behind the second object, this continues and creates the effect of an endless

background etc. Preferably, each image should be at least as wide as the screen, but this class lets you

use as many CCSprites as you like, so you could have 10 if you like... The minimum number to pull off the

trick is 2 images at least as wide as the screen, but this restriction isn't enforced.

Note that this class can be used just for a repeating background, it would be parallax if you had

another set of CCSprites on top that moved at a different speed ratio.

// EASY WAY FOR INFINITE PARALLAX

// Uses CCSpriteBatchNode for more efficient rendering when using a lot of sprites

parallax = [CCParallaxScrollNode makeWithBatchFile:@"parallax"];

// Create sprites (this refers to frames loaded by CCParallaxScrollNode, used for CCSpriteBatchNode)

CCSprite *clouds1 = [CCSprite spriteWithSpriteFrameName:@"clouds1.png"];

CCSprite *clouds2 = [CCSprite spriteWithSpriteFrameName:@"clouds2.png"];

// Easier way, the X in ScrollX means we will be moving in X axis, so line up sprites left to right

[parallax addInfiniteScrollXWithZ:0 Ratio:ccp(0.5,0.5) Pos:ccp(100,100) Objects:clouds1, clouds2, nil];

// Add to layer, sprite, etc.

[self addChild:parallax z:-1];

// MANUALLY - MORE CONTROL

// Doesn't use CCSpriteBatchNode

parallax = [CCParallaxScrollNode node];

// Create sprites from file

CCSprite *clouds1 = [CCSprite spriteWithFile:@"clouds1.png"];

CCSprite *clouds2 = [CCSprite spriteWithFile:@"clouds2.png"];

// Create 2 sprites, as one leaves screen, it is placed behind the other.

// This is what easy way does using addInfiniteObjects.

float totalWidth = 2 * clouds1.contentSize.width;

// Manually specify offset once the sprite moves off screen (e.g. to move it behind next object)

[parallax addChild:clouds1 z:0 Ratio:ccp(0.5,0.5) Pos:ccp(0,100) ScrollOffset:ccp(totalWidth,0)];

[parallax addChild:clouds2 z:0 Ratio:ccp(0.5,0.5) Pos:ccp(clouds1.contentSize.width,100) ScrollOffset:ccp(totalWidth,0)];

// Add to layer, sprite, etc.

[self addChild:parallax z:-1];

// MOVING THE PARALLAX

This part's the whole point. You need to tell the parallax to move, you can use:

float myVelocity = -4;

[parallax updateWithVelocity:ccp(myVelocity, 0) AndDelta:dt];

in your update method, with -4 meaning move left. You can change the velocity to anything to speed up

or slow down the parallax!

// FUNCTIONS DEFINITIONS

There are several functions included for adding, removing CCSprite children, as well as creating infinite parallax, which was the point of this class to begin with. Here's what everything means.

Ratio: When updating velocity of the parallax, by what ratio should the CCSprite move in X and Y?

This controls the magnitude of the parallax effect for each object. Make closer objects with

higher (X,Y) ratios (moving quickly) and distant objects with lower values.

Pos: The starting (X,Y) position of a CCSprite. If doing it manually, you'll want the second image starting

behind the first etc.

Dir: This tells the helper function addInfiniteScrollWithObjects:Z:Ratio:Pos:Dir: where to place the

second and subsequent images (on the left/right and top/bottom) of the first. For a left moving

parallax, this would have the direction as ccp(1,0) so the second CCSprite will be placed to the

right of the first. ccp(-1,0) would have it to the left, and would also look exactly the same.

What matters is the direction it is travelling in (due to the velocity in X and/or Y), which should

not be confused with the "Dir:" parameter. If using the helper functions:

addInfiniteScrollX... or addInfiniteScrollY...

you won't need to specify the Dir.

Z: The z-index.

Alex

Hi,
Thank you for the tutorial and provided info; I’m also trying to build a parallax effect similar as you did but with CCLayers… and I manage to scroll them but I don’t know to set the limit of the scroll to be the width of my back layer.

Cheers!
- Alex
  
  P.S. – Wanted to ask you if you know how to fix that
Aram

Hmm, I’ve read that it’s best to use a CCSpriteBatchNode and a bunch of CCSprites added to it for efficiency, as opposed to CCLayers which are more costly to render. Either way, your CCLayer is a CCSprite, so it shouldn’t be too hard to just use CCSprites, unless you’re using some methods specific to CCLayer. The general idea with my method is that you ensure the sprite is at least as wide as your screen width, then you make 2 copies of them, place on on the screen and the other next to it on the right. When the first moves to the left and off the screen, the sprite beside it moves onto the screen. Once the left sprite has moved off completely, it places itself behind the right one and becomes the new right. This keeps repeating and makes an infinite background, and with different speeds and overlaying you can create the parallax effect. That’s pretty much what my class above does.
teddy

how do I change the sprite that is following. for example have one sprite follow itself like you have above then after an amount of time change that sprite to another sprite??
I’ve seen it done in a game called jetpack joyride, where the background changes after an amount of time.
- Anonymous
  
  The methods above don’t contain logic for swapping sprites, that would be something you could write. So at some point where one of the sprites travels a certain distance you would remove both and add their replacements.
Guest

Hi!
Download link is broken.Could you fix it?
http://aramk.com/ Aram Kocharyan

Works fine for me…
http://www.facebook.com/profile.php?id=1645190136 Ahmad Ashraf Azman

i got small little problem. im usually move parallax node. when i try to use this approach the parallax didn’t move. When i see the code seem like you moving the child inside parallax rather than parallax node itself. Am i correct? and how to modified this code so i can move the parallax.
http://twitter.com/lilwins Little Wins, LLC

I ported this to Cocos2d-x (C++). I left out the batch features, still getting the hang of C++ and how it handles static classes. But otherwise it works pretty well.

Here’s a link to the github repo: https://github.com/jasonmarziani/CCParallaxScrollNode

Thanks for the work on this!
- http://aramk.com/ Aram Kocharyan
  
  Nicely done!
Pingback: List of Open Source Cocos2d Projects, Extensions and Code Snippets | iUridium
Jubun

Thanks For Share Tutorial It Gave me Lot Help
Allan

Hi,

Thanks for share this! I have some questions: With this class you created, I can choose which part of the parallax will be repeated and which will not? For example, the sky is a static element and other element are moving.

There is the possibility of parallax moving in the y-axis rather than the x-axis?