Cocos Creator 2.4.6 released!

Cocos Creator 2.4.6 is released

This update fixes some known issues. Cocos Creator will continue to optimize performance to bring developers a better experience! The following is the detailed update content.

Important updates

  • Optimize the loading speed of editor resources. After the resources are imported for the first time, the editor will be opened again afterward. The time required is only less than 50% of the previous version, which greatly optimizes the startup speed and improves development efficiency

  • Optimize the stuttering problem when the editor is built. We moved the engine compilation process to the worker, which will not block the execution of the main process, and the developer can continue the development work while building

  • Optimize the performance of the sequence frame animation on the iOS platform, which can increase the performance by up to three times on the old iPhone 6s Plus model [#8528]

  • Add the scene list to the preview toolbar, you can quickly select the preview scene without switching to the corresponding scene, improving work efficiency



  • Fixed the problem that the Hash value of the Zip file is inconsistent after each build

  • Fixed the problem that dragging nodes with subclasses to the properties of the parent class is invalid

  • Fixed the problem that the node on the hierarchy panel cannot be located by clicking the attribute option on the attribute panel

  • Fixed an issue where the small Gizmos square was offset outside the node when the light node was moving

  • Fixed the problem that the Explorer did not enter the selected state after renaming and pressing Enter

  • Fixed the problem that the modification of numTilesX and numTilesY in the 3D particle Texture Animation module did not take effect immediately.

  • Fixed the problem that the 3D particle Rotation module could not set separateAxes, and the modified XY rotation was invalid.

  • Fixed the problem that the modification does not take effect immediately when using the curve in the 3D particle size module.

  • Added VideoClip type, the video resource is automatically recognized as VideoClip format after import

  • Fixed the problem of noise in compressed textures, thanks to Xiaopang Dacheng

  • Fixed the problem that the depthWrite value of the built-in Unlit material is incorrect

  • Fixed the problem that the rich text component causes the open scene data to change [#8903]


  • Fixed the problem of incorrect calculation of material hash value due to uniform order [#8823]

  • Fixed the issue that sp.Skeleton.clearTrack does not reset the initial posture [#8801]

  • Fixed the problem of incorrect calculation of cc.Color.fromHex [#8762]

  • Added Node.setSelfGroupIndex interface for setting self grouping [#8614], thanks to Xiaopang Dacheng

  • Fixed the problem that the Mark component uses the wizard to check the delay loading error after checking [#8264]

  • Fixed the issue of event loss caused by triggering other events in event callback [#8276]

  • Fixed the problem that the game content cannot be pushed up after opening the soft keyboard multiple times [#8374]

  • Fixed the problem that touch nodes, and then hide nodes, all touch events are invalid after releasing the touch point [#8969]

  • Added Animation.hasAnimationState API to determine whether there is an AnimationState, thank you Xiaopang Dacheng

Mini Game

  • Fixed the problem of reporting errors when calling cc.assetManager.cacheManager.clearLRU [#234]

Breaking Change

-cc.sys.isNative is changed to false on the fast game platform

Upgrade Tips

As Cocos Creator 3.0 version has been officially released, v2.4.x will be used as the LTS (long-term support) version, providing continuous updates for the next two years! In 2021, 2.4 will continue to be updated to provide bug fixes and new mini-game platform support to ensure the successful launch of your project; in 2022, we will continue to provide developers with the key to 2.4 Bug fixes to ensure the smooth operation of online games! therefore:

  • Existing 2.x projects can continue to develop without a compulsory upgrade to 3.0.

  • For new projects, it is recommended to use version 3.0 for development. We will continue to optimize the development experience and operating efficiency of 3.0 to support the smooth launch of heavy games of different categories such as 2D and 3D.

Upgrading a project from a previous version of Cocos Creator is irreversible. Please backup the old version of the project before upgrading.

Most projects can usually be upgraded automatically, but because the project is inevitably unique, developers should try and evaluate the new version of the engine in advance according to the needs of the project. In addition, due to stability considerations, it is recommended that projects that are about to go online or already online should be carefully upgraded. The following is the upgrade instructions. If developers encounter difficulties during the upgrade, please give us feedback and we will try our best to assist.

Upgrade from <2.4.0 version

  • cc.loader is no longer recommended, please use the latest cc.assetManager instead, please refer to the Resource Management Module Upgrade Guide

  • The sub-package function has been upgraded to Asset Bundle, please refer to the Resource Subcontract Upgrade Guide

  • Adjusted the directory structure after the project is built and adjusted the API of BuildResults. If you use the editor plug-in to get the editor’s build results, please refer to Customized Project Build Process Upgrade Guide

  • The cc.RawAsset that was deprecated since 1.10 has been officially removed, please use cc.Asset instead. Since 2.4 is no longer compatible with the legacy usage of the RawAsset type in the original 1.x project, it is recommended that all projects be upgraded to 2.4, especially those upgrading from version 1.9, be edited in any 1.10 ~ 2.3 version. All warnings or errors output when the compiler compiles the code is processed correctly and then upgraded to 2.4.

  • cc.Color.fromHex is deprecated, please use cc.Color.fromHEX interface

Upgrade from < 2.3.3 version

  • The CCTexture2D and CCTexture2DRGB methods in the Effect have been abandoned.

  • Vec3.FRONT has been abandoned, please use Vec3.FORWARD instead.

Upgrade from < v2.3.0 version

Since v2.3.0, Android and Android Instant use the same build template, please note:

  • If the code is used solely by the Android platform, please put it in the app/src directory, and the third-party library used by itself, please put it in the app/libs directory.

  • If the code and third-party libraries used by Android Instant are separate, please put them in the game/src, game/libs directories.

  • For code and third-party libraries shared by Android and Android Instant, please place them in the src and libs directories under the root directory, respectively.

  • under the root directory jni/, jni/, mainly used to configure engine-related configuration, developer configuration, it is recommended that Android be placed in app/jni/ and app/jni/, Android Instant, please put in game/jni/ and game/jni/

  • When Cocos Creator compiles for Android, it will execute assembleRelease/Debug by default, and when compiling for Android Instant, it will execute instant: assembleRelease/Debug.

In addition, when Cocos Creator compiles for Android, it will execute assembleRelease/Debug by default, and when compiling Android Instant, it will execute in stant:assembleRelease/Debug.

If you have customized the pause logic when switching between audio background and background, please remove it after upgrading to 2.3.0 Currently Cocos Creator games automatically pause and resume audio internally when switching between front and back on all platforms. If the developer has customized this block before, and listens for and performs audio operations like cc.audioEngine.pause() and resume(), it may conflict with the engine’s default behavior. If you encounter related audio issues, simply remove the corresponding custom code.

Upgrade from version v2.0 – v2.3.0

Starting from 2.3.0, the Canvas component is no longer responsible for setting the Canvas node size to the screen size. This behavior will be implemented in conjunction with the Widget component. To ensure compatibility, after the 2.0 project is upgraded, the node where Canvas is located will automatically add Widget components. (No problem upgrading from a 1.0 project)

Upgrade from < v2.2.0

Starting from 2.2.0, we have strengthened the memory management mechanism, and now require users to dynamically create cc.Node which is independent of the scene node tree through code must be released through destroy(), otherwise the engine cannot know when to recycle this type The memory of the node will cause a memory leak.

  • In addition, the nodes that are manually removed from the scene need to be unified when they are not needed.

// Assuming testNode is a node in the scene, if it was manually

// removed from the scene before, such as

testNode.parent = null;

// or


// or


// If testNode will be used again in the future, there is no need to

// manually destroy the node otherwise it should be called manually


  • If a node is managed via cc.NodePool, it is not affected.

Upgrade from < v2.0

If you open the 1.x project, all resources such as scenes will be upgraded automatically. If there are warnings or errors in the code, you can refer to v1.10.0 Resource Upgrade Guide and the v2.0.0 Upgrade Documentation.


Dashboard for MacOS

Dashboard for Windows

Download Creator from Dashboard

Cocos Dashboard

The Cocos Dashboard serves as a unified downloader and launch portal for Cocos Creator. Everyone can upgrade and manage multiple versions of Cocos Creator. In addition, unified project management and a creation panel is integrated, which is convenient for everyone to develop projects with different versions of engines at the same time.

Manage projects developed under different versions:

You can choose to use a different version of Cocos Creator when creating a new project:

1 Like

Is there any roadmap for 2.4?

I would love to see the in-editor game preview, like 3.x, rolling into 2.4

We will just be adding polish to the future 2.4.x releases. No major new features.

Looking like a very nice upgrade for stabilization and bugfixes, thank you!

I do have though a problem immediately when trying to startup my 2.4.5 project into 2.4.6

I’m guessing this comes from:

  • Added VideoClip type, the video resource is automatically recognized as VideoClip format after import

But don’t know how to solve :thinking:, could a CC developer help?

Figured it out, it was my custom engine which wasn’t upgraded yet

I’m using AutoAtlas. After upgrading to 2.4.6, Cocos Creator generates non-compressed PNGs or five times bigger than 2.4.5.
Any idea? :slight_smile:

@Fabrizio i can ask engineering to take a look. Do you have any screenshots of the size difference?

There is no visual differences, just 2.4.6 generates uncompressed PNG files. Everything else is working fine. I tried to play a bit with AutoAtlas settings with no luck.

I understand, but perhaps an image of your file system or the way you see the size is 5 times the size? I want to make sure the team has everything they need to look into this.


I’m sorry. That’s not what I mean. Can you show the original size in 2.4.5 and then the increased size in 2.4.6?

Based on above files:
2.4.5.png 167,863 bytes
2.4.6.png 716,873 bytes

i am still waiting for normal-maps support ! … or does any one of you get it working ???

@Fabrizio the issue has been verified and the team will work on a fix.

Really? Phew…thanks for the info. I got some hope in waiting for it. :beers: