Cocos Creator 3.1.0 released!

Cocos Creator 3.1 is released

The launch of Cocos Creator v3.0 marks a new journey for Creator, and Cocos Creator 3.1 is the first cornerstone of the journey. This version update brings many great new features, including deferred rendering contributed by the Huawei HiSilicon team. Pipeline, PhysX physics backend support, etc.; at the same time, compared to version 3.0, various aspects of performance have also been optimized, such as frame animation performance, loading performance, package body, and so on. We will continue to cultivate deeply on the basis of 3.x, with a sincere attitude and dedicated spirit, steadfastly improve the product experience, and benefit all developers. All developers are welcome to use and experience! Please make a backup of relevant files before upgrading! The following is the detailed update!


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 and Cocos Creator 3D engines. 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:

Developer’s can choose to use a different version of Cocos Creator when creating a new project:

What’s new

  • Added deferred rendering pipeline (thanks to the contribution of the Huawei HiSilicon team), you can select the deferred rendering pipeline in the project settings:

  • Introduce multi-threaded rendering architecture. On the native platform, the traditional single-threaded architecture can no longer meet the rendering of large-scale scenes. Therefore, Creator initially split the traditional single-threaded architecture into two main threads, a rendering thread and a device thread, in v3.1. In addition to the split of the main thread, Creator also parallelizes the submission process of command buffers to speed up rendering efficiency. The multi-threaded rendering architecture diagram is as follows:

  • Added PhysX physics support, currently supports native platforms other than Android x86, and has a performance improvement of more than 100% on iOS (if you need to preview on the web platform, you can refer to the physics-3d project in example-3d, the main content is modified In the preview-template folder):

  • The editor supports bone octahedron display, you can visually see the distribution status of the model bones:

  • Support previewing animation on the Inspector of FBX/glTF resources:


  • Open the new version of the curve editor, support to edit the left and right slopes separately, and support the cycle mode of directly displaying the curve:

  • Android platform supports the construction of x86_64 architecture.

  • Support adding/removing components on the Prefab instance.

  • The Mac build supports the M1 option, which is used to better prompt the support issues of some known engine modules on Apple M1 (Silicon) architecture devices.

  • Added the laboratory function of scene instant cache, which is enabled by default, and can restore data after the scene exits abnormally.

  • The editor adds ui-curve and ui-curve-editor components, which can be used directly by plug-in developers.

Release Notes


  • Improve the operating performance of the engine’s native platform.

  • Improve the performance of engine frame animation.

  • Improve the loading speed of runtime resources (build mode).

  • Optimize the stuttering problem of the animation editor when editing a large number of key frames.

  • The auto atlas panel adds three optimization options when using auto atlas in the Bundle, which is used to eliminate unused resources in the auto atlas in the Bundle to reduce the package body.

  • Optimize the problem that the automatic atlas is referenced by multiple Bundles, which causes the pictures to be copied, and reduce the package body.

  • Shadow Map supports linear depth, depth map compression (mutually exclusive with linear depth function), self-shadow effect, and normal bias parameter settings.

  • Lighting Map supports RGBE format.


  • Optimize the event editing panel of the animation editor to avoid generating empty function data.

  • The release path of the build release panel is adjusted to a switchable protocol header.

  • The export/import build configuration function of the build release panel supports cross-version import after export.

  • The build release panel adds a verification mechanism, and the build cannot be built when the build options are filled in incorrectly.

  • Optimize the output log of packaged rpk for some small game platforms.

  • Optimize the construction of output log information and fix the problem of log loss.

  • Optimize the handling of resource loss, which can be automatically restored after resource recovery.

  • New Button locks the Label node by default, making it easy to select in the scene.

  • Fix the scene data problem that may be caused by exiting from Prefab.

  • The animation baking rate can be selected when FBX is imported.

  • Solve the problem that some FBX import will cause the editor to freeze.

  • FBX/glTF adds import option Promote single root node.

  • Fixed the issue that TiledMap was lost when importing .tmx resources.


  • Fixed the problem of TiledMap animation failure.

  • Fixed the problem that Spine did not take effect in native premultiplication.

  • Fixed the issue that the transparency display of Spine was abnormal when the premultiplication was turned on.

  • Fixed the incompatibility of Vulkan drivers for some models.

  • Fix the problem that the Shadow Map display of Metal related platforms is disordered.

Breaking Changes

  • The playback interface of AudioClip has been removed, and the started event monitoring is not supported. AudioClip is now a pure audio resource type.

  • You can no longer directly call the CCStandardShading function in the effect resource, and encapsulate it in the CC_STANDARD_SURFACE_ENTRY macro definition. It is recommended to only do custom logic in the surface function.

  • Rename the GFX module, remove the GFX prefix, and use import {gfx} from'cc'.

  • The automatic atlas and compressed texture switches have been removed from the build panel, and the project will be processed directly after the automatic atlas and compressed texture are configured.

  • Deprecated cc-fog header files, use cc-fog-vs and cc-fog-fs instead.

  • Removed some constants under sys, including sys.LINUX, sys.BLACKBERRY, sys.EMSCRIPTEN, sys.TIZEN, sys.WINRT, sys.WP8, sys.QQ_PLAY, sys.FB_PLAYABLE_ADS.

Known Issue

  • There is a problem with the keyboard and mouse adaptation of WeChat PC. We will fix this problem in v3.1.1. You can merge this PR manually to fix #8626.

  • The SafeArea component is temporarily unavailable. We will fix this problem in v3.1.1. You can solve this problem by manually merging this PR #8652.

  • You need to manually call the Sprite.updateMaterial function after setting the RenderTexture in Sprite, otherwise it may cause the problem of image flipping on some platforms.


Cocos Creator 3.x version has been officially released, version 2.4 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 update the version, providing bug fixes and new mini-game platform support to ensure that your project is successfully launched; 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:

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

  2. 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.

Upgrade from version <3.1.0

  • Starting from v3.1, the priority attribute of the UITransform component has been deprecated. If you need to adjust the order of the node tree, please use the setSiblingIndex method. Prior to v3.1, nodes that were created by code and depended on the priority attribute may have inconsistencies in the performance of the node tree. Please adjust them manually.

  • RenderTexture will be inconsistent between positive and negative on different platforms. In order to solve this problem, Creator has added the SAMPLE_FROM_RT macro to the effect. When using RenderTexture, you need to set the SAMPLE_FROM_RT macro to true, and each backend will be uniformly adapted to The correct effect.

Upgrade from version <2.4.5

Cocos Creator 3.x version has been officially released, and version 2.4 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 2.4 key issue fixes to ensure that games that have already been launched Smooth operation! therefore:

  • Existing 2.x projects can continue to develop with peace of mind, without compulsory upgrade to 3.0.

  • If you want to upgrade an existing 2.x project to 3.x due to project requirements, you can use the 2.x resource import tool provided by Creator. This tool will support the perfect import of old project resources and the auxiliary import of codes. Code-assisted import will convert js into ts, add component type declarations, attribute declarations and function declarations. The references of components in the scene will be preserved, and the code inside the function will be imported in the form of comments, which can reduce the developer’s upgrade Difficulty. For detailed upgrade instructions, please refer to the Upgrade Guide.

  • 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.

The upgrade operation of Cocos Creator to the project is irreversible. Please submit or 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, for stability considerations, it is recommended that projects that are about to go online or already online should be carefully upgraded. For detailed upgrade instructions, please refer to the Upgrade Guide. Those who encounter difficulties in upgrading, welcome to give us feedback and we will try our best to assist.



I just upgrade my project (in a different branch) from 3.0 to 3.1 and everything seems good so far.
My project is for web desktop and mobile.
One thing that I noticed is that my mobile build when accessed from a iPad I cannot play with the virtual joystick because it tries to scroll the page.
Same build accessed from Android works fine. Tested Safari and Firefox on iPad and had the same behavior.
It seems that after 3.1 upgrade the canvas is not getting touch inputs when running from iPad OS.

Anyone knows something about this?

I will ask the engineering team to help.

sorry, we tested our test case on iPad mini 5, but didn’t encounter the issue you mentioned.
could you please provide us with a simple demo project ?

Hey @PP_Pro

You can download the zip and the video here:!AnpkU0ouGo8Uiv4byhjnXts9tNsmuA?e=cC5ug3

It seems like the html canvas is not getting the inputs so the browser just scrolls the page up and down.

On the video you can see that the audio plays when I touch the screen but the car does not accelerate


So, I tested the Taxi example created directly with 3.1 and had the same problem

Trying on iPad (8th generation) iPad OS 14.5.1

Didn’t happen on iPhone though, so it seems by your tests that other iPads may not happen as well.

I’ll create a zip and send here soon.

Wow, I’m impressed how much android performance increased in this release. Good job!

Hey @PP_Pro

We tested here on:

  • iPad Pro (12,9 pol) (2nd generation)
    • iPad OS 14.4.1
  • iPad (8th generation)
    • iPad OS 14.5.1

And we discovered that it works on Chrome, so:

  • Safari don’t work
  • Firefox don’t work
  • Chrome works

Please check if you tested on chrome.
Hope you can take a look at this because this but is the only thing stopping us from upgrading to 3.1

Thanks for your attention.

Can you please fix the Tiled Map bug? You had this bug for 2 versions.
I opened two threads on this and I also posted a message in Chinees…

I made a video for the issue:

Got it, we’ll fix this issue on the coming v3.1.1
you can reference to this pull request:

Thanks for your feedback !

1 Like

Hey, thank you so much!

Do you already know for when 3.1.1 is planned to release?

Maybe in two or three weeks if our testing process goes smoothly :slight_smile:

i got an error when calling game.restart();

1 Like

Thank you for the Update.

Some things are not working:

  • Android 4.1 can´t be deployed
  • Dashboard disappeared

So i am not able to install it on such an older Device. Lowest Android is 5.1. What happened ? In release 3.0 it worked pretty fine. When starting, the well know dashboard in which you can select projects, see recent opened ones and so on, is disappeared. Also in previous vers. 3.01 it worked. What happend here ?

Hi, anyone have problem with animation when upgrade from 3.0.1 to 3.1? I try but all animation from 3D object not running if UseBakedAnimation is enable. version 3.0.1 work normal.

Let’s ask engineering.

can you provide a simple demo?

Regarding this issue, there is a problem on Android, and issue has been set up to track.
Tested yesterday, ios platform can be called normally, android shows exception.

Test Android version 4.4 using gles2 can run normally, Android 4.2.2 test is not possible. There is no test machine for Android 4.1, so I can’t test it.
This issue has been created to track and troubleshoot.