Cocos2d-x is a mature open source cross-platform game development framework that supports 2D and 3D game creation
Version 3.17.2 focuses on bugs fixing and performance opimization on OPPO devices.
FileUtils::listFiles() can not work correctly if the file path starts with assets/ on AndroidVideoPlayer can not play video in obb file on AndroidMore detail change log please refer to ChangeLog.
The 3.17.1 release focuses on bug fixing.
This release contains more than 45 bugs fixed and 34 misc improvements, please refer to ChangeLog
The 3.17 release focuses on stability and increased performance with some under the hood enhancements that will make cross-platform development easier.
v3.17 has been tested using Android Studio (3.0, 3.1, 3.1.1) with NDK r16
3.17 brings support for iPhone X including supporting full screen mode, using Storyboards for launch images, safe area API and support for auto hiding the Home indicator. It is important to note exactly what and where the safe area is:
Developers can get the safe area easily by calling: Director::getSafeAreaRect().
Android Studio is the only official IDE for Google’s Android operating system.
Cocos2d-x supports Android Studio using NDK version r16. Gradle configurations have been updated, including simplifying Gradle PROP_* values, changing the deprecated compile to the new implementationin dependency declaration, and added Proguard configuration to reduce Release package size.
CMake is now supported on all platforms, including Android(NDK), iOS, macOS, Windows (VC++ compiler), Linux. Supports precompile libraries for engine, and reusing precompiled libraries in the new build process. Your projects build time will be greatly reduced. For detailed usage, please refer to CMake Doc
Spine skeleton animation is widely used in games developed by Cocos2d-x. Spine runtime has been upgraded to 3.6.39 to keep current.
GLFW has been upgraded to 3.2.1 to help fix joystick issues. You can also now use GLFW as a precompiled library.
Box2D hasn’t been updated in quite some time. A new production version has yet to be released so far in 2018. We felt GitHub commit was stable. You can also now use Box2D as a precompiled library.
Each Cocos2d-x release comes with a specific version of third-party libraries. If you want to upgrade third-party libraries due to your projects needs, please refer to: 3rd-party Doc
Google officially deprecated ant build support starting in Android SDK Tools 25.3.0. The old ant based proj.android and been dropped and now proj.android is an Android Studio project. The default architecture is changed from armeabi to armeabi-v7a.
Visual Studio 2013 support has been dropped. Visual Studio 2015/2017 are still currently supported. The existing win32 project files is quite suitable for 2015. To use 2017, you can open a 2015 project file, modify the configuration to suit your needs, or use CMake (See above).
This release contains more than 51 bugs fixed and 33 misc improvements, please refer to Changelog
Android tool version tested in this version:
creator_to_cocos2dx creator plugincreator_to_cocos2dx is a Cocos Creator plugin that will export Scene information created by Cocos Creator for cocos2d-x C++/Lua projects. We mention it as plugin following.
With this plugin, you can use Cocos Creator as Scene editor for cocos2d-x. Curretly, the plugin supports these features, and will continue to add more features. As you can see, RichText img tag support only works in cocos2d-x v3.16+ because of cocos2d-x's limitation. So cocos2d-x will continue to be improved to support more Cocos Creator features.
More detail information and usage please refer to plugin's the README. You are appreciated if you can use it and give feedback.
Scene effect in cocos creator
Scene effect in cocos2d-x
LayerRadialGradient is similar to LayerColor, but will only draw color in a circle.
After updating to Xcode 8.0+, lua projects will crash on iOS simulator. It is a bug of luagit. In this version, the bug it is fixed. You can just update luajit if you don't want to update cocos2d-x.
Before cocos2d-x v3.16, CCFileUtils uses system( ) to remove a directory. iOS 11 remove system, so will cause compiling error with iOS 11. This version fixes this issue. The corresponding PR for this issue is here, you can apply this PR to fix it if you don't want to upgrade to v3.16.
coocs2d-x v3.15 updates flatbuffer, which breaks compatibility of Cocos Studio. In this version, we revert flatbuffer and Cocos Studio reader.
If you don't want to update cocos2d-x, you can replace flatbuffer and Cocos Studio reader shift in this version.
As bullet is not needed for most developers, so we use prebuilt bullet. It will speed up compiling speed, and we will continue to use more prebuilt 3rd party libraries, such as 3d particles, Box2D and so on to speed up compiling speed.
We also fix many warnings too in this version. As some warnings are imported by 3rd party libaries, so we can not treat warnings as error, but we will continue to achieve it.
As we are lack of human resources, so we remove some platforms.
MS maintians Win10 related platform, but it doesn't continue to maintain it. So we remove it. Which means cocos2d-x based games can not run on Win10 metro mode and Windows Phones, but you can run it in Win32 mode.
Tizen platform is removed too because of huaman resources.
Since v3.15, can use Android Studio 2.3+ to edit, compile and debug c++ codes. What you need to do is just use Android Studio to open proj.android-studio(such as tests/cpp-empty-test/proj.android-studio), then click run menu button to run on Android devices or simulators.
Please refer to this doc for detail usage.
Before v3.15, new Audio engine uses OpenSL ES to decode and play audio files. But many Android device manufacturers modify OpenSL ES decoding codes which cause issues. This thread lists many issues caused by it.
In order to fix these issues, we decide to use 3rd party audio decoding libraries tremolo and MP3 Decoder Library, which are used by Android have good performance and stability. What's exciting is what, after using tremolo, the audio engine's performance is highly improved too.
MS guys maintain Windows 8.1. They think there is not need to support it, so they remove the support.
Most PC are 64-bit, so we decide to remove linux 32-bit support. By remove 32-bit linux support, cocos2d-x zip file is more less, and we can have more resource on more important things.
If you need linux 32-bit support, you can build the 3rd party libraries through cocos2d-x-3rd-party-libs-src repo by yourself.
Android SDK Tools 25.3.0+ removes ant script and android tool, which leads to that cocos command can not generate apk files with Eclipse projects(proj.android). Currently, cocos command will do nothing if using SDK Tools 25.3.0+, you can use these two methods to fix it:
It seems google doesn't want developers continue to use Eclipse to develope Android applications, so i suggest to switch to use Android Studio.
This release brings bug fixes and API maintenance, as well as these highlights:
Read the full release notes .
Downloadit today!
ResizeBy and ResizeToButton's title labelEditBox adds horizontal text alignmentIn previous it is not convenient to generate luajit 64bit bytecode. You need to generate the bytecode in real devices, which means you should generate luajit 64bit bytecode on iOS 64bit devices.
Now, we can generate luajit 64bit bytecode on Mac OS X, windows or linux, so we change to use luajit for all platforms. If you use cocos command with -m release, it will generate bytecode automatically. And it will put 64bit bytecode into 64-bit folder. One exception is that, it doesn't generate luajit bytecode on linux, we don't know whether to generate 32bit or 64bit byte codes. So you should generate luajit bytecode yourself by using cocos luacompile command. Please refer to the help information of cocos luacompile -h for detail usage.
The generated bytecodes architecture are:
| Platform | generate 32bit luajit bytecode | generate 64bit luajit bytecode |
|---|---|---|
| iOS | yes | yes |
| Android | yes if APP_ABI not only includes arm64-v8a, such as APP_ABI := arm64-v8a | yes if APP_ABI includes arm64-v8a |
| Mac | not | yes |
| Windows | yes | no |
| Linux | no | no |
Now Sprite supports slice9 feature, you can use it like:
auto sprite = Sprite::create(...);
// set center rect
// the origin is top-left
sprite->setCenterRectNormalized(Rect(x, y, width, heigh));More detail information please refer to the comments of Sprite::setCenterNormalized().
lua project will crash on iOS simulator if using Xcode 8.2+. The issue is caused by luajit. We thought it is a but of Xcode because there is not problem if using Xcode 8.1 or lower version.
We can not fix it in v3.14, can track the issue for the progress of this issue.
Prior to 3.13 the cocos command would find an Android API level >= a specified
Android API level inorder to build source codes on Android. For example, if the contents of
APP_ROOT/proj.android/project.properties is:
target=android-13 // the default android api level
android.library.reference.1=../../../cocos/platform/android/javathen the cocos command will find android-13 in ANDROID_SDK_ROOT/platforms. If android-13
is not found then it will try to find android-14. If android-14 is not found, then it will find
android-15 and so on until it finds one.
This algorithm has a problem. If you only download Android 21, then your application will be built with
Android 21 even though the default API level is 13. If your application runs on a device with a lower Android OS,
such as Android 4.0, then your application may crash. Building with a higher API level does not ensure that your
application will run on devices with a lower Android OS.
Starting in 3.13.1, the cocos command will stop if it can not find a specific API level. The default
is android-13. If you want to build with a higher level Android SDK, you should explicitely specify it.
Example:
cocos compile -p android --ap android-19Keep in mind that, after running this command, the contents of APP_ROOT/proj.android/project.properties will
be changed, android-19 will now be the default API level.
There is a map between Android API level and Android OS version that you can refer to for detailed information.
There is also more detailed information in our GitHub repo about this issue.
We are happy to announce the release of Cocos2d-x v3.13!
Support for Gear, Deepoon, Google Cardboard and Oculus has been added. Read about VR in our Programmers Guide
Thanks halx99's contribution, now cocos2d-x supports ETC1 alpha channel by default.
If want to use ETC1 alpha chaneel, you should put xxx.pkm and xxx.pkm@alpha in the same folder, and use it like this:
auto sprite = Sprite::create("xxx.pkm");xxx.pkm@alpha is the resource for alpha channel. @alpha subfix is required by engine to load alpha texture automatically.
More detail usage can refer to the implementation of Sprite1ETC1Alpha in tests/cpp-tests/Classes/SpriteTest/SpriteTest.cpp.
As you can see, the blue block in the middle of the picture is an ETC1 picture with alpha channel.
AudioEngine uses OpenSL ES on Android, and it supports decoding audio source file to PCM data in codes since Android 4.2. Now AudioEngine uses this feature to fix the performance issue. The performane is the same as before if running on Android 4.1 or lower version. Should preload first, or there is not performance improved for first time playing of the audio.
In v3.12, we improved WebGL renderer in the web engine, this version have brought the dirty region algorithm to improve canvas renderer performance. Basically, it detect every region that have been changed between frames, then only render these parts instead of refresh the whole canvas. This technique is beneficial for many games in which the dynamic region is often limited, it can improve frame rate and reduce CPU usage, power consumation. It's desactivated by default, to activate it, you can do the following:
// Enable dirty region algorithm
if (cc._renderType === cc.game.RENDER_TYPE_CANVAS) {
cc.renderer.enableDirtyRegion(true);
// Maximum dirty region count to activate the partial rendering process
cc.renderer.setDirtyRegionCountThreshold(6);
}
// Detect if dirty is enabled
var enabled = isDirtyRegionEnabled();Now we provide arm-64 bit 3rd party libraries, which means can build 64-bit apps on Android. You can use the command to build 64-bit apps:
cocos run -p android --app-abi arm64-v8acocos2d-x switch to use clang in v3.12, but developers reported some crash issue that caused by using clang+gnustl_static, so we switch to use gcc 4.9. We will change to use clang+c++_static when c++_static is stable.
Because CURL has a bug about connect to IPV4 numerical IP address in NAT64 environment, and it is fixed in v7.50.0, so we upgrade to this version when v7.50.0 is released.
We are happy to announce the release of Cocos2d-x v3.12!
You can use Cocos Console command line tool to run the test cases on almost all supported platforms.
In console application:
// Enter cpp test folder
cd tests/cpp-tests
// Or enter js test folder
cd tests/js-tests
// Or enter lua test folder
cd tests/lua-tests
// Compile or run test case
cocos compile -p ios|mac|android|win32|win8_1|metro|web -m debug|release
cocos run -p ios|mac|android|win32|win8_1|metro|web -m debug|releaseFor example, if you want to run cpp test in release mode on Android, you can use the following command:
cocos run -p android -m releaseYou can run the samples by:
You can run the samples by either using the command-line or Eclipse:
Using command line:
$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10
$ adb install cocos2d-x/tests/cpp-empty-test/proj.android/bin/CppEmptyTest-debug.apkThen click item on Android device to run tests. Available value of -p is the API level, Cocos2d-x supports from level 10.
Using Eclipse:
$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10Next:
cpp-empty-test Android project into Eclipse, the path used to import is tests/cpp-empty-test/proj.androidcpp-empty-test Android project and runYou can run the samples by:
You can run the samples by:
$ cd cocos2d-x/build
$ ./install-deps-linux.sh
$ cd ../..Next:
$ mkdir build
$ cd build
$ cmake ../cocos2d-x
$ make -j4Then run:
$ cd bin/cpp-empty-test
$ ./cpp-empty-testUse the cocos console app to create a new game:
cocos new -l cpp|js|lua MyNewGameVR Support is now available! Currently there is support for Google Cardboard, Oculus Rift, Samsung Gear and Deepoon E2. Also provided is a generic VR renderer to help with testing. It should not be used to trust deploying a production VR game. In usual Cocos2d-x fashion it is very easy to get started with an easy to understand API. Read our chapter in the Programmers Guide for more information.
You can now develop for the Tizen mobile platform. The latest 2.4 SDK is supported. Tizen development uses it's own uniqie IDE as well as a simulator for testing applications. For setup instructions please read our documentation.
Thank you to our users for helping diagnose performance issues on some Android devices. It is because Cocos2d-x creates a big map buffer by default and fills the map buffer with actual data, which is less than the map buffer size. On some Android devices, it will transfer as much data as the map buffer size which causes performance issue.
More detail information and discussion can refer to the issue.
The web engine is receiving a big performance upgrade. The WebGL renderer have been completely refactored from the ground up. This means improved rendering and a reduced memory footprint.
Google deprecated gcc starting in NDK r11, Cocos2d-x now uses clang. We suggest using the NDK r11c.
We found an issue that, if using NDKr 10c + clang, then Node::enumerateChildren() will crash on Android.
View our full changelog.
You can use Cocos Console command line tool to run the test cases on almost all supported platforms.
In console application:
// Enter cpp test folder
cd tests/cpp-tests
// Or enter js test folder
cd tests/js-tests
// Or enter lua test folder
cd tests/lua-tests
// Compile or run test case
cocos compile -p ios|mac|android|win32|win8_1|metro|web -m debug|release
cocos run -p ios|mac|android|win32|win8_1|metro|web -m debug|releaseFor example, if you want to run cpp test in release mode on Android, you can use the following command:
cocos run -p android -m releaseYou can run the samples by:
cpp-tests, lua-tests, js-tests for iOS or OS X target in scheme toolbarYou can run the samples by either using the command-line or Eclipse:
Using command line:
Perform the following steps:
$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10
$ adb install cocos2d-x/tests/cpp-empty-test/proj.android/bin/CppEmptyTest-debug.apkThen click item on Android device to run tests. Available value of -p is the API level, cocos2d-x supports from level 10.
Using Eclipse:
Perform the following steps:
$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10Next:
cpp-empty-test Android project into Eclipse, the path used to import is tests/cpp-empty-test/proj.androidcpp-empty-test Android project and runYou can run the samples by:
You can run the samples by:
$ cd cocos2d-x/build
$ ./install-deps-linux.sh
$ cd ../..Next:
$ mkdir build
$ cd build
$ cmake ../cocos2d-x
$ make -j4Then run:
$ cd bin/cpp-empty-test
$ ./cpp-empty-testUse the cocos console app to create a new game:
cocos new -l cpp|js|lua MyNewGameretain/release in JS, it is disabled by defaultWith new memory model, you don't have to care about object lifecycle. Which means you don't have to invoke retain/release in JS any more.
Though we have finished many tests about this new memory model, we can't make sure it is too perfect to enable it by default. But you are appreciated if you can enable it to have a try. If you want to enable it, you should change the value of CC_ENABLE_GC_FOR_NATIVE_OBJECTS to 1 in base/ccConfig.h like this:
#ifdef CC_ENABLE_SCRIPT_BINDING
#ifndef CC_ENABLE_GC_FOR_NATIVE_OBJECTS
#define CC_ENABLE_GC_FOR_NATIVE_OBJECTS 1 // change to 1
#endif
#endifCocos2d-x has upgraded OpenSSL to version 1.0.2g.
Beginning July 11, 2016, Google Play will block publishing of any new apps or updates that use older versions of OpenSSL. It is important that you update the use of OpenSSL in your projects. More detail information can refer to this ticket.
If you use v2.x or use older versions of v3.x, you can just update CURL and OpenSSL.
To do this:
v3-deps-92, and for v2.x it is v2-deps-5(jtsm @ 15 ~) $ cd cocos2d-x
(jtsm @ 15 ~/cocos2d-x) $ ./download-deps.py
=======================================================
==> Prepare to download external libraries!
==> Ready to download 'v3-deps-92.zip' from 'https://github.com/cocos2d/cocos2d-x-3rd-party-libs-bin/archive/v3-deps-92.zip'
==> WARNING: Couldnt grab the file size from remote, use 'zip_file_size' section in '/Users/jtsm/Chukong-Inc/cocos2d-x/external/config.json'
==> Start to download, please wait ...
==> Downloading finished!
==> Extracting files, please wait ...
==> Extraction done! ==> Copying files...
==> Cleaning...In previous version, can not use Firefox 30+ to debug cocos2d-x JSB programs. This limit is fixed since v3.11. And web console feature is added too. This documentation shows how to use Firefox to debug cocos2d-x JSB programs(this is a little difference from current usage).
Of course you can use VSCode to debug cocos2d-x JSB programs too. You can read about how to use VSCode to debug cocos2d-x JSB programs here.
In v3.11, we have refactored the WebGL renderer in web engine, here is the detailed changes:
Compare with old version, the draw calls in your game should be significantly reduced if the textures is well managed. This improves also the CPU usage and memory usage. The above is just a first step of WebGL renderer upgrade, we will continue to investigate in this direction in the future versions.
You can also take a look at the full changelog.
You can use Cocos Console command line tool to run the test cases on almost all supported platforms.
In console application:
// Enter cpp test folder
cd tests/cpp-tests
// Or enter js test folder
cd tests/js-tests
// Or enter lua test folder
cd tests/lua-tests
// Compile or run test case
cocos compile -p ios|mac|android|win32|win8_1|metro|web -m debug|release
cocos run -p ios|mac|android|win32|win8_1|metro|web -m debug|releaseFor example, if you want to run cpp test in release mode on Android, you can use the following command:
cocos run -p android -m releasecocos2d-x/build folder, open cocos2d_test.xcodeprojcpp-tests, lua-tests, js-tests for iOS or OS X target in scheme toolbarrun buttonYou can run the samples…
Using command line:
$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10
$ adb install cocos2d-x/tests/cpp-empty-test/proj.android/bin/CppEmptyTest-debug.apkThen click item on Android device to run tests. Available value of -p is the API level, cocos2d-x supports from level 10.
Using Eclipse:
$ cd cocos2d-x
$ ./setup.py
$ cd build
$ ./android-build.py cpp-empty-test -p 10Then
cocos/2d/platform/androidcpp-empty-test Android project into Eclipse, the path used to import is tests/cpp-empty-test/proj.androidcpp-empty-test Android project and runcocos2d-x/build, and open cocos2d-win32.slncocos2d-x/build, and open cocos2d-win8.1-universal.slncocos2d-x/build, and open cocos2d-win10.sln$ cd cocos2d-x/build
$ ./install-deps-linux.sh
$ cd ../..Then
$ mkdir build
$ cd build
$ cmake ../cocos2d-x
$ make -j4Run
$ cd bin/cpp-empty-test
$ ./cpp-empty-testUse Cocos Console to create a new game:
cocos new -l cpp|js|lua MyNewGameWe are happy to announce the release of Cocos2d-x v3.10. Following are the highlighted features, improvements and API updates in this version.
.zip file available containing the source code. Scale9Sprite to improve performance and reduce memory consumption.PageView to derive from ListView. PageView can add any widget as a child.Label: CLAMP，SHRINK, RESIZE_HEIGHT.ClippingNode that corrects its behavior when being set as a child.You can also take a look at the full changelog.
We are happy to announce the release of Cocos2d-x v3.9. Following are the highlighted features, improvements and API updates in this version.