New Features and Improvements

Engine

• Pool: Supports setting shrink threshold, ensuring the pool size after shrinking will not be smaller than the threshold.

• Added support for mouse-enter and mouse-leave events to detect when the mouse enters or leaves the window.

• Added Vec2.toVec3() method.

• Added Vec3.toVec2() method.

• Added ResolutionPolicy.getContentStrategy() method.

• Added ContentStrategy.strategy property.

• Tween: When using sequence/parallel/then to chain Tweens, each child tween can have a different target. [issue]

• Added various Tween methods: reverse, id, union(fromId), timeScale, duration, pause, resume, pauseAllByTarget, resumeAllByTarget, update, and start(time).

• If the Tween's target is a Node, the system will automatically pause, resume, or stop based on the Node’s activation and destruction state. [PR1, PR2]

• Tween now supports easing strings and custom progress/easing functions for any property type. [PR]

• Taobao Mini Games: WebSocket now supports multiple instances. [PR]

• WebGPU support has been added (experimental).

• Added Tween.running getter to check if a Tween is running. [PR]

• Added Tween.getRunningCount(target) static method to get the number of active tweens associated with a target. [PR]

• Added built-in support for Bezier and Catmull-Rom curve progressions in Tween, allowing custom properties to be passed to tween.to/by(). [PR]

• Added Tween.updateUntil() method, which can add actions with uncertain durations to the tween system. The action will end when a callback function returns true. This can be used to create dynamic object tracking. [PR]

• Added utf-16 encoding support for TextDecoder on native platforms. [PR]

• Customizable Pipeline enters Beta:

  • Introduced a built-in customizable pipeline.

  • Cocos Built-in Pipeline is the new default, replacing the previous forward pipeline (builtin-forward) and customizable post-process pipeline.

  • Deprecating PostProcess, allowing package size reduction.

  • Default DepthStencil discard to improve mobile performance.

  • New projects will use the Builtin pipeline by default.

  • In upgraded projects:

    • If the project was using a customizable pipeline before, it will continue using the same customizable pipeline.

    • If the project was not using a customizable pipeline, the original pipeline will be retained.

  • Added a pipeline selection page where users can choose between customizable or original pipelines.

     

    

  • Customizable pipelines will package the following scripts: builtin-pipeline.ts, builtin-pipeline-settings.ts, builtin-pipeline-types.ts.

  • Debug view runtime control is currently unsupported and will be excluded from the package when using Builtin pipelines.

  • The Builtin pipeline currently has a larger package size, but optimizations are ongoing to reduce it to a reasonable size.

  • The BuiltinPipelineSettings can be used to configure post-processing effects, which have been migrated from PostProcess.

     

    

• SafeArea: Added support for setting symmetry for top/bottom and left/right areas, with visual examples.

   

  

Editor

• Improved UI layout for the build panel.

• Added a menu entry for creating resource templates.

•  

  

• SourceMap: Added support for the inline parameter. Previously, enabling SourceMap would default to creating separate files, which hindered debugging in Chrome on native platforms. Now, developers can select inlinemode for easier debugging on native platforms.

•  

  

• Improved spacing in the Windows menu bar.

• The Project Settings interstitial preview now adjusts according to the adaptation mode.

•  

  

• Auto Atlas preview now shows the combined image size.

• The editor now supports zoom level for window scaling.

•  

  

• Hotkey Support

•  

  

• Added a preference option to relocate the built-in resource library globally, improving the startup speed for different projects. Plugins that directly reference the resource library path may be affected. This feature can be enabled in Preferences -> Labs (default: disabled). (Known issue: simulator preview and native engine scene lab functions are not supported when this feature is enabled).

•  

  

  
  

   

Bug Fixes

Engine

• Fixed an issue where setting event.preventSwallow to true caused overlapping areas to not respond to touch events.

• Fixed an issue where some Node setter functions would send change events even when the values did not change.

• Fixed an issue where the absence of innerAudioContext.onCanPlay on Taobao and Alipay Mini Game platforms prevented sound playback.

• Fixed a nesting issue in NodeEventProcessor.dispatchEvent().

• Fixed flickering when tweening colors.

• Fixed an issue where _rot.x/y/z/w data in .scene and .prefab files might contain null values.

• Fixed a type enforcement error in the onStart/onUpdate/onComplete callback functions in Tween.to/by when using the opt?: ITweenOption parameter.

• Fixed an issue where Tweening would modify the target object’s properties.

• Fixed missing type definitions for custom progress and easing properties in Tween.to/by.

• Fixed an issue where the Tween system would automatically assign a uuid property to non-Node target objects.

• Fixed a memory leak caused by WebSocket receiving binary data on Android platforms.

• Fixed a memory leak issue on Android x86 emulators caused by padding bytes automatically inserted into gfxstructure by the compiler.

• Fixed a memory leak when modifying label text in CacheMode.NONE mode on native platforms.

• Fixed an issue where Button UI elements became unresponsive to touch/mouse events after exceptions were thrown in callback functions and caught by window.onerror/jsb.onError.

• Fixed incorrect window size display after screen rotation on iPads.

• Fixed an issue where sound would continue playing even when the mute switch was enabled on iOS devices.

• Fixed an issue where sound would not resume after receiving a phone call and returning the game to the foreground on iOS devices.

• Fixed an issue where cache-manager.clearLRU would not reset cleaning under specific conditions.

• Fixed inconsistent behavior when enable_multi_touch was set to true or false.

• Fixed shader compilation errors caused by non-integer uniform values in Web skeleton animations.

• Fixed out-of-range issues with multiple light sources on native platforms.

• Fixed syntax errors in scripts generated in the native release package, introduced in version 3.8.3.

• Fixed a compilation error when using private member functions (e.g., #foo()) in TypeScript, introduced in version 3.8.3.

• Fixed an issue where unnecessary .wasm and .mem.bin files for Spine were generated on native platforms.

• Fixed incorrect return values in Node.angle().

• Fixed timing errors in Component.scheduleOnce() callbacks.

• Fixed out-of-range issues in the gles2 backend.

• Fixed an issue where throwing an exception in a node's touch callback would prevent other nodes from responding to touch events.

• Fixed a black screen issue on some Android emulators (e.g., MEmu).

• Fixed memory leaks in bullet bodies.

• Fixed cache cleanup issues on Taobao Mini Game platform.

• Fixed a crash issue on native platforms when calling game.restart() with unhandled promise rejections.

• Fixed an issue where newly added dirtyRenderers were deleted during the updateAllDirtyRenderers process.

• Fixed a warning for outline when using richtext.

• Modified the video player on ByteDance platforms to display content using a texture-based method.

• Unified the interstitial display method for better adaptation to multi-resolution schemes.

• Fixed inconsistent behavior when ENABLE_MULTI_TOUCH was set to true or false.

• Fixed the issue of bmfont's colorDirty property not working on the web platform.

• Fixed rendering issues in SpriteRender Atlas.

• Fixed the creation of unnecessary atlases.

• Fixed incorrect system detection in sys.os/sys.isMobile on mini-game platforms and added Mac OS detection.

• Fixed an issue where switching the button type in the editor (from color to sprite, then back to color) would turn the button black.

• Optimized development experience: Avoid using debugger in ccAssert and use console.error instead.

• Optimized the 2D particle update buffer process by reducing unnecessary multiplication operations.

• Optimized file reading logic on native platforms by switching from synchronous to multi-threaded asynchronous reads, reducing resource loading stutters. JSON deserialization performance improved by approximately 30% on low-end Android devices.

• Fixed a crash issue on some mini-game platforms (e.g., Alipay, ByteDance, Taobao) when frequently creating canvases on low-end devices due to resource limitations.

• Fixed an issue where Spine node opacity was not working.

• Fixed incomplete release of some objects after releasing Skeleton-Asset.

• Optimized the frequency of parsing JSON for Skeleton-Asset.

• Fixed errors in the PhysicsContract.emit function when Collider did not have a rigid body.

• Fixed rendering errors for non-UI images in TextureRender on native platforms.

• Fixed an issue introduced in this version where updates to the child array did not trigger modification event dispatches in native platforms.

• Fixed an issue where Bullet was not exported.

• Fixed an issue where mouse enter and leave window messages were being swallowed.

• Fixed an issue introduced in this version where only one touch listener would respond to TOUCH_END or TOUCH_CANCEL.

• Fixed an issue on native platforms where the callback function order in performFunctionInCocosThread was incorrect.

• Fixed an issue where modifying a node’s position in performFunctionInCocosThread callbacks would prevent the node’s worldPosition from updating in the next frame.

• Fixed an issue where modifying a node’s position in Director.EVENT_AFTER_DRAW would prevent the node’s worldPosition from updating in the next frame.

• Fixed a crash when enabling or disabling Spine in setXXListener() on native platforms.

• Fixed an issue where the geometry renderer did not display in the customizable pipeline on native platforms.

• Compressed the effect.bin file in the customizable pipeline and added version control.

• Fixed an issue where reflection probe spherical previews were not displayed in the customizable pipeline editor.

• Fixed an issue where the clear color was incorrect with multiple cameras in the customizable pipeline.

• Fixed viewport rounding issues in the customizable pipeline.

• Fixed unrelated material pass rendering issues when rendering UI in the customizable pipeline.

• Fixed an issue where the skybox was incorrectly displayed in reflection probe scenes in the customizable pipeline editor.

• Reduced the package size of the customizable pipeline.

• Fixed the this pointer issue in Taobao Mini Game platform WebSocket callback functions.

• Fixed Xcode 16.0 compilation issues.

• Fixed warnings in the customizable pipeline editor.

• Fixed errors when baking reflection probes in the customizable pipeline.

• Merged the render queue fill in the customizable pipeline.

• Fixed potential crashes during the UI phase of the customizable pipeline on native platforms.

• Fixed wild pointer issues in the render window of the customizable pipeline on native platforms.

Editor

• Upgraded Xiaomi packaging tool to support Node 18 and above for Xiaomi compilation

• Added a lab feature option to toggle automatic MD5 processing of build template files, allowing users to disable it

• Fixed an issue where MD5 path replacement could inadvertently replace other tag attributes in HTML

• Fixed build errors on HarmonyOS platform when creating Bundles

• Fixed the display name issue for sub-resources in the assets panel

• Fixed the issue where the bottom of the Bundle resource preview list was not fully displayed when the list was too long

• Fixed the issue where custom script template URL parameters were invalid and improved the validation process for script file naming

• Optimized and fixed issues with the selection of scenes in the build panel and interactions when in a "missing" state

• Fixed the issue where creating a new build task for Huawei AGC platform did not update the configuration

• Fixed the issue where gizmo icons for nodes in the animation panel were not displayed in animation editing mode

• Fixed the missing scrollbar when adding multiple skeletons in the project settings for skeleton texture layout

• Fixed the issue where reselecting terrain nodes required switching texture layers to paint the selected texture layer

• Fixed the issue where terrain sculpting data was lost when entering and exiting Prefab editing mode

• Fixed the issue where the large circular cursor was truncated when moving the mouse over the terrain

• Fixed texture compression failures when building certain image formats

• Fixed the potential ineffectiveness of the CLEANUP_IMAGE_CACHE configuration in the build interface

• Removed the invalid "Select All" option for Include Bundles in the parameters of the empty project build panel

• Fixed the issue where small atlases nested inside auto atlas folders were not excluded

• Fixed errors and preview anomalies when starting the editor in an offline/intranet environment

• Fixed the lack of clear error messages when the initial build scene was missing

• Fixed the issue where filling out the development data field in the WeChat build template was ineffective

• Fixed inconsistency between the parameters of the build plugin hook functions onBeforeMake and onAfterMakeand the build options

• Fixed the issue where child nodes were incorrectly assigned during drag selection in the animation editor

• Fixed the issue where the editor would jump to the first clip after editing and saving multiple clips in the animation editor

• Fixed repeated texture compression for the same texture configuration on different platforms

• Fixed the issue where small images used as textures within auto atlases would lose image data after being built

• Fixed potential missing resource dependencies when building Bundles independently

• Fixed layout errors when opening the editor for the first time on a device

• Fixed settings request failure errors when opening the preview page with the editor

• Fixed the issue where the main process error display might lack a complete call stack when launching the editor via command line

• Fixed an error when clearing the import-map path in the project settings that caused the editor to fail on startup

• Fixed incomplete display of console logs in command-line builds on Mac

• Fixed the issue where memory usage would increase when frequently switching the properties panel, especially when switching between multiple MeshRenderer components with added Materials

Known Issues

• If you encounter the Effect compilation error shown in the figure below, or if warnings appear after enabling WebGPU, please re-import all Effects and restart Creator. The re-import button can be found at: Menu -> Developer -> Refresh All Effects.

•  

  

   

  

• XR functionality is not yet supported in the new rendering pipeline.

• The separated engine functionality for Taobao Mini Games is currently experiencing issues; it runs on iOS but not on Android. This needs to be addressed by Taobao's official team. If you need to use the separated engine functionality in the future, please consult Taobao's official support.

Features

Engine

Features

Engine

1.  Added Subpass and MSAA support in the custom render pipeline.

2.  Animation Graph has restored support for AnimationClip (non-skeletal animations).

3.  The script system now supports parsing symbolic links for use with package managers that support symbolic links, such as pnpm.

4.  Added a delay trigger for edge gestures on iOS to prevent accidental touches.

5.  Added 'patch' method support for HTTP requests on native platforms.

6.  Added a default color interface for RichText.

7.  Added materials for piano lacquer, car paint, and glass.

9. Added wasm support for Box2D (Experimetnal)

10. Added Trigger Event for CharacterController, now the CharacterController component and collider support 'onControllerTriggerEnter', 'onControllerTriggerStay' and 'onControllerTriggerExit' events.

11. Added support for dymamically changing the mesh property of MeshCollider.

12. Transitioned to a more stable mesh simplify tool.

13. Supported mesh cluster

14. Supported mesh quantize

15. Supproted mesh encode/decode and inflate/deflate

a. options

b. Improved loading speed and rendering performance for larget scenes.

Editor

1. Added Java Home path settings to preferences to address the issue of multiple JDK installations on deveices during Android builds.

2. Added "Resizeable Activity" and "Max Aspect Ratio" options to the Android build panel.

3. Added support for configuring the launch mode and quick start of the Douyin Developer Tools.

4. Enabled "CLEANUP_IMAGE_CACHE" by default on the WeChat Mini Game platform, for other platforms, it follows the project settings.

5. Added grids, skybox and gizmo to the preview windows of materials, models, meshes, and skeletal animations. It also supports controlling the preview perspective.

6. Added a 3D tool visibility toggle. When turned off, it hides 3D gizmos other than the transform tools.

7. The Inspector now supports dragging to adjust the width of property names.

8. The Inspector now supports displaying icons for certain components.

9. Improved the display of visibility for Light and Camera components in the Inspector.

10. Reduced the number of boost library files to decrease the size of Cocos Creator application.

11. Various optimizations for overall user experience.

Fixes

Engine

1. Fixed rendering errors under specific conditions in the custom pipeline.

2. Fixed the animation graph variants were not working on embedded state machines.

3. Fixed the issue of that after calling the forceLOD mothod, changing node's active not work correctly.

4. Optimized the interaction of the EditText on Android.

5. Fixed potential display errors with EditBox after rotation on web-mobile.

6. Fixed display errors of EditBox when switching between windowed and fullscreen mode.

7. Fixed a crash issue related to multi-touch on Android.

8. Fixed sound playback would not resume after unlocking the screen during playback.

9. Fixed web audio artifacts issue in iOS Safari after playing for more than 5 minutes.

10. Fixed an issue where the player stored in the audioManager could be destroyed.

11. Optimized potential lag issues when performing mutliple audio operations on the same audio object within the same frame.

12. Fixed calling audio play multiple times would cause the progress bar to remain stuck at 0 on Taobao Mini Game.

13. Fixed dragging the progress bar during audio playback would cause it to jump back to 0 on Xiaomi Game.

14. Fixed a memory leak issue on certain mini-game platforms where playing more than 10 audios and continuing to call other audio APIs could lead to memory leaks.

15. Fixed incorrect status retrieval through the isPlaying interface after pausing or ending a videoplayer.

16. Fixed abnormal behavior that may occur when switching video sources.

17. Fixed an issue with swig binding where namespace information was lost when overloading constructor functions.

18. Fixed an exception issue caused by swig binding to multi-level (>= 2) internal classes.

19. Fixed compilation failure of glue code when renaming internal classes in `.i`.

20. Fixed issues with the incorrect implementation of scene._instantiate on native platforms.

21. Fixed crashes or freezes on non-Android platforms caused by repeated calls to `game.restart()`.

22. Fixed display errors in the scene editor when the scale is not 1 for widgets.

23. Fixed a bug in the Button component where, on startup, it would use the Sprite component's spriteFrame to override its own normalSprite. Serialized data from the button component is now used to populate the spriteFrame state.

24. Fixed an issue in ScrollView where the scrolling property remained true after using the mouse scroll.

25. Fixed a bug in scenes with a camera where clicking the mouse would result in an offset.

26. Fixed incorrect resolution after receiving a resize event in OpenHarmony.

27. Fixed a connection issue in OpenHarmony after unchecking WebSocket.

28. Fixed rendering errors in the custom pipeline when mixing Fog, AO, and semi-transparent effects (requires enabling CC_USE_FLOAT_OUTPUT macro).

29. Fixed issues with reflection probe baking and updates during movement, optimizing native engine performance.

30. Fixed switching fog effect types did not affect the skybox.

31. Fixed the default center of a created SphereCollider not set to 0.

32. Now when the move method of CharacterController is called, the physical world position will be synchronized to the node immediately.

33. Fixed a program launch crash issue when compiling iOS projects with Xcode 15.

Editor

1. Fixed a runtime error caused by configuring texture compression for both single textures and the corresponding atlases simultaneously.

2. Fixed the issue where AutoAtlases still included original images after texture compression.

3. Fixed atlases referenced by multiple bundles with consistent priority experienced abnormal texture compression image copying.

4. Fixed duplicate data in Bundle config redirection configurations.

5. Fixed empty Bundles did not output config.json.

6. Fixed text resources in Bundles containing "uuid" caused build errors.

7. Fixed output path in the Bundle build panel could not be selected.

8. Fixed the Build panel could not create new build tasks after building with "Bundle Only" option.

9. Fixed changing the name of a build task could result in a wrong task name when switching build modes.

10. Fixed after implementing a script component in an extension, errors occurred during preview and build due to class dulication.

11. Fixed when enabling first scene sub-packages, scripts and resources output locations might be incorrect.

12. Fixed abnormal data after undoing certain operations on prefabs.

13. Fixed saving failure after referencing a prefab's child node in click events.

14. Fixed losing embedded prefab modifications when dragging a prefab node to Assets window to overwrite its original prefab file.

15. Fixed severval issues during prefab editing.

16. Fixed localStorage could not be debugged in the "Preview in Editor" mode.

17. Fixed FPS setting was not working in the "Preview in Editor" mode.

18. Fixed terrain data become abnormal after opening a prefab then closing while editing terrain.

19. Fixed unexpected behavior after undoing and redoing certain operations while editing terrain.

20. Fixed the "+" icon was not displayed when adding nodes to a node instanced from embedded prefab.

21. Fixed potential errors when configuring the default browser as Safari through the program manager on Mac.

22. Fixed FontAtlas might lose data due to import order.

23. Fixed various issues in the animation editor related to event frames, keyframes, and curve editing.

24. Fixed several interactive issues in the particle curve panel during editing.

25. Fixed issues with dragging and incorrect positioning of event frame icons when editing FBX resources.

26. Fixed inaccuracies in undo operations for the Widget.

Breaking Changes

1. Marked the UIMeshRenderer component as deprecated. Users are encouraged to use RenderTexture for similar functionality. Refer to UIMeshRenderer Component Reference for more details.

2. Users may need to add plane shadow-related passes to their custom Effects, following the structure of effects/legacy/standard.effect in internal resources. Otherwise, dynamic batching for plane shadows may not work as expected. See issue #14958 for more details.

Known issues

1. When an EditBox is displayed at the top of the screen in iOS web, it might be pushed out of the screen by the input method when first gaining focus. If you encouter this issue, refer to the PR for a fix.

Features

Custom Render Pipeline with Post-Processing

Creator 3.x relies on post-processing as the most demanding requirement for 3D games. Before, developers were recommended to use RenderTexture for production but did not provide built-in capabilities. The main reason is that the custom rendering pipeline supporting post-processing still needs to be completed. After the 3.7 Cyberpunk Demo verified the custom rendering pipeline, With Cocos Creator 3.8, we can finally deliver developers anti-aliasing, super-resolution, ambient light occlusion, glare, and other post-processing effects. These post-processing processes are currently integrated into CustomPipeline, on the one hand as an example of RenderGraph. On the other hand, it can also be used as a testing ground for our standard “Forward” pipeline.

1. Anti-aliasing: Provides FXAA with very low power consumption and time based TAA with better quality.

2. Super-resolution FSR: This helps to either achieve higher image quality with lower cost, or reduce the performance pressure while keeping the same resolution.

3. Bloom: Greatly improve the visual quality of your game by enhancing the lighting range of the highlight areas.

4. HBAO: High quality real time ambient occlusion, it can visually improve the sense of space and the rendering quality.
5. Custom Color Grading: This is a very simple but effective post-processing method, which can be used to enhance contrast, saturation, adjust color, white balance, and other image properties. Support any Nx1 bar graph and 8x8 block size. The system automatically adapts to different input format.

Starting from 3.8, we recommend all projects that need post-processing to switch to the Custom Rendering Pipelines, and you can refer to the Full-Screen Post Process documentation to activate it for your project. You can also refer to the example project using post-processing pipeline to learn how to use it.

2D & UI

• High-definition Label: This optimization will upgrade all the Label components in your project to higher resolution automatically. The implementation is to recalculate the actual rendered font size of the Label according to the pixel scaling ratio of the view to obtain a higher resolution text texture. The difference of resolution varies, but it will be much bigger especially on mobile platforms. Besides, 2D renderer refactor have landed in this version, the main goal is to make the 2D renderer adapt to different operating systems and have a relatively unified framework for implementing various components. The implementation of high-definition Label also benefits from this, and it will be easier to expand 3D UI in the future and 2D rendering capabilities in 3D spaces.
  
  
• Use Spine WebAssembly runtime library to replace web library, unify Web & Native runtime and APIs.
• Reduce the initial memory allocation of WebAssembly and allow dynamic expansion of memory.
• Spine now uses WebAssembly to run on Web and WeChat games, significantly optimized performance.
  
  

Rendering algorithm and advanced material updates

1. Skin effects: add simple skin effect and advanced skin effect, example can be found in Character scene of Cocos Example Materials repository.

2. Eyeball effect: add advanced eye effect, example can be found in the same scene as skin effects.

3. Leaf effect: add advanced leaf effect.

4. Supports pre-baked simulation animations exported by Houdini and Zeno: This feature allows developers to integrate high-quality physical simulation animations calculated offline into their projects, including explosion, fluids, cloth, etc. This could be very helpful in making the game narrative scenes or some fixed scenes with great expressiveness, especially for in-app 3D simulations such as car HMI.

a. Zeno

b. Houdini

5. Blending support in Reflection Probes: In previous versions, the movement of dynamic objects between different probe areas will cause jumps. In 3.8, not only the effect mixing between Probes is supported, but also the mixing between Probes and skyboxes is supported. You can get a very natural transition effect in different baking areas and indoor to outdoor scenes.

Procedural animation in Marionette animation system

Pose graph and IK support

We have introduced a new feature to the Marionette animation system: pose graphs. This new feature will provide support for procedural animation as well as dual bone IK animation. Using the pose graph, developers can conveniently define various procedural animations, and action poses through the node system to build more complex and delicate scene interactions. This will also significantly reduce the number of animations users need to create character animations. For example, you can define the IK of a character's feet on different planes, let the character climb terrain at different heights, or look in a particular direction while walking. In addition, the pose graph can also be used as a supplement to the animation state machine, which can be nested in the state machine. For details, see: "Cocos Creator 3.8 Manual - Procedural Animation."

Auxiliary curves support for skeletal animation

When making complex procedurally generated animations, you may need to add variable curves to the animation for logical judgment or as variables. We've added auxiliary curves to the animation editor to meet these needs. You can now add additional curves to any skeletal animation, and once added, these curves can be read and blended in the pose graph and state machine. This new feature will allow greater freedom and help you better control and customize animations.

In addition, the Marionette animation system has the following upgrades:

• The animation state machine removes the experimental transition interruption function and supports multiple transitions instead.
• Numerical conditions of the animation state machine support several different types of conditional bindings: weight binding, animation time binding, and auxiliary curve value binding.
• The hierarchy panel supports dragging to adjust the sorting order.

Physics system updates

1. New CharacterController component: for role-playing and action games, it can significantly reduce the cost of character development and has built-in character control capabilities which can naturally interact with the environment.

2. Constraints: Added ConfigurableConstraint component, which can be used to customize the connection methods of various physical components to achieve complex uni-objects, such as car axles and various joints.
3. Constraints: Hinge constraints add new shaft drive and rotation range restrictions.

4. New sweep collision detection

Lightmap baker updates

• The filter option “Apply Filter” is added to the light map panel, which is used to set the blur effect of the light map, enabled by default.
  

• LightFX supports alpha threshold in builtin standard material.

  
   
  
  
• Shadow saturation also works in LightFX baker
  
  

RenderGraph: infrastructure for custom render pipeline

The customization capability of render pipeline is officially opened to developers in 3.8. It also supports our bultin post-processing capabilities. For the specific usage of the custom render pipeline, please refer to the Custom Render Pipeline, or refer to the custom pipeline examples repository. Some detailed upgrades of RenderGraph in 3.8 are as follows:

• Use RenderGraph to implement the Custom Forward Pipeline with support for all builtin Post-Processing effects.
• Use RenderGraph to implement Custom Deferred Pipeline to optimize the architecture, maintainability, and scalability.
• Add Compute Shader capability.
• Pipeline type is divided into BasicPipeline and Pipeline.
• Pipeline adds the capabilities APIs, which can obtain the graphics capabilities of the current hardware platform.
• Refactored the interfaces of MovePass and CopyPass.

Asset Bundle workflow optimization

Asset Bundle now supports building specified Bundles separately, which allows users to update resources independently, and the function entry is located in the selected Bundle folder settings.

Support for adding filtering options in the Bundle folder settings, allowing users to more flexibly filter the resources in the Bundle that will participate in the actual build.

Optimize the platform setting method of Bundle configuration, support preset format, and facilitate users to manage export options for different platforms accurately.

Note: After upgrading the project to 3.8, Cocos Creator will automatically migrate the Bundle configuration to the project settings. Please submit changes to the project's settings folder and the metafile corresponding to the bundle folder to the project source code library (such as Git) after the upgrade to avoid configuration conflicts.

Build options support only building Bundles.

The Bundle that participates in the construction is supported to be filtered during construction, and all are exported by default.

Workflow optimization for model LOD

In addition to the support for importing LOD models in the previous version, we added support for displaying LOD information in the model and the new LOD automatic generation function so that users can use LOD more efficiently.

Users can directly import any model that does not contain LOD in 3.8 and set different LOD levels in the model import options. Cocos Creator will automatically generate lower LOD levels by reducing the surfaces and automatically add the LOD Group component when creating a model instance in the scene.

Unified workflow for integrating WebAssembly library and more WebAssembly libraries

Starting from 3.8.0, some engine modules have been implemented using wasm, including spine, rendering webGPU backend, physics engine bullet, and PhysX backend. Pay attention to the following when using it:

Package sizes

Platform differences

Future plans for WebAssembly include:

• Optimization of wasm package size by using sub-packages on the mini-game platforms: #15493
• Experimental support for wasm module loading on the project side: #14980
• Integrate third-party WebAssembly support on the iOS platform, relying on the performance result: #15170

Notice:

• If you enable wasm subcontracting on the WeChat platform, please enable the physics wasm option at the same time. Otherwise, it will cause the engine to fail to start. We will provide a fault-tolerant process in 3.8.1
  
• In addition to the WeChat platform, if the engine asm.js subpackage is enabled on other small game platforms, the spine module needs to be checked. We will deal with this problem in 3.8.1, and the fix PR is merged to 3.8.1
• Due to the large size of the physX physical backend, wasm subcontracting is currently not supported

New platform supports

Google Play Games on PC Support

At this year's Google IO conference, Google Play Games on PC and large-screen experience are the Android platform updates that have received great attention. Cocos has also been officially recommended by Google as an engine for Google Play Games on the PC platform and a recommended game engine for a large-screen experience.

Several well known Cocos games has already published on the platform. Starting from v3.8, you only need to check the x86 architecture and the InputSDK option when building Android to meet the platform requirements of Google Play Games on PC. This platform is an important opportunity for Google Play to expand to the desktop platform. Like the continuous emergence of folding screens and tablets, it marks that large-screen adaptation is becoming more and more critical for mobile games, and it can also help developers acquire more users.

OpenHarmony Support

The Cocos engine and the OpenHarmony team have been working closely together for more than two years and have jointly pushed forward the continuous improvement of the OpenHarmony system's support in the gaming industry. Now we are thrilled to announce the official support of the latest OpenHarmony 4.0 version.

Other platform updates

• Support gamepads as an input device on Android.
• Support for customizing the CLEANUP_IMAGE_CACHE macro for a single platform.
• Add Executable Name field for Window/Mac platforms.
  
  
• Android build adds Input SDK integration option
  
• Add CMake Generator / Visual Studio version option for Windows build
  
• Support to execute Make separately through the stage parameter when building on the command line. See "Publish in the Command Line" for details.
• Support Alipay mini game platform, please refer to detailed publish instruction.
• Support XHR on Taobao mini game platform.

Improvements

• We have added the "Fill Vertex Color" option in the model import function. This prevents models that lack vertex color attributes from being blacked out on import. If your material uses vertex color, but the imported model does not have vertex color, or the model is abnormally black when imported, it is recommended that you enable this option.
  
• Automatic atlases can be previewed in the property inspector without clicking save.
• The minimum display time of the interstitial screen will be ignored when the browser previews and the interstitial screen will be closed immediately after the loading is completed.
• Browser preview resolution supports being set to full screen.
  
• The preview server port is adjusted from the global configuration to the local configuration.
• Browser preview and build platform preview support HTTPS protocol to adapt to the security restrictions of some particular environments. This function needs to be enabled in the preview tab of preference settings.
• Support import and export the complete configurations of preferences and project settings.
  

• The program manager of the preference setting supports configuring the default image editor.

• The default design resolution of newly created projects has been adjusted from the 960x640 to 1280x720

• Hierarchy manager supports using the shortcut keys [ or ] to move nodes up and down. If you press Ctrl / Command at the same time, it will be the top/bottom node.

• When you open the preferences, project settings, animation graph, and other panels, they will be displayed at the location of the scene editor by default

• The @menu decorator of the component supports the use of menu paths, for example:
  
  The corresponding component menu is displayed as follows: 

  

   

   

• Add `EDITOR_NOT_IN_PREVIEW` macro, which is used to simplify the judgment of various plug-ins and debugging codes on the editor's operating environment. If it is true, it means that the code is executed in the editor and the scene is not in the preview state. Example:
  
  
  
• Optimize the gradient color editor, support input of hexadecimal color value (Hex Color).
• By default, standalone graphics cards are used first on computers with both standalone graphics card and builtin graphics card in CPU (like Intel IRIS).
• Optimized the user experience of various editor items.

Fixes

Engine

Editor

• Fix some problems with undo and redo, improve the stability of Undo system
• Fix the problem that two interstitial screens will be displayed at the same time on the WeChat mini-game and the iOS platform
• Fix the problem that the build may be stuck when resources are circularly dependent
• Fix the problem that the build will fail when the game name on the Android platform contains Chinese
• Fix the problem that the game name on the native platform is not verified
• Fix the problem that the script may be lost when starting the editor
• Fix the problem that the layer will become the layer of the parent node when cloning a node
• Fix the problem that there is no prompt to save when switching scenes when setting the active state of the node
• Fix the related problems of nested prefabs
• Fix the problem that the data is not cleared after the prefab rewrite attribute information becomes invalid
• Fix object reference related issues of prefabs
• Fixed the problem that the pasted 2D components were not displayed correctly in prefab editing
• Fix the problem that other bounding boxes are affected when the physical bounding box is modified
• Fix `resetInEditor` not being called in the editor
• Fix the problem that the environment reflection is dark after using the reflection probe
• Fix the problem that the effect of plane reflection is not correct when it is not horizontal
• Fix radiosity error for baked GI materials
• Fix the problem that the model may not be visible when using the surface reduction algorithm to reduce the surface of the imported model
• Fix the problem that keyboard and mouse event support is incomplete when the editor is previewing
• Fix the problem that an error may be reported when deleting resources in batches
• Fix other editor-related issues

Breaking Changes

• Required Gradle is upgraded to 8.0.2, and AGP is upgraded to 8.0.2. JDK needs to be upgraded to JDK 17. At the same time, required Android Studio is upgraded to 2022.2.1.
• Adjustment of underlying logic of text, users who want to deeply customize label component capabilities to the assembler layer need to migrate customization capabilities to TextProcessing, which doesn't affect the visual effect.
• High-definition text: Since the text textures generated by each platform are not exactly the same, there may be a rendering difference of 1-2 pixels from the previous version.

Known Issues

• Android Instant App running on the Android Studio Flamingo | 2022.2.1 Patch 2 version may have unresponsive problems, it is recommended to consider carefully before upgrading.
• RichText with a length greater than 2048 may have irregular line breaks on some platforms, the behavior will be adjusted and optimized in subsequent versions.

Fixes

Engine

• Fixed the error caused by re-playing a destroyed web-audio. #15235
• Fixed the problem of inability to disable Physics2D Contact. #15224
• Unlocked the lock of UITransform on Spine. The new mechanism sets the ContentSize and AnchorPoint based on the resource settings when changing SkeletonData, allowing users to customize as needed. #15240
• Taobao Mini Game: Re-adapted XMLHttpRequest using my.tb.request  #15238
• Fixed the issue of windows becoming ineffective when switching between screens on Mac.  #15247

Editor

• Fixed the slow startup of the Preview in Editor function. #15214
• Fixed the errors reported in the debug tool after undo/redo the operation of adding nodes to a prefab. #15256
• Fixed the potential crash during build when the plist atlas in a Bundle contains a large number of small images.
• Fixed the potential freeze or crash during build caused by self-referencing resources.
• Fixed the issue of inconsistent MD5 generated for the assets on Windows and Mac platforms when build to Taobao Mini Game with the TaoBao Engine Plugin option checked.
• Fixed the issue of invalidation of compressed texture cache for Auto Atlas during build.
• Fixed the inconsistency of attributes between the Inspector and the Animation Editor panel when the WrapMode on the Animation Editor is set to Reverse, LoopReverse and PingPongReverse.

Scripting

• Fixed the issue where compiling the engine would cause Cocos Creator to fail to start.
• Fixed the problem where scripts may be lost due to process conflicts when launching Cocos Creator.
• Fixed the issue where building with generic classes may result in an error of "Unknown node type: 'TSInstantiationExpression'".

Features

Engine 

Features

Engine 

• Add a runtime control panel for Rendering Debug View.
  
  refer to https://docs.cocos.com/creator/manual/en/shader/surface-shader.html
• Add a 'destroySelf' method to the tween for destroying the current node when it is tweening.
• Skip rendering when the UI element opacity is 0.
• Reduce GFX Buffer memory consumption of WeChat mini-games in iOS 14 high performance mode.

Editor

• Supports baking high-precision lightmaps for better baking results. When turned on, 16-bit colors will be used instead of the original 8-bit colors, and AO will be baked separately. This feature can be used to solve the problem of color spots caused by the lack of mapping accuracy when the light intensity is too high, but the disadvantage is that it will increase the storage and memory usage of the lighting map.
  
  High-precision lightmaps OFF vs. ON:

• Add light probe baking preview to improve debugging efficiency. When an object affected by light probes is selected, the probes affecting the object are displayed in the scene, as well as the baking results used to estimate the light information of the object are displayed on the probe sphere.
  
  
• Support baking the AO (Ambient Occlusion) channel separately.
• The Project Settings panel allows you to set the default open scene to avoid other users only seeing empty scenes when opening the current project for the first time.
• Support for main.js build templates on native platforms.
• New feature to display nodes that missing assets in Hierarchy Manager.
  

• Support for dragging Prefab to multiple nodes selected in the hierarchy and generating child for each selected node using the Prefab.
• Editor Improvements
• Move Light Baking from the Project Settings menu to the Panel menu
• Use the Surface Shader as buildin-standard.effect.
• When the Debug option is not selected in the build panel, Android Studio will take the Release configuration.
• Adjusted contents of internal/effects directory (does not affect existing projects) 
• Added Tooltip for frequently used material parameters
• Optimized the parameters of the scroll wheel/touchpad to improve the roaming experience in the scene editor.
• Optimize the search functionality of Extension Manager, now you can search for Official Extensions, Built-in Extensions and Installed Extensions at the same time.
• Supports for selecting the next node with a single click when using the Rect Gizmo tool in Scene Editor .
• Improved the experience of setting Skybox Envmap.

Fixes

Engine

• Normatived implementation of normalize & angle in the math library.
• Fixed the problem of incomplete display of iPad screen on Bytedance platform.
• Fixed the problem that facebook instant games could not be launched in some cases.
• Fixed the issue of touch sorting was not updated synchronously when updating the sibilingIndex of a node.
• Fixed the issue where Mat4.getRotation may calculate incorrect results.
• Fixed a color exception in the CHAR mode of Label component on native platforms.
• Fixed a memory leak that could be caused by 2D modules in some cases.
• Fixed the problem that incorrect calculation of LOD screen-to-body ratio on native platforms.
• Fixed an issue where Mesh objects created with MeshUtils.createMesh could cause an exception.
• Fixed the issue where sevalue_to_native conversion for std::function<...> does not support null/undefined.
• Editor
• Fixed an issue that prevented cross-project reuse of bundle scripts due to their dependency on import-map.
• Fixed the problem that the project script in the extension cannot be loaded in the simulator.
• Fixed the problem that importing plugin scripts over 500KB will report an error.
• Fixed the problem that the texture compression configuration of AutoAtlas does not work.
• Fixed the problem that custom texture compression configuration does not work.
• Fixed an issue where the engine module configuration could be restored after upgrading a project to 3.7.
• Fixed the problem that the custom first screen template file on WeChat mini-game does not work.
• Fixed an occasional resource loss when building from the command line.
• Fixed the issue that building JSON groups may result in slow build process.
• Fixed the issue that the main light still lights on the terrain after baking.
• Fixed preview and data update issues related to light probes and reflection probes.
• Fixed the problem that the mouse and touch events are triggered several times and the left and right mouse buttons are not recognized when previewing in the editor.
• Fixed the problem that tween color would report an error when previewing in the editor.
• Fixed the problem that an error may be reported when exiting from the Preview in Editor mode.
• Fixed the problem that some properties in the particle curve panel do not show negative axes.
• Fixed the problem that the keyframe data is not refreshed after creating or switching animation clips in the animation editor.
• Fixed the problem that the animation editor reports an error after cropping the 3D module.
• Fixed the problem that the material rendering in the scene is not reverted when the material modification is cancelled.
• Fixed the problem that deleting a node with child nodes and then undoing it in Prefab editing mode will cause an error.
• Fixed the issue where the resetInEditor lifecycle function of a component is not being called by the editor.
• Fixed other miscellaneous issues.

Features

Engine

• Add more API docs (engine#13937, engine#14079, engine#14088)
• [Optimize] add image asset’s zh i18n (engine#14108)
• [Optimize] Add pointerlock function for mac platform (engine#14187)
• [Pipeline] enable custom pipeline in the editor (engine#14084)
• [Pipeline] add native pipeline ubo uploading (engine#14061)
• [Pipeline] Fix web-pipeline ui in post-processing (engine#14145)
• [Pipeline] Disable over-aligned memory allocation (engine#14164)
• [Pipeline] Refactored web profiler and native framebuffer (engine#14168)
• [Pipeline] Refactored custom-pipeline initialization (engine#14176)
• [Pipeline] Fix memory leak of pipeline JS binding objects (engine#14190)
• [Pipeline] Resource states & fgd signal split end barrier (engine#14207)
• [Pipeline] Fixed transparent pass barrier issue (engine#14218)
• [XR] AR engine module update

Editor

• Support direct lighting of Light Probe directional light
• Open more Mesh surface reduction parameters in FBX import items to obtain better surface reduction effects
  
  

Fixes

Engine

• Fix shadowmap lowp with huawei and reflection probe brightness (engine#14058)
• Fix shader compilation error with the new version of lightmap (engine#14071)
• Fix unsynchronized model data issue when adding lod levels dynamically (engine#14054)
• Fix the issue that lod is not working properly when forced to use certain levels (engine#14055)
• [Physics-2d] Fix box2d syncRotationToPhysics’s euler angle calculation issue (engine#14048)

Editor

• Fix the discarded gltfpack surface reduction algorithm in the model surface reduction configuration is invalid
• Fixed the event editing panel of the animation editor to display abnormally
• Fix the problem that the default image import type in Preferences (Preferences - AssetDB - Default import image type) fails after restart #14176
• Fix the problem that the configuration of the Preferences - Program Manager may be invalid after upgrading to 3.7
• Fixed the problem that some 3D physics backend configurations did not take effect in the editor preview
• Fixed the problem of inaccurate scene clicking on Windows devices with DPI exceeding 2
• Fixed the abnormal gizmo display caused by the camera FOV setting of the scene editor
• Fix the problem that UI_2D may not be selected for a layer when creating a new Canvas node
• Fix Lightmap spotlight rendering error
• Fix the problem that the custom texture compression tool does not support the relative path of the project
• Fix the problem that the result.settings obtained by the build plug-in is invalid
• Fix the problem that when the application.ejs template is used for building, the build result has an extra application.ejs file

Cocos Creator 3.7.0 is another milestone on our path of constantly challenging and improving ourselves. In order to support a larger, and more realistic 3D world, we have made improvements in rendering effects, global illumination, LOD, animation systems, physics systems, and performance in this version. There are large numbers of updates in V3.7.0, so only important ones are listed here. You can also view the update list in our GitHub repository: GitHub update list.

Rendering

Light probes

For a more realistic 3D world, global illumination on dynamic objects is needed. Unlike lightmaps that only support indirect light baking on static objects, light probes are used to apply indirect lighting on characters or other dynamic objects. Light probes capture light information in the space first, and then apply the approximation on the dynamic objects. This approach has advantages of good processing performance at runtime and fast precomputation. For more details, please read our document: Light Probe.

Characters with light probes:

Spheres using light probes with instancing:

Light probes editing:

Reflection probe

Another technique we introduced in 3.7 to improve rendering result is reflection probe. Especially for the scenes with reflective materials, reflection probe improves the immersive feeling dramatically. Reflection probes take a baked result of the nearby environment from a certain point, and store a texture of the surrounding environment. Then apply this texture on the objects that have reflective materials to achieve a realistic look. There are two modes: a cube mode that requires baking of the surroundings, and a live planar reflection mode used mainly for planar surfaces like floors and water. For more details, please read our document: Reflection Probe.

Level of Details (LOD)

Level of Details (LOD) is a technique that reduces the number of GPU operations needed to render distant meshes. LOD is a common way to improve the performance of large scenes by adjusting the precision for models according to their proportion on the screen. It saves rendering resources by displaying low precision resources when objects are far from the camera. When a node uses LOD, the engine would display the appropriate LOD level based on the screen size . For more details, please read our document: Level of Details.

CSM layer transition

The purpose of CSM is to use different shadow resolutions for different layers. A problem this leads to is that the layer switching point could be easy to spot and it makes the shadow looks unnatural. In 3.7, we added support for a smooth blend transition between layers, so CSM layers switching looks more natural.

Post effects：Bloom & FXAA

We introduced Bloom post effect and FXAA on the new customized render pipeline that based on RenderGraph. Unlike the old render pipeline which is hard to customize, the new one is designed for users to customize and expand features easily. Adding post effects like Bloom is never been this easy as well.

Editor

Native engine for the Editor (experimental)

We support native engine for the scene editor in V3.7.0, scene editor can run with the C++ based Windows/Mac native Cocos engine instead of JS/WebGL based HTML5 engine now. This means scene editor's performance can improve to the next level with native advantages. It better prepares users for the larger 3D world. This feature currently is in experimental stage. You can turn it on with the option "Use native engine for scene editor" at menu Preferences - Laboratory. After it is turned on, you can preview and debug with multiple native viewport.

All-new extension manager

We updated extension manager in V3.7.0. This all-new extension manager added support for extensions hot update, Project dependencies auto install, improved UI, and update version selection. It makes project distribution and extension management easier.

For better version control, we updated some rules for extension management:

1. No longer reading global extensions from global folder. For projects on older versions, it would automatically copy all the global extensions into the project on update time. This migration feature is supported with Dashboard 1.2.4. Please make sure Dashboard is automatically updated to the version 1.2.4 before the project update.
2. Project's extension dependencies would be recorded. If a project is opened from Dashboard version 1.2.4 or above, dependencies would be installed automatically. For now, only official extensions are supported, extension from store will be supported in later versions.
3. For extensions that is under development, users can use the Developer Import button to create soft links for external extensions which are under development. This feature allows extension developers to use an external extension directly without copying them to the project.
4. If you need to share extensions from the store, it is the same as previous version. Users need to install extension manually on a different device, or upload extensions to GitHub.

Splash settings update

Splash settings are used to display Cocos or your brand's logo during the game initiation time. At the same time, we optimized the first screen loading time to improve user experience. From version 3.7, we started to renew some previously under maintained features based on the users' feedbacks, such as Splash settings. Here are the main updates:

• Temporary removed the user questionnaire interface, users can switch on/off for the splash display.
• Removed splash background color setting. Currently it only support black.
• Minimum display time for splash updated to 500ms

Project setting interface:

Building interface:

Resource management

• Support compressed textures to use Mipmaps. After the option is turned on, the editor would automatically generate mipmaps with compressed textures, and then export at the same time.
• Added support for the .exr image format.
• Support green channel flip config option for the image assets.
  
  
• After moving or renaming the ts script in the editor's explorer, editor would automatically updates the import path now. To enable this function, please enable this switch in the Laboratory section of Preferences.
  
  
• Added new mesh optimizer face reduction algorithm: simplify. New algorithm does not change prefab structures, and improved face reduction result for fbx.
  
  

Mesh UV inspector

In 3.7, users can inspect UV for different channels in the property inspector. Now you can just simply select the imported mesh to inspect uv channels to see weather it is within (0,1) space or if it has overlap.

Framework

Marionette animation system

• Added a new animation asset type: animation variants, it enables the reuse of the same animation graph on different characters.
  

• Introduced improved animation state machine 2D blend preview panel
  
  
• Animation state machine now supports node copy feature.
• Class AnimationController added a method to dynamically overwrite animation clips in the animation map.
• Class AnimationController added a method to query the number of layers in the animation map.
• Animation diagram editor: add a right-click menu to change the motion state to sub-statemachine state
• Fixed and optimized some status query method

Particles system performance optimization

Updated CurveRange building logic, deferred building curve data, and optimized internal decorators to improve particles system initialization speed.

3.7 and 3.6 Particles initialization speed compare (The shorter, the faster, and more modules the particles use, the more time it saves in 3.7).

Other performance optimization

Besides the improvement on performance of the particles system, we also improved performance for other modules, such as those listed below:

Note: In the the performance testing result graphs below, we increased the load for each platform step by step during the testing. Different platforms might have a different load increase step. The performance result shows in frames per second, therefore, higher value means better performance.

1. Frame animation
   
   
2. 3D model rendering
   
   
3. 3D physics
   
   

3D Physics

• Added fixed constraints to the physical system.
• Updated PhysX backend implementation for Point2point constraints to use SphericalJoint.
• Added lineStripCast support for Physical system.
  
  
• Default physics Material can be set through file in project setting now.
• Fixed the problem that bullet rigid-body cannot set to Sleep.
• Optimized bullet MeshCollider setMesh func to run x100 faster.
• Fixed bullet safe delete bug.
• Added machenism to dynamically set the convex property of the MeshCollider after rigid body generation become ineffective.
• Unify the zoom behavior for cylinder collider and cone collider on each physics backend.
• Fixed the problem that PhysX native backend sometimes pollutes with large number of error events.

2D Physics

• box2d shape-2d apply() now take consideration of node/collider status.
• box2d syncRotationToPhysics uses rotation from scene node's world quat.
• Fixed box2d shape aabb not accurate.
• Fixed box2d joint2d anglelimit conversion from degree to radian.
• Fixed physics2d-builtin shape sets group order. Now it first check collider then addShape.
• Optimized Physics2d Box2d::syncSceneToPhysics().
• Optimized builtin-2d-physics removeShape() speed.
• Added new polygon partition algorithm: Hertel Mehlhorn.
• Made world origin as physics-2d joint's connected body.
• Physics-2d now supports switching back-end in EDITOR.

More

• 【Scene Rendering】Added sorting component and provided sorting layer order editing interface. Users can use this component to control the rendering order of MeshRenderer or SpriteRenderer.
• 【Scene Rendering】Added FXAA HQ to fix shadows under objects in some cases.
• 【Scene Rendering】Optimized render associated default settings, such as PBR materials default values, default skybox, and skylight direction.
• 【Create Project】Added a new High Quality 3D template, with shadows and fine lighting options default on to achieve better render quality. Save the time of setting different shadow and lighting options on the scene, lights, and objects.
  
  
• 【Build】Support building and publishing on a new platform: Facebook Instant Games. For destails, please check: 《Release game to Facebook Instant Games》.
• 【Build】WeChat games supports high performance mode now.
  
  
• 【Build】Support interrupting a build task by clicking the "x" button during the build process.
• 【Build】Support build task queuing.
• 【Scene Edit】Added scaling properties for the reference image.
• 【Scene Edit】Added more exposure related properties to the scene camera.
  
  
• 【Editor】Added more exposure related properties to the scene camera.
  
  
• 【Editor】Support multi selection edit for asset folders
• 【Editor】Moved physics configuration in project settings to physics material. Old configuration will be automatically generated as custom physics material.
• 【Editor】Moved joint texture layout to project settings
• 【Editor】Moved build extension generation case to create extension panel. After click on the create extension menu item, users need to fill the template and other settings in the panel.
  
  
• 【Framework Ability】Added new “Mobility” property for scene node.
  
  
  • Static: The renderer views a static node as an object or light that would not move. It only participates in static light baking with direct and indirect light.
  • Stationary：The renderer views a stationary node as a object or light would not move. An light source with "stationary" setting participates only indirect light baking. Direct light are still calculate during the runtime.
  • Movable: The renderer views a movable node as a object or light would move over the runtime. It only affected by dynamic lighting.
• 【Framework Ability】Optimized the layout refreshing logic. Removed the condition that a layout must have children to be refreshed.
• 【Native Framework】Switch to swig to generate JS bindings code, the old bindings-generator tool is now deprecated. The time cost of generating all JS bindings code is reduced to 3~5 seconds.
• 【Native Framework】Optimized construction and destruction of se::Object, removed unused hash operations.
• 【Native Framework】Added se::Object:createObjectWithConstructor method to create JS objects via JS constructor in CPP code.
• 【Native Framework】Support passing command-line arguments to executable files on local desktop platforms (Windows, Linux, macOS).
• 【Native Framework】Added support for se::Object to create, modify and check ES6 Map/Set.
• 【Native Framework】Provided cc::event::EventBus and cc::event::EventTarget to simplify event scheduling within the engine.
• 【Native Framework】Removed the BaseNode class and use the Node class instead.
• 【Native Framework】Downloader supports abort function.
• 【Native Framework】Support for ios websocketServer.
• 【Native Framework】Added network module to function-corpping.
• 【Native Framework】Added pretype validator for setUniform.
• 【Native Framework】Optimized engine package size.
• 【Documentation】Complete some missing API documentation and optimize API documentation content.

In version 3.6.3, we have added support for the Taobao mini program platform and also fixed a series of critical bugs, so we strongly recommend all 3.6 users to upgrade.

Features

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. 

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:

AutoGen Mipmaps 

GGX Convolution 

GGX vs. Dir vs. Mip 

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

Surface Snapping (Press and hold ctrl/cmd + shift) 

Vertex Snapping (Press and hold v) 

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.

Blender | Material Conversion Off | Material Conversion On 

Convert Phong materials from FBX 

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.

Features

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)

Features

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)

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!

Features

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.

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

Features

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

Features

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

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

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

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

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

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

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.

Features

• 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

Fixes

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

Features

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:

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.

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.

Features

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:

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

• Optimized rendering pipeline to reduce IO pressure
• Optimize the experience of using large projects: reduce the memory usage of the editor, avoid crashes, and optimize lag
• Optimize the standard lighting model
• Animation data reconstruction and upgrade: prepare for the animation system upgrade and animation state machine
• The physical behavior of each back-end is unified
• 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.

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.

Features

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

Features

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

Features

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