{"_id":"546a2ed0394c861a00c3a413","is_link":false,"__v":39,"project":"5463e333447e0a100024a087","category":{"_id":"5463e333447e0a100024a08b","project":"5463e333447e0a100024a087","pages":["5463e334447e0a100024a08d","54646a285871e90800f50174","54667e7af2b6390800dfd82a","54679c8c98b6840800268982","54679d8498b6840800268987","546a2ed0394c861a00c3a413","546b6a4862515a14007ebbba","547b1c2e7eec0f080099e1dd","55d33d90b9ef4435006dec70","56570c764d1c720d001f51bb"],"version":"5463e333447e0a100024a08a","__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-12T22:46:11.951Z","from_sync":false,"order":1,"slug":"documentation","title":"Documentation"},"user":"54639d06447e0a1000249f7f","version":{"_id":"5463e333447e0a100024a08a","project":"5463e333447e0a100024a087","__v":6,"createdAt":"2014-11-12T22:46:11.486Z","releaseDate":"2014-11-12T22:46:11.486Z","categories":["5463e333447e0a100024a08b","54645c365871e90800f50151","547b1c5a4366a708001b3b50","547b1cdf4366a708001b3b5a","54e3bef8464a9c3700f7ca67","54ec651d7ab3172d00c01ab7"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-11-17T17:22:24.572Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":8,"body":"Sprite is a 2D image or animation which is put inside a scene. Sprites are nodes like most things in Cocos.\n\nPopular image formats such as PNG's and JPG's are supported plus many other formats. [**For more information click here**](http://www.cocos2d-x.org/wiki/Texture_Formats_Supported_by_Cocos2d-x).\n\n##**Creating A Sprite** - with a filename (basic sprite creation). \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Sprite *coolSprite = Sprite::create( \\\"Image Filename.png\\\" );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"var coolSprite = new cc.Sprite( \\\"Image Filename.png\\\" );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\n##**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. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Sprite *coolSprite = Sprite::create( \\\"Image Filename.png\\\", Rect( 0, 0, 100, 50 ) );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"var coolSprite = new cc.Sprite( res.CloseNormal_png, cc.Rect( 0, 0, 100, 50 ) );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\nNote 1: *Rect( startingXPos, startingYPos, rectWidth, rectHeight )*\n\nNote 2: *Rects start at the top left corner unlike most things in Cocos which start in the bottom left corner.*\n\n##**Creating A Sprite With A Sprite Frame Cache** - uses a sprite frame from the cache \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"SpriteFrameCache *spriteCache = SpriteFrameCache::getInstance();\\n\\nspriteCache->addSpriteFramesWithFile( \\\"spriteSheet.plist\\\" );\\n\\nSprite *coolSprite = Sprite::createWithSpriteFrameName( \\\"coolFrameName.png\\\" );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"cc.spriteFrameCache.addSpriteFrames( \\\"spriteSheet.plit\\\" );\\n\\nvar coolSprite = new cc.Sprite( spriteFrameCache.getSpriteFrame( \\\"coolFrameName.png\\\" ) );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\nNote: *\"coolFrameName.png\" is part of the sprite sheet and should be renamed to whatever your frame name is.*\n\nThe following tools can be used to create sprite sheets:\n  * Texture Packer - free version and a paid version\n  * Cocos Studio - free plus is a tool created by Chukong\n  * Zwoptex - free version and a paid version\n\n##**Creating A Sprite With A Sprite Frame** - uses a sprite frame from a sprite sheet. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"SpriteFrameCache *spriteCache = SpriteFrameCache::getInstance();\\n\\nspriteCache->addSpriteFramesWithFile( \\\"spriteSheet.plist\\\" );\\n\\nSpriteFrameCache *frameCache = SpriteFrameCache::getInstance()->getSpriteFrameByName( \\\"coolFrameName.png\\\" );\\n\\nSprite *coolSprite = Sprite::createWithSpriteFrame( frameCache );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"cc.spriteFrameCache.addSpriteFrames( \\\"spriteSheet.plit\\\" );\\n\\nvar coolSprite = new cc.Sprite( \\\"coolFrameName.png\\\" );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\nNote: *\"coolFrameName.png\" is part of the sprite sheet and should be renamed to whatever your frame name is.*\n\nThe following tools can be used to create sprite sheets:\n  * Texture Packer - free version and a paid version\n  * CocoStudio - free plus is a tool created by Chukong\n  * Zwoptex - free version and a paid version\n\n##**Creating A Sprite With A Texture** - uses a texture which is a cached image to create the sprite. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Texture2D *coolTexture = Director::getInstance( )->getTextureCache( )->addImage( \\\"Coolest Image.png\\\" );\\n\\nSprite *coolSprite = Sprite::createWithTexture( coolTexture );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"cc.textureCache.addImage( \\\"Cool Image.png\\\" );\\n\\nvar coolSprite = new cc.Sprite( \\\"Cool Image.png\\\" );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\n##**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. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Texture2D *coolTexture = Director::getInstance( )->getTextureCache( )->addImage( \\\"Coolest Image.png\\\" );\\n\\nSprite *coolSprite = Sprite::create( \\\"Coolest Image.png\\\", Rect( 0, 0, 100, 50 ) );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"cc.textureCache.addImage( \\\"Cool Image.png\\\" );\\n\\nvar coolSprite = new cc.Sprite( \\\"Cool Image.png\\\", cc.Rect( 0, 0, 100, 50 ) );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\nNote 1: *cc.rect( startingXPos, startingYPos, rectWidth, rectHeight )*\n\nNote 2: *cc.rect start at the top left corner unlike most things in Cocos which start in the bottom left corner.*\n\n##**Sprite Frame Properties** - you can get and set the sprite frame after initialisation. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// getting the sprite frame (returns a SpriteFrame *)\\nsprite->getSpriteFrame( );\\n\\n// get sprite frame cache\\nSpriteFrameCache *frameCache = SpriteFrameCache::getInstance()->getSpriteFrameByName( \\\"coolFrameName.png\\\" );\\n\\n// set sprite frame using a frame cache\\nsprite->setSpriteFrame( frameCache );\\n\\n// set sprite frame using the frame name\\nsprite->setSpriteFrame( \\\"coolFrameName.png\\\" );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"// in Cocos2d-JS you can only get a texture not a sprite frame\\n\\n// set sprite frame using a frame cache\\ncoolSprite.setSpriteFrame( spriteFrameCache.getSpriteFrame( \\\"coolFrameName.png\\\" ) );\\n\\n// set sprite frame using the frame name\\ncoolSprite.setSpriteFrame( \\\"coolFrameName.png\\\" );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\nNote: *\"coolFrameName.png\" is part of a sprite sheet that has been loaded into cache and should be renamed to whatever your frame name is.*\n\n##**Sprite Texture Properties** - you can get and set the sprite texture after initialisation. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// getting the sprite texture (returns a Texture2D *)\\ncoolSprite->getTexture( );\\n\\n// set texture using a image\\ncoolSprite->setTexture( \\\"coolImage.png\\\" );\\n\\n// set texture using a Texture2D\\ncoolSprite->setTexture( texture );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"// getting the sprite texture (returns a cc.Texture2D)\\ncoolSprite.getTexture( );\\n\\n// set texture using a image\\ncoolSprite.setTexture( \\\"coolImage.png\\\" );\\n\\n// set texture using a cc.Texture2D\\ncoolSprite.setTexture( texture );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\n##**Sprite Texture Rect Properties** - you can get and set the sprite's texture rect size after initialisation \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// getting the sprite texture rect (returns a Rect &)\\ncoolSprite->getTextureRect( );\\n\\n// set the texture rect\\ncoolSprite->setTextureRect( Rect( 0, 0, 100, 50 ) );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    },\n    {\n      \"code\": \"// getting the sprite texture rect (returns a cc.Rect)\\ncoolSprite.getTextureRect( );\\n\\ncoolSprite.setTextureRect( cc.Rect( 0, 0, 100, 50 ) );\",\n      \"language\": \"javascript\",\n      \"name\": \"Cocos2d-JS\"\n    }\n  ]\n}\n[/block]\nNote 1: *Rect( startingXPos, startingYPos, rectWidth, rectHeight )*\n\nNote 2: *Rects start at the top left corner unlike most things in Cocos which start in the bottom left corner.*","excerpt":"This page will cover how Cocos handles sprites.","slug":"frequently-asked-questions-2","type":"basic","title":"Sprites"}

Sprites

This page will cover how Cocos handles 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**](http://www.cocos2d-x.org/wiki/Texture_Formats_Supported_by_Cocos2d-x). ##**Creating A Sprite** - with a filename (basic sprite creation). [block:code] { "codes": [ { "code": "Sprite *coolSprite = Sprite::create( \"Image Filename.png\" );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "var coolSprite = new cc.Sprite( \"Image Filename.png\" );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] ##**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. [block:code] { "codes": [ { "code": "Sprite *coolSprite = Sprite::create( \"Image Filename.png\", Rect( 0, 0, 100, 50 ) );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "var coolSprite = new cc.Sprite( res.CloseNormal_png, cc.Rect( 0, 0, 100, 50 ) );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] 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 [block:code] { "codes": [ { "code": "SpriteFrameCache *spriteCache = SpriteFrameCache::getInstance();\n\nspriteCache->addSpriteFramesWithFile( \"spriteSheet.plist\" );\n\nSprite *coolSprite = Sprite::createWithSpriteFrameName( \"coolFrameName.png\" );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "cc.spriteFrameCache.addSpriteFrames( \"spriteSheet.plit\" );\n\nvar coolSprite = new cc.Sprite( spriteFrameCache.getSpriteFrame( \"coolFrameName.png\" ) );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] 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. [block:code] { "codes": [ { "code": "SpriteFrameCache *spriteCache = SpriteFrameCache::getInstance();\n\nspriteCache->addSpriteFramesWithFile( \"spriteSheet.plist\" );\n\nSpriteFrameCache *frameCache = SpriteFrameCache::getInstance()->getSpriteFrameByName( \"coolFrameName.png\" );\n\nSprite *coolSprite = Sprite::createWithSpriteFrame( frameCache );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "cc.spriteFrameCache.addSpriteFrames( \"spriteSheet.plit\" );\n\nvar coolSprite = new cc.Sprite( \"coolFrameName.png\" );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] 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. [block:code] { "codes": [ { "code": "Texture2D *coolTexture = Director::getInstance( )->getTextureCache( )->addImage( \"Coolest Image.png\" );\n\nSprite *coolSprite = Sprite::createWithTexture( coolTexture );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "cc.textureCache.addImage( \"Cool Image.png\" );\n\nvar coolSprite = new cc.Sprite( \"Cool Image.png\" );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] ##**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. [block:code] { "codes": [ { "code": "Texture2D *coolTexture = Director::getInstance( )->getTextureCache( )->addImage( \"Coolest Image.png\" );\n\nSprite *coolSprite = Sprite::create( \"Coolest Image.png\", Rect( 0, 0, 100, 50 ) );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "cc.textureCache.addImage( \"Cool Image.png\" );\n\nvar coolSprite = new cc.Sprite( \"Cool Image.png\", cc.Rect( 0, 0, 100, 50 ) );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] 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. [block:code] { "codes": [ { "code": "// getting the sprite frame (returns a SpriteFrame *)\nsprite->getSpriteFrame( );\n\n// get sprite frame cache\nSpriteFrameCache *frameCache = SpriteFrameCache::getInstance()->getSpriteFrameByName( \"coolFrameName.png\" );\n\n// set sprite frame using a frame cache\nsprite->setSpriteFrame( frameCache );\n\n// set sprite frame using the frame name\nsprite->setSpriteFrame( \"coolFrameName.png\" );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "// in Cocos2d-JS you can only get a texture not a sprite frame\n\n// set sprite frame using a frame cache\ncoolSprite.setSpriteFrame( spriteFrameCache.getSpriteFrame( \"coolFrameName.png\" ) );\n\n// set sprite frame using the frame name\ncoolSprite.setSpriteFrame( \"coolFrameName.png\" );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] 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. [block:code] { "codes": [ { "code": "// getting the sprite texture (returns a Texture2D *)\ncoolSprite->getTexture( );\n\n// set texture using a image\ncoolSprite->setTexture( \"coolImage.png\" );\n\n// set texture using a Texture2D\ncoolSprite->setTexture( texture );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "// getting the sprite texture (returns a cc.Texture2D)\ncoolSprite.getTexture( );\n\n// set texture using a image\ncoolSprite.setTexture( \"coolImage.png\" );\n\n// set texture using a cc.Texture2D\ncoolSprite.setTexture( texture );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] ##**Sprite Texture Rect Properties** - you can get and set the sprite's texture rect size after initialisation [block:code] { "codes": [ { "code": "// getting the sprite texture rect (returns a Rect &)\ncoolSprite->getTextureRect( );\n\n// set the texture rect\ncoolSprite->setTextureRect( Rect( 0, 0, 100, 50 ) );", "language": "cplusplus", "name": "Cocos2d-x C++" }, { "code": "// getting the sprite texture rect (returns a cc.Rect)\ncoolSprite.getTextureRect( );\n\ncoolSprite.setTextureRect( cc.Rect( 0, 0, 100, 50 ) );", "language": "javascript", "name": "Cocos2d-JS" } ] } [/block] 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.*