Merge remote-tracking branch 'cocos-for-editor/v3.5.2' into merge3.5

# Conflicts:
#	cocos/core/components/renderer.ts
#	cocos/core/global-exports.ts
#	cocos/core/renderer/core/render-scene.ts
#	cocos/core/renderer/core/render-window.ts
#	cocos/core/renderer/scene/index.ts
#	cocos/core/root.ts
#	cocos/core/scene-graph/scene-globals.ts
#	package.json

cocos/2d/framework/ui-renderer.ts

@@ -128,9 +128,6 @@ export class UIRenderer extends Renderer {
      */
     public static PostAssembler: IAssemblerManager | null = null;
 
-    @override
-    protected _materials: (Material | null)[] = [];
-
     @override
     @visible(false)
     get sharedMaterials () {
@@ -152,9 +149,6 @@ export class UIRenderer extends Renderer {
         }
     }
 
-    @type(Material)
-    protected _customMaterial: Material| null = null;
-
     /**
      * @en The customMaterial
      * @zh 用户自定材质
@@ -194,11 +188,31 @@ export class UIRenderer extends Renderer {
         }
     }
 
+    /**
+     * @internal
+     */
     get renderData () {
         return this._renderData;
     }
 
+    /**
+     * @internal
+     */
+    get blendHash () {
+        return this._blendHash;
+    }
+
+    /**
+     * @internal
+     */
+    get useVertexOpacity () {
+        return this._useVertexOpacity;
+    }
+
     // Render data can be submitted even if it is not on the node tree
+    /**
+     * @internal
+     */
     set delegateSrc (value: Node) {
         this._delegateSrc = value;
     }
@@ -209,6 +223,11 @@ export class UIRenderer extends Renderer {
      */
     public stencilStage : Stage = Stage.DISABLED;
 
+    @override
+    protected _materials: (Material | null)[] = [];
+    @type(Material)
+    protected _customMaterial: Material| null = null;
+
     @serializable
     protected _srcBlendFactor = BlendFactor.SRC_ALPHA;
     @serializable
@@ -222,32 +241,18 @@ export class UIRenderer extends Renderer {
     protected _renderDataFlag = true;
     protected _renderFlag = true;
 
-    // 特殊渲染节点，给一些不在节点树上的组件做依赖渲染（例如 mask 组件内置两个 graphics 来渲染）
+    // Special delegate node for the renderer component, it allows standalone component to be rendered as if it's attached to the delegate node
+    // It's used by graphics stencil component in Mask
     protected _delegateSrc: Node | null = null;
     protected _instanceMaterialType = -1;
     protected _blendState: BlendState = new BlendState();
     protected _blendHash = 0;
 
-    /**
-     * TODO mark internal
-     */
-    get blendHash () {
-        return this._blendHash;
-    }
-
     /**
      * @en Marks for calculating opacity per vertex
      * @zh 标记组件是否逐顶点计算透明度
      */
     protected _useVertexOpacity = false;
-    get useVertexOpacity () {
-        return this._useVertexOpacity;
-    }
-
-    public updateBlendHash () {
-        const dst = this._blendState.targets[0].blendDst << 4;
-        this._blendHash = dst | this._blendState.targets[0].blendSrc;
-    }
 
     protected _lastParent: Node | null = null;
 
@@ -297,6 +302,15 @@ export class UIRenderer extends Renderer {
         }
     }
 
+    /**
+     * @en Update the hash for the blend states.
+     * @zh 更新混合模式的哈希值标记
+     */
+    public updateBlendHash () {
+        const dst = this._blendState.targets[0].blendDst << 4;
+        this._blendHash = dst | this._blendState.targets[0].blendSrc;
+    }
+
     /**
      * @en Marks the render data of the current component as modified so that the render data is recalculated.
      * @zh 标记当前组件的渲染数据为已修改状态，这样渲染数据才会重新计算。

cocos/2d/renderer/vertex-format.ts

@@ -26,28 +26,68 @@
 import { AttributeName, Format, FormatInfos, Attribute } from '../../core/gfx';
 import { legacyCC } from '../../core/global-exports';
 
+/**
+ * @en Vertex format with vector 3 position attribute
+ * @zh 包含三维位置属性的顶点格式
+ */
 export const vfmt = [
     new Attribute(AttributeName.ATTR_POSITION, Format.RGB32F),
 ];
 
+/**
+ * @en Vertex format with the following layout
+ * 1. Vector 3 position attribute (Float32)
+ * 2. Vector 4 color attribute (Float32)
+ * @zh 包含以下数据的顶点格式
+ * 1. 三维位置属性（Float32）
+ * 2. RGBA 颜色属性（Float32）
+ */
 export const vfmtPosColor = [
     new Attribute(AttributeName.ATTR_POSITION, Format.RGB32F),
     new Attribute(AttributeName.ATTR_COLOR, Format.RGBA32F),
 ];
 
+/**
+ * @en Vertex format with the following layout
+ * 1. Vector 3 position attribute (Float32)
+ * 2. Vector 2 uv attribute (Float32)
+ * 3. Vector 4 color attribute (Float32)
+ * @zh 包含以下数据的顶点格式
+ * 1. 三维位置属性（Float32）
+ * 2. 二维贴图 UV 属性（Float32）
+ * 3. RGBA 颜色属性（Float32）
+ */
 export const vfmtPosUvColor = [
     new Attribute(AttributeName.ATTR_POSITION, Format.RGB32F),
     new Attribute(AttributeName.ATTR_TEX_COORD, Format.RG32F),
     new Attribute(AttributeName.ATTR_COLOR, Format.RGBA32F),
 ];
 
+/**
+ * @en Vertex format with the following layout
+ * 1. Vector 3 position attribute (Float32)
+ * 2. Vector 2 uv attribute (Float32)
+ * 3. First vector 4 color attribute (Float32)
+ * 4. Second vector 4 color attribute (Float32)
+ * @zh 包含以下数据的顶点格式
+ * 1. 三维位置属性（Float32）
+ * 2. 二维贴图 UV 属性（Float32）
+ * 3. 第一套 RGBA 颜色属性（Float32）
+ * 3. 第二套 RGBA 颜色属性（Float32）
+ */
 export const vfmtPosUvTwoColor = [
     new Attribute(AttributeName.ATTR_POSITION, Format.RGB32F),
     new Attribute(AttributeName.ATTR_TEX_COORD, Format.RG32F),
     new Attribute(AttributeName.ATTR_COLOR, Format.RGBA32F),
     new Attribute(AttributeName.ATTR_COLOR2, Format.RGBA32F),
 ];
 
+/**
+ * @en Get total components count for all attributes per vertex.
+ * @zh 获取每个顶点上所有属性的分量数总和
+ * @param attrs All attributes of the vertex format
+ * @returns Total components count
+ */
 export function getComponentPerVertex (attrs: Attribute[]) {
     let count = 0;
     for (let i = 0; i < attrs.length; i++) {
@@ -59,6 +99,12 @@ export function getComponentPerVertex (attrs: Attribute[]) {
     return count;
 }
 
+/**
+ * @en Get total stride for all attributes per vertex.
+ * @zh 获取每个顶点上所有属性的总步进
+ * @param attrs All attributes of the vertex format
+ * @returns Total stride
+ */
 export function getAttributeStride (attrs: Attribute[]) {
     let count = 0;
     for (let i = 0; i < attrs.length; i++) {

cocos/3d/lights/light-component.ts

@@ -267,7 +267,7 @@ export class Light extends Component {
 
     protected _destroyLight () {
         if (this._light) {
-            legacyCC.director.root.destroyLight(this);
+            legacyCC.director.root.destroyLight(this._light);
             this._light = null;
         }
     }

cocos/audio/audio-clip.ts

@@ -23,10 +23,8 @@
  THE SOFTWARE.
  */
 
-import {
-    ccclass, type, serializable, override,
-} from 'cc.decorator';
-import { AudioPlayer, OneShotAudio } from 'pal/audio';
+import { ccclass, serializable, override } from 'cc.decorator';
+import { AudioPlayer } from 'pal/audio';
 import { Asset } from '../core/assets/asset';
 import { legacyCC } from '../core/global-exports';
 import { AudioState, AudioType } from '../../pal/audio/type';
@@ -40,9 +38,9 @@ export interface AudioMeta {
 
 /**
  * @en
- * The audio clip asset. <br>
+ * The audio clip asset.
  * @zh
- * 音频片段资源。<br>
+ * 音频片段资源。
  */
 @ccclass('cc.AudioClip')
 export class AudioClip extends Asset {

cocos/core/assets/asset.ts

@@ -29,11 +29,11 @@ import { EDITOR, PREVIEW } from 'internal:constants';
 import { property } from '../data/decorators/property';
 import { getUrlWithUuid } from '../asset-manager/helper';
 import { Eventify } from '../event';
-import { GCObject } from '../data/gc-object';
 import { Node } from '../scene-graph';
 import { legacyCC } from '../global-exports';
 import { extname } from '../utils/path';
 import { debug, getError, warn } from '../platform/debug';
+import { CCObject } from '../data/object';
 
 /**
  * @en
@@ -57,7 +57,7 @@ import { debug, getError, warn } from '../platform/debug';
  * @extends CCObject
  */
 @ccclass('cc.Asset')
-export class Asset extends Eventify(GCObject) {
+export class Asset extends Eventify(CCObject) {
     /**
      * 应 AssetDB 要求提供这个方法。
      * @internal
@@ -156,7 +156,7 @@ export class Asset extends Eventify(GCObject) {
         this._file = obj;
     }
 
-    constructor (...args: ConstructorParameters<typeof GCObject>) {
+    constructor (...args: ConstructorParameters<typeof CCObject>) {
         super(...args);
 
         Object.defineProperty(this, '_uuid', {

cocos/core/assets/effect-asset.ts

@@ -220,7 +220,7 @@ export class EffectAsset extends Asset {
      */
     public static remove (asset: EffectAsset | string) {
         if (typeof asset !== 'string') {
-            if (EffectAsset._effects[asset.name] && EffectAsset._effects[asset.name].equals(asset)) {
+            if (EffectAsset._effects[asset.name] && EffectAsset._effects[asset.name] === asset) {
                 delete EffectAsset._effects[asset.name];
             }
         } else {

cocos/core/components/camera-component.ts

@@ -517,31 +517,53 @@ export class Camera extends Component {
         }
     }
 
+    /**
+     * @en Convert a screen space (left-top origin) point to a ray.
+     * @zh 将一个屏幕空间（左上角为原点）坐标转换为射线。
+     * @param x The x axis position on screen.
+     * @param y The y axis position on screen.
+     * @param out The output ray object.
+     * @returns Return the output ray object.
+     */
     public screenPointToRay (x: number, y: number, out?: Ray) {
         if (!out) { out = Ray.create(); }
         if (this._camera) { this._camera.screenPointToRay(out, x, y); }
         return out;
     }
 
+    /**
+     * @en Convert a world position to a screen space (left-top origin) position.
+     * @zh 将一个世界空间坐标转换为屏幕空间（左上角为原点）坐标。
+     * @param worldPos The position in world space coordinates
+     * @param out The output position in screen space coordinates.
+     * @returns Return the output position object.
+     */
     public worldToScreen (worldPos: Vec3 | Readonly<Vec3>, out?: Vec3) {
         if (!out) { out = new Vec3(); }
         if (this._camera) { this._camera.worldToScreen(out, worldPos); }
         return out;
     }
 
+    /**
+     * @en Convert a screen space (left-top origin) position to a world space position.
+     * @zh 将一个屏幕空间（左上角为原点）转换为世界空间坐标。
+     * @param screenPos The position in screen space coordinates
+     * @param out The output position in world space coordinates
+     * @returns Return the output position object.
+     */
     public screenToWorld (screenPos: Vec3, out?: Vec3) {
         if (!out) { out = this.node.getWorldPosition(); }
         if (this._camera) { this._camera.screenToWorld(out, screenPos); }
         return out;
     }
 
     /**
-     * @en 3D node to UI local node coordinates. The converted value is the offset under the UI node.
-     *
-     * @zh 3D 节点转 UI 本地节点坐标。转换后的值是该 UI 节点下的偏移。
-     * @param wpos 3D 节点世界坐标
-     * @param uiNode UI 节点
-     * @param out 返回在当前传入的 UI 节点下的偏移量
+     * @en Convert a 3D world position to the local coordinates system of the given UI node.
+     * The converted position will be related to the given UI node under local space.
+     * @zh 将一个 3D 空间世界坐标转换到指定的 UI 本地节点坐标系下。转换后的位置是指定 UI 节点坐标系下的局部偏移。
+     * @param wpos @en The world position to convert @zh 需要转换的世界坐标
+     * @param uiNode @en The UI node coordinates in which the world position will be convert to @zh 用于同步位置的 UI 节点
+     * @param out @en Return the corresponding position of the given world position in the UI node's local coordinates @zh 返回传入的世界坐标在 UI 节点本地坐标系下的局部坐标
      *
      * @example
      * ```ts

cocos/core/components/model-renderer.ts

@@ -36,12 +36,9 @@ import { Renderer } from './renderer';
  */
 @ccclass('cc.ModelRenderer')
 export class ModelRenderer extends Renderer {
-    @serializable
-    protected _visFlags = Layers.Enum.NONE;
-
     /**
-     * @zh 组件所属层，影响该组件下的所有 model 的 visFlags
-     * @en The layer of the current component, which affects all the visFlags of the models belonging to this component.
+     * @en The visibility which will be applied to the committed models.
+     * @zh 应用于所有提交渲染的 Model 的可见性
      */
     get visibility () {
         return this._visFlags;
@@ -52,6 +49,8 @@ export class ModelRenderer extends Renderer {
         this._onVisibilityChange(val);
     }
 
+    @serializable
+    protected _visFlags = Layers.Enum.NONE;
     protected _models: scene.Model[] = [];
 
     /**