Cocos2d-x v3.9 released!

Cocos2d-x v3.9 released!

We are happy to announce the release of Cocos2d-x v3.9. Following are the highlighted features, improvements and API updates in this version.

  1. 3D Module:
    • Added 3D MotionStreak to support streak effect.
    • Refined Sprite3D to support material system.
  2. 2D Module:
    • Added frame callback function and animation callback function.
    • Added script component system.
    • Reconstruction of 2D physics with Component.
    • Improved EditBox implementation on iOS and Win32 platform.
    • Removed dependence of libcurl on AssetsManager, AssetsManagerEx and Downloader (iOS & Android).
    • Improved particle performance.
  3. Others:
    • Supported Action inheritance, update function overwriting in JSB.
    • Improved ScrollView performance in Web engine.
    • Improved Scale9Sprite performance in Web engine.
    • Decoupled Sprite's setTexture() and updateColor() in Web engine.
    • Added support for debugging and release on real devices with Xcode7 and iOS9.

Download link (includes C++, Lua and JS)

The main features in detail of Cocos2d-x v3.9:

  1. 3D MotionStreak

    In this version, 3D MotionStreak is added to support streak effect. Here is the PR for this feature, and you can check the test case of Sprite3Dtest to see how to use it.

  2. Sprite3D

    Added Sprite3D material class. It will be easy and convenient to create internal material.

  3. Frame callback function and animation callback function

    Three interfaces are added in ActionTimelineData class, which are addFrameEndCallFunc, removeFrameEndCall and clearFrameEndCalls. It will be easy to add or remove specific frame event.

  4. Script Component

    Script component is used to extend c++ Nodes. You can add a script component to a Node, then the script component will receive onEnter,onExit and update events. For example:

    // create a sprite and add a lua component auto player =
    auto luaComponent = ComponentLua::create("player.lua");
    // player.lua
    local player = { 
        onEnter = function(self)
        -- do some things in onEnter 
        onExit = function(self) 
        -- do some things in onExit 
        update = function(self)
        -- do some things every frame 
    -- it is needed to return player to let c++ nodes know it 
    return player 

    Javascript can work as the same way, just use ComponentJS instead of ComponentLua.

    There are some differences between lua component and Javascript component:

    Should return the object in lua component, in Javascript, you only have to extend cc.ComponentJS, and ensure the result of the last statement is the class of Component.

    Lua component can only be used in lua projects, Javascript component can only be used in Javascript projects.

    More detail usage please refer to: tests/lua-tests/src/ComponentTest and tests/js-tests/src/ComponentTest

  5. 2D Physics

    Before v3.9, there are many physics related codes in Node, such as Node::setPhysicsBody(). Since v3.9, we move these codes into physics component.

    After using physics component, the way to use physics is changed. Before v3.9, you can use physics like this:

    auto node = Node::create(); 

    Since v3.9 you should use like this:

    auto node = Node::create();
  6. EditBox implementation on iOS and Win32 platform

    • Specify the maximum number of characters in the dialog box.
    • Support password input.
    • Games will continue when the dialogue box pops up.
    • Sync the content in dialogue box.
  7. Remove dependence of curl on AssetsManager, AssetsManagerEx and Downloader (iOS & Android)

    From v3.9, iOS and Android version will not depend on libcurl, which make the game package smaller and solve some bugs caused by libcurl. Stability has been improved with the updated iOS and Android system.

  8. Supported Action inheritance, update function overwriting in JSB

    In previous version of JSB, developers cannot inherit Action class in JS script, such as Action / ActionInterval / ActionInstant, for their update function will not be called. In v3.9, developers can create subclass of Action and make extensions. More detail usage please refer to the test case in ActionTest / ActionCustomTest.

  9. ScrollView performance on Web engine

    ScrollView and ListView are the popular UI controls in Web engine. Their performance is not perfect in previous versions, especially when there are multiple sub-controls. In v3.9, we have improved its rendering performance. They only act on the contents displayed on the current screen. Test date shows that, comparing with v3.8, rendering efficiency of v3.9 have been improved for twice to four times in different devices and browsers.

  10. Scale9Sprite performance on Web engine

    In this version, we have changed the way to construct 9-slice sprite. The engine uses 9 rendering commands instead of the 9 nodes in previous versions. This helps to reduce memory usage and improve rendering performance.

  11. Decoupled Sprite’s setTexture and updateColor in Web engine.

    • Organized the rendering logic in Sprite. UpdateColor is accomplished by texture instead of the Sprite.
    • Fixed a bug about image with alpha channel that when the image is set to black, there is color difference between previous and current version.
    • Improved texture update logic to reduce texture updates when changing colors.
    • Improved the logic about the rendering function in SpriteCanvasRenderCmd.
    • Removed some duplicate codes about updateColor.
  12. Support for debugging and release on real devices with Xcode7 and iOS9

    In v3.8.1, we have made it possible to debug on Xcode7. However, there was a bug with iOS9 real device debugging, and in v3.9, we have fixed the bug.

Other changes

[NEW] Label: Added line spacing/leading feature to Label.
[NEW] ListView: Added APIs to scroll to specific item in list.
[NEW] ListView: Added APIs to get an item in specific position like center, leftmost, rightmost, topmost and bottommost.
[NEW] ListView: Added a feature for magnetic scrolling.
[NEW] Animate: Added ActionTimeline::setAnimationEndCallBack and ActionTimeline::addFrameEndCallFunc.
[NEW] Animate: Added CSLoader::createNodeWithVisibleSize, CSLoader::createNodeWithVisibleSize and moved “ui::Helper::DoLayout” into them.
[NEW] Studio: Added support for Cocos Studio Light3D.
[NEW] Platform: Added the missing CURL support to the Windows 10 UWP version.
[NEW] Platform: Added UIEditBox support on linux platform.

[REFINE] 3D: Added non-null checks in PUScriptCompiler::visit before dereferencing.
[REFINE] 3D: Refined SkyboxBrush by making the shader parameter take effect at once.
[REFINE] Label: Changed label font size type to float to support high precision when font size is small.
[REFINE] ListView: Fixed an issue that list view’s Magnetic::CENTER is not working well when non-bounceable.
[REFINE] ListView: Added feature of jumping to a specific item in list view.
[REFINE] Sprite: Added a “unsupported image format!” log when creating a sprite in CCImage.cpp.
[REFINE] ScrollView: Merge logics of Scroll View for scroll by inertia and auto scroll into one.
[REFINE] Animate: Moved initialization of image to an appropriate location, because it always called twice in SpriteFrameCache::addSpriteFramesWithFile().
[REFINE] Simulator: Changed the size of startFlag to 13.
[REFINE] Simulator: Show Node and Skeleton in the middle of the simulator.
[REFINE] Simulator: Removed screen direction check in simulator to avoid render error.
[REFINE] Physics: Refined components to improve physics performance.
[REFINE] UI: Refined ComponentContainer to improve performance.
[REFINE] UI: EventListenerMouse will dispatch EventMouse events.
[REFINE] OpenGL: Added check for glfwCreateWindow.
[REFINE] Platform: Fixed a crash on xiaomi2 if Cocos2d-x is built as a dynamic library.
[REFINE] Platform: Updated libcococs2d name to v3.9 on WinRT platforms.
[REFINE] Platform: Added some support for mouse on WinRT. Include: Show/Hide mouse cursor; Mouse event implemented similar Desktop version; Left button send mouse event and touch; Support other mouse button and scroll wheel.
[REFINE] Platform: Correct the convertion between unicode and utf8 on WinRT.
[REFINE] Platform: Improved EditBox implement on Win32 platform.
[REFINE] JS: Add jsb.fileUtils.writeDataToFile().
[REFINE] JS: Set js templates Mac target platform from null to 10.7.
[REFINE] JS: Removed the static define of variable in headfile of ScriptingCore.
[REFINE] Lua: Added AssetsManagerEx constants UPDATE_FAILED and ERROR_DECOMPRESS in Lua.
[REFINE] Lua / JS: Refined lua/js binding tool.
[REFINE] I/O: Refined AssetsManagerEx unzipping by using async.
[REFINE] Web: Improved logic of jsb_boot.js to sync with the web engine behavior.
[REFINE] Web: Sync with CCBoot for web.
[REFINE] Build: Fixed various compiler warnings on Xcode 7.
[REFINE] Build: Fixed Wformat-security warning on Xcode.
[REFINE] Build: Fixed a compile error in __LayerRGBA.
[REFINE] Tool: Added tools for generating documents automatically.
[REFINE] Doc: Clean up the code of setRect() function.

You can also take a look at the full changelog.


  1. JSB Module

    Added jsb.fileUtils.writeDataToFile, please see

  2. ActionTimelineData

    Three interfaces are added in ActionTimelineData class, which are

    • ActionTimelineData::addFrameEndCallFunc
    • ActionTimelineData::removeFrameEndCall
    • ActionTimelineDataclearFrameEndCalls
  3. Added ActionTimeline::removeFrameEndCallFunc

  4. Improvements for ListView

    • Add APIs to scroll to specific item in list.
    • Add APIs to get an item in specific position like center, leftmost, rightmost, topmost and bottommost.
    • Add a feature for magnetic scrolling.

    For more information:

  5. Node

    Added the missing API Node::getChildByTag

  6. Label

    Added Label::setLineSpacing and Label::getLineSpacing

  7. CSLoader

    Added CSLoader::createNodeWithVisibleSize and CSLoader::createNodeWithVisibleSize

  8. ComponentContainer

    Removed ComponentContainer::isEmpty

  9. Sprite

    Removed Sprite::debugDraw(bool on)


Nice work and a big thank you to all contributors! :+1:

Would it be possible to tag all releases properly in git? It would help a lot with tracking/diffing changes when working with a forked/patched version.

Related issue:

Thanks a lot!

Yes, i saw the related issue and we do use tags. It looks like a few are missing. I commented on the GitHub issue as well.

Ouch, no official AppleTV support, huh?

1 Like

I don’t think we are quite there yet. It was just released a few weeks ago.

First of all, thank you for the update :ok_hand:

I apologize for this silly question…
Where is the updated doxygen documentation of the framework, I could find the 3.8.1 but not the 3.9

Thanks a lot!

@nikozy drat, I’ll get it updated.

Thanks you very much!

Is video implementation for mac / win32 in development for the next release?

We have a public roadmap!

Waiting for 3.9.1 :slight_smile: With Apple TV and Watch os2 suport

You are waiting for nothing. Maybe 3.10, which is mid-December release. Although I don’t see it on the roadmap.

API Docs have been updated:


Congratulations! Thank you!!
v3.9 Added this issue?
I want to use this with Texture Packer.


COCOS2D_VERSION is still 0x00030800.

I have updated Cocos2d-x v3.9 and created new project, bellow error become. Please check it. When I try do it with Cocos2d-x v3.8.1, it is ok. Sorry for my English
Traceback (most recent call last):
File “/Volumes/…/setup/cocos/cocos2d-x-sources/tools/cocos2d-console/bin/”, line 22, in
import cocos_project
File “/Volumes/…/setup/cocos/cocos2d-x-sources/tools/cocos2d-console/bin/”, line 4, in
import cocos
File “/Volumes/…/setup/cocos/cocos2d-x-sources/tools/cocos2d-console/bin/”, line 874, in
language, encoding = locale.getlocale()
File “/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/”, line 562, in getlocale
return _parse_localename(localename)
File “/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/”, line 475, in _parse_localename
raise ValueError, ‘unknown locale: %s’ % localename
ValueError: unknown locale: UTF-8



Do you know when the framework mode will be released on Cocos Store?

I think the pull request should be this

Thank you.

Run this commands in terminal:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8
source ~/.bash_profile

I found this on StackOverflow. There are for mac, I had the same problem, I don’t know whether it runs on windows too. I have also updated python to 3.5. I don’t know if this was the problem.


@slackmoehrle Missing git tags, late API Docs update, COCOS2D_VERSION still on 0x00030800 , … maybe it’s time for a fully automated release process? :smile: