Sprites

Sprite is a 2D image or animation which is put inside a scene. Sprites are nodes like most things in Cocos.

Popular image formats such as PNG's and JPG's are supported plus many other formats. For more information click here.

Creating A Sprite - with a filename (basic sprite creation).

Sprite *coolSprite = Sprite::create( "Image Filename.png" );

var coolSprite = new cc.Sprite( "Image Filename.png" );

Creating A Sprite With A Rect - with a filename and a rect size (create the sprite with only a certain portion of the image). Without specifying the rect size the sprite will use the entire image.

Sprite *coolSprite = Sprite::create( "Image Filename.png", Rect( 0, 0, 100, 50 ) );

var coolSprite = new cc.Sprite( res.CloseNormal_png, cc.Rect( 0, 0, 100, 50 ) );

Note 1: Rect( startingXPos, startingYPos, rectWidth, rectHeight )

Note 2: Rects start at the top left corner unlike most things in Cocos which start in the bottom left corner.

Creating A Sprite With A Sprite Frame Cache - uses a sprite frame from the cache

SpriteFrameCache *spriteCache = SpriteFrameCache::getInstance();

spriteCache->addSpriteFramesWithFile( "spriteSheet.plist" );

Sprite *coolSprite = Sprite::createWithSpriteFrameName( "coolFrameName.png" );

cc.spriteFrameCache.addSpriteFrames( "spriteSheet.plit" );

var coolSprite = new cc.Sprite( spriteFrameCache.getSpriteFrame( "coolFrameName.png" ) );

Note: "coolFrameName.png" is part of the sprite sheet and should be renamed to whatever your frame name is.

The following tools can be used to create sprite sheets:

Texture Packer - free version and a paid version
Cocos Studio - free plus is a tool created by Chukong
Zwoptex - free version and a paid version

Creating A Sprite With A Sprite Frame - uses a sprite frame from a sprite sheet.

SpriteFrameCache *spriteCache = SpriteFrameCache::getInstance();

spriteCache->addSpriteFramesWithFile( "spriteSheet.plist" );

SpriteFrameCache *frameCache = SpriteFrameCache::getInstance()->getSpriteFrameByName( "coolFrameName.png" );

Sprite *coolSprite = Sprite::createWithSpriteFrame( frameCache );

cc.spriteFrameCache.addSpriteFrames( "spriteSheet.plit" );

var coolSprite = new cc.Sprite( "coolFrameName.png" );

Note: "coolFrameName.png" is part of the sprite sheet and should be renamed to whatever your frame name is.

The following tools can be used to create sprite sheets:

Texture Packer - free version and a paid version
CocoStudio - free plus is a tool created by Chukong
Zwoptex - free version and a paid version

Creating A Sprite With A Texture - uses a texture which is a cached image to create the sprite.

Texture2D *coolTexture = Director::getInstance( )->getTextureCache( )->addImage( "Coolest Image.png" );

Sprite *coolSprite = Sprite::createWithTexture( coolTexture );

cc.textureCache.addImage( "Cool Image.png" );

var coolSprite = new cc.Sprite( "Cool Image.png" );

Creating A Sprite With A Texture And Rect - uses a texture which is a cached image to create the sprite (create the sprite with only a certain portion of the texture). Without specifying the rect size the sprite will use the entire texture.

Texture2D *coolTexture = Director::getInstance( )->getTextureCache( )->addImage( "Coolest Image.png" );

Sprite *coolSprite = Sprite::create( "Coolest Image.png", Rect( 0, 0, 100, 50 ) );

cc.textureCache.addImage( "Cool Image.png" );

var coolSprite = new cc.Sprite( "Cool Image.png", cc.Rect( 0, 0, 100, 50 ) );

Note 1: cc.rect( startingXPos, startingYPos, rectWidth, rectHeight )

Note 2: cc.rect start at the top left corner unlike most things in Cocos which start in the bottom left corner.

Sprite Frame Properties - you can get and set the sprite frame after initialisation.

// getting the sprite frame (returns a SpriteFrame *)
sprite->getSpriteFrame( );

// get sprite frame cache
SpriteFrameCache *frameCache = SpriteFrameCache::getInstance()->getSpriteFrameByName( "coolFrameName.png" );

// set sprite frame using a frame cache
sprite->setSpriteFrame( frameCache );

// set sprite frame using the frame name
sprite->setSpriteFrame( "coolFrameName.png" );

// in Cocos2d-JS you can only get a texture not a sprite frame

// set sprite frame using a frame cache
coolSprite.setSpriteFrame( spriteFrameCache.getSpriteFrame( "coolFrameName.png" ) );

// set sprite frame using the frame name
coolSprite.setSpriteFrame( "coolFrameName.png" );

Note: "coolFrameName.png" is part of a sprite sheet that has been loaded into cache and should be renamed to whatever your frame name is.

Sprite Texture Properties - you can get and set the sprite texture after initialisation.

// getting the sprite texture (returns a Texture2D *)
coolSprite->getTexture( );

// set texture using a image
coolSprite->setTexture( "coolImage.png" );

// set texture using a Texture2D
coolSprite->setTexture( texture );

// getting the sprite texture (returns a cc.Texture2D)
coolSprite.getTexture( );

// set texture using a image
coolSprite.setTexture( "coolImage.png" );

// set texture using a cc.Texture2D
coolSprite.setTexture( texture );

Sprite Texture Rect Properties - you can get and set the sprite's texture rect size after initialisation

// getting the sprite texture rect (returns a Rect &)
coolSprite->getTextureRect( );

// set the texture rect
coolSprite->setTextureRect( Rect( 0, 0, 100, 50 ) );

// getting the sprite texture rect (returns a cc.Rect)
coolSprite.getTextureRect( );

coolSprite.setTextureRect( cc.Rect( 0, 0, 100, 50 ) );

Note 1: Rect( startingXPos, startingYPos, rectWidth, rectHeight )

Note 2: Rects start at the top left corner unlike most things in Cocos which start in the bottom left corner.