Sprite Sheet

Blog Store Support

TexturePacker

TexturePacker3D

SpriteIlluminator

PhysicsEditor

BabelEdit

Features Tutorials Documentation Support Download Store

TexturePacker

Features Tutorials Documentation Support Download Store

Tutorial: Using sprite sheet animations in cocos2d-x V3

Andreas Löw

texturepacker, tutorial, cocos2d-x

GitHub

Tutorial: Using sprite sheet animations in cocos2d-x V3

This tutorial is for cocos2d-x V3.

We recently wanted to upgrade it to cocos2d-x V4 but found out, that the framework is not supported anymore. The company behind cocos2d sets more and more focus on Cocos Creator and totally neglects the c++ community.

While researching options for our readers, we found a cocos2d-x fork called Axmol Engine that gets regular updates and fixed.

If you want to get started with game development in c++, this is the right place: Using sprite sheet animations in Axmol Engine

What you are going to learn from this tutorial

In this tutorial you are going to learn:

Why you should use sprite sheets
Designing and running your game on different devices and screen sizes
Creating optimized sprite sheets
Creating animations
Playing character animations

In short: Develop once, make money on all platforms.

The source code for this tutorial is available on GitHub.

Basic Project

I'll describe how to set up Cocos2d-x for a build and create a basic project in this section. If you are already familiar with Cocos2d-x, you can skip ahead to the next chapter.

This section describes how you can get cocos2d-x running on a Mac with Xcode. Instruction for other operating systems are available from the cocos2d-x homepage.

Start by downloading Cocos2d-x from https://github.com/cocos2d/cocos2d-x/tree/v3. The tutorial is created using 3.16 - all parts except for the polygon packing should also work with older releases, too.

Unzip the downloaded file and move in a location where you want to keep your installation.

Open a command line interface and change the directory to the Cocos2d-x installation and run the setup

cd cocos2d-x-3.16
python setup.py

The command asks you about the locations of your different build environments. Enter the paths if you want to build for Android. You can press Enter if you are on a Mac and just want to build for macOS or iOS.

Note: Cocos2D-x requires Python 2.7 which is outdated. macOS ships with Python 3 - and for that does not work. You have to download the old Python interpreter from here, both on macOS and Windows: Python 2.7 Download

Finally close and re-open the command line. You now have a new command available: cocos

You'll use this command to create new projects.

Creating your first game

Enter the following command to create a new empty project:

cocos new -l cpp -d ~/cocos2d-x-games Cocos2dx-SpriteSheetTutorial

Note : If you see the following error: ValueError: unknown local: UTF-8
set the locale variables before running cocos and try again:
export LC_ALL=en_US.UTF-8<br/> export LANG=en_US.UTF-8

This line creates a new cocos2d-x project in a subfolder of your home directory called cocos2d-x-games . Inside the folder, a project is created called Cocos2dx-SpriteSheetTutorial .

The selected language is c++ (cpp). You could also create games using Lua or Javascript - this tutorial's focus is on c++.

You find a bunch of folders, all starting with the prefix "proj." These folders contain files for the different supported development environments - which includes Visual Studio and XCode - and some platform specific code required to start the App.

It does not matter which platform you choose for development. Choose the environment you like most. Just build on the other platforms you want to support from time to time.

The important thing is that you stay away from platform-specific code and libraries. Cocos2d-x should give you a good base for all kinds of games.

I am writing this tutorial on a Mac, using XCode, with the focus on keeping things portable. It should be easy for you to follow the tutorial on other systems. The only difference is how you add the files to the project and how you start the simulator.

Running the project on a Mac opens the iOS Simulator. What you see is the standard Hello World application.

The application contains 2 classes: The AppDelegate and the HelloWorldScene .

Why you should use sprite sheets

You want to use different sprites and animations in your game. The naive approach is to add them all to your project and create a loop that loads them one after the other.

That's a bad idea for several reasons:

loading each file takes time
each sprite has to be loaded into the graphics memory separately
switching between the textures is expensive
sprites can't be optimized to reduce overdraw

Take a look at this sprite. I've taken it from a walk animation of the character you are going to use later in this tutorial. The transparency around the sprite is required to align the animation phases:

Transparency seems to consist of nothing but that's not the case for the graphics processor (GPU). It has to do the blending for each pixel — no matter if it's visible or not. Take a look at the checkered regions. The total overhead coming from the transparency for this animation is 68%.

The trick is preventing the GPU from working on these transparent pixels. A simple way is to reduce the area to the rectangle containing all non-transparent pixels. This reduces the amount of transparency by 24%.

The even better solution is to create polygons matching the sprite's non-transparent areas.

The good news is: You don't have to care about it when you are using TexturePacker — it can create rectangular and polygon trimmed shapes for your sprites in a format that cocos2d-x can read out of the box.

Designing for different resolutions

cocos2d-x is a highly portable game development framework - which takes a lot of work from you when you want to support different devices. The same code should run on all of them.

But you have to be careful about the design. Some of the devices will come with a 4:3 aspect ratio (like iPad), some come with 16:9 like several mobile phones and some come with strange sizes in between.

Mobile phone stats

Newer phones come with a higher screen resolution — but there are still many old phones in use. Take a look at this chart: It shows screen resolutions from mobile phones and tablets, start of 2023.

Screen view port sizes: Desktop, January 2023

Screen view port sizes: Tablet, January 2023

Screen view port sizes: Mobile, January 2023

These numbers might seem low in some cases. This is because the values in the charts do not take the device pixel ration in account.

E.g. an iPhone 13 reports the view port size as 390 x 844 with a 3x density. That means that the "real" resolution of the screen is 1170 x 2532.

Different resolutions

Different resolutions is not a problem as long as your games does not require many detailed objects and small fonts. You can simply design your game at the highest resolution and scale the images down for the smaller devices.

Memory is an issue on smaller devices combined with low performance. For these devices it's a good idea to create scaled down versions of your sprite sheets and only load the sheets with the appropriate resolutions. A true color 2048x2048 sprite sheet requires 16MB of RAM — scaled down to 50% it's just 4MB.

TexturePacker can create scaled versions of the sprite sheets on the fly.

Different aspect ratios

Aspect ratio is a bit more trouble since it has an effect on game play. You have 3 choices:

Design separate screens for 4:3 and 16:9
Design for 16:9 or 4:3 and add black bars
Design for 16:9 and extend your art to fill 4:3

Using black bars - score moved outside of screen

Using black bars - score moved outside of the game scene

Extending the scene - the tablet has more sky and ground

The first option might be the best - but it's the one with the most work on your side. It also changes the game - e.g. more enemies are visible.

The second one feels a bit like in the 90ies.

I prefer the third - it gives all players the same gameplay. The assets for this tutorial are created for 4:3 but the main content will be focused on 16:9.

Creating sprite sheets with TexturePacker

Start by downloading and installing TexturePacker if you've not already done it.

Download TexturePacker 7.7.0

for Windows

Also available for macOS and Linux

Drag & drop the cityscene folder onto the left panel. TexturePacker adds all contained sprites to your sheet. This preserves the file name structure inside the folder. It also updates the sprite sheet when you add or remove files from the folder.

Select cocos2d-x as Data Format . Don't use the cocos2d format — it does not contain polygon packing.

Enable the polygon mode: Change the Trim mode to polygon . This also enables polygon packing. You can adjust the Tracer tolerance to change the amount of vertices created for the sprites. Tighter fitting polygons create less overdraw but have a higher vertex count. Try to keep the vertex count low because each vertex required CPU time for calculating its position.

The sprite sheet here comes still with high overdraw of 95% — this is because of the background image. It's rectangular and has no transparency to trim.

Add scaling variants for the different device sizes. Click on Scaling variants in the right panel. Select cocos2d-x HDR/HD/SD from the drop-down menu in the dialog. Press Apply . You see 3 scaling variants: /HDR/ with a scaling factor of 1, /HD/ with a factor of 0.5 and /SD/ with 0.25. You can add or remove scaling variants if you don't want them. Press Close to return to the sprite sheet.

You should now see 3 tabs in the center screen. Each one is a preview of the sprite sheet created for that scaling variant.

Click the small folder next to Data file and set it to save a file names cityscene.png inside your project's res folder. This will give you an error, informing you that you have to add a placeholder {v} as part of your file name. Edit the file name and change it from .../res/cityscene.plist to .../res/{v}/cityscene.plist . The placeholder is replaced with the scaling variant name when writing the sprite sheets.

Press Publish sprite sheet in the toolbar. You should now see 6 files in your project folder:

res
- HDR
  - cityscene.plist
  - cityscene.png
- HD
  - cityscene.plist
  - cityscene.png
- SD
  - cityscene.plist
  - cityscene.png

That's it for now in TexturePacker.

Application startup and device resolutions

Let's now start with the code. Before you can use the sprite sheets you now have to lay the foundation for a solid game. Your game code should be free of resolution dependent code if you get the setup right in the AppDelegate.

Replace the content of AppDelegate.h with this code block:

#ifndef _APP_DELEGATE_H_

#define _APP_DELEGATE_H_

#include "cocos2d.h"

class AppDelegate : private cocos2d::Application

{

public:

virtual void initGLContextAttrs();

virtual bool applicationDidFinishLaunching();

virtual void applicationDidEnterBackground();

virtual void applicationWillEnterForeground();

private:

void initOpenGL();

void initMultiResolution();

void initDirector();

void createAndRunScene();

};

#endif

The public virtual methods will be called on different occasions during the application's runtime. You have to implement them because they are declared pure virtual in the ApplicationProtocol. The private methods help us to get some better structure in the startup process.

Clear the code in AppDelegate.cpp and start with this code:

#include "AppDelegate.h"

#include "HelloWorldScene.h"

USING_NS_CC;

static cocos2d::Size designResolutionSize = cocos2d::Size(2048, 1536);

static cocos2d::Size smallResolutionSize = cocos2d::Size(512, 384);

static cocos2d::Size mediumResolutionSize = cocos2d::Size(1024, 768);

static cocos2d::Size largeResolutionSize = cocos2d::Size(2048, 1536);

The designResolutionSize is the size you used for designing the game. You can set it to whatever size you want but there are 2 values that make the most sense:

(512, 384): 1 unit in your game corresponds with 1 pixel in the lowest resolution.
(2048x1536): 1 unit in your game corresponds with 1 pixel in your art.

Getting pixel perfect designs working with cocos2d-x is hard — simply because you'll have to deal with a bunch of different target sizes — especially if you want to run your game on Android devices. But even the iOS devices come with all different sizes and screen ratios.

I personally prefer using the higher resolution as designResolutionSize because it allows you to measure sizes and positions in your graphics program. But: An object placed on a coordinate that is not divisible by the scaling factor 4 will be placed between pixels and trigger sub-pixel rendering on lower resolution devices. This might sound like a problem but since there is additional scaling from the design resolution to the device resolution it's not a real restriction.

The following 3 values smallResolutionSize , mediumResolutionSize and largeResolutionSize represent the screen sizes scaled down for different devices. The sizes have to correspond to the scaling variants set up in TexturePacker.

Add the following method, it is responsible for loading the pre-scaled versions of the graphics:

void AppDelegate::initMultiResolution()
{
    auto director = Director::getInstance();
    auto glview = director->getOpenGLView();

    glview->setDesignResolutionSize(
            designResolutionSize.width,
            designResolutionSize.height,
            ResolutionPolicy::NO_BORDER
    );

    ...

The first part of this code setDesignResolutionSize sets the mapping of the defined design resolution size on the display. The interesting parameter is the last one: ResolutionPolicy::NO_BORDER . This means that the complete screen will be filled with our game — no borders. There are other options you can use:

Value	Description
`EXACT_FIT`	Matches the design resolution to the screen but does not keep the aspect ratio. The result might be that the whole game screen is distorted.
`NO_BORDER`	Preserves the aspect ratio of the application, some parts of the game scene might be outside of the screen and not be visible.
`SHOW_ALL`	Preserves the aspect ratio of the application and scales the design resolution size to completely fit on the screen. Black bars are added on 2 sides if the aspect ratio of the screen does not match the design.
`FIXED_HEIGHT`	Uses the height of the design resolution size and adjusts the width to fit the aspect ratio of the screen.
`FIXED_WIDTH`	Uses the width of the design resolution size and adjusts the height to fit the aspect ratio of the screen.

EXACT_FIT might not really be an option when using sprites. NO_BORDER might be the easiest to use.

Finish initMultiResolution() with the following lines:

    std::vector<std::string> searchPaths;
    float scaleFactor = 1.0f;
    Size frameSize = glview->getFrameSize();

    if (frameSize.height > mediumResolutionSize.height)
    {
        searchPaths.push_back("res/HDR");
        scaleFactor = largeResolutionSize.height/designResolutionSize.height;
    }
    else if (frameSize.height > smallResolutionSize.height)
    {
        searchPaths.push_back("res/HD");
        scaleFactor = mediumResolutionSize.height/designResolutionSize.height;
    }
    else
    {
        searchPaths.push_back("res/SD");
        scaleFactor = smallResolutionSize.height/designResolutionSize.height;
    }

    director->setContentScaleFactor(scaleFactor);
    FileUtils::getInstance()->setSearchPaths(searchPaths);
}

getFrameSize() delivers the size of the display. The following if block evaluates our pre-scaled resolutions against the display height, always using the higher resolution and scaling down.

Display height	Sprite sheet
`h < 512`	SD
`513 < h < 1024`	HD
`h > 1024`	HDR

The code also sets the search path for the resources. This is a big help because the application can now always load the cityscene.plist — the decision which one is loaded is handled by cocos2d itself.

Some mode code is required to implement the application. Simply copy this code block — it's required to create the OpenGL view:

Additional code required in the AppDelegate

These code blocks are also required in the AppDelegate . They are responsible for the setup and for sending your game to the background / foreground.

void AppDelegate::initOpenGL()
{
    auto director = Director::getInstance();
    auto glview = director->getOpenGLView();
    if(!glview)
    {
        #if (CC_TARGET_PLATFORM == CC_PLATFORM_WIN32) ||
            (CC_TARGET_PLATFORM == CC_PLATFORM_MAC) ||
            (CC_TARGET_PLATFORM == CC_PLATFORM_LINUX)
        glview = GLViewImpl::createWithRect("Cocos2dx-SpriteSheetTutorial",
            Rect(0, 0, designResolutionSize.width, designResolutionSize.height));
        #else
        glview = GLViewImpl::create("Cocos2dx-SpriteSheetTutorial");
        #endif
        director->setOpenGLView(glview);
    }
}

The following code block initialises the Director — setting the frame rate for animations. It also enables some stats which are printed in the bottom-left corner of the screen.

void AppDelegate::initDirector()
{
    auto director = Director::getInstance();
    director->setAnimationInterval(1.0 / 60);
    director->setDisplayStats(true);
}

The following method creates your game scene and activates it in the Director . You'll create the HelloWorld scene later.

void AppDelegate::createAndRunScene()
{
    auto scene = HelloWorld::createScene();
    Director::getInstance()->runWithScene(scene);
}

This method calls all the previous methods when the application is ready to run.

bool AppDelegate::applicationDidFinishLaunching()
{
    initOpenGL();
    initDirector();
    initMultiResolution();
    createAndRunScene();
    return true;
}

The following 2 functions are called when your application goes into background or re-gains focus. Use it to stop all animations and the music. You can also use it in your game to pause all other calculations etc.

void AppDelegate::applicationDidEnterBackground()
{
    Director::getInstance()->stopAnimation();
    // SimpleAudioEngine::getInstance()->pauseBackgroundMusic();
}

void AppDelegate::applicationWillEnterForeground()
{
    Director::getInstance()->startAnimation();
    // SimpleAudioEngine::getInstance()->resumeBackgroundMusic();
}

The final method required is the initGLContextAttrs() — it prepares the OpenGL context for rendering. Just leave it like this if you don't have an important reason to reduce the amount of colors.

void AppDelegate::initGLContextAttrs()
{
    //set OpenGL context attributions,now can only set six attributions:
    //red,green,blue,alpha,depth,stencil
    GLContextAttrs glContextAttrs = {8, 8, 8, 8, 24, 8};
    GLView::setGLContextAttrs(glContextAttrs);
}

Using the sprite sheets

After the less interesting tasks of initializing the app you'll now get the sprite sheets to work.

Start with HelloWorldScene.h using the following code block:


#ifndef __HELLOWORLD_SCENE_H__
#define __HELLOWORLD_SCENE_H__

#include "cocos2d.h"

class HelloWorld : public cocos2d::Layer
{
public:
    static cocos2d::Scene* createScene();
    virtual bool init();
    CREATE_FUNC(HelloWorld);

private:
    cocos2d::Vector<cocos2d::SpriteFrame*> getAnimation(const char *format, int count);
};

#endif

It contains 4 method declarations:

createScene()
Creates a Scene object that contains the HelloWorld layer. A Scene is a container class holding the layers and game objects. It's required by the Director. You've used this method with runWithScene() in AppDelegate::createAndRunScene.
init()
Init initialises the HelloWorld object, creates the game objects and animations.
CREATE_FUNC(HelloWorld)
CREATE_FUNC is a macro that creates a static method HelloWorld::create(). This method creates a new HelloWorld object, initialises the memory management and calls init().
getAnimation()
This method will help your creating animations from the sprite sheet.

Now switch to HelloWorldScene.cpp .

#include "HelloWorldScene.h"

USING_NS_CC;

Scene* HelloWorld::createScene()
{
    auto scene = Scene::create();
    auto layer = HelloWorld::create();
    scene->addChild(layer);
    return scene;
}

As already mentioned above: This method wraps the HelloWorld Layer object into Scene object that you can pass to the Director.

Adding a static background

The next method you have to add is init() :

bool HelloWorld::init()
{
    if ( !Layer::init() )
    {
        return false;
    }

    SpriteFrameCache::getInstance()->addSpriteFramesWithFile("cityscene.plist");

    Vec2 origin = Director::getInstance()->getVisibleOrigin();
    Vec2 visibleSize = Director::getInstance()->getVisibleSize();

    // background
    auto background = Sprite::createWithSpriteFrameName("background.png");
    background->setPosition(origin.x + visibleSize.x / 2,origin.y + visibleSize.y/2);
    this->addChild(background);

    return true;
}

The first block is required to get the Layer super class initialized.

You have to load the sprite sheet before you can use it. The addSpriteFramesWithFile does this for you. The plist file contains a reference to the sprite sheet texture file — which is loaded automatically.

Note that this code does not contain anything that is resolution dependent. The code in AppDelegate ensures that addSpriteFramesWithFile loads the resources of the required size.

The next 2 lines return the bottom left corner of the screen as origin and the size of the display as visibleSize . All coordinates are returned in the design resolution. You'll use these 2 variables to center the background in the next code block.

Call Sprite::createWithSpriteFrameName() to create a new sprite. The sprite name parameter is the name of the sprite added to TexturePacker.

The calculation performed for setPosition centers the background image on the screen. On 4:3 displays you'll see more sky and street — on 16:9 the game will be more focused on the center.

The final line in this block adds the background object as child of the game layer.

Compile and run, you should now see the following scene

Playing animations

You have to tell cocos2d-x which sprite frames should be used in an animation. The easiest way for this is to create a helper method that creates a list:

Vector<SpriteFrame*> HelloWorld::getAnimation(const char *format, int count)
{
    auto spritecache = SpriteFrameCache::getInstance();
    Vector<SpriteFrame*> animFrames;
    char str[100];
    for(int i = 1; i <= count; i++)
    {
        sprintf(str, format, i);
        animFrames.pushBack(spritecache->getSpriteFrameByName(str));
    }
    return animFrames;
}

This method retrieves the animation frames from the sprite sheet that follow a given format. You can call it in the following way:

Vector<SpriteFrame*> frames = getAnimation("capguy/walk/%04d.png", 8);

The format string %04d creates 4-digit numbers prefixed with 0: 0001 , 0002 , 0003 ,...

The call returns a list of 8 sprite frames: capguy/walk/0001.png ,... capguy/walk/0008.png

Add the following code block to the bottom of the init() method in HelloWorldScene.cpp before the return true :

// sprite
auto frames = getAnimation("capguy/walk/%04d.png", 8);
auto sprite = Sprite::createWithSpriteFrame(frames.front());
background->addChild(sprite);
sprite->setPosition(100,620);

auto animation = Animation::createWithSpriteFrames(frames, 1.0f/8);
sprite->runAction(RepeatForever::create(Animate::create(animation)));

The first line is the one you already know from above — to create the animation frames. The second creates a sprite using the first frame from the list.

You add the sprite as child of the background, not as child of the scene. This ensures that the sprite is always positioned in the right spot on the background.

The second block creates an Animation object with the sprite frames. The 1.0f/8 is the frame rate. It's playing 8 frames in 1 second. Make sure to write 1.0f/8 and not 1/8 . The latter is an integer division resulting in 0 — so the animation will never play!

The last line of the block chains 3 function calls:

creating an Animate object, responsible for playing the animation
a RepeatForever object that repeats the animation
the assignment of the RepeatForever to the sprite

Compile and run - you should now see Capguy walking in place.

Moving the sprite

Let's now make Capguy move from left to right. cocos2d-x comes with a MoveTo action. It takes 2 parameters: The duration in seconds, and the target to move to.

Add the following code block at the end of init() in HelloWorldScene.cpp before the return true :

auto movement = MoveTo::create(10, Vec2(2148,620));
auto resetPosition = MoveTo::create(0, Vec2(-150,620));
auto sequence = Sequence::create(movement, resetPosition, NULL);
sprite->runAction(RepeatForever::create(sequence));

The resetPosition sets Capguy's position to the left of the screen. The time is 0 to perform this action immediately.

The Sequence runs a bunch of actions in sequence, starting the next one after the previous is finished. You can add several actions at once - just make sure to terminate the list with NULL .

Finally, assign the actions to the sprite - again using the RepeatForever .

Compile and run - you now see Capguy walking down the street.

References

Name
Latest commit gogo2464 fix typo (#20809 ) 7a5282a · 7 months ago History 37,362 Commits
.github/workflows	V4 macos fix build (#20704 )	4 years ago
cmake	Update cmake readme (#20669 )	4 years ago
cocos	Setup github actions for V4 (#20702 )	4 years ago
docs	fix typo (#20809 )	7 months ago
extensions	delete useless files and clean codes (#20279 )	6 years ago
external	update 3rd bin (#20316 )	6 years ago
licenses	update to v4 (#20392 )	6 years ago
templates	Setup github actions for V4 (#20702 )	4 years ago
tests	Setup github actions for V4 (#20702 )	4 years ago
tools	[CI ]add cocos new for iOS (#20380 )	6 years ago
.appveyor.yml	enable windows ci (#19497 )	6 years ago
.gitattributes	fix line end in windows	12 years ago
.gitignore	Update gradle to 5.1.1 (#19958 )	6 years ago
.gitmodules	Remove jsb/h5 (#19621 )	6 years ago
.travis.yml	[CI ]add cocos new for iOS (#20380 )	6 years ago
AUTHORS	Update AUTHORS	9 years ago
CHANGELOG	update to v4 (#20392 )	6 years ago
CMakeLists.txt	set default minimum deployment target (#20323 )	6 years ago
CONTRIBUTING.md	rename contribute.md to contributing.md	10 years ago
README.md	update cocos creator link in the README.md	2 years ago
download-deps.py	Setup github actions for V4 (#20702 )	4 years ago
install-deps-linux.sh	Setup github actions for V4 (#20702 )	4 years ago
issue_template.md	Fix minor typo in issue_template (#16672 )	9 years ago
setup.py	delete ANT check on setup.py (#19042 )	7 years ago

Repository files navigation

README

cocos2d-x

Win32	Others

cocos2d-x is a multi-platform framework for building 2d games, interactive books, demos and other graphical applications. It is based on cocos2d-iphone, but instead of using Objective-C, it uses C++. It works on iOS, Android, macOS, Windows and Linux.

Cocos2d-x Framework Architecture:

cocos2d-x is:

Fast
Free
Easy to use
Community supported

Git user attention

Clone the repo from GitHub.

  $ git clone https://github.com/cocos2d/cocos2d-x.git

After cloning the repo, please execute download-deps.py to download and install dependencies.
```
  $ cd cocos2d-x
  cocos2d-x $ python download-deps.py
```

After running download-deps.py.

  cocos2d-x $ git submodule update --init

Download stable versions

Cocos2d-x stable versions

Documentations and samples

All Docs in a single place!
Online API Reference Note that Cocos2d-x and Cocos Creator have different API set
Programmers Guide
Latest Release Note
Changelog

Main features

Scene management (workflow)
Transitions between scenes
Sprites and Sprite Sheets
Effects: Lens, Ripple, Waves, Liquid, etc.
Actions (behaviours):
- Transformation Actions: Move, Rotate, Scale, Fade, Tint, etc.
- Composable actions: Sequence, Spawn, Repeat, Reverse
- Ease Actions: Exp, Sin, Cubic, Elastic, etc.
- Misc actions: CallFunc, OrbitCamera, Follow, Tween
Basic menus and buttons
Integrated with physics engines: Box2d and Chipmunk
Particle system
Skeleton Animations: Spine and Armature support
Fonts:
- Fast font rendering using Fixed and Variable width fonts
- Support for .ttf fonts
Tile Map support: Orthogonal, Isometric and Hexagonal
Parallax scrolling
Motion Streak
Render To Texture
Touch/Accelerometer on mobile devices
Touch/Mouse/Keyboard on desktop
Sound Engine support
Integrated Slow motion/Fast forward
Fast and compressed textures: PVR compressed and uncompressed textures, ETC1 compressed textures, and more
Resolution Independent
Language: C++, with Lua and JavaScript bindings
Open Source Commercial Friendly(MIT): Compatible with open and closed source projects
OpenGL ES 2.0 (mobile) / OpenGL 2.1 (desktop) / metal(macos and iOS) based

Build Requirements

Mac OS X 10.7+, Xcode 8+
or Ubuntu 14.04+, CMake 3.1+
or Windows 7+, VS 2015
Python 2.7.5+(NOT Python 3)
NDK r16+ is required to build Android games
Android Studio 3.0.0+ to build Android games(tested with 3.0.0)
JRE or JDK 1.6+ is required for web publishing

Runtime Requirements

iOS 8.0+ for iPhone / iPad games
Android 3.0.0+ for Android
OS X v10.9+ for Mac games
Windows 7+ for Win games

Environment Setup

Should set up environment before starting a new game or running tests

$ cd cocos2d-x
$ ./setup.py
$ source FILE_TO_SAVE_SYSTEM_VARIABLE

Should invoke this script if using linux system

$ cd cocos2d-x
$ ./install-linux-deps.sh

Running Tests

$ cd cocos2d-x
$ mkdir build
$ cd build
$ cocos run --proj-dir .. -p [mac|win32|android|linux|ios]

How to start a new game

$ cd cocos2d-x
$ ./setup.py
$ source FILE_TO_SAVE_SYSTEM_VARIABLE
$ cocos new MyGame -p com.your_company.mygame -l cpp -d NEW_PROJECTS_DIR
$ cd NEW_PROJECTS_DIR/MyGame
$ mkdir build
$ cd build
$ cocos run --proj-dir .. -p [mac|win32|android|linux|ios]

You can also create a Lua project with -l lua.

Using IDE

If need to debug program, then it is more convinent to use IDE to run and debug it. All platforms other than Android can use CMake to generate corresponding project file. Can refer to Detail CMake Guide for detail information.

For Android, the Android Studio project file lies in PROJECT_DIR/proj.android. Can just use Android Studio to import the exsting project file.

Learning Resources

Spreading the word!

You can help us spread the word about cocos2d-x! We would surely appreciate it!

Twitter: @CocosEngine
Facebook: https://www.facebook.com/CocosEngine
YouTube: https://www.youtube.com/cocosengine
Weibo: @Cocos引擎
bilibili: https://space.bilibili.com/491120849

Where to get help

English Forums
中文社区
Bug Tracker
API Reference.
Latest Release Note
Changelog
Discord Channel
cpp-tests project. This project is our basis for testing. Use this project to learn how we implement the functionality of the engine. This project is located in cocos2d-x_root/build.

Contributing to the Project

Cocos2d-x is licensed under the MIT License. We welcome participation!

Did you find a bug? Do you have feature request? Do you want to merge a feature?

contributing to cocos2d-x

Embrace the Future: Switch to Cocos Creator for a Better Experience

Cocos Creator is the new generation of Cocos game engine with a full featured editor and content creation friendly workflow. It supports all major platforms allowing games to be quickly released for the web, iOS, Android, Windows, Mac, and various mini-game platforms. Millions of developers have built 2D / 3D experiences, from hardcore games to web instant entertainment. A pure JavaScript-developed engine runtime is available on the web and mini-game platforms for better performance and smaller packages. On other native platforms, C++ is used to implement the underlying framework, providing greater operational efficiency. The engine is completely open source, and retains the advantages of Cocos2d-x which includes high performance, customizability, ease for debugging, easy to learn, and small package size.

Therefore, we no longer recommend new users to start with Cocos2d-x. Instead, please use the brand-new Cocos Creator for project development to enjoy the best editor and 3D support.

About

Cocos2d-x is a suite of open-source, cross-platform, game-development tools utilized by millions of developers across the globe. Its core has evolved to serve as the foundation for Cocos Creator 1.x & 2.x.

www.cocos.com/en/cocos2d-x

android windows c-plus-plus ios gamedev lua metal game-engine game-development cocos2d cocos2d-x linx

Releases

98 tags

Packages

No packages published

Contributors625

+ 611 contributors

Languages

新手入门
了解引擎
基本概念
基本功能
精灵(Sprite)
- 精灵创建
  - 使用图集
  - 使用精灵缓存
- 精灵控制
- 多边形精灵
动作(Action)
场景(Scene)
UI 组件
进阶内容
特殊节点对象
事件分发机制
3D 支持
使用脚本
物理引擎
音乐和音效
高级话题
环境与工具
环境搭建
引擎工具
解决方案常见问题
本书使用 GitBook 发布

使用图集

图集(Sprite Sheet) 是通过专门的工具将多张图片合并成一张大图，并通过 plist 等格式的文件索引的资源，使用图集比使用多个独立图像占用的磁盘空间更少，还会有更好的性能。这种方式已经是游戏行业中提高游戏性能的标准方法之一。

在使用图集时，首先将其全部加载到 SpriteFrameCache 中，SpriteFrameCache 是一个全局的缓存类，缓存了添加到其中的 SpriteFrame 对象，提高了精灵的访问速度。SpriteFrame 只加载一次，后续一直保存在 SpriteFrameCache 中。

示例：

单看这个图集，似乎很难分析出什么，让我们对比一下：

这就很容易看出来，它至少完成了将多个图像素材合为一个，同时减少了磁盘空间占用。

继续来看如何在代码中使用。

加载图集

获取到 SpriteFrameCache 的实例，把图集添加到实例中。

// load the Sprite Sheet
auto spritecache = SpriteFrameCache::getInstance();

// the .plist file can be generated with any of the tools mentioned below
spritecache->addSpriteFramesWithFile("sprites.plist");

这样我们就完成了，将一个图集添加到 SpriteFrameCache 中，现在我们就能利用这个对象创建精灵了！