Important Updates

• Improved performance of Spine and DragonBones on native platforms #12788. Especially for Spine, performance gains of up to 40% or more on lower-end iOS devices. There are also significant performance gains on Android platform.

• [Experimental Feature] On the Web-Desktop platform, we have added a future-oriented rendering backend based on wasm technology - WebGPU (Chromium 105). Based on WebGPU backend, we will gradually add advanced rendering features such as ComputeShader, which is important to improve the rendering capability of the Web platform. WebGPU details can be found at https://www.w3.org/TR/webgpu/

Engine

• Removed USE BATCHING from the material options (please use USE INSTANCING) #12892
• Spine and Dragonbones components support batch rendering #12847
• Fixed errors when loading Spine files in binary format #12894
• Fixed some bugs related to GPU Instancing #12786
• New default skybox #12917
• Fixed okhttp doesn't call close in onClosing on Android #12783
• Fixed an issue that downloading resources will fail when url request doesn't encode space #12826
• Properties of color type support FLOAT3 in Cocos Effect  #12962
• Fixed the problem of setting special fonts (such as OpenSans-BoldItalic) on some native platforms #13048
• Fixed the drawing errors caused by type errors in Graphics component #13037

Editor

• Fixed the issue that the Visibility property of the Camera component does not load user-defined Layers in the Inspector
• Bundle names only support numbers, letters, underscores and minus
• Fixed the problem that copy and paste camera nodes will report errors
• Fixed the problem of switching from animation mode to prefab mode will cuase prefab data error #12752
• Fixed the orthogonal view display error in scene editor
• Fixed the problem that the properties in the script component cannot be saved properly when they refer to the children nodes of prefab
• Fixed the problem that the resolution of the small preview window of selected camera is not consistent with the settings when paused in Preview in Editor mode

Known Issues

• In version 3.6.2, we moved Spine's updating logic to the C++ environment on the native platform for better performance. Because of the different garbage collection mechanism in the C++ environment, errors are reported in some use cases that refer to suspended pointers. Please avoid the following usage in your development as much as possible: 1. manipulating data of node that are not added to the scene (including component data), and 2. using isValid to determine if a node exists when you need to operate it in a callback. We will fix this issue in 3.6.3.
• When using semi-transparent images in the WebGPU backend, the color could be pre-multiplied bytransparent channel and causing rendering artifacts, it can be solved temporarily by adjusting the blend modein the material.
• The CopyTextureToBuffers interface is not currently supported on the WebGPU backend.

Cocos Creator 3.6.1 Release Notes

After the release of v3.6.0, we received a lot of feedbacks from developers about user experience, performance, issues and so on.

Thank you for your continued support.

In v3.6.1, we fixed many of the important ones from these feedbacks and recommend all users who are using v3.x to upgrade.

The following is the main content of this update.

Engine

• Added the feature of saving image data on native platforms #12503
• Support text shadow, italic on iOS platform #12421  #12382
• Now you can play *.wav audio properly on Windows
• Optimized the performance of animation system on some platforms which support JIT #12308
• Optimized the performance of some parts of the UI system for iOS platform #12390
• Refactor the Mask component. Instead of inheriting from the rendering component, it holds a rendering component so that it no longer affects its children nodes #12636
• Modify the Websocket:onclose API on native platforms to be consistent with the web standard #12370
• Add approxEquals method to the math library on the native platform to determine if it is approximately equal#12610
• Optimized the efficiency of JSBClassType::findClass on native platforms #12548
• Reduced the package size of the app built for Android platform, reducing unnecessary third-party library references #12537
• Fixed an issue that may cause interruptions when multi-tasking downloading on iOS platform#12743
• Fixed a problem caused by extra spaces when parsing HttpRequestHeader#12757
• Fixed possible resource loss when cropping engine modules (e.g. particle-2d module resources lost due to cropping 2d modules)#12602
• Fixed the problem that tiledtile cannot be moved #12377
• Fixed spine/dragonbones engine modules cropping problem #12605
• Optimize spine memory usage, using RGBA8 color format#12619
• The Anisotropic Lighting parameters of Cocos Creator materials can be interfaced with the Substance material library.#12371#12376
• Fixed the bug of Downloader connection timeout setting error on Android platform #12642
• Fixed the problem that the configuration of jointTexture does not work on native platform #12639
• Fixed the problem that mesh.minPosition and mesh.maxPosition return a type other than Vec3 on native platforms #12628
• Fixed a possible crash caused by Node::isChildOf on native platforms #12493
• Fixed the problem that ValueArrayPool::get may trigger asserts in DEBUG mode on native platforms. #12499
• Fixed the problem that building to Android on Windows will report an error when the project path contains spaces #12754
• Fixed some rendering issues with Fog and Debug View #12571#12343
• Fixed the problem of possible lag when playing audios on Android platform #12589
• Fixed a memory leak when changing clips of an AudioSource #12592

Editor

• Support for tif and tiff format images
• Support for displaying build progress in the taskbar on Windows
• Allow decorators for array properties in script components to affect their elements
• Support dragging transition to sort priority in Marionette system
• Optimized event handling of animation editor, function name can not be nil
• Support for command line builds using pre-configured settings from the build panel
• Support Cocos Creator - Preferences - Engine Manager - Use Custom use relative paths
• Optimized the scene editor launch process to speed up the launch speed
• When the image compresse quality of png/jpg/webp is set to 100 or the compressed size is larger than the source image, the source image will be used directly.
• Fixed the problem that Sprite in the scene editor may not be rendered after editing its SpriteFrame
• Fixed the problem that the scale of a Prefab cannot take effect in real time in the scene editor after modification.
• Fixed the problem that the onBeforeMake and onAfterMake callbacks are not triggered when building
• Fixed the problem that the nodes are not displayed normally after using filters in the animation editor
• Fixed the problem that some scene data will be left when a parent node is deleted after the children are mounted to others
• Fixed the problem that the name may be lost when using SpriteFrame resources in scripts
• Fixed the problem that the generated file extension is wrong after importing *.webp images as Cubemaps.
• Fixed the problem that the 'scene:create-component' message does not correctly receive the parameter: component {string}
• Fixed the problem of status displaying incorrectly when ui-asset / ui-component / ui-node is missing.
• Improved some other details and experience of the editor

Known Issue

• After upgrading to 3.6.1, L10n as an experimental feature, still needs the help of an external extension to make it work properly. If you need it, please move to the forum post at https://discuss.cocos2d-x.org/t/3-6-1-l10n-patch/57222 to download the extension.

Cocos Creator 3.6 is an important milestone for Cocos Engine, and it also has the longest iteration since Cocos Creator 3.0. This version has significant improvements in rendering, editor features, performance, and enhancements in stability and compatibility of the engine. Due to the large number of updates (engine: 1110 PRs, editor: 678 PRs), only the relatively important ones are listed here. 

Important Updates

Rendering

Surface Shader

Surface Shader uses a unified rendering process and structure that allows users to write shaders that focus onsurface material without anything related to the lighting model. The advantages over the older version (Legacy Shader) are easier to write and maintain, better version compatibility, and less prone to rendering errors. And you can get a lot of public features from the unified process, such as unified environment lighting, rendering debug view etc.Surface Shader also makes it easier to provide a variety of common and complex materials to users in Cocos Creator.

Cascaded Shadow Maps

The regular shadow map has a serious drawback: when the projection area is large, a very high-resolution shadow map texture is needed to achieve a good shadow effect, which may exceed the limits of the hardware capacity. If the resolution is not increased, the shadows will be jagged, shapeless and unclear, but reducing the projection area will result in a very short shadow distance, objects a little further away will lose their shadows. Adjusting the balance between shadow distance and shadow quality is a major headache and it has been in previous versions.

CSM (Cascade Shadow Map) divides the view frustum into multiple blocks from near to far, with a smaller projection area for the near block and a larger projection area for the far block, which is equivalent to an adaptive shadow map, thus increasing the utilization of shadow map texture several times. It can have a very precise shadow for closer objects and a just fine shadow effect at a longer distance from the view point, so developers no longer have to spend their time on shadow parameter settings.

Rendering Debug View

This feature provides a variety of custom display modes to help users investigate issues of material, lighting, and shadow display much faster. It also allows users to view specific scene information more clearly and provides a reference basis for optimization decisions.

GGX Convolution

Since the specular of direct lighting are using GGX BRDF model, for environment lighting the same BRDF must be used for spherical convolution in order to make the lighting effects of both light sources correspond. In addition, by storing the reflection information of different roughness in the corresponding mipmap level, the convolution calculation can fix the following problems compared to the automatically generated mip maps.

1. Flooding and trailing of Environment Lighting specular are greatly reduced
2. Different effect from Substance's standard PBR material
3. Difference between specular of direct lighting and environment lighting

As shown below:

Anisotropic Lighting

With the benefit of Surface Shader, we can fully extend the PBR lighting model. In V3.6 there is complete support for isotropic and anisotropic materials and lighting models of Direct Lighting and Environment Lighting. You can work with Substance PBR material library to create brushed metal, hair, silk, etc.

Others

1. Support for setting Skybox material
2. Add the Normal Strength range of material
3. Support for glTF specular-glossiness workflow
4. Enhanced support for the default FBX surface-phong material
5. Extended Specular channel support for Blender principled BSDF materials
6. Add support for materials of mixamo.com model

---

Editor

UI Enhancements

V3.6 has updated a new version of editor user interface, and has made an all-round reconstruction in order to achieve a "more coordinated" visual system, "more scientific" visual feedback, and "more immersive" interactive feeling. In the future, we will continue to standardize design based on Cocos' design principles, continue to update and iterate, and continue to optimize core interactions and workflows.

Preview in Editor

Development efficiency is a core value that Cocos Creator places great importance on, and in V3.6 this has been further improved. In addition to the "Preview in Browser" and the "Preview in Simulator", developers can now use the "Preview in Editor" to preview the project. In this mode, the scene manager will run the code directly, allowing developers to debug scenes in real time. While bringing a seamless preview experience, it also makes up for the shortcomings in debugging.

This feature is currently in experimental stage, welcome to give us more feedbacks about it. In the future, we will also continue to focus on development efficiency and continue to improve user experience in script compilation, project debugging and build release.

Embedded Players for Animation Clips

Animation Editor adds the ability to embed players, developers can embed other particles and other animations in any animation. Moreover, it can be programmed in a way like editing tracks in video editing software, with free adjustment of duration and playback position.

After editing, the content of the embedded player will play along with this AnimationClip, which is supported in both Animation component and Animation Graph. This feature is also available for animations from FBX, allowing for more flexible effects control and solving the problem of imported animations being difficult to re-edit.

Both particle and animation players are currently available in V3.6 and can be enabled in the Preferences > Laboratory.

Localization Editor

To better produce multilingual versions of projects, V3.6 provides a built-in multilingual tool, Localization Editor (L10n), which currently supports text translation and resource replacement. It is positioned to deeply integrate with Cocos Creator and improve the efficiency of translation through highly automated tool. In a codeless way, it's very intuitive and lowers the usage threshold.

Main Features:

1. Support for AI translation, currently connected to Google and Youdao
2. Support for one-click extraction of all kinds of content that needs to be translated
3. Support for import and export Excel, csv, po files in batch
4. Support for real-time preview and resource replacement

Localization Editor is currently in the experimental stage and will provide richer localization capabilities in the future, we look forward to your feedbacks.

Scene Editor

1. Support for Surface Snapping and Vertex Snapping

2. Support for box selection, you can quickly select multiple objects

Build

1. Developers can freely select and combine Build, Make, Run and other subtasks in the build panel to execute
2. Resource Server Address has been used as a common parameter for all platforms, and you can also check the useBuiltinServer option to use the built-in server address for easy local development testing
3. Optimized the task scheduling of engine compilation and script compilation at build time, with independent process execution to reduce the memory consumption of the build process
4. Add custom cmake tools in the preferences panel that will be used when building native projects
5. New onError hook function in the build process to catch build failures
6. Allow to turn off Cache Build Engine, Cache Compressed Texture, Cache Auto Atlas in Preferences > Build

Others

1. Support for thumbnail display of 3D meshes
2. Support for removing the frame rate limit on the scene editor (lab feature)
3. Supports filtering the Bundle folder directly in the assets panel to quickly find Bundles

---

Infrastructure

Convert more infraustructure to native C++ implementation

For higher performance, more realistic rendering, better compatibility, more scalability, and better productivity, theCocos Engine team has been iterating and refactoring the core engine framework continuously since the release of version 3.3.

It took the engine team more than a year to refactor the engine in multiple phases and modules to achieve a significant all-around improvement while still maintaining compatibility with old projects.

While bringing significant performance improvements and rendering enhancements, it also lays the groundwork for further iterations of the engine in the future.

From the microcosm of V3.6, we can see the determination of the Cocos Engine team: to insist on constant self-change to keep up with the update of hardware and the changing needs of our users.

2D Rendering Performance

Another important milestone for V3.6 is that it reaches the same level of 2D rendering performance as V2.x. This means that V2.x users can upgrade to V3.x with confidence. Based on the work of converting infrastructure to native C++ implementation, we have made the 2D rendering data structure, 2D batcher, and rendering process all native so that the 2D batching and rendering processes are performed natively to achieve V2.x's performance. At this stage, there is still some legacy work left to be done, such as supporting Spine batching and fixing iOS WeChat drawbacks, but this also means that there is a higher ceiling for 2D rendering performance V3.x needs us to break through.

Native Extensions

Native extensions can link to a developer's existing C/C++ code base, bind interfaces to the JS layer and be reused across projects.

With the power of CMake, extensions can flexibly integrate source files, static libraries or dynamic libraries. C/C++ interfaces can be exported directly to the scripting layer using the traditional auto/manual binding mechanism, or using the new sebind high-level interface added in V3.6. Once developed, the native extensions can be distributed individually as zip packages or packaged as editor extensions.

Please take a deeper look into the usage manual and the example case.

New RenderGraph Infrastructure

As the infrastructure for the next-generation custom rendering pipeline of our engine, we have wrapped the higher-level RenderGraph on top of FrameGraph to provide a series of capabilities and APIs for building rendering pipelines more easily. Includes typescript based cross-platform pipeline description, material system pre-processing, automatic management of various render states, transient render resources lifecycle management, and other capabilities. We have already implemented our web version forward and deferred rendering pipeline with RenderGraph. In future releases this year, we will replicate the native platform pipeline in its entirety, and open up the built-in pipeline customization capabilities based on RenderGraph, such as adding post-processing effects. At the same time, the ability to produce an entirely customized rendering pipeline based on RenderGraph will be fully open to developers.

Currently, you can select forward or deferred pipeline by setting `CUSTOM_PIPELINE_NAME` to `Forward` or `Deferred` in the project's Macro Configuration, and you also need to turn on "Custom Render Pipeline (Experimental)" in the Feature Cropping. The usage details can be found in the usage documentation.

Others

1. Added an easier-to-use JS binding layer Sebind
2. Integrated Android Game Activity
3. Supports Downloader breakpoint transfer on iOS/Android
4. Added the `settings` module for user access, which holds the user's pre-defined runtime project configuration
5. Refactored the engine startup process, simplified the code of application.js, and added more events to the startup phase

Framework

Marionette Animation System

• Animation Graph supports preview while editing
  When editing the animation state machine, you can preview it in real time to see the result of transition and blending, and debug it quickly without having to run the game after each modification to see the result.

• Animation Graph supports renaming variables and Layers
• Animation Graph supports sorting of transition lines to clearly see the priority of the transitions
• Animation Graph adds the "Destination Start Time" property, which allows the target animation to start playing from the specified position.
• Animation Graph can now allow specified transitions to be interrupted by other transitions, this feature can be enabled in the Preferences > Laboratory.

Particle System

•  Add  Noise Module to bring a more natural and controllable random motion effect to the particles

• Models in particle systems support GPU Instancing to improve emitter performance
• Particle editing support Undo operation, improve the efficiency of particle effects creation
• Support for previewing and controlling particle groups in the Hierarchy

Others

• Support for dynamic mesh, developers can now update the mesh data at runtime through API

• Add new curve type Spline to GeometryRenderer (support Linear, Bezier, Catmull-Rom curves)

• Support for SpriteRenderer in 3D space
• Fill z-values in UI vertex data to support 3D Transform of UI
• Support for prioritization of rendering components
• Supports access to PCMData and sampleRate from audio 
• Support for terrain brush rotation
• Support for terrain height brush

• Support for using tga format texture by light map baker 
• MeshRenderer automatically sets the light map resource for rendering
• Update EditBox style for iOS native platform

---

DCC

Import Phong & PBR materials from FBX/GLTF Automatically

When importing materials, V3.6 supports Diffuse-Specular material models (including Phong and SpecularGlossiness PBR), which can intelligently convert material parameters to standard Metallic Roughness PBR models. This allows you to get a material representation close to that of the original DCC software without changing the lighting model.

Mesh Split disabled by default

Due to the limitation of the number of uniforms, in CPU computed skeletal animation, when the number of skeletonsexceeds a certain value, it is not possible to store all the skeleton data by uniforms at once, so in the previous version, we may split the meshes and bones. We often received feedback that one of our character models would take up multiple draw calls, mainly because it was automatically split here. What's more is that since splitting cannot be done at runtime and can only be pre-processed, our splitting criteria can only be used as a reference for lower hardware devices and drivers (iPhone 6 WebGL), which is very limited for the number of skeletons.

Therefore, Cocos Creator 3.6 has made a strategic optimization of this issue as follows:

• By default, the model is no longer split and no changes are made to the imported model data (also keep model settings unchanged)
• If the number of bones does not exceed the limit of the actual runtime driver, it will be passed directly using the uniforms
• If the number of bones exceeds the limit, it will be passed using textures

Note: Using textures to pass skeletal animation data requires the ability to access textures in the vertex shader. This feature is minimally supported by OpenGL ES 3.0, WebGL 2.0. But relies on GL extensions, it has almost 100% coverage on devices which only support OpenGL ES 2.0 and WebGL 1.0 , so there is no need to worry about compatibility issues.

This option is currently retained only to maintain compatibility with old projects and will be considered for removal when appropriate.

---

Upgrade Tips

• Windows platform no longer supports for publishing to Win32, only Win64 is supported
• Minimum version support for iOS platform changed from iOS 10.0 to iOS 11.0 (in order to use C++ 17)
• The name of the built-in material is unified with the name in the editor, so you need to add the "builtin-" prefix when using the built-in Effect by calling EffectAsset.get and Material.initialize.
• The application.js, game.js, index.js, etc. files in the build template have been updated. If you have customized the template in your project or build-extension, please regenerate it and make changes accordingly. See Upgrade Manual for details.
• The format of settings.json file has been modified, extensions that have customized this file may not work. See Upgrade Manual for details.
• Since the nodes under the Mask will be specially handled inside the engine, it is recommended to use the getChildByName function to get the child nodes under the Mask by the name instead of index to avoid unpredictable problems.
• Android gradle：replaced jcenter by mavenCenter 
• Add `native` module that can be imported from `cc`, including code hints, to replace the `jsb` global variable.
• The ES6 to ES5 conversion feature of ByteDance Developer Tools is disabled by default to resolve some compilation issues. So developers need to manually adjust the open data domain template project to conform to CommonJS specification, otherwise it will cause the subdomain launch failure when running projects on ByteDance platforms because it cannot recognize ES Module. If your project also encounters this problem, please refer to https://github.com/cocos/cocos-engine/pull/12334/files and make corresponding changes to files under the path "project-path/build/bytedance-mini-game/ openDataContext"

Editor Update

• Fixed an issue where an error might be reported when modifying properties of nested prefab.
• Fixed the problem that the initialized width and height of the material preview are not integers, causing an error to be reported.
• Fixed the problem that the script reading npm package did not correctly process the upper-level package.json, causing the reading to fail.

Engine Update

• Fix memory leak issue when switching scenes in editor (engine#11355)
• Remove unnecessary data saving dialog when editing material in node inspector (engine#11284)
• Fix isnan(0.0) issue in shader for glsl100 (engine#11262)
• Fix specular params with toon surface (engine#11265)
• Code format and add sliders for DCC material parameters (engine#11266)
• Fix rendering bug caused by setUseBakedAnimation operation (engine#11267)
• Fix websocket onError not call onClose on Android (engine#11441)
• Don't force top align for editbox's placeholder label (engine#11303)
• Fix more API docs in core (engine#11338)
• Add api doc for vertex format (engine#11394)

V3.5.1 adds two far-reaching experimental features without affecting the stability of the original functionality of V3.5.0. The first is the Smart Material Conversion which permit to import DCC default materials from FBX, restoring the materials and appearance created by artist in various DCC tools. The second is a series of built-in Surface Shader material resources, which will be the cornerstone of material customization in the future. In addition, we have shipped with this version a series of critical fixes, experience optimizations, and numerous documentation optimizations. We strongly recommend that all 3.x users upgrade.

Important Updates

Experimental: FBX Smart Material Conversion

FBX Smart Material Conversion is a feature in the model importer that assists in converting materials. It maps some of the standard materials exported from various DCC tools directly to Cocos Creator's built-in materials, restoring as much as possible the material effects seen by the artist in the DCC tools. This feature supports some of the standard materials in mainstream DCC tools: 3ds Max, Blender, Maya, C4D.

You can compare the effect of the Standard Surface material in Maya after importing it into Cocos Creator:

Appearence in Maya tools

Appearence in Cocos Creator after turning on FBX Smart Material Conversion

For more information on how to use this feature, please refer to the usage documentation.

We will also continue to optimize the model and material import experience in 3.6, so stay tuned.

Experimental: New Surface Shader

Since version 3.0, many developers have experienced the problem of materials not working properly during the upgrade process and need to migrate. The root cause of this problem is that the engine's lighting model and surface material calculations are being adjusted along the way, which affects all related material effect codes and also affects the compatibility of these materials when reused by users.

In order to improve the compatibility of the material system, we have added a series of Surface Shader resources that abstract the lighting model and surface material calculations in the engine, so that future developers can use these built-in headers and functions to greatly simplify the effect resources they write. At the same time, due to the abstraction, cross-version compatibility will also be more secure.

Please refer to the usage documentation for more details on the use of Surface Shader.

Documentation optimization

In v3.5.0, we updated the API documentation page with a new version, which was well received by developers with some important feedbacks. In v3.5.1, we continued to do a lot of documentation checks, with nearly 40 PRs to further complete some remaining API documentation and fix some documentation errors. We hope to bring developers a better and better documentation experience.

Important fixes

1. Fix the problem of slow preview speed on browsers

2. Fix the problem that the preview is not available on Mobile Safari.

3. Fix the problem that some materials cannot be upgraded automatically from 3.4.2 or lower version

4. Fix the possible error and performance problem of 3D particle system when switching states

5. Fix the light and shadow effects of deferred pipeline.

Detailed Updates

• [FEATURE] Add smart material conversion for FBX importer
• [FEATURE] add experimental surface shader (engine#11048)
• [OPTIMIZE] change camera settings to orthogonal type in 2d scene templates (engine#11020)
• [OPTIMIZE] Improve API documentations in engine
• [OPTIMIZE] Add a new experimental import strategy in AssetDB, avoid repeative import process
• [OPTIMIZE] Update lightmap tool LightFX
• [OPTIMIZE] Inspector keep group display order
• [OPTIMIZE] Improve shadowmap settings in default scene (engine#11213)
• [OPTIMIZE] Optimize anisotropy sample (engine#11075)
• [OPTIMIZE] Spotlight interface description change (engine#10964)
• [OPTIMIZE] Listen WINDOW_RESIZE event by application (engine#10930)
• [OPTIMIZE] Load libGLESv3.so by default while user choose glesv3 (engine#10941)
• [OPTIMIZE] Allow native projects use user pre-set global cmake variables (engine#11011)
• [OPTIMIZE] Refine MissingScript debugger (engine#10916)
• [OPTIMIZE] Automically unfold array list when editing array length in the inspector
• [OPTIMIZE] Optimize curve unit test (engine#10912)
• [FIX] Fix long loading time issue
• [FIX] Fix camera preview not working issue
• [FIX] Fix no responding due to lock on scene scripts
• [FIX] Fix preview issue on some browsers like Safari
• [FIX] Fix inspector cannot create new clip under animation editing mode
• [FIX] Fix clip list not updated after clip creation under animation editing mode
• [FIX] Fix clip removal check under animation editing mode
• [FIX] Fix frequent update of nodes in the animation editor
• [FIX] Improve error handling during node data migration for animation clip
• [FIX] Popup warning when regenerate an exist prefab asset
• [FIX] Fix asset builder issue which cause wrong JSON group for auto-atlas asset and duplicated assets in JSON
• [FIX] Data tolerance for animationBlendType in AnimationGraph
• [FIX] Fix conflict after importing custom texture compression config
• [FIX] Fix code sample issue in the template of the builder's plugin
• [FIX] Fix engine error caused by material switch
• [FIX] Fix prefab data copy issue when the root node is 2d node
• [FIX] Fix issue when copy component data from prefab instance to other prefab
• [FIX] Fix error when AnimationGraph panel is initialized during editor startup
• [FIX] Fix selection issue in scene editor when viewing on screen with dpr larger than 2
• [FIX] Avoid potential infinity loop in tickInEditMode
• [FIX] Fix error caused by empty result when dumpping node data
• [FIX] Fix error when typing enter in the texture name field of the joint texture layout
• [FIX] Fix builder malfunctioning after importing configurations
• [FIX] Fix view rotation after modifying scale value of the preview window
• [FIX] Fix part of circular reference issue by upgrading rollup to 2.37.0
• [FIX] Fix collision matrix setup issue in project setting
• [FIX] Fix issue that the last panel cannot be dragged in dock
• [FIX] Circular references should cause workflow failed (engine#10841)
• [FIX] Fix geometry-renderer in deferred pipeline (engine#10890)
• [FIX] Fix meshBuffer checkCapacity bug (engine#10910)
• [FIX] Remove ambient.mipmapCount (engine#10920)
• [FIX] Fix auto-atlas test bug cause time sequence (engine#10914)
• [FIX] Fix fog is more brighter with native engine (engine#10972)
• [FIX] Fix android crash due to surface not ready (engine#10984)
• [FIX] Fix pause operation fail when play and pause audio in the same frame on native platforms (engine#10990)
• [FIX] Fix instanced model has no spot light shadow (engine#10921)
• [FIX] Fix particle system memory issue (engine#11032)
• [FIX] Terrain and model automatic choose lightmap shader (engine#11006)
• [FIX] Correct render pipeline script template error (engine#10927)
• [FIX] Fix animation mask data cannot be load from gltf (engine#11033)
• [FIX] Fix shader migration from lower version (engine#11038)
• [FIX] Fix subcontextview for wechat platform (engine#11049)
• [FIX] Fix notifySkinnedMeshRemoved (engine#11074)
• [FIX] Fix word wrap for Vietnamese characters (engine#10925)
• [FIX] Instantiate all FastDefined objects as value type (engine#11052)
• [FIX] Fix format feature request for Float32 for gles3 and webgl2. (engine#11084)
• [FIX] Fix eglSwapbuffer error due to eglSurface is not ready (engine#11083)
• [FIX] Disable gametick after enter background(revert to logic to version 3.4.2 (engine#11095)
• [FIX] Skip a pair of quotations for avoiding spaces when image name are detected in RichText (engine#10954)
• [FIX] Assign underline initial value when label segments are contructed in RichText (engine#10954)
• [FIX] Fix clear particle bug (engine#11066)
• [FIX] Fix ndc->world with deferred shading (engine#11099)
• [FIX] Remove enableBatch from spine/db (engine#11100)
• [FIX] Fix deferred pipeline depth stencil with linear sampling in webgl2.0 (engine#11110)
• [FIX] Fix multi blank lines (engine#11116)
• [FIX] Fix ios accelerometer not working (engine#11142)
• [FIX] Add sky.effect with surface shader (engine#11156)
• [FIX] Fix error during particle switch (engine#11139)
• [FIX] Change logger level (engine#10944)
• [FIX] Don't push data if debug is not enabled. (engine#11118)
• [FIX] Fix physics collision matrix (engine#11181)
• [FIX] Fix multi quotations bug and add unit tests (engine#11190)
• [FIX] Fix light flashes at instanced model (engine#11203)
• [FIX] Solve getInstancedModel judgment error (engine#11205)
• [FIX] Fix prefab generates incorrect data (Repeated node) (engine#11211)
• [FIX] Fix terrain index buffer sharing bug (engine#11206)
• [FIX] Fix isnan(0.0) with webgl1.0 (engine#11262)
• [FIX] Fix specular params with surface toon (engine#11265)

Important updates

Marionette animation system

We added the Marionette animation system in v3.4 for complex character animation. It supports state machine editing and weighted blending. In v3.5, we added several crucial new features to the Marionette animation system. Layer and skeleton masks are the most important updates because they allow the developer to separate animation blending for different character parts.

Improvement for 2D-only projects

For 2D users and 2D projects, we have improved the user experience in the editor. It's been a very popular request for 2.x users when they consider upgrading. We have progressively improved things and will continue to do so. In v3.5, you can see the following changes:

1. All scenes created in 2D projects will only contain a default canvas and a 2D camera (ortho projection).
2. The scene view is in 2D mode by default.
3. Some inspector is adjusted for 2D editing.
4. All 3D modules are not selected by default, and there won’t be 3D features in the additional component panel and node creation panel.
5. If you want 3D features back, you can just select 3D modules back in the project settings.

Frame Pacing Library (Swappy)

For quite a while, we have been working with Google to bring a better Android development experience to our developers.We are proud to announce Frame Pacing Library has been integrated into v3.5. It's part of the Android Game Development Kit (AGDK). It helps OpenGL and Vulkan games achieve smooth rendering and correct frame pacing on Android. You can activate Frame Pacing in the Android build panel.

Geometry Renderer

A new simple geometry render API is introduced in v3.5. It's designed for simple debug rendering using prebuilt primitive geometry types. It supports lines, boxes, spheres, polygons, etc. You can draw them in wireframe or solid mesh. All drawing geometries are in world space with a configurable transform. Furthermore, some geometries can be affected by real-time lighting.

Detailed functionalities are shown in the following chart.

Material editing improvement

We have put a lot of effort into visual effect upgrades in the past versions. Meanwhile, we have also started to invest in improving the DCC workflow. We are starting to ship some improvements in v3.5.0, and you will see much more coming in future releases. Here are what you can expect in this version:

1. You will no longer need to dump material and modify it into a new one, you can directly modify the imported material of the FBX/GLTF.
2. While you edit the material, you can now use undo / redo to reverse or rewind actions.
3. When switching effects during editing, the same properties (e.g. 'mainTexture') will be cached and retained.

Flatten tool in the terrain editor

Terrain editor now has new brush modes Flatten and SetHeight with a height parameter. It's for more effortless sculpting fixed height planes in the terrain editor.

Platform Abstraction Layer

In v3.5, we assembled all platform-related low-level adaptations into Platform Abstraction Layer, including system info, window adaptation, audio, input, etc. The distribution of system-level events is also unified. This is a low-level refactorization, developer-level API hasn't been affected, but it will allow Cocos to adapt to new environments more easily.

Various performance optimization

We continue to improve performance in v3.5, here are the most visible ones.

1. The performance of spine and dragonbones on native platforms has been improved by reusing the same buffers between native and JS instead of copying them in previous versions.
2. Optimized memory occupation of RealCurve, CurveRange.
3. Optimized decorator performance for particle system instantiation.
4. Improved WebSocket power consumption on Android by using okhttp for implementation.
5. Improved Label and Graphics render performance on native with less invocation from native to js.

API documentation redesign

We are genuinely sorry that the previous API documentation usage experience is relatively poor, making the user's learning curve steeper. In v3.5, we are using a new generator to make it more clear and more reliable. It's just a start, and we will continue to improve the content of API documentation in the following months.

Please take a look at our new API documentation page.

Engine repository transfer and customization

To better support open source community, we have merged our engine native repository into engine repository, and it has been transferred to cocos/cocos-engine. Since now, we will be more open by maintaining public issues and public projects. If you are using customized engine, you must pay attention to this change, from v3.5, you only need to clone one engine repository. All customizations in typescript engine can be rebased to v3.5, but previous customizations in native engine must be reapplied manually through diffs. You can refer to the engine customization documentation.

Breaking changes

• [FIX] Fix dragonbones/spine sockets transform (engine#10260)

From version 3.5.0，please do not set an using node as the target of sp.Skeleton’s (or dragonBones.ArmatureDisplay) sockets directly, otherwise the transform parameters (Position, Rotation and Scale) will be overritten. The correct way is creating an empty node as the target node, and setting components which to be attached to Skeleton component as children of the target node. For more details and examples please read the Spine Attachment documentation.

• Instead of global configuration of shadow bias, now we support individual shadow bias configuration for models, this allows detailed control of shadow effect on simple or complex surfaces. If you have any custom effect, please refer to the upgrade documentation for enabling it.
• The effect syntax for Macro Tags and Functional Macros have been upgraded to avoid the occupation of standard glsl define, old effects in project will be upgrade automatically, but if you are using external effects without meta or writing a new one, you have to pay attention.
  • New syntax for Macro Tag: `#pragma define-meta`
  • New syntax for Funtional Macro: `#pragma define`

Known issues

• On iOS 15.4, Apple enabled experimental feature "WebGL via Metal" by default, it's causing some games to have serious rendering issue (graphics not refreshing, strange artifact etc). It's been tracked in the issue, the temporary workaround is to disable `ENABLE_WEBGL_ANTIALIAS` macro in project settings (only disable it for iOS build is suggested). It will probably be fixed in future iOS versions.

Detailed change log

• [FEATURE] Marionette: layer, mask, auto-reset trigger, empty state, localization (engine#10179)(engine#9913)(engine#10550)
• [FEATURE] Improve user experience for 2D only project
• [FEATURE] Integrate Android Frame Pacing library (engine#10327)
• [FEATURE] Add low level geometry renderer for debugging (engine#10189)
• [FEATURE] Make builtin material of FBX and GLTF directly editable (engine#10518)
• [FEATURE] Support undo redo on editing assets (engine#10657)
• [FEATURE] Add Flatten and SetHeight sculpt tool to terrain editor
• [FEATURE] Support drag or select animation clips directly to the animation editor for editing
• [FEATURE] Make animation module optional (engine#10257)
• [FEATURE] Add shadow bias setting for MeshRenderer (engine#10102)
• [FEATURE] Add constants for surface shaders (engine#10590)
• [FEATURE] Support selecting mipmap range for Texture2D and TextureCube. (engine#10500)(engine#10096)
• [FEATURE] Add Texture2D option to fix blending artifact caused by semi-transparent pixels (engine#10419)
• [FEATURE] Add a new interface to query format feature info: Device.getFormatFeature (engine#9949)
• [FEATURE] Add specular intensity for DCC effects (engine#10613)
• [FEATURE] Rich text supports vertical alignment (engine#10340)
• [FEATURE] Add spacingX property to Label inspector for BMFont type (engine#9541)
• [FEATURE] Distribute touch events independently (engine#10712)
• [FEATURE] Add destroy window event and recreate window event on windows platform (engine#10365)
• [FEATURE] Add Node.getPathInHierarchy for getting complete path in hierarchy (engine#9536)
• [FEATURE] Support custom texture compress tools in the Project Settings
• [FEATURE] Support engine separation feature in OPPO platform build
• [FEATURE] Support the OS Target (simulator or device) option in iOS platform build
• [FEATURE] Add cmake hooks support for cocos-service (engine#10691)
• [FEATURE] Support inspector droppable config (engine#10440)

• [OPTIMIZE] Redesign platform abstraction layer
• [OPTIMIZE] Optimize memory occupation of RealCurve, CurveRange (engine#10346)
• [OPTIMIZE] Optimize decorator performance for particle system instantiation (engine#10323)
• [OPTIMIZE] Avoid spine & dragonbones copping buffer from native to js (engine#10235)
• [OPTIMIZE] Android: reduce power consumption by using okhttp to implement websockets (engine#10384)
• [OPTIMIZE] Improve CameraComponent inspector user experience (engine#10708)
• [OPTIMIZE] Improve Skybox inspector user experience (engine#10004)
• [OPTIMIZE] Refine context 2d implementation, reduce call from native to js (engine#10211)
• [OPTIMIZE] Reset light map when rebuild terrain (engine#10714)
• [OPTIMIZE] Simplify cmake configurations in the native template (engine#10479)
• [OPTIMIZE] Improve the JSON grouping strategy for building dependencies of merged bundle
• [OPTIMIZE] Optimize texture compress panel, support searching config in panel
• [OPTIMIZE] Optimize output logs of the build process, parameter completions of the command line build, parameter checks for some platforms
• [OPTIMIZE] Disable bindingMappingInfo validation (engine#10701)
• [OPTIMIZE] Reset-property from unknown type (engine#10687)
• [OPTIMIZE] Exclude arm64 arch and specify x86_64 for ios simulator by default (engine#10679)
• [OPTIMIZE] Do not play particle system component in Editor (engine#10678)
• [OPTIMIZE] Disable post-process alpha blend (engine#10658)
• [OPTIMIZE] Set simulator window position to center (engine#10655)
• [OPTIMIZE] Remove cocos2d-x network deprecated code (engine#10647)
• [OPTIMIZE] Remove deprecated API in animation module (engine#10645)
• [OPTIMIZE] Remove some deprecated api (engine#10656)
• [OPTIMIZE] Minor module refactor in core/renderer/ (engine#10643)
• [OPTIMIZE] Add `keep` attribute to java class in project cfg (engine#10641)
• [OPTIMIZE] Change rich text warning for splitting long strings (engine#10624)
• [OPTIMIZE] Disallow animation on particle system properties (engine#10605)
• [OPTIMIZE] Mark some methods as internal (engine#10604)
• [OPTIMIZE] Disallow animation on customMaterial (engine#10601)
• [OPTIMIZE] Do not remove all RichText children when resetting (engine#10599)
• [OPTIMIZE] Modify the application interface name and remove the js keyword (engine#10556)
• [OPTIMIZE] Optimize ts templates (engine#10553)
• [OPTIMIZE] Optimize assets editing interface (engine#10531)
• [OPTIMIZE] Output warning info when attached to the node has zero scaling (engine#10524)
• [OPTIMIZE] Android: prevent class CocosWebSocket from obfuscation in release mode (engine#10511)
• [OPTIMIZE] Optimize the way how animation component update its animation content (engine#10485)
• [OPTIMIZE] Shader optimization always on (engine#10483)
• [OPTIMIZE] Move AppDelegate into template (engine#10509)
• [OPTIMIZE] Add dynamic library export macro (engine#10393)
• [OPTIMIZE] Add DisallowMultiple for UIOpacity component (engine#10390)
• [OPTIMIZE] SDL related interface encapsulation (engine#10385)
• [OPTIMIZE] Optimize material editing using cache prop-value (engine#10376)
• [OPTIMIZE] Keep EditBox placeholder overflow (engine#10368)
• [OPTIMIZE] Use approx instead of strict equal in UITransform to avoid potential endless loop (engine#10357)
• [OPTIMIZE] Modify diffuseMap property visibility (engine#10333)
• [OPTIMIZE] Windows platform handles multiple events at once (engine#10344)
• [OPTIMIZE] Shader code style improvements for future surface shader (engine#10326)
• [OPTIMIZE] Bypass job system creation if not needed (engine#10308)
• [OPTIMIZE] Optimize android download tasks. (engine#10274)
• [OPTIMIZE] @disallowAnimation should not imply visible (engine#10262)
• [OPTIMIZE] Optimized deletion operation for skybox environment map (engine#10248)
• [OPTIMIZE] Optimize property name display format (engine#10241)
• [OPTIMIZE] Return aabb objects back to pool after usage (engine#10230)
• [OPTIMIZE] JSB add convert routines for size_t/long (engine#10198)
• [OPTIMIZE] Change lighting map unpack and luminance multiply (engine#10185)
• [OPTIMIZE] Rearrange IA input variables and functions for surface shader (engine#10123)
• [OPTIMIZE] GFX: refactor access typed array to access flags (engine#10103)
• [OPTIMIZE] Gfx: refactor binding mappings (engine#10013)
• [OPTIMIZE] Use lagacyPublic to marked deprecated public interface (engine#9859)
• [OPTIMIZE] Shadow info migration (engine#9857)
• [OPTIMIZE] Safely destroy the geometry data (engine#9849)
• [OPTIMIZE] UI: add same value check in property setter (engine#9744)
• [OPTIMIZE] Optimize label serialization of "spacingX" and "underlineHeight" (engine#9629)
• [OPTIMIZE] Rich Text format optimization by split into small sections (engine#9601)
• [OPTIMIZE] Clean up gfx module for independent compilation (engine#9573)
• [OPTIMIZE] Code style: replace macros to functions (engine#9572)
• [OPTIMIZE] Set active to false if pass undefined or null to Node.active (engine#9571)
• [OPTIMIZE] Optimize scroll view offset annotations (engine#9553)
• [OPTIMIZE] Remove deprecated attributes: srcBlendFactor and dstBlendFactor#6461 (engine#9533)
• [OPTIMIZE] Show pipelineStates in inspector (engine#10586)
• [OPTIMIZE] Add category config file for docs (engine#10589)

• [FIX] Fix rendering issue after baking light map with prefab
• [FIX] Fix baking tool LightFX multi-thread error
• [FIX] Fix prefab data lost when exiting from animation edit mode to prefab edit mode
• [FIX] Fix prefab/scene data may be overwritten when switch between scene and prefab quickly
• [FIX] Fix inability to save changes to nested prefab
• [FIX] Fix warning when clicking on different FBX assets
• [FIX] Fix a series of optimization issues related to keyframe operation in the animation editor
• [FIX] Fix build error on windows platform when editor path contains spaces
• [FIX] Fix build failure after check [Main Bundle is remote] option on mac platform
• [FIX] Fix an issue where the editor extension failed to start and could still be queried
• [FIX] Fix prefab ID will be changed after rename of FBX or GLTF

• [FIX] Fix octree culling rule (engine#10723)
• [FIX] Walk around iOS 15.4 wasm memory issue (engine#10721)
• [FIX] Bypass the bug that vulkan destroys resources that are still in use (engine#10716)
• [FIX] Fix the performance issue caused by texture mipmap (engine#10713)
• [FIX] Fix native module override (engine#10709)
• [FIX] Fix #11925 skin instancing vertex attributes binding order for native… (engine#10703)
• [FIX] Fix rich text children index bug (engine#10700)
• [FIX] Fix sub context view not working when the design resolution size is less than 513 * 513 (engine#10698)
• [FIX] Fix scroll view Auto Scroll Brake bug (engine#10693)
• [FIX] Fix instanced rendering issue by joint index (engine#10692)
• [FIX] Fix: set tmxAsset not apply file (engine#10690)
• [FIX] Fix: set skeleton data, _cachedSockets should be reset (engine#10671)
• [FIX] Remove playing audio when player is destroyed (engine#10670)
• [FIX] Use correct macro patches (engine#10669)
• [FIX] Correct profiler statistics (engine#10667)
• [FIX] Fix screen size && touch event on Alipay platform (engine#10666)
• [FIX] Fix ndk path not working (engine#10627)
• [FIX] Fix android crash due to eglSurface unavailable (engine#10621)
• [FIX] Use macro to set XXTEAKEY (engine#10607)
• [FIX] Fix opacity bug when active false (engine#10595)
• [FIX] Fix #11796 using cc_shadowbias without batching macro (engine#10587)
• [FIX] Fix ui-mesh-renderer in editor (engine#10582)
• [FIX] Fix ios enter forground crash by useless appDelegateBridge (engine#10580)
• [FIX] Fix cross fade bug introduced in #10485 (engine#10576)
• [FIX] Fix skeletal animation state got update twice (engine#10571)
• [FIX] Avoid creating the window twice (engine#10566)
• [FIX] Fix animation event type typing (engine#10562)
• [FIX] Animation state bugfix (engine#10558)
• [FIX] Fix watermark can not show normally (engine#10547)
• [FIX] Fix sprite-frame size after repetitive dynamic creation of tiled map (engine#10535)
• [FIX] Fix MTLTexture::doInit (engine#10532)
• [FIX] Fix gfx::FrameBufferInfo rehash crash bug (engine#10525)
• [FIX] Fix tiled show with pixel offset (engine#10523)
• [FIX] Fix label Blend Factor bug for byte dance platform (engine#10516)
• [FIX] Fix animation bug introduced from #10485 (engine#10512)
• [FIX] Fix vec3 & vec4 transformAffine (engine#10508)
• [FIX] Fix animation blending zero check (engine#10499)
• [FIX] Fix pointer event when camera.orthoHeight changed (engine#10496)
• [FIX] Fix Android websocket send string (engine#10495)
• [FIX] Fix getUrlWithUuid smart hint issue (engine#10484)
• [FIX] Fix punctual lights luminance * PI (engine#10480)
• [FIX] Set light map clamp to border and fixed rebuild terrain weights (engine#10470)
• [FIX] Clear Particle under UIMeshRenderer when play end (engine#10468)
• [FIX] Fix: There is no need to execute updatePreview in the ready lifecycle (engine#10466)
• [FIX] Fix fog accumulated error with multiple local lights (engine#10445)
• [FIX] Fix templates and minor tweaks (engine#10434)
• [FIX] Force update for spine color setting. (engine#10417)
• [FIX] Fix opacity dirty bug when parent change (engine#10416)
• [FIX] Fix gen-simulator (engine#10401)
• [FIX] Fix animation not work caused by creating spine in a hided node (engine#10380)
• [FIX] Fix 2D physics rotation error (engine#10373)
• [FIX] Reset render data before set asset for spine/dragonbones (engine#10370)
• [FIX] Fix crash caused by incorrect hash (engine#10359)
• [FIX] Fix spine/dragonbones opacity update (engine#10349)
• [FIX] Fix spine rendering confusion (engine#10348)
• [FIX] Fix bug: reset renderer-component would not update model (engine#10342)
• [FIX] Fix ios icon res lost (engine#10336)
• [FIX] Fix compiling error with merged code (engine#10332)
• [FIX] Fix: #11580 create new light source with unknown typed intensity in the inspector (engine#10324)
• [FIX] Fix skinned mesh morph rendering (engine#10318)
• [FIX] Avoid spine and dragon crash. (engine#10314)
• [FIX] Fix spine in native platform can not get animation name (engine#10303)
• [FIX] Fix dragonbones/spine sockets transform (engine#10260)
• [FIX] Fix crash when app jump to camera (engine#10255)
• [FIX] Fix translucent problem due to SurfaceView‘s limit (engine#10228)
• [FIX] Fix unnecessary include for surface shader (engine#10220)
• [FIX] Fix misuse of draw API on metal (engine#10195)
• [FIX] Fix: linux build use static link. need add sndio lib (engine#10186)
• [FIX] Fix ios device display effect (engine#10184)
• [FIX] Fix spine binary data read issue. (engine#10172)
• [FIX] Fix android 12 crash when using Vulkan backend (engine#10158)
• [FIX] Fix fps calculation error for linux and QNX (engine#10141)
• [FIX] Fix default scene camera clear flags is solid not skybox (engine#10132)
• [FIX] Update ci yml files, add native/web prefix, cherry-pick from #10083 (engine#10104)
• [FIX] Fix binding mappings (engine#10058)
• [FIX] Fix shader code style (engine#10039)
• [FIX] Fix decorator order issue in standalone mode (engine#9911)
• [FIX] Fix keyframe editorExtras serialization (engine#9905)
• [FIX] Fix pixels offset (engine#9829)
• [FIX] Fix negative scale widget in editor (engine#9811)
• [FIX] Particle alpha blend fix (engine#9784)
• [FIX] Fix import relation (engine#9765)
• [FIX] Fix bug that causes autoScrolling is always triggered in v3.5 (engine#9548)
• [FIX] Fix crash: native model is destroyed but not removed from render scene (engine#9543)
• [FIX] Update the split condition of RichText truncations (engine#10252)
• [FIX] Fix iOS Simulator compile error when using TBB on Apple Silicon device (cocos-engine-external#232)

In v3.4.1, we improved the data submission and batching strategy of 2D rendering components. Since these are basic changes, it caused some problems with Tiledmap and Graphics. Also, the performance of Spine and Dragonbones on the Android browser has not been improved, these problems have been resolved in the v3.4.2 version.

In addition, under the active testing and feedback from the community, we have also fixed some editor-related experience problems, such as memory leaks caused by script recompilation, and resource copying problems when large projects are built on the iOS platform. Thanks again to the community developers.

Developers currently using v3.4 to v3.4.2 should upgrade to get a better stability and development experience.

Important updates

Version notice

Recently, we have conducted extensive exchanges with the majority of users on forums and offline, and received many pertinent suggestions and criticisms. In response to some product usability issues that have been reported by users recently, we have planned version 3.5 to deal with it as soon as possible, and the public beta will be launched soon. 3.5 will iterate in small steps on the basis of 3.4, improve the usability and ease of use of the product, and ensure stability and compatibility as much as possible.

In the remaining releases for this year, the engine team will also focus on the business needs and pain points of developers, do their best to take care of the needs of various types of projects, and benefit all users. In particular, some projects encountered problems such as heat generation, native performance, package body, editor stability and workflow, which will be mainly solved this year.

Release Notes

Engine

• Shared vertex buffer accessor for Spine and DragonBones [10077]
• Fix skeletal animation sample() does not work as intended [10006]
• Fix DragonBones node can’t be moved in editor [10031]
• Fix 2d particle rendering issue [10038]
• Fix Tiled map rendering issue [10059]
• Fix TiledLayer culling row and col [10035]
• Fix MotionStreak updateColor bug [10055]
• Add default skybox [10021]
• Fix planar shadow z-fighting [10026]
• Add OHOS platform detection [10028]
• Fix skybox stretch in ortho projection [10045]
• Fix releaseMapInfo error. [10062]
• Add protection for invalid node.uiProps [10060]
• Fix native platform mesh-render-data index error. [10071]
• Optimize multi-touch on ByteDance platform [10086]
• Fix canvas widget bug in editor [10052]
• Fix renderData update bug when renderable2d is not rendering [10101]
• Fix interface checking [10109]
• Fix pointer event list manager [10084]
• Fix custom class missing when the instantiate error [10128]
• Fix bug for compress texture usage under Sprite grayscale mode [10129]
• Fix getTiledTileAt cause layer show wrong. [10137]
• Fix Node rotate API doc [10140]
• Ensure RenderData.clear won’t break usability [10177]
• Update editBox size when node resize [10188]
• Fix iOS version detection on Wechat platform [10159]
• Fix mask is not working for spine/db [10201]
• Improve touch event performance by caching system info on ByteDance platform [10218]
• Fix merge batches issue with multi canvas [10232]
• Add JsbBridgeWrapper for OHOS [4204]
• VK: fix android 12 crash [4217]
• Supply a default context when surface destroyed [4222]
• Use same mtx for write [4220]
• iOS/mac skip POST_BUILD copy Resources folder procedure [4216]
• Fix spine binary data read issue. [4229]
• Fix loop audio would stop for ios system [4254]
• Fix restart view size [4256]
• Fix spirv incorrect name on binding [4259]
• Fix app crash after switch back from Camera [4268]
• Fix incorrect resize behavior on iOS [4265]

In v3.4.1, we focused on fixing problems reported by users after the release of v3.4.0 and improving the overall stability. At the same time, in order to help v2.x developers to upgrade to v3, we adjusted the batch strategy of 2D rendering components, which has greatly improved the overall performance of 2D rendering. Compared with v3.3, the improvement rate ranges from 20% - 70%.

For the performance test results, we also compared the v2.x version. Take a look at the comparison charts below, the performance of most of the tests has been close to or the same as that of 2.x, and a small number of tests have exceeded it.

Legend explanation: All tests are done on low-end and mid-range computers. The four intervals of each icon are Android Web, iOS Web, Android WeChat, and iOS WeChat. In addition, the overall performance improvement on the native platform will also be greatly optimized in the native version of 3.6 [GitHub PR].

In addition, in order to allow WebGL 2.0 to be enabled on WeChat mini-games in the future, we have also modified the build options of the WeChat platform and added an experimental option: support to enable WebGL 2.0 following the configuration of the project module, and to turn off the reduced package by default. If you choose to follow the configuration of the project module, and the WebGL 2.0 rendering backend is checked in the project module, then the future and other WeChat environments that support WebGL 2.0 can be successfully enabled.

Important updates

• Refactored 2D batching strategy, RenderData holds static VertexBuffer memory to optimize 2D rendering performance on all platforms
• Optimized the state management of 2D rendering components: UV and Color now fill immediately to avoid polluting the VB state
• Material.copy now supports modification parameters from override material
• Enable WebGL 2.0 on WeChat to prepare for future WeChat versions that support WebGL 2.0
• Slightly optimized the performance of the particle system
• Fixed the response speed problem when the editor has too many startup scripts
• Fixed the problem that an error will be reported when compiling the simulator
• Limit the maximum device pixel ratio of the web platform to 2, and fixed the performance degradation caused by it
• Fixed event dispatch priority so that UI listeners always take precedence over input event listeners
• Fixed the problem of performance degradation in shadow collection logic
• Fixed the problem of abnormal exit when restart is called for the second time in iOS/macOS
• Fixed the problem that the game logic stops when the Android platform enters the background
• Fixed the problem of independent use of SkeletalAnimation sample API
• Fixed the problem of using animation crossFade API
• Fixed the color setting problem of TiledLayer
• Fixed the problem that multiple camera outputs are overwritten when rendering to the same RenderTexture
• Fixed some memory fragmentation issues on the native platform
• Fixed the problem that Label spacingX property is not serialized
• Fixed the problem that the profiler disappears after restarting in debug mode
• Fixed the problem that burst does not behave correctly after replaying after pause
• Fixed the problem that the UseHDR button has the opposite effect when switching scenes
• Fixed iOS & Mac Safari does not support USE_REFLECTION_DENOISE
• Fixed the problem of performance degradation introduced by getSystemInfoSync on Cocos Play and WeChat platform
• Fixed the problem that Sphere Light doesn’t work correctly on Android Web
• Fixed the crash when three Cocos games are running at the same time in the debug mode on the windows platform

Known legacy issues

• Slider cannot be smoothly dragged in ScrollView: solution planned in v3.4.2
• SkeletalAnimation cannot have a valid setTime call without calling play [#10006]
• 2D particles flicker in some cases: [#10038]
• DragonBones needs to call ArmatureDisplay.markForUpdateRenderData after setting the position to update correctly: [10031]

Detailed update list

• Android: Java flush game thread tasks [4193]
• Fixed iOS keyboard hiding issue [4185]
• Fixed mem status [4179]
• M1 deferred rendering issue: fbf & write to same texture not fully support [4174]
• Fixed the problem of deferred pipeline multi-execution transparent queue [4168]
• Improved mesh buffer to avoid iOS14 performance drop [10015]
• Added sprite frame event off & fix renderData hash bug [10012]
• Fixed sprite rect bug [10011]
• Removed deprecated in error map [10007]
• Protect meshBuffer max vertex count [10005]
• Changed macro for meshBuffer [10001]
• Fixed touch event on IMAGE STENCIL mask component [10000]
• Fixed TiledLayer’s color setting [9997]
• Enable model after playing instead of onEnable [9991]
• Fixed EventDispatcherPriority, ensure UI have higher priority than input [9976]
• Cleared attachment for editor camera render area [4164]
• Removed local reference array [4161]
• Fixed Lighting stage feedback loop [4157]
• Removed unnecessary include [4153]
• Fill vb with 0 when allocate [9989]
• Fixed spriteFrame apply time [9987]
• Added MeshRenderData.resize for changing both buffer size and IA size [9986]
• Fixed tiled map [9980]
• Particle performance improve [9979]
• Separated IA range and buffer range in MeshRenderData [9978]
• Fixed planar-shadow normal is zero [4165] & [9975]
• Fix: keep children with same layer in editbox [9971]
• Avoid one MeshRenderData upload repeat [9969]
• Request IA by pool [9967]
• Fixed skeleton animation cross fade/play won’t stop last animation [9965]
• Set opacity all time [9959]
• Fixed Opacity cascade [9958]
• Fixed no planar shadow on mac [9953]
• Fixed particle switch cpu / gpu bug caused by alignment space [9952]
• Adjusted PhysX initialization [9641]
• Removed redundant autoreleasepool [4102]
• Closed uv_handle_t [4106]
• updateLightingMap sync to native-engine [4109] & [9828]
• Removed origin code for twice call to java method [4114]
• Allow tick() in background [4081]
• Fixed Android+WebGL PS struct variables has unexpected mediump precision [4120] & [9863]
• Fixed shadow queue performance [4119]
• Fixed memory leak [4115]
• Optimize fixedArea mode culling process [4124]
• Fixed windows text alias [4128]
• Added JsbBridgeWrapper[4125]
• Combined planar-shadow calculations [4127]
• Multiple Cameras support rendering to the same RenderTexture [4132] & [9924]
• Change define(CC_DIR_SHADOW) to uniform(cc_lightDir.w) [4129] & [9921]
• Position Delete & Normal Compress in deferred pipeline [4135] & [9939]
• Open ddx ddy extension on safari WebGL1 [9820]
• Added profiler reset [9806]
• Fixed terrain _updateHeight texcoord error [9809]
• Added burst restart [9832]
• Fixed UseHDR button & Skybox HDR status [9843]
• Added decorator “serializable” [9848]
• Restrict DPR on Web platform [9850]
• Improved GPU particle performance [9847]
• Disable multi_draw extension on mobile [9835]
• Cache systemInfo on Cocos Play platform [9856]
• Fixed skeleton model receive shadow macro error and toon shadow display errors [9836]
• Fixed shadow queue performance [9862]
• Fixed mask not working with spine [9864]
• Fixed define syntax error [9870]
• Detach from scene before destroying Model/Light [9869]
• Fixed set frame rate on runtime [9874]
• Material.copy accepts overrides [9881]
• Label string setter optimization [9880]
• Fixed Color.fromHex Bug [9867]
• Changed ts template [9883]
• Optimized fixedArea mode culling process [9878]
• Modified builtin texture generation + particle unit test [9841]
• Updated Scheduler API [9815]
• Fixed readPixels [9900]
• Fixed skybox RGBE macro get invalid in startup and mipmap count is overridden [9904]
• Fixed bug: remove all actions by tag [9876]
• Fixed audio bugs [9889]
• Fixed particle index count 0 [9885]
• Jsb-event-handler for event dispatch [9879]
• Fixed bug of builtin default texture [9916]
• Refactored communication between skinned mesh renderer and skeletal animation [9787]
• Added extra steps to the destroy functions to update the cached resources in GFX [9875]
• Combing planar-shadow calculations [9903]
• Fallback of shadow supports on Baidu [9897]
• Prefab: Support the persistent flag [9884]
• Fixed particle capacity issue[9910]
• Support screen.devicePixelRatio [9926]
• Fixed skeleton animation component play or cross fade [9930]
• Animation controller api document [9866]
• Fixed event processor list updating [9932]
• Fixed multi touch bug [9917]
• Fixed MOUSE_WHEEL event can’t be swallowed by node [9931]
• Fixed audio buffer memory leak on ByteDance and Web platform [9933]
• Improved compatibility for string of SystemEventTypeUnion [9934]
• Particle culling loop fix [9922]
• Fixed keyboard event listening on mobile [9935]
• Fixed pointer event sorting after activating node [9906]
• Fixed culling deprecated module [9937]
• Fixed cc_base.d.ts [9944]
• Add cpu & gpu particle culling unit test [9945]
• Fixed planar-shadow plane offset sign issue [9946]
• Fixed spine typing [9942]
• Static vertex buffer accessor refactor for Batcher2D [9802]
• Revert deprecate system event [9941]
• Reset swallow state after event handling [9950]
• Fixed some spine bugs [9948]

Cocos Creator v3.4 is the final version we released this year for Creator. Stability is our most important goal! The development and testing cycle of this version is longer than any previous version, and it has been publicly tested in the community for a month. Thank you to all the developers who participated in the test!

In v3.4, not only important functions such as the Marionette animation system have been added, but also a lot of work has been done in terms of product experience, stability, performance optimization, and infrastructure levels. In addition, we listened to the community and fixed a number of problems that have received a lot of feedback. Our devoted engine team believe 3.4 version will become a great milestone in terms of game development user experience!

Highlights

Animation System Marionette

The all new animation system is the most important feature in 3.4. We named it Marionette, which means 'puppet', which both captures the essence of the animation system and also by itself, a long-standing traditional Chinese art form. It has appeared since the Tang Dynasty and has been circulating for thousands of years, and it is still an important opera form till this day in the Minnan region (where our company is located!). With Marionette, we also hope that developers can precisely control the game characters and enhance the game’s narrative ability.

In version 3.4, Marionette supports the key features of an animation system, including state machines, sub-state machines, animation node graphs, trigger variables, multidimensional blending, etc. Of course, more new features are already under development, such as animation levels and masks, humanoid bones and IK support. To help you learn the Marionette animation system, we have also prepared detailed documents, a [Demo](https://github.com/cocos-creator/MarionetteDemo) and video tutorials.

Editor experience optimization

In terms of editor experience, we have done a lot of fixes and enhancement for user experience. Features and experience optimizations include:

• The animation editor supports Bezier curve presets now, select the curve segment and click on the curve preset to apply.

• Added smart alignment for Rect Gizmo

• Customized macros are supported now

• Added wrap mode and filter controls for RenderTexture

• Added Octree space accleration structure, optimized frustum culling performance that can be activate in the inspector

Lighting Model And Rendering Optimization

Starting from v3.0, Creator has been elevating and polishing its rendering capabilities. In v3.4, in order to improve the rendering quality of the engine, we brought a series of important upgrades. In particular, the enhancement of the lighting model will make the rendering more refined for our engine.

• Automatic generation of environment map for diffuse reflection

manually set ambient light vs automatically generate diffuse map

• upport HDR and LDR rendering switch (located in the scene node, under Skybox configuration). 

HDR on vs HDR off

• BL sampling noise reduction( USE REFLECTION DENOISE option under "stardard material")

Denoise on vs Denoise off

Render pipeline enhancement

In terms of rendering pipeline, FrameGraph is an infrastructure introduced in v3.1. After several iterations, in v3.4 we formally docked both the Forward and Deferred pipelines with FrameGraph. Below is a simplified deferred pipeline FrameGraph:

Currently, the engine’s deferred pipeline contains a total of 2 calculation passes and 7 rendering passes. Although it is not complicated, it can already highlight the role of FrameGraph. On the one hand, it simplifies the code organization of the pipeline layer and reduces maintenance costs; on the other hand, it also reduces the cost of developers when customizing pipelines. Based on FrameGraph, the Huawei HMS CG Kit team continued to contribute Clustered Light Culling to the deferred pipeline in v3.4 to optimize the calculation performance of dynamic light sources. It can support hundreds of dynamic light sources on the same screen on the mobile side (Kirin 990 chip in Sponza scene Running 1000 dynamic light sources can reach 40 fps).

In addition, the Subpass in the rendering pipeline is also implemented based on FrameGraph. The second major advantage of FrameGraph is the deferred mode for rendering (different from the deferred rendering pipeline). The engine can analyze the rendering process and optimize it before executing the complete rendering process. Currently, mobile GPUs share system memory with CPUs. One of the hotspots of power consumption is the reading and writing of video memory. Subpass optimization is to make full use of the GPU’s Tiled cache to reduce the power consumption of video memory read and write. When the write and read resources of two adjacent rendering Subpass are the same in-frame resource and will not be referenced by other passes, this Resources can be read and written directly through the Tiled cache without wasting any memory bandwidth, which can significantly reduce power consumption. This automatic derivation of resources and rendering processes is exactly the advantage that FrameGraph brings.

Important Fix and performance optimization

Stability is the primary goal of the v3.4 version, so we have also fixed some flaws that have been troubling for a long time, pushing the stability of the engine to a new height. Here are some of the more important fixes:

• Fixed the serious problem that using Active during animation editing may cause data loss.
• Fixed the problem that the MissingScript component will appear when some abnormal errors are reported in the scene, which causes the scene to fail to start.
• Fixed the crash caused by repeatedly exiting and entering iOS.
• Fixed the crash caused by material compilation on some chips in the back end of GLES3.
• Fixed the black screen problem of Vulkan backend on some low-end machines (by issuing barriers and image layout conversion more accurately).
• Fixed the crash of Vulkan backend on some low-end machines (by modifying some shader usages to workaround some problematic drivers).
• Fixed the problem of Vulkan backend crashing or incorrect resolution when rotating or splitting screens.
• Fixed a crash when using a large number of high-resolution textures in the Vulkan backend.
• Fixed the black screen issue on Chrome on a few devices.
• Fixed the problem that PrefabInstance in mountedChlidren may cause data errors.
• Fixed the fileId conflict that may occur when copying Prefab, which will cause data loss and error.
• Fixed the problem that the deleted element data is referenced in Prefab, which causes a lot of redundant data to be serialized.
• Fixed the issue that Undo may cause some override data in the prefab to be lost.
• Fixed the problem that data errors may occur when the terrain is restored.
• Fixed the problem that the GPU memory referenced by Label is not released after switching scenes at runtime.
• Fixed the memory leak problem of InstanceBuffer and BatchedBuffer due to holding aglobal Map.
• Fixed a large number of problems caused by the failure of global precision designation on some small game platforms, such as the shadow sampling problem.
• Fixed the problem that the native platform did not pass the correct baked parameter in the case of scene baking.
• Fixed the random model flickering issue under GLES (by using glMapBufferRange instead of glBufferSubData).
• Fixed the screen glitching issue on devices that do not support floating-point mapping when there are NaNs in the model's joint weights (by equally dividing all NaN weights in the importer).
• Fixed the crash of large-scale data synchronization after the native-side pre-baked animation Instancing is processed.
• Fixed the problem that multiple plugins with the same name and registered resources will cause script compilation to fail.
• Fixed the problem that the content of the remote resource package cannot be updated after the native platform is rebuilt feedback from the forum.
• Fixed the problem that the original code is still entered into the apk after the original selection encryption is built feedback from the forum.
• After repairing the automatic atlas using compressed textures, modify the atlas configuration to rebuild and still use the cache.

In addition to fixing important issues, the overall performance of the engine has also been improved, such as 2D rendering and batch efficiency, physical performance, iOS Web 3D scene performance, and Android partial scenes. Here are some test results of 2D rendering:

Known Defects and Potential Compatibility Issues

Build Template Upgrade

Due to the adjustment of the relevant logic of web platform screen adaptation, we have changed the web-related index.html template, which includes preview templates and building web platform templates. We have done related compatibility processing inside the engine cocos-creator/engine#9830

This process will ensure that there is a fixed div structure inside index.html:

<div id="GameDiv">
    <div id="Cocos3dGameContainer">
        <canvas id="GameCanvas"></canvas>
    </div>
</div>

If GameDiv/Cocos3dGameContainer is missing, it will be automatically filled during runtime.

Note: this div structure is a private structure managed internally by the engine. We hope to keep this structure intact and not customized. If other web tags are added to this structure, it may cause some uncertain compatibility issues.

IBL sampling noise reduction

The newly added IBL sampling noise reduction algorithm currently has some problems with the compatibility of the iOS Web environment. Since it was found that it was not merged in the version later, the support for iOS Web will be completed in the follow-up 3.4.1

Delayed pipeline defects

Currently, the deferred pipeline is still in the process of high-speed iteration, and there are still some problems with function and platform compatibility. It is not recommended to use it in actual projects for the time being. Some of the current known issues include some particle blending modes that cannot be rendered, builtin-toon materials are not supported temporarily, some low-end platforms and devices have compatibility issues, spotlight shadows are not supported, and 2D & 3D camera mixing issues.

Fix List

Features

• [Animation] Added Marionette animation system, supporting state switching, sub-state machine, Blend Tree and other necessary functions for character animation
• [Animation] The animation editor supports standard Bezier curve easing presets
• [Animation] Curve key frame supports Broken disconnection and separate control of left and right joysticks
• [Scene] Supports automatic generation of environment map convolution map for diffuse reflection calculation
• [Scene] Added smart alignment function of Rect Gizmo
• [Scene] Added Octree space management acceleration structure, optimized frustum culling performance, document
• [Scene] Added GPU Occlusion Query culling (default disabled), you can turn it on through root.pipeline.setOcclusionQueryEnabled(true); to support developer custom macro configuration, document
• [Scene] Newly added native platform memory leak detection system (closed by default), you can pass #define USE_MEMORY_LEAK_DETECTOR 1 to turned it on,document
• [Builder] Build support for external developers to register custom texture compression processing tools
• [Builder] Added “Skip Xcode project update” option for Mac / iOS platform building to avoid overwriting changes to project files
• [Builder] Combine the GLES options of Android and Windows, and it is not allowed to select GLES2 separately
• [Particle] Support particle emitter elimination, offline automatic calculation, and manual adjustment (RenderCulling module)
• [Particle] Support the unity of particle orientation and node orientation
• [Asset] Support RenderTexture’s wrap mode, filter and other parameters
• [Asset] RenderTexture adds readPixels interface
• [Prefab] supports batch disassociation
• [Asset] Added “Auto” option for animation baking rate of FBX importer
• [Asset] New option for FBX importer: give priority to file time range
• [Asset] The packable property on the SpriteFrame resource panel will affect the automatic atlas construction process in addition to the automatic image collection, and will not participate in the construction of the assembled image after it is closed
• [Asset] Terrain module supports automatic LOD
• [Graphics] Support IBL sampling and noise reduction (check USE REFLECTION DENOISE in standard material)
• [Graphics] More accurate Gamma Correction
• [Renderer] Support HDR and LDR rendering switch (in the scene node Skybox configuration)
• [Renderer] Both forward and deferred rendering pipelines are reconstructed based on FrameGraph and subpass
• [Renderer] gfx encapsulates the swapchain public interface and supports multi-window applications
• [Renderer] Deferred pipeline uses Clustered Light Culling to optimize dynamic light source calculation performance, Reference Demo
• [Renderer] Deferred pipeline supports setting off-screen FBO resolution scaling
• [Renderer] Deferred pipeline supports FXAA anti-aliasing
• [Renderer] Deferred pipeline supports simple Bloom post-processing effects
• [Scripting] Support @requireComponent to pass in array
• [Scripting] The newly added interface JsbBridge simplifies the use of calling Java code and ObjC code, refer to Display Use Case
• [PAL] Added input module, which will replace systemEvent in the future. For details, please refer to Event Input Documentation and Event Node Documentation
• [PAL] Support preventSwallow property on EventMouse and EventTouch, support event penetrating dispatch: event.preventSwallow = true
• [PAL] Support sys.hasFeature() interface to query whether platform features are supported

Improvements

• [Scripting] Upgrade the v8 engine that the native depends on to v9.1.269
• [Renderer] Performance optimization of multi-light source collection
• [Renderer] Optimize the RT performance of GLES/WebGL
• [Renderer] Optimize the use of native memory/video memory (by calling framegraph gc periodically)
• [Graphics] Fixed the calculation of lighting and shadows of translucent objects
• [Graphics] Optimize the fog effect and transfer the calculation to Fragment Shader to ensure the correct fog effect transition
• [Graphics] Disable multi-light source lighting for translucent objects
• [Scene] Add axis text to the world axis
• [Scene] Terrain editor adds selection mode
• [Physics] Optimized the package of PhysX on the native platform
• [Physics] PhysX now supports M1 devices
• [PAL] Optimize the orientation adaptation of the web end, focusing on the direction selected by the construction panel, ignoring the browser direction
• [PAL] On the Web and small game terminals, immediately dispatch input events to solve some user interaction permissions issues
• [PAL] New App default icons have been replaced for all platforms and emulators
• [PAL] Now the iOS platform construction will introduce the corresponding default Launchscreen image according to the horizontal screen or vertical screen option (if the change does not take effect in time, you need to restart the device to clear the cache)
• [Asset] Fixed the problem that the last frame of FBX animation import is lost
• [Asset] Fixed the problem that the resource change notification may be lost when the extension is capitalized
• [Asset] Solve the problem that the add event may not be sent for newly added resources, which may cause the assets panel to wait all the time
• [Builder] The address of the build configuration server is changed to be recorded in settings.json to facilitate dynamic updates
• [Builder] When creating a new automatic atlas, the elimination option in the Bundle will be turned on by default (the optimization requirements are from this forum topic 1
• [Extension] The developer panel of the plug-in manager allows to import plug-ins other than the current project or global catalog.

Highlights

The main function of this version is to allow native applications built by the engine to support iOS 10+. In order to support iOS 10+, the engine code removed the dependency on C++17.

Some functions of the engine depend on C++17, and some functions require using the Android API. For the convenience of developers, the function configuration interface of the editor prompts for these dependencies. For example, when Android uses the delayed pipeline, Android API 21+ is required. If the configuration chooses to use the delayed pipeline, the editor will prompt the required Android API version:

Of course, we also provide a complete document explaining the requirements of each functional module for the Android API and C++ versions. For more information, please refer to the native options documentation.

Key update list

• Cocos Store download has improved performance
• Native GPU Instancing material switching causes rendering failure
• Fix the problem that muti cannot be modified in the Two Curve mode of the curve component
• Fix the problem that the override may be lost when saving immediately after undo in the prefab modification mode
• Fix the UITransform component or Canvas node problem when adding UI nodes when editing prefab resources

Known Issues

• Topon and Tradplus Service plugins will have exceptions when building the IOS platform, which we will fix with a hot update in the near future.

Upgrading

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

Bugs Fixed

Editor

• Optimize the display of the physical laboratory options on the WeChat byte panel. When creating a new WeChat build task, the Wasm physics system will be enabled by default. After it is turned on, it will override the physical backend selection set by the project
• Fix several animation editor operation problems, including:
  • Some types of animations are not correctly interpolated
  • The curve data is not copied when copying the track
  • Cannot continuously operate the selected keyframe attribute track
  • Wrong position of adding keyframe when scroll bar exists
  • After selecting multiple keyframes, clicking on the keyframe moves abnormally
  • Fix the failure of pasting keyframe data across nodes and attributes
• Fixed and improved particle curve related controls: including the Bursts property cannot be added normally, the curve containing the Constant mode is displayed abnormally, the display of Two Curve is optimized, and the curve is displayed incorrectly after removing the keyframe.
• Fixed the problem that joint-texture-layout is invalid when building on the command line (it will cause loading failure at runtime)
• Fix the problem that the FileId of Component in the created object is the same
• Fix that when the auto atlas and renderTexture resources are in the same folder, they cannot be previewed and built normally
• Customized engine settings are stored according to the editor version
• Fixed the problem that the script in Prefab was not updated in time after modification
• Fix the problem of creating ui node in Prefab edit mode
• Fix the problem that the resource is deleted when editing the Prefab resource, and the save will not be automatically transferred to save at this time
• Fix the issue of select all and copy functions related to the root node on Hierarchy
• Fixed an issue where Hierarchy called the db interface and reported an error when switching scenes
• Fixed the problem that the file name of the custom script template cannot be a pure number
• Fixed the issue of db reporting errors when deleting assets in batches in the assets panel
• Support the mechanism to filter the suffix of the input name when creating a new resource in the assets panel
• Fix the problem that the resource that failed to import will report an error every time the focus returns to the editor
• Fix the problem that the old private node in the scene will cause a warning
• Fix the problem that the scene resource upgrade will add a blank line at the end

Engine

• Fix the problem of decreased performance of particle system instantiation Link to Chinese Forum post
• Fixed iOS 14 Web platform performance issues
• Optimize the Shadow Culling algorithm. After the upgrade, you need to use resolution and distance to adjust the shadow quality
• Fix calculation errors on the shadow of the spotlight
• Shadow bias is changed to use world space units, which will be more intuitive to adjust
• Fix the crash problem in Android 11 API Level 30 environment
• Fixed the issue that AnimationClip.createWithSpriteFrames failed to dynamically create animation
• Fix inverseTransformPoint function error
• Fix widget’s monitoring of target anchor changes
• Fixed the issue that the Editbox backgroundImage property was not synchronized when modifying SpriteFrame
• Rollback the deprecation of the EventKeyboard.isPressed property
• Fix the problem that the node scale cannot be set in the button’s scale mode and the problem of infinite zoom

What’s new!

Performance optimizations

In version 3.3, the focus continues to be optimizing the loading performance and running performance of the WeChat mini-game platform. After all internal projects are upgraded, the WeChat cloud testing starts with a performance score that can reach more than 80 points.

We continue to leverage the native binding layer to a new level, we have implemented a native version of render scene, lighting, model and other render objects, the render objects collection process is also completely running with native implementation, which further improved the performance of the native platform.

There is also a side benefit. Due to the upward migration of the binding level, some underlying data sharing mechanisms have been lifted, such as Pass, SubModel, etc. This makes the implementation of the upper layer of the JS engine, especially the data related to the UI and 2D rendering batches more simplified, and the data structure of some high-frequency operations is restored from TypedArray to direct properties, which makes the performance of the Web and small game platforms also visible improvements .

Optimized Scene editing experience

1. Optimize the roaming mode of the scene camera, and add an acceleration switch.

2. Add a scene light switch (open by default).

3. Increase the display of the maximum and minimum coordinates of the model.

4. Increase the snap function of Transform Gizmo (when you move, rotate, zoom Gizmo, hold down the Ctrl key, you can increase the value according to the set step length.

5. Optimize the experience of using large projects: reduce the memory usage of the editor, avoid crashes, and optimize lag.

New Animation Editor and Animation Data upgrade

Currently, the Animation Editor has built-in curve editing, which matches the time axis, and supports the editing of the time curve between any key frames.

Animation Data has also bee upgraded to introduce a new basic curve class, refactoring AnimationClip, and unifying the curve data used by animation and particle systems. These works are prepared for the subsequent improvement of the animation system. In the subsequent version, we will support advanced functions such as animation state machine editing and Blend Tree animation fusion.

In addition, the Animation Editor also:

• Supports the animation display editing after the animation root node is hidden.
• Optimizes the occlusion relationship between the key frame of the Animation Editor and the small red line, the size of the key frame, the selected color, etc…
• The Animation Editor supports holding down shift + mouse wheel scrolling to move the timeline.

Platform support and Build system optimizations

Windows x64 build option have been added, and the win32 platform will be gradually deprecated in the future.

In the Build panel, there are many new optimizations:

• The iOS build configuration option supports developer id configuration related to the target iOS version and signature.
• After constructing md5Cache, you can add md5 suffix to the script to ensure that the version is updated; (feedback from the forum.)
• As some versions of WeChat already support astc, the compressed texture configuration of the small game platform astc is currently open.
• Preferences-Build a new option to open the build log.
• Build an interstitial configuration panel, which supports direct drag and drop of pictures in the file system to place.
• Command-line construction supports the input logDest to specify the log output path.
• Due to the limitation of the number of exit codes on the Mac, the command line to build the exit code has been modified.
• After the native platform is built, the game name cannot be modified a second time.

Shadow effects and settings optimization

In previous versions, the configuration of shadows has always been a feature that confuses developers. We have a complete plan and are gradually improving shadow support. v3.3 will first simplify the configuration of shadows, optimize soft shadow algorithms, and repair shadows. Part of the effect problem. Configuration adjustments include:

• Shadow color is migrated to the grayscale adjustment option of Shadow saturation, which will automatically migrate the alpha channel of the old version.
• The soft shadow options are changed from the previous X9, X25, etc. to Soft and Soft2X.
• The size of the simplified shadow map is set to High, Medium, Low.
• Remove the SelfShadow option, now self-shadow calculation will be turned on by default.

v3.1

v3.3

Perfect Physics system

As v3.1 supports the PhysX physics backend, the selection and use of multiple sets of physics engines has also become our focus of use experience. In v3.3, we not only strengthened the physical functions, but also unified the different physical backends as much as possible.

• Support CCD continuous collision detection function

• Increase the minimum volume control of the collision body to avoid a series of problems caused by node zero scaling.
• Supports more flexible configuration options for the PhysX physical packed byte platform.
• Support the global control in Bullet physics to allow automatic sleep.
• Support Bullet physics in ray detection filter trigger collision body.
• Fix local inertia with no additional status of rigid body in Bullet physics.

Other

1. After the audio system removed the playback control interface on all AudioClip resources in v3.1, the developers were quite dissatisfied. In v3.3, we added the playback control interface back to the AudioClip resource by marking it as obsolete. We still hope that all developers can switch to using the AudioSource component to play audio, which is essential for future audio system enhancements.
2. Input events were dispatched before they were received. If the event response logic is complex, it may affect the frame callback and cause the frame rate to be unstable. v3.3 has been adjusted to the inter-frame recording event queue, and the events are processed in the main loop. Queue.
3. The View and Screen interfaces have been simplified, some platform-related interfaces have been discarded, and some of the View’s window control functions have been unified on the Screen.

Key update list

Editor

• New version of animation time curve editing and animation editor experience optimization.
• The curve editor of each module is unified: particles, animation, etc…
• Optimize the editing operation of the particle curve, add a button to reset the coordinate movement range, and support directly right-click to edit the position of the key frame point.
• Scene editor experience optimization:
  • Add a scene light switch (open by default).
  • Optimize the roaming mode of the scene camera, and add an acceleration switch.
  • Increase the display of the maximum and minimum coordinates of the model.
  • Increase the snap function of the Transform Gizmo .
• Support HDR file import, the engine internal processing RGBE codec.
• Editor performance and experience optimization.
• When the Image resource is changed to SpriteFrame type, the Clamp configuration of texture is automatically modified to CLAMP_TO_EDGE to avoid the problem of edge blending and black edges.
• Support for editing animation events directly on the property panel with animation model.
• Fix the resource leakage problem in the editor and reduce the memory usage.
• Turn on ASTC compression texture configuration for WeChat mini game platform.
• Optimize the performance of the hierarchy panel, add prefab nodes to directly enter the editing function of prefab resources.
• Optimize the performance of the console panel and fix the problem that a large amount of log data slows down the startup speed.
• Color picker supports color gamma correction preview.
• Inspector supports grouped display of component attributes, using @group decorator
• The inspector edit node adds the world coordinate of the copy node.
• Supports a single grayscale image or a combination of channels of the rgb channel that displays the baking results.
• Support custom script templates, and some preset variables can be used when generating scripts.
• Support the installation directory with Chinese on Windows platform.
• iOS build and fill configuration options: target iOS version, signature-related developer id.
• Added generation platform option for Windows platform, support win32 and x64 options
• Support script import map
• Added the function of clearing code cache, the entry is in the menu: [Developer → Cache → Clean Code Cache]
• At the bottom right corner of the editor, add a hint that the engine version is inconsistent with the editor version.
• Electron upgraded to 13.1.4.
• Fix the occasional progress bar stop problem when building projects with m1 cpu devices.

Engine

• Optimize the AO calculation in the standard lighting model.
• Shadow parameters and rendering optimization.
  • Repair the shadow effect, optimize the shadow edge blur algorithm.
  • Migrate Shadow Color to Shadow Saturation single channel option, it will automatically migrate the alpha channel of the old version.
  • The soft shadow options are changed from the previous X9, X25, etc. to Soft and Soft2X.
  • The size of the simplified shadow map is set to High, Medium, Low.
  • Remove the SelfShadow option, now self-shadow calculation will be turned on by default.
• Introduce general curve class (Curve).
• Refactoring AnimationClip, refactoring and upgrading of animation data: prepare for the fusion of animation state machine and complex animation.
• Optimize the first screen rendering speed of WeChat mini games.
• Fixed the rendering problem caused by UI transparency cascade.
• Fixed the problem of Label repeatedly adding dynamic pictures.
• The particle curve uses unified Curve data.
• Physics Engine.
  • Unify the behavior of each physical back-end.
  • Support CCD continuous collision detection.
  • Increase the minimum volume control of the collision body to avoid a series of problems caused by the zero scaling of the node.
  • Supports more flexible configuration options for the PhysX physical packed byte platform.
  • Support whether to allow automatic sleep in the global control of Bullet physics.
  • Support Bullet physics ray detection filter trigger collision body
• Baking library supports Apple m1 cpu device.
• Byte game audio is implemented using the WebAudio interface.
• Event system.
  • All input events are collected and processed in the main loop of the game.
  • AudioSource supports monitoring audio start and end events AudioSource.EventType.STARTED & AudioSource.EventType.ENDED.
  • SystemEventType and macro.KEY are deprecated, use SystemEvent.EventType and KeyCode instead.
  • Deprecated SystemEventType, and some system event-independent enumerations under SystemEventType, please use SystemEvent.EventType.
  • Obsolete static properties Event.TOUCH, Event.MOUSE, Event.KEYBOARD, Event.ACCELERATION.
• Simplify the discarded part of the view and screen interfaces, and implement them in the platform adaptation layer (PAL).
  • Obsolete view.adjustViewportMeta and view.isAutoFullScreenEnabled.
  • Obsolete view.enableAutoFullScreen, please use screen.requestFullScreen.
  • Obsolete cc.winSize, please use view.getVisibleSize
  • Discard screen.autoFullScreen, please use screen.requestFullScreen.
  • Discard screen.disableAutoFullScreen.
• Fix the memory leak that may be caused by removing the Spine animation (thanks to Github PR from @hailua54).

Infrastructure

• Native rendering scene module: optimize the performance of the native platform.
• Use controllable off-screen FrameBuffer for content rendering.
• Support MSAA anti-aliasing based on the off-screen FrameBuffer (enable the project macro Enable Antialias): Note that if the project macro is enabled before, the performance loss of the native platform will increase after the upgrade to 3.3, which is normal.
• Built-in Frame Graph rendering customization layer, subsequent versions will be connected to the rendering pipeline, and the customization interface will be opened to users.
• Support Subpass in Vulkan & Metal backend.
• Add the ability to debug with iOS Simulator on Apple devices with M1 CPU, you need to refer to Document Usage.
• The binding generator is fully compatible with python 2.7/3.x (64 bit).

Breaking changes

• Building compressed textures no longer has a default png image. If you use a project with this feature, please add a default image for the existing compressed texture configuration in the project configuration (from Forum Feedback.)
• Currently supports direct import of HDR textures. If you used an RGBE formatted .png before, please replace with the original .hdr textures.
• We fixed an FBX resource import problem: If the FBX model contains multiple animations, the second and subsequent animations incorrectly include all the animation data of the previous segment.Note: If animation segmentation has been configured, it may need to be adjusted. However, we have not received feedback from external developers on this issue.

Known Issues

• The native platform Bullet back-end ray detection performance has decreased. We will fix this problem in the next minor version. You can temporarily switch to the PhysX back-end for use or reduce the number of rays per frame.
• The startSpeed, startRotation, gravityModifier properties of 3D particles may display abnormally in Curve mode. This problem will be fixed in the next minor version.

Upgrading

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

What’s new!

Cocos Creator v3.2.1 is the result of merging v3.1.2 into v3.2.1, and continues to bring a more stable experience on the major version branch. Both v3.2 users and v3.1.x users can upgrade without pain.

Release Notes

• Web & mini-game 2D rendering performance optimization
• Optimize the startup performance of mini-games
• Optimize the runtime performance of animation components
• Optimize the PCF shadow blur effect, which is more friendly to low-precision ShadowMap
• Optimize bullet physics engine performance
• Added automatic resource scanning switch, large projects can manually refresh the resource manager to improve the editor experience
• TS strict mode is not turned on by default when creating a project (manually recommended)
• Solve the memory leak caused by Mask
• Solve the memory leak caused by MeshRenderer setting material
• Enhance the fault tolerance of FBX model import
• Compatible with obsolete AudioClip playback interface

Important

• Fixed the issue of the Empty template creation project
• Fixed the problem of multiple PASS switching in the material editor and some attribute display loss
• Fixed JointTextureLayout panel cannot be scrolled
• Fixed the issue that the setting window of SplashScreen could not be closed
• Fixed the problem that the script on the root node of the prefab is lost in the native environment
• Fixed rendering errors caused by repeated loading of Morph models
• Fixed crash when TTF font is missing
• Animation editor fix
• Fixed the problem that the keyframe of the animation editor node could not be deleted directly
• After the animation editor is selected, press Ctrl to add keyframes and then copy and paste, zoom, and arrange keyframes are abnormal
• Fixed the problem that the scroll bar does not appear when the attribute list of the animation editor exceeds the limit. After the sample is modified, the current time display is not updated in real-time
• Environment and light and shadow
• Fixed the texture error after IBL is turned on
• Fixed the problem that the skybox could not be displayed for the first time setting
• Fixed GPU pre-baked skeletal animation failure after opening ShadowMap shadow
• Particle module repair
• Fixed the issue that the particle material cannot be displayed when the node is not enabled
• Fixed the particle start speed effect problem and the gravity effect problem when rotating
• Build module repair
• Fixed an error after restarting the build plugin feedback from forum
• Fixed that the cache is still used in the build after the modification of the automatic atlas configuration feedback from the forum
• Fixed the git ignore configuration problem of Android ABI without default value and native folder feedback from forum
• Tiled map fixes
• Fix the display error of Tilesets under multi-atlas
• Fix the error of TiledLayer getTiledTileAt function
• 2D skeletal animation
• Fixed the problem of editor update color, Spine and DB transparency does not take effect
• Fixed the problem that Spine on web and native uses blend mode to display incorrectly
• Fixed the issue that the Spine hanging node did not take effect after the editor set the scale

In addition, the v3.3.0 version has entered late testing. This version has some very important updates that should be known in advance:

1. Further increase the proportion of nativization, implement rendering scenes in the native layer, optimize performance, and lay a solid foundation for the future upper-layer nativization and scene management
2. Optimized rendering pipeline to reduce IO pressure
3. Optimize the experience of using large projects: reduce the memory usage of the editor, avoid crashes, and optimize lag
4. Optimize the standard lighting model
5. Animation data reconstruction and upgrade: prepare for the animation system upgrade and animation state machine
6. The physical behavior of each back-end is unified
7. Delayed rendering pipeline optimization: light source clipping, SSPR, etc.

Cocos Creator 3.2 officially supports HarmonyOS, becoming the world’s first game engine that supports HarmonyOS. At the same time, Creator has conducted in-depth cooperation with the Bytedance platform to support the use of PhysX provided by the platform in byte games with experimental features! All developers are welcome to use and experience!

What’s new!

Support building HarmonyOS applications

In version 3.2, Creator supports one-click packaging of games into HarmonyOS applications. After configuring the HarmonyOS SDK and NDK paths, select HarmonyOS one-click packaging in the build panel. For detailed operations, please refer to the publishing HarmonyOS applications documentation.

ByteDance games support the use of PhysX capabilities provided by the platform

Cocos Creator and the ByteDance platform have conducted in-depth collaboration, with the experimental feature in v3.2 to support the use of PhysX physics capabilities provided by the ByteDance platform in ByteDance Mini Games, optimizing the performance of physics calculations, and having a nearly 100% performance improvement compared to Bullet physics

Multithreading can be enabled in the build panel:

Upgrading

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.

What’s new!

Cocos Creator 3.1.2 mainly fixes the stability problems of v3.1 and optimizes the editor workflow. All developers are welcome to use and experience! Please make a backup of relevant files before upgrading! The following is the detailed update content.

v3.1.2 is a version that optimizes experience and performance on v3.1.1. The update content of this version is not included in v3.2. Later, the v3.1.2 update will be merged into v3.2.1 and v3.3.0!

Since 3.1.0, the engine group has actually been advancing three version lines in parallel, v3.2.0, v3.1.x, v3.3.0, of which v3.2 has a requirement for the release of Hongmeng 2.0, so the release date is set early Now, for stability, the main reason is to increase the Hongmeng platform support on the basis of v3.1.1. After that, we continue to receive feedback from developers about 3.1. In order to more effectively solve the pain points encountered by developers and lower the upgrade threshold for developers, we have decided to continue to optimize the experience and performance on v3.1.2 Performance, delivered to developers. At present, Cocos Creator v3.x, as a new 3D engine, is still far from the expectations of developers. We hope to give developers stronger confidence through this practical action of continuous delivery. At the same time, thank you to all the v3.x pioneers for their support, it is your feedback that makes the engine more and more perfect!

Release Notes

• Web & mini-game 2D rendering performance optimization
• Optimize the startup performance of mini-games
• Optimize the runtime performance of animation components
• Optimize the PCF shadow blur effect, which is more friendly to low-precision ShadowMap
• Optimize bullet physics engine performance
• Added automatic resource scanning switch, large projects can manually refresh the resource manager to improve the editor experience
• TS strict mode is not turned on by default when creating a project (manually recommended)
• Solve the memory leak caused by Mask
• Solve the memory leak caused by MeshRenderer setting material
• Enhance the fault tolerance of FBX model import
• Compatible with obsolete AudioClip playback interface

Important

• Fixed the issue of the Empty template creation project
• Fixed the problem of multiple PASS switching in the material editor and some attribute display loss
• Fixed JointTextureLayout panel cannot be scrolled
• Fixed the issue that the setting window of SplashScreen could not be closed
• Fixed the problem that the script on the root node of the prefab is lost in the native environment
• Fixed rendering errors caused by repeated loading of Morph models
• Fixed crash when TTF font is missing
• Animation editor fix
• Fixed the problem that the keyframe of the animation editor node could not be deleted directly
• After the animation editor is selected, press Ctrl to add keyframes and then copy and paste, zoom, and arrange keyframes are abnormal
• Fixed the problem that the scroll bar does not appear when the attribute list of the animation editor exceeds the limit. After the sample is modified, the current time display is not updated in real-time
• Environment and light and shadow
• Fixed the texture error after IBL is turned on
• Fixed the problem that the skybox could not be displayed for the first time setting
• Fixed GPU pre-baked skeletal animation failure after opening ShadowMap shadow
• Particle module repair
• Fixed the issue that the particle material cannot be displayed when the node is not enabled
• Fixed the particle start speed effect problem and the gravity effect problem when rotating
• Build module repair
• Fixed an error after restarting the build plugin feedback from forum
• Fixed that the cache is still used in the build after the modification of the automatic atlas configuration feedback from the forum
• Fixed the git ignore configuration problem of Android ABI without default value and native folder feedback from forum
• Tiled map fixes
• Fix the display error of Tilesets under multi-atlas
• Fix the error of TiledLayer getTiledTileAt function
• 2D skeletal animation
• Fixed the problem of editor update color, Spine and DB transparency does not take effect
• Fixed the problem that Spine on web and native uses blend mode to display incorrectly
• Fixed the issue that the Spine hanging node did not take effect after the editor set the scale

In addition, the v3.3.0 version has entered late testing. This version has some very important updates that should be known in advance:

1. Further increase the proportion of nativization, implement rendering scenes in the native layer, optimize performance, and lay a solid foundation for the future upper-layer nativization and scene management
2. Optimized rendering pipeline to reduce IO pressure
3. Optimize the experience of using large projects: reduce the memory usage of the editor, avoid crashes, and optimize lag
4. Optimize the standard lighting model
5. Animation data reconstruction and upgrade: prepare for the animation system upgrade and animation state machine
6. The physical behavior of each back-end is unified
7. Delayed rendering pipeline optimization: light source clipping, SSPR, etc.

In addition, various demos are also in production, such as the Parkour Demo that has been put on the Store.

The API documentation page is also being redesigned.

In short, we attach great importance to the voice of the community and will try our best to improve the 2D & 3D development experience of Cocos Creator v3.x step by step.

What’s new!

Cocos Creator 3.1.1 mainly fixes the stability problems of v3.1 and optimizes the editor workflow. All developers are welcome to use and experience! Please make a backup of relevant files before upgrading! The following is the detailed update content.

Improvements

• Added the ability to create Prefab resources in the Explorer panel
• Added a new level manager panel that can be set in batches (Alt + click) to lock the node function (after being locked, it cannot be selected in the scene editor panel)
• When the property in the property inspector is a non-null type, but has a null value, a new creation function is added

Bug Fixes

• [EDITOR] Fixed the issue that may report errors when building the Android platform.
• [EDITOR] Fixed the problem that the command line build using default values ​​could not be successful.
• [EDITOR] Fixed the problem of some boolean parameter conversion errors when building the command line.
• [EDITOR] Fixed the invalid modification of Target Api Level when building Android platform.
• [EDITOR] Fixed the problem that the PNG format image is generated incorrectly when the ETC1 RGB Separate A format and the PNG format are selected at the same time for the compressed texture.
• [EDITOR] Fixed the issue that after adding skeletal animation events, it cannot be deleted all.
• [EDITOR] Fixed the selection problem of component track in animation editor.
• [EDITOR] Fixed the problem that the nodes or components in the nested Prefab referenced in the Prefab will be lost after saving.
• [EDITOR] Fix the problem that the nodes or components in the Prefab will be lost after saving in the newly added components in the Prefab instance.
• [EDITOR] Fixed the problem that the collapsed state of the property inspector interface record is invalid.
• [EDITOR] Fixed the issue of whether to modify the child nodes together after editing the layer property of the node in the property inspector panel.
• [EDITOR] Fixed the problem that the array in the property inspector panel does not recognize the dragged resource.
• [EDITOR] Fixed the problem that when the SpriteFrame resource is dragged to the level manager panel to create a node, the layer property of the node is not UI_2D.
• [EDITOR] Fixed the problem that there is no selected record for the last-level resource in the resource preview panel.
• [EDITOR] Fixed the problem that the resource manager panel cannot accurately scroll to the internal resources in the folded folder.
• [EDITOR] Fix the problem that the Joint Texture Layout panel cannot be scrolled.
• [ENGINE] Fix the problem of incorrect effect of SafeArea component [#8654].
• [ENGINE] Fixed the problem that the time scale of stop is not reset to 0 after calling pause on the audio of the Xiaomi Kuai game platform [#8636].
• [ENGINE] Fix the issue that the audio of Huawei Quick Game Platform gets currentTime as string type [#8656].
• [ENGINE] Fixed the problem that the touch event callback of the LianShang game platform will cause the stuck on the low-end machine [#8661].
• [ENGINE] Fix the problem that touch events are unavailable on the iPad browser [#8673].
• [ENGINE] Fix the problem that the gravity sensor of QQ browser, WeChat mini game iOS terminal, Baidu mini game cannot be turned on or is incorrect [#8632].
• [ENGINE] Fix the problem of CacheManager.clearLRU call error [#8663].
• [ENGINE] Fix the problem that the SubContextView node cannot be rendered due to the modification of the node layer [#8677].

Known Issues

• There is a problem with the keyboard and mouse adaptation of the WeChat PC. We will fix this problem in the next version, or you can manually merge this PR fix: [#8626]
• You need to manually call the Sprite.updateMaterial function after setting the RenderTexture in Sprite, otherwise it may cause image flipping problems on some platforms
• Checking UseIBL on the scene skybox option may cause the cc_environment binding to be lost. This problem will be fixed in the next version

Upgrading

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.

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!

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

Improvements

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

Editor

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

Engine

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

Upgrading

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.

What’s new

• The option simulate global variables is removed, and the option execution scope is newly added.

• The optional values are Global or Enclosed. When it is Global, execute the script directly in the target environment. When Enclosed, the entire script is wrapped in an IIFE function for execution, which means that variables declared with var at the top of the script will not be promoted to global variables.
• Added functions for aligning the scene camera to a certain node.

• Added 2D/3D mode switching shortcut key (number key + 2)

Release Notes

Improvements

• Give clearer hints when trying to reference Node modules in the project
• Eliminate redundant code of project scripts in the package body when building
• Optimize the WeChat engine separation function and module removal to reduce the package body
• Supports BMFont compressed texture using transparent channel separation format [#8364]

Editor

• Fix the issue that the command line build will add a new build task
• Fix the problem that the shortcut keys of the shortcut key panel may not be modified successfully under certain circumstances
• Fixed the problem of delay in deleting multiple selected animation events by right-clicking
• Fixed the problem of skeletal animation not being able to click on the property track and move the small red line to view normally in the animation editor
• Fix the problem that the plugin manager needs to be manually refreshed to display after creating a build plugin
• Fixed the problem that the plugin manager failed to import plugins on mac
• Fix the problem of pop-up warning when plug-in mall is closed
• Fixed the difference between the main light source of the engine and the baking effect
• Fix the problem of baking non-n*n terrain errors
• Fix the cache problem in the interface of editing particle nodes
• Fix the problem that the sub-resource editing interface is not displayed when the picture is of textrue type
• Fix the problem that the shortcut key configuration panel cannot be scrolled
• Fixed the issue that the terrain brush of the terrain node was not reset after switching scenes
• Fix the problem that iOS project cannot be built on M1 device
• Fix the problem that sub-resources may be lost when glTF resources are imported
• Fix the problem that the template file of the build plug-in created cannot be modified
• Fix the problem that scene.name is missing when previewing

Engine

• [SPINE] Fix the problem that the SkeletonTexture type is not exported [#8359]
• [UI] Fix the problem of incorrect rendering of static batch components on iOS 14 [#8320]
• [UI] Fix the incorrect line break of RichText component [#8345]
• [UI] Fixed the problem of mask click penetration [#8313]
• [UI] Fixed the always mode problem of Widget [#8304]
• [UI] Fixed the memory leak of Mask [#8375]
• [SHADOW] Fixed the problem of setting extra texture error for plane shadow under instancing[#8336]
• [SHADOW] Fixed the problem that the transparent model renders incorrectly after opening the shadow map under the Nvidia graphics card[#8303]
• [SHADOW] Fixed the problem that flat shadows are not displayed under multiple light sources [#8328]
• [TWEEN] Fix the problem that Tween does not support custom easing functions [#8321]
• [PHYSICS] Fix the problem that the initialization type of rigid body is incorrect when it is not enabled [#8307]
• [PHYSICS] Fix the problem that setting grid does not take effect when Ammo is running [#8315]
• [ASSET] Fixed the rendering problem of ETC1 format compressed texture in WebGL2 environment [#8351]

Native

• Fix the problem that the native Spine/Dragonbones node cannot be displayed after the active change [#8323]
• Fix the problem that EditBox on Win32 / macOS platform cannot end editing after pressing Enter [#3295]

Breaking Changes

• After the easing system update timing is changed from the lateUpdate stage to the update stage, the processing timing may need to be adjusted [#8305]
• In order to adapt to M1, the third-party library is recompiled, and the Xcode version is required to be 11.5+.

Known Issue

• When importing FBX with negative frame animation, the editor may not work. Please make sure that there is no negative frame animation in the corresponding DCC tool. Later versions will fix this problem.
• The native platform Spine premultiplied rendering is incorrect, this issue will be fixed in later versions.

Upgrading

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.

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.

After the v3.0 preview was released, the engine team received a lot of enthusiastic feedback from developers, this feedback really helped to increase the team’s motivation to release an amazing product. Creator v3.0 unifies the development workflow of 2D and 3D, taking into account the development experience from light and heavy games, and integrates almost all the functions of Creator v2.x and Creator 3D 1.x. v3.0 now encompasses these versions under a single umbrella.
v3.0 has been further optimized in performance, improved quality, and introduces more features, such as access to the native runtime of Spine and DragonBones, support for the use of NPM libraries, and refactored the Prefab system and UI System and many other contents.

What’s new

v3.0 uses a new future-oriented engine architecture, which will bring high-performance, data-oriented and load-balanced renderers to the engine, and seamlessly support Vulkan, Metal & OpenGL ES multi-backend rendering. In the future, we also plan to support mobile VR/AR and some of the desktop & console platforms. Below is a brief introduction to core features of v3.0.

Powerful editor features

The integrated editor brings a lightweight and easy-to-use creative experience. Cocos Creator v3.0 is refactored, expanded and upgraded on the editor framework that Cocos Creator 2.x has used for many years.

• Brand new interface design, more concise and clear.
• Resource system upgrade, enhanced support for super large projects, more efficient and reliable.
• Code isolation between modules, pure message-driven, more stable.
• The extension system is completely modularized to welcome a more powerful plug-in mechanism.

One-click access to Cocos’s quality services

Cocos Creator v3.0 provides one-click access to various high-quality services officially launched by Cocos, improving development efficiency and launching more high-quality content. Cocos will continue to launch additional and improved services.

Brand new Prefab system

Creator v3.0 re-implements the Prefab system with features such as:

• Support Prefab automatic synchronization.
• Prefab instance can overwrite attributes in Prefab resource.
• Support Prefab nesting.

Build system

Build content caching

After building, Creator v3.0 will cache most of the build content, including resources, compressed textures, automatic atlas, engine code, etc. In the subsequent build, if nothing has changed, the cached content will be used directly to speed up the build and improve efficiency.

Task-based build list

The build and publish will be carried out in the form of build tasks, saving the configuration, status, log, etc. of each build, making it easy to switch build tasks and view historical configurations.

Compile and generate separately after build

The generation stage of each mini game platform is extracted, allowing to modify the content of the file after build to regenerate rpk/cpk.

Build process hooks

The build extension support adding hooks before and after compilation to customize the build process.

Support Asset Bundle

Creator v3.0 uses Asset Bundles as a resource modularization tool. Developers can build textures, scripts, scenes and other resources into multiple Asset Bundles, and then load them on demand during the game’s running process, thereby reducing the time required to download and load the game for the first time. Asset Bundles can be placed freely as required, for example, they can be placed in remote servers, local, or sub-packages of small game platforms, or they can be reused across projects to load Asset Bundles in sub-projects.

Splash Screen

It supports setting up Splash Screen during construction, which is used to display a cutscene before the game starts, and optimize the startup speed of the first screen.

GameView

GameView is a game running panel embedded in the editor. Developers can run the game directly in the editor without opening the browser preview. In addition to a more seamless development experience, debugging and modifying element states in real time through the scene editor or other panels during the game running process, making game development more efficient!

Extension

Powerful extension system

Cocos Creator v3.0 has a more powerful extension system. Almost all internal modules of the editor are built with extension system. You can quickly create your own extensions in the extended menu to achieve the customizations you want. In addition, Creator v3.0 also provides an extension manager, which can easily manage the operation and uninstallation of all extensions.

Message communication

Extensions can use IPC messages to communicate with other extensions or the editor core, and quickly and easily use the capabilities provided in the editor. Cocos Creator v3.0 also provides a message manager, which can clearly see the functions currently provided in the editor, reducing the threshold for extension development.

Animation Editor

The Animation Editor is an important module that we have been continuously optimizing. In addition to standard displacement, rotation, zoom animation and sequence frame animation, this animation system also supports driving arbitrary component attributes and user-defined attributes, plus it can be edited at will The time curve and innovative movement trajectory editing functions allow content producers to produce various dynamic effects without writing a line of code, and drive the game logic at will.

In addition to regular operations, the v3.0 Animation Editor also provides the following shortcut operations to help game developers achieve the desired content:

• Batch key frame interval adjustment.
• Copy and paste across node tracks.
• Indirect attributes (such as material attributes) keyframe editing.
• Directly select resources and directly edit key frame data in the animation editor.
• Multi-select key frame zoom, move and delete.
• Support multi-select nodes to add attribute tracks in batches.
• Support copy and paste all animation data on the node.
• Support shielding no key frame nodes and search nodes.
• Support editing component tracks.
• Support to adjust the layout of the animation editor.

A more complete tool chain

• Support model preview.
  • After selecting the model in the editor, you can preview the model resources in all directions, and you can also view various textures used in the default materials.
• New version of FBX importer.
• Support the import of glTF resources, support khr-draco-mesh-compression, sparse accessor.
• Support animation cutting.
• Provide Mesh Optimizer tool.
• Model import support quantized joints/weights.

Terrain Editor

Convenient terrain system to quickly draw terrain textures. Terrain editing mainly includes three major functions: Manage, Sculpt, and Paint. It also supports Normal Map, PBR material and custom material.

Built-in baking system

Baking is the process of generating light maps by pre-calculating the influence of light sources on objects and shadows projected with very high level of details. The light maps are then applied to the scene in runtime very efficiently, which can greatly improve the graphics quality of static scenes.

Configuration

Visual macro configuration

Provides a shortcut to modify the engine macro configuration. The configured macro will take effect during preview and build. At the same time, the default value of the current macro configuration will be updated with the configuration of the custom engine.

Batch configuration of compressed textures via presets

Support for adding compressed texture preset configuration, which is used to quickly configure the compression method of texture. After setting presets for image assets, you can also directly modify the presets to update the configuration for corresponding textures all at once, which greatly facilitates the overall management of the project.

Support 2.x project migration

In order to facilitate the upgrade of 2.x users, we provide a project migration plugin in 3.0, which can migrate projects above version 2.4.3 to version 3.0.0. This tool will support the perfect import of old project resources and the auxiliary import of code. 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. However, there is still a big difference between the 2.x API and 3.0. We use deprecation and removal mechanisms to make runtime warnings as much as possible. But developers still need to make a lot of adjustments to the code in order to upgrade to 3.0 perfectly.

Powerful engine features

Cocos Creator v2.4 is very powerful in 2D rendering, while Cocos Creator v3.0 allows developers to make more beautiful 3D games. We have integrated the advantages of the two in 3.0, and fully support various functions of 2D and 3D. Whether 2D or 3D, 3.0 will meet your needs.

Rendering system

As the core module of the game engine, the rendering system plays a vital role and directly determines the content that the game can output to the player. An excellent rendering system must also take into account various platforms and smooth the differences between platforms. The rendering system of Cocos Creator v3.0 aims at future-oriented, high-performance, and cross-platform from architecture to design, which greatly improves rendering capabilities and robustness.

• Supports multiple rendering backends of Metal, Vulkan, WebGL 1.0, WebGL 2.0, GLES2, GLES3, and provides a unified GFX graphics API layer to the rendering pipeline layer.
• The GFX API design close to the modern graphics API helps the rendering pipeline layer to release the performance and possibilities provided by the modern graphics API as much as possible.
• Built-in forward rendering pipeline, support user-defined rendering pipeline.
• Physically based light sources, cameras and materials help developers use industrialized processes to create the most realistic visual effects.

• Supports GPU Instancing batch optimization, which is suitable for drawing a large number of dynamic models with the same mesh, and supports instancing batches of models containing skeletal animation calculations.

• Support global fog effect.

• Powerful native renderer, using memory sharing mechanism to reduce JSB calls and speed up data access.
• Support ASTC, ETC, ETC2, PVR and other compressed textures.

Light and Shadow

In the 3D world, light and shadow have always been extremely important components. They can enrich the environmental performance, and good quality shadows can achieve a fake effect and make the whole world more three-dimensional.

• Physically based light source.
  Cocos Creator v3.0 uses optical measurement units to describe light source parameters. Based on optical measurement units, we can convert all the relevant parameters of the light source into physical values in the real world. In this way, the designer can adjust the light intensity, color, range and other information according to the actual lighting industrial parameters and the actual physical parameters of the real environment, so that the overall lighting effect and light attenuation are more in line with the real natural environment.

• Multi-light support based on multi-pass.
• Support high-performance flat shadow Planar Shadow.
• Directional light and spotlight dynamic shadow based on Shadow Map, support PCF soft shadow and GPU Instancing.

Particle System

The particle system is the basis of the special effects of game engines. It can be used to simulate natural phenomena such as fire, smoke, water, clouds, snow, and fallen leaves, and it can also be used to simulate abstract visual effects such as luminous trajectories and speed lines. Good particle effects can make the game screen more stunning.

• Support up to dozens of module settings, and support various types of curves, constant changes.

• Support GPU particles, greatly improving rendering performance.
• Support Cocos traditional 2D particles.

Material System

As a resource, material determines the rendering effect of the attached object. Almost all the rendered effects in the game are inseparable from the material. As a basic module, the material system provides a solid foundation for the superstructure.

• Built-in physical-based standard materials.
• Support Cocos Effect.
  The Cocos Effect based on YAML and GLSL designed by Cocos is a single-source embedded domain specific language(single-source embedded DSL). The YAML part declares the flow control list, and the GLSL part declares the actual Shader fragment. The above complement each other and together constitute a complete rendering process description.
• Support more than 32 Effect macro definitions.
• Cocos Effect compiler automatically removes invalid codes.
• Support importing Effect header files.
• Effect’s resource panel now supports previewing the compiled Shader code, and supports visual editing of each Define of the Shader.
• Support material preview.

Middleware

• Support TiledMap.

• Support Spine, DragonBones.
• Support Spine, DragonBones and TiledMap rendering in 3D scene (need to customize material to control depth detection).

Skeleton Animation System

Cocos Creator v3.0 has a built-in general animation system to display animation based on key frames. In the editor, we can easily produce key frame animation clips. We can also support importing skeletal animations already contained in external FBX and glTF resources. These animations can be edited in the resource manager. Animation effects can be previewed in the animation editor, animation event triggers can be added, and animation system APIs can be used. You can also freely control the animation playback.

In addition, we also support the following features:

• CPU or GPU driven skeletal animation, can be switched freely.
• Supports the fusion transition of animation (CPU driven).
• Use binary format to store skeletal animation to reduce file size.
• Support two components: general animation and skeletal animation.
• Support material sub-attribute animation such as Uniform.
• Support CPU driven Morph Target (Blend Shape).

Script system

The project development of Cocos Creator v3.0 has fully turned to TypeScript, and JavaScript is no longer supported in the project except for plug-in scripts in JavaScript or NPM modules. TypeScript support has been improved in v3.0:

• Embrace ES6 and TypeScript, complete code hints and automatic import.
• Attributes support independent type decorator: @integer, @float, @string, @boolean, @type etc…
• Support Async Await syntax.
• Optional Chaining support.
• Nullish Coalescing support.
• Certain circular reference behaviors will be detected and warned during operation.
• Added core-js polyfills to help some low-end platforms complete ES6 support.
• Support loose compilation mode, which can reduce package body and optimize performance.
• Support using NPM modules.
• Subdivide engine modules, allowing more detailed module removal.

UI system

Cocos Creator v3.0 continues the 2.x UI design, and further optimizes and upgrades, including the following:

• Flexible and concise 2D rendering and UI interaction, layout components, support 20 kinds of components including Sprite, Label, Button, Widget, etc. You can use these basic components to combine various types of UI effects.
• Support static batching.
  The engine provides the UIStaticBatch component. UIs that do not require frequent changes can use this component to cache rendering data, thereby reducing rendering consumption and improving performance.
• Support dynamic image combining at runtime, reduce the number of drawcalls, and optimize performance.

• Merged the UI rendering process and the forward rendering process, allowing 2D and 3D rendering components to be mixed, and rendering visibility is completely determined by the node Layer and camera Visibility.

Physics

Cocos Creator v3.0 currently has a built-in lightweight collision detection system Builtin and a physics engine cannon.js with physical simulation, as well as a powerful bullet compiled into asm.js/WASM version ammo.js, and provides users with an efficient componentized workflow and convenient usage.

• Support multiple physical backend options, including ammo.js, cannon.js and more lightweight builtin physical.
• Support WeChat mini games using WASM physical backend, which can achieve higher performance on iOS.
• Physics system supports fixed step refresh.
• Support physical materials.
• Supports a variety of practical collision bodies including simple shapes, cones, planes, terrain, capsules, cylinders, static mesh collision bodies, etc…

• Support point-to-point and hinge constraint components.
• Mesh collider adds convex hull approximation function.

• Support traditional Creator 2D physics and collision system.

In a near future, we will provide builtin PhysX backend on native platforms, which will greatly improve performance and physics capabilities.

Detailed changes (compared to Creator 3D)

Editor

• [3.0 NEW FEATURE] New FBX importer.
• [3.0 NEW FEATURE] supports loose compilation mode when compiling.
• [3.0 NEW FEATURE] Terrain supports normal map and pbr material.
• [3.0 NEW FEATURE] supports EditBox in GameView mode.
• [3.0 NEW FEATURE] supports code removal according to pre-compiled macros when compiling project scripts.
• [3.0 NEW FEATURE] supports removing deprecated compatible codes during the build process and reducing the package body.
• [3.0 NEW FEATURE] Brand new Prefab system, supports Prefab nesting.
• [3.0 NEW FEATURE] The terrain system supports the use of custom brushes and normal map settings.
• [3.0 NEW FEATURE] Support resource package import and export function.
• [3.0 NEW FEATURE] native platform supports script encryption.
• [3.0 NEW FEATURE] Added Huawei AGConnect build platform.
• [3.0 NEW FEATURE] Added Huawei quick game debugging tool.
• [3.0 NEW FEATURE] supports access to Cocos Service.
• [Sync 2.x] supports simulator preview.
• [Sync 2.x] supports publishing LianShang mini game platform.
• [Sync 2.x] supports publishing interesting headlines game platform.
• [Sync 2.x] supports building Android Instant.
• [Sync 2.x] supports the new version of serialization mechanism.
• [Sync 2.x] Asset Bundle support.
• [Sync 2.x] supports engine module removal during preview.
• [Sync 2.x] editor supports importing JSON resources.
• [Sync 2.x] editor supports importing text resources.
• [Sync 2.x] editor supports importing LabelAtlas resources.
• [IMPROVE] Upgrade electron, computer that supports M1 chip.

Engine

• [3.0 NEW FEATURE] supports using NPM library.
• [Sync 2.x] supports Tiledmap.
• [Sync 2.x] supports Spine.
• [Sync 2.x] supports DragonBone.
• [Sync 2.x] supports MotionStreak.
• [Sync 2.x] supports WebView.
• [Sync 2.x] supports VideoPlayer.
• [Sync 2.x] supports 2d physics and collision system, including box2d and builtin.
• [Sync 2.x] supports Asset Manager resource management.
• [Sync 2.x] supports LabelShadow.
• [Sync 2.x] supports SafeArea.
• [Sync 2.x] Mask supports image stencil.
• [Sync 2.x] audio supports multicast.
• [Sync 2.x] supports dynamic picture combination.
• [IMPROVE] UIMeshRenderer supports receiving parallel light.
• [IMPROVE] remove cc.Class() style declaration.
• [IMPROVE] Reconstruct 3d physical collision matrix. The collision matrix is ​​only used to initialize the grouping and mask of rigid bodies. It is no longer maintained and updated, and the Use Collision Matrix configuration item is abolished.
• [IMPROVE] Refactored 3d rigid body, removed RigidBody.isKinematic, added RigidBody.type to set the rigid body type, removed fixedRotation, and replaced it with angularFactor.
• [IMPROVE] UI supports custom materials.
• [IMPROVE] Optimize UI system performance and reduce the number of drawcalls.
• [FIX] Fix Safari 14 performance issues.
• [FIX] Fix the problem of Button component Scale setting abnormal.
• [FIX] Fix the problem that the lightPassIdx of submodels are consistent and cause rendering errors.
• [FIX] Fix the problem that the terrain collider does not match the rendering effect after the node is zoomed.
• [FIX] Fix the problem of reporting errors when calling the view.setFrameSize interface.
• [FIX] Fix the problem that setting the label alignment of EditBox component is invalid when InputMode is not ANY.‍‍‍‍‍‍‍‍‍

Mini Game

• [3.0 NEW FEATURE] supports a new subdomain scheme.
• [3.0 NEW FEATURE] supports WeChat mini games to use wasm physical backend.

Native

• [3.0 NEW FEATURE] Support Metal rendering backend.
• [3.0 NEW FEATURE] supports Vulkan rendering backend.
• [IMPROVE] further reduces jsb calls and optimizes performance.

Known Issue

• The Vulkan backend on Android currently has performance issues, to be fixed in a future version.
• On a machine with M1 chip, an error will appear when compiling the ios simulator, you need to manually change arch to arm64, which will be fixed in subsequent versions.
• Android does not currently support the release of x86_64 architecture.
• The native platform does not currently support freetype for text rendering.
• Button component does not currently support enable auto gray effect option.
• It is currently not possible to create components, delete components, delete sub-nodes, and adjust the order of sub-nodes for Prefab instances in the scene. It is recommended to perform these operations in the Prefab resource.
• Nodes outside the prefab hierarchy currently cannot reference nodes or components in Prefab.
• When the terrain’s size is not by n*n, the baking process will fail.
• Upgraded old project from v2.x might have property referencing issue in prefab data, please refer to this topic 1 for detailed information and fix.

Breaking changes

• The built-in effects of the engine source code are uniformly changed to a different naming rule from the editor resources. If an effect is not used at all in the project scene, it will not be obtained by using the effect name in the script (such as builtin-unlit, etc.). It is recommended that when developers need to create materials programmatically, they should uniformly expose the effect asset as the property of the script, mount it in the scene, and then directly pass in material.initialize.
• The editor HOME directory has been switched from \~/.CocosEditor3D back to \~/.CocosCreator, and the plugin directory has been renamed from packages to extensions. Plugins after 3.0 will be stored in \~/.CocosCreator/extensions and PROJECT/extensions.
• The original subdomain plan is no longer applicable, please switch to the latest subdomain plan.
• No longer supporting JavaScript, only TypeScript.
• cc.global variables are no longer supported, please use module import.
• The 2D node will now strictly judge whether it can be rendered according to the visibility of the layer and the camera. If multiple cameras exist, there may be repeated rendering, and the layer of the node needs to be re-adjusted.
• Refactored physics events. Events between static rigid bodies are no longer supported. It is recommended to add a Kinematic or Dynamic rigid body component to the corresponding node of the collision body that monitors the event.
• Unable to upgrade to the Prefab of the new Prefab system, it will break the relationship and restore to a normal node.

API update (relative to Cocos Creator 3D)

• The name of the physical material type has been changed.

Creator 3D v1.2	Creator v3.0
PhysicMaterial	PhysicsMaterial

• Some type names and method names under the geometry space have been changed.

Creator 3D v1.2	Creator v3.0
line	Line
plane	Plane
ray	Ray
triangle	Triangle
sphere	Sphere
aabb	AABB
obb	OBB
capsule	Capsule
frustum	Frustum
MorphModel	models.MorphModel
ray_aabb	rayAABB
ray_plane	rayPlane
ray_triangle	rayTriangle
ray_sphere	raySphere
ray_obb	rayOBB
ray_capsule	rayCapsule
ray_subMesh	raySubMesh
ray_mesh	rayMesh
ray_model	rayModel
line_plane	linePlane
line_triangle	lineTriangle
line_aabb	lineAABB
line_obb	lineOBB
line_sphere	lineSphere
aabb_aabb	aabbWithAABB
aabb_obb	aabbWithOBB
aabb_plane	aabbPlane
aabb_frustum	aabbFrustum
aabbFrustum_accurate	aabbFrustumAccurate
obb_point	obbPoint
obb_plane	obbPlane
obb_frustum	obbFrustum
obbFrustum_accurate	obbFrustumAccurate
obb_obb	obbWithOBB
obb_capsule	obbCapsule
sphere_plane	spherePlane
sphere_frustum	sphereFrustum
sphereFrustum_accurate	sphereFrustumAccurate
sphere_sphere	sphereWithSphere
sphere_aabb	sphereAABB
sphere_obb	sphereOBB
sphere_capsule	sphereCapsule
capsule_capsule	capsuleWithCapsule

• Some platform variables under sys have been changed.

Creator 3D v1.2	Creator v3.0
BAIDU_GAME	BAIDU_MINI_GAME
VIVO_GAME	VIVO_MINI_GAME
OPPO_GAME	OPPO_MINI_GAME
HUAWEI_GAME	HUAWEI_QUICK_GAME
XIAOMI_GAME	XIAOMI_QUICK_GAME
JKW_GAME	COCOSPLAY
ALIPAY_GAME	ALIPAY_MINI_GAME
BYTEDANCE_GAME	BYTEDANCE_MINI_GAME

• The Canvas component no longer has properties such as clearFlag, color, priority, targetTexture, visibility, etc., please get it directly through the Camera component referenced by the Canvas component.
• Some components related to 2d have been renamed.

Creator 3D v1.2	Creator v3.0
UIRenderable	Renderable2D
UIDrawBatch	DrawBatch2D

Upgrade guide

In order to ensure the smooth transition of the existing Cocos Creator 2.4 project, we will use 2.4 as the LTS (long-term support) version and provide continuous updates for the next two years! In 2021, 2.4 will continue to be updated, providing bug fixes and new mini-game platform support, as well as Apple Silicon (M1) chip support. In 2022, we will continue to provide developers with 2.4 key issue fixes to ensure the smooth operation of online games! therefore:

• Existing 2.x projects can continue to develop without 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.

The original Cocos Creator 3D, as a branch version of Creator, has been iterated in China for a year, and has successfully launched major projects such as Starry Sky Battle and The Strongest Magic Fighter! After 3.0 is released, Creator 3D will also be included in 3.0, and existing 1.2 projects can be directly upgraded. Therefore, Cocos Creator 3D will not release a separate version in the future, and we hope developers using Creator 3D versions to be noticed.

Although we do not recommend projects under development, especially those that are about to go online, to upgrade to 3.0, we will still launch 2.x resource import tool in the 3.0 official version. If the existing project needs to be upgraded for special reasons, and you encounter technical or workload difficulties, you can also contact zhengxiong.zhao@cocos.com for our manual assistance!

Reference documentation

• Cocos Creator v3.0 User Manual
• Cocos Creator v3.0 Upgrade Guide