Tutorial: Using sprite sheet animations in cocos2d-x V4

The tutorial we wanted to write...

We recently wanted to update our game development tutorials for the current release of cocos2d-x — but we really hit some road blocks doing so.

I describe in detail what had happened in this post...

... if you want to save some time read Using sprite sheet animations in Axmol Engine instead.

The new cocos2d-x V4 experience

Cloning cocos2d-x from github (now working!)

It stated all by checking out the current version V4 of cocos2d-x from GitHub. It does not work!

The initial download using

git clone https://github.com/cocos2d/cocos2d-x.git
python download-deps.py

works. You might have to change python to python3...

But after that you receive errors:

git submodule update --init

Submodule 'tests/cpp-tests/Resources/ccs-res' (git://github.com/dumganhar/ccs-res.git) registered for path 'tests/cpp-tests/Resources/ccs-res'
Submodule 'tools/bindings-generator' (git://github.com/cocos2d/bindings-generator.git) registered for path 'tools/bindings-generator'
Submodule 'tools/cocos2d-console' (git://github.com/cocos2d/cocos2d-console.git) registered for path 'tools/cocos2d-console'
Cloning into '/Users/sk/Programming/_tmp/cocos2d-x/tests/cpp-tests/Resources/ccs-res'...
fatal: unable to connect to github.com:
github.com[0: 140.82.121.4]: errno=Operation timed out

fatal: clone of 'git://github.com/dumganhar/ccs-res.git' into submodule path '/Users/sk/Programming/_tmp/cocos2d-x/tests/cpp-tests/Resources/ccs-res' failed
Failed to clone 'tests/cpp-tests/Resources/ccs-res'. Retry scheduled
Cloning into '/Users/sk/Programming/_tmp/cocos2d-x/tools/bindings-generator'...
fatal: unable to connect to github.com:
github.com[0: 140.82.121.4]: errno=Operation timed out

fatal: clone of 'git://github.com/cocos2d/bindings-generator.git' into submodule path '/Users/sk/Programming/_tmp/cocos2d-x/tools/bindings-generator' failed
Failed to clone 'tools/bindings-generator'. Retry scheduled
Cloning into '/Users/sk/Programming/_tmp/cocos2d-x/tools/cocos2d-console'...
fatal: unable to connect to github.com:
github.com[0: 140.82.121.4]: errno=Operation timed out

fatal: clone of 'git://github.com/cocos2d/cocos2d-console.git' into submodule path '/Users/sk/Programming/_tmp/cocos2d-x/tools/cocos2d-console' failed
Failed to clone 'tools/cocos2d-console'. Retry scheduled
Cloning into '/Users/sk/Programming/_tmp/cocos2d-x/tests/cpp-tests/Resources/ccs-res'...

You can fix this by changing the .git/config to use a new paths to the submodules:

git submodule set-url tools/cocos2d-console git@github.com:cocos2d/cocos2d-console.git
git submodule set-url tools/bindings-generator git@github.com:cocos2d/bindings-generator.git
git submodule set-url tests/cpp-tests/Resources/ccs-res git@github.com:dumganhar/ccs-res.git

The next step is to install cocos2d-x using

./setup.py

On a Mac, you most likely get

zsh: ./setup.py: bad interpreter: /usr/bin/python: no such file or directory

and if you call it with python3

The python version is 3.10. But python 2.x is required. (Version 2.7 is well tested)
Download it here: https://www.python.org/

Ok - so you have to install python 2.7.... which you can get from here: Python 2.7 Installer

After that, you can run the following command in a new command line:

python setup.py

Create your project (still not working!)

You can create your new project using the following command:

cocos new --package com.example.cocosproject --language cpp MyProject

And with this, you start it for your platform:

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

It compiled some time... and exited with an error.

** BUILD FAILED **

The following build commands failed:
	Ld /Users/sk/Programming/_tmp/MyProjectV4/ios-build/build/MyProjectV4.build/Debug-iphonesimulator/Objects-normal/arm64/Binary/MyProjectV4 normal arm64 (in target 'MyProjectV4' from project 'MyProjectV4')
(1 failure)

Giving up...

This is not how a game engine should work. After all, you want to focus on game development, not on fixing issues with the game eninge. Or not even being able to install it.

After this quite frustrating experience, I decided to take a look at the repository:

Last commit: Dec 3, 2021.
Pull requests: 199
Issues: 1400

Nobody cares about the pull requests. Even important pull requests like adjusting the repository to python3 or at least fixing the github urls are simply ignored.

This leads to only one conclusion: cocos2d-x is dead.

... but what next?

cocos2d-x was a really great game engine, and it's quite mature in its feautres.

I recently found a fork of cocos2d-x which is called Axmol Engine.

It was created 2019 and already has more than 300 starts on github. It gets regular updates, supports python3 and you can install it without any issues.

This looks really promising!

So... what are your options:

Fork cocos2d-x and fix the stuff yourself
Use the Axmol fork - which seems quite promising at this time
Switch to Cocos Creator and develop your game in Javascript/Typescript
Switch to a different game engine

Where is this tutorial?

We think that Axmol looks good - and think that it's really worth giving it a try. This is why we've decided to support it with our tools.

We've created a new tutorial using the Axmol Engine fork of cocos2d-x:

Using sprite sheet animations in Axmol Engine

We've not tested it, but it's most likely that the code will also work with cocos2d-x V4 in case you get it working...