重要更新
Marionette 动画系统
在 v3.4 版本中我们带来了支持复杂角色动画的动画系统 Marionette,支持动画状态机和多维混合等功能。在 v3.5 中,我们继续向其中添加了不可或缺的关键能力:层级和遮罩。这可以让开发者轻松做出更复杂的动作系统,比如下面展示的上下半身分离。

2D 项目体验优化
对于 2D 用户和 2D 项目开发,我们做了一些编辑器的体验增强,这也是为了帮助有升级需求的 2.x 开发者更好得升级上来,获得与 2.x 类似的体验。从 3.0 发布以来,我们一直在通过各项性能和体验优化积极推动开发者的升级,并且还会持续优化下去。在 v3.5 中,你将可以看到下面的一些体验优化:
- 所有 2D 项目创建出的场景都会默认包含 Canvas 和一个正交投影的 2D Camera,不会包含 3D Camera
- 默认的 2D 场景会默认使用 2D 场景视图
- 一部分属性面板,比如节点,也会支持 2D 视图
- 所有 3D 模块被默认剪裁了,并且在添加组件列表和节点创建列表中也不会包含 3D 相关的组件和节点
- 如果你的 2D 项目中需要使用 3D 能力,只需要在项目配置中将 3D 模块添加上即可

Frame Pacing Library (Swappy)
Cocos 和 Google 在 Android 移动平台上一直以来都有非常紧密的合作,Android 也是我们最重要的平台之一。我们很高兴宣布在 v3.5 引擎中加入了Frame Pacing Library。它是 Android Game Development Kit (AGDK) 的一部分,主要用于帮助游戏平滑和稳定帧率,对 OpenGL 或 Vulkan 后端都适用。你可以在 Android 构建面板中启用 Swappy 来开启此功能。

基础几何渲染 Geometry Renderer
我们在此版本中引入了一个新的简易几何渲染的 API,这些 API 是为了绕过组件层,直接在屏幕上渲染一些用于调试的标记几何体。目前已支持线条、盒子、球体、多边形等几何体,渲染模式支持线框模式、填充模式,一部分几何体也可以动态开启光照和深度测试。所有几何体的坐标系在世界空间,并且支持 transform。

更详细的几何体信息请参考下面的表格

材质编辑体验优化
在过去几个版本中,我们一直在修正和提升渲染表现,同时,我们也在关注美术侧的 DCC 内容生产工作流。在 v3.5 中会有一部分材质体验的优化交付给大家:
- 当一个 FBX/GLTF 资源被导入后,如果需要修改材质,你不再需要 dump material 然后在复制后的材质中修改,你可以直接在导入的材质上修改。
- 当你修改材质时,新版本将支持 undo / redo 操作。
- 当你在编辑材质时切换 effect,不同 effect 之间匹配的属性值会被缓存并迁移,比如 'mainTexture' 的贴图资源,如果在不同 effect 中都包含就会自动维持。

同时敬请期待我们后续版本中更显著的美术体验优化。
地形的抹平画刷和高度设置
地形编辑器在新版本中提供了新的抹平和高度画刷,可以让开发者们更方便得编辑平面地貌。

平台抽象层 Platform Abstraction Layer
从 v3.5 开始,我们将所有平台层相关的底层适配代码集合到了 PAL 模块中,包括系统信息、窗口适配、音频、输入系统等。系统层的事件派发行为也被统一了。这是一个底层重构,用户层 API 不会收到影响,但这次重构会让 Cocos Creator 未来有能力更轻松得适配新的平台和环境。
性能优化
此版本中比较显著的性能优化包含以下几点:
- Spine 和 Dragonbones 在原生平台通过共享内存避免了 C++ 向 JS 拷贝数据,对原生平台性能有一定的提升。
- 优化了 RealCurve 和 CurveRange 的内存占用。
- 大幅度优化了粒子系统的反序列化性能。
- 在 Android 平台使用 okhttp 来实现 WebSocket 模块以降低功耗并提升性能。
- 通过减少原生对 JS 的调用次数来提升 Label 和 Graphics 的渲染性能。
新的 API 文档设计
对于之前的 API 文档体验社区用户多有吐槽,也让引擎的新人上手门槛和学习曲线抖升。为了解决这个至关重要的问题,我们重新设计了 API 文档的组织方式和界面设计,大家可以访问我们 新的 API 文档链接 来体验。当然,这只是一个开始,我们也希望大家继续反馈建议帮助我们持续改善文档的体验。
引擎仓库和自定义引擎升级
为了更好服务开源社区,我们将原生引擎仓库合并到了 engine 仓库中,并且迁移到 cocos/cocos-engine,从现在开始,我们将通过公开 issues 和 公开 projects 向开源社区同步我们的后续计划。如果你正在使用自定义引擎,那么这个修改对你的影响会比较大,从 v3.5 开始,自定义引擎只需要克隆 engine 仓库即可。所有以前在 TS 引擎仓库的修改可以直接 rebase 到 v3.5 分支,但是以前在 engine-native 仓库的修改需要手动应用到 engine 仓库的 native 目录下。详细信息可以参考自定义引擎文档。
破坏性更新
- [FIX] Fix dragonbones/spine sockets transform (engine#10260)
从 v3.5 开始,请避免向 sp.Skeleton 或 dragonBones.ArmatureDisplay 的 sockets 挂件 target 设置已在使用的节点,否则这个节点的变换矩阵会被覆盖。正确的方法是创建一个新的空节点并设置为 socket target,详细信息可以参考 Spine 挂件文档。
- 从 v3.5 开始引擎将支持模型级别阴影偏移(Shadow bias),这将使得阴影效果更容易适配不同模型的表面。如果你的项目中包含自定义材质,请参考升级文档来应用这个配置。
- Effect 资源中关于 Macro Tags 和 Functional Macros 的语法得到了升级,避免了占用 glsl 的标准 define 语法,旧项目中的 Effect 资源在升级过程中会被自动升级。但如果你从外部直接复制旧版本的 Effect 资源或写新的 Effect 资源时,请注意语法方面的变化:
- Macro Tag 的新语法:`#pragma define-meta`
- Funtional Macro 的新语法:`#pragma define`
已知问题
- 在 iOS 15.4 中,Safari 中默认开启了 “WebGL via Metal” 这项实验性功能,这将会导致部分项目出现渲染问题(画面不刷新或部分刷新,错误的图块等)。一般在开启了 `ENABLE_WEBGL_ANTIALIAS` 的情况下,并且使用了离屏 FrameBuffer 并对其采样,会触发此问题。临时解决方案是在项目配置中关闭 `ENABLE_WEBGL_ANTIALIAS`,此问题暂无根本性的修复方案,很可能会在新的 iOS 版本中得到修复。
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)