refactor(clone): type-driven default clone mode for container elements

packages/core/src/clone/CloneManager.ts

@@ -46,6 +46,30 @@ export function deepClone(target: Object, propertyKey: string): void {
   CloneManager.registerCloneMode(target, propertyKey, CloneMode.Deep);
 }
 
+/**
+ * Class decorator that sets the default clone mode for instances of the decorated type.
+ *
+ * When a field holds an instance of a type decorated with `@defaultCloneMode`, the clone system
+ * uses the specified mode instead of the default Assignment behavior. This applies when the field
+ * has no explicit per-field clone decorator, or when the value is encountered inside a container
+ * (Array, Map, Set) that is being deep-cloned.
+ *
+ * @param mode - The clone mode applied to instances of the decorated type
+ *
+ * @example
+ * ```ts
+ * @defaultCloneMode(CloneMode.Deep)
+ * class MyConfig {
+ *   value = 0;
+ * }
+ * ```
+ */
+export function defaultCloneMode(mode: CloneMode) {
+  return function (target: Function): void {
+    Object.defineProperty(target.prototype, "_defaultCloneMode", { value: mode });
+  };
+}
+
 /**
  * @internal
  * Clone manager.
@@ -113,7 +137,18 @@ export class CloneManager {
 
     if (cloneMode === CloneMode.Ignore) return;
 
-    // Primitives, undecorated, or @assignmentClone: direct assign
+    // If no per-field decorator, consult the value's type-level default clone mode
+    if (cloneMode === undefined && sourceProperty instanceof Object) {
+      const typeDefault = (<ICustomClone>sourceProperty)._defaultCloneMode;
+      if (typeDefault === CloneMode.Deep) {
+        cloneMode = CloneMode.Deep;
+      } else if (typeDefault === CloneMode.Shallow) {
+        cloneMode = CloneMode.Shallow;
+      }
+      // typeDefault === undefined or Assignment → fall through to assignment below
+    }
+
+    // Primitives, undecorated (no type default), or @assignmentClone: direct assign
     if (!(sourceProperty instanceof Object) || cloneMode === undefined || cloneMode === CloneMode.Assignment) {
       target[k] = sourceProperty;
       return;
@@ -150,7 +185,7 @@ export class CloneManager {
             <Array<any>>sourceProperty,
             targetPropertyA,
             i,
-            cloneMode,
+            undefined,
             srcRoot,
             targetRoot,
             deepInstanceMap

packages/core/src/clone/ComponentCloner.ts

@@ -1,11 +1,18 @@
 import { Component } from "../Component";
 import { Entity } from "../Entity";
 import { CloneManager } from "./CloneManager";
+import { CloneMode } from "./enums/CloneMode";
 
 /**
  * Custom clone interface.
  */
 export interface ICustomClone {
+  /**
+   * @internal
+   * Default clone mode for instances of this type when encountered as a value in a field.
+   * Set via `@defaultCloneMode`. Absence defaults to Assignment (shared reference).
+   */
+  readonly _defaultCloneMode?: CloneMode;
   /**
    * @internal
    */

packages/core/src/shader/state/BlendState.ts

@@ -2,7 +2,8 @@ import { IHardwareRenderer } from "@galacean/engine-design";
 import { Color } from "@galacean/engine-math";
 import { RenderStateElementMap } from "../../BasicResources";
 import { GLCapabilityType } from "../../base/Constant";
-import { deepClone } from "../../clone/CloneManager";
+import { deepClone, defaultCloneMode } from "../../clone/CloneManager";
+import { CloneMode } from "../../clone/enums/CloneMode";
 import { ShaderData } from "../ShaderData";
 import { ShaderProperty } from "../ShaderProperty";
 import { BlendFactor } from "../enums/BlendFactor";
@@ -15,6 +16,7 @@ import { RenderTargetBlendState } from "./RenderTargetBlendState";
 /**
  * Blend state.
  */
+@defaultCloneMode(CloneMode.Deep)
 export class BlendState {
   private static _getGLBlendFactor(rhi: IHardwareRenderer, blendFactor: BlendFactor): number {
     const gl = rhi.gl;

packages/core/src/shader/state/DepthState.ts

@@ -1,5 +1,7 @@
 import { IHardwareRenderer } from "@galacean/engine-design";
 import { RenderStateElementMap } from "../../BasicResources";
+import { defaultCloneMode } from "../../clone/CloneManager";
+import { CloneMode } from "../../clone/enums/CloneMode";
 import { ShaderData } from "../ShaderData";
 import { ShaderProperty } from "../ShaderProperty";
 import { CompareFunction } from "../enums/CompareFunction";
@@ -9,6 +11,7 @@ import { RenderState } from "./RenderState";
 /**
  * Depth state.
  */
+@defaultCloneMode(CloneMode.Deep)
 export class DepthState {
   private static _getGLCompareFunction(rhi: IHardwareRenderer, compareFunction: CompareFunction): number {
     const gl = rhi.gl;

packages/core/src/shader/state/RasterState.ts

@@ -1,5 +1,7 @@
 import { IHardwareRenderer } from "@galacean/engine-design";
 import { RenderStateElementMap } from "../../BasicResources";
+import { defaultCloneMode } from "../../clone/CloneManager";
+import { CloneMode } from "../../clone/enums/CloneMode";
 import { ShaderData } from "../ShaderData";
 import { ShaderProperty } from "../ShaderProperty";
 import { CullMode } from "../enums/CullMode";
@@ -9,6 +11,7 @@ import { RenderState } from "./RenderState";
 /**
  * Raster state.
  */
+@defaultCloneMode(CloneMode.Deep)
 export class RasterState {
   /** Specifies whether or not front- and/or back-facing polygons can be culled. */
   cullMode: CullMode = CullMode.Back;

packages/core/src/shader/state/RenderState.ts

@@ -1,7 +1,8 @@
 import { ShaderData, ShaderProperty } from "..";
 import { RenderStateElementMap } from "../../BasicResources";
 import { Engine } from "../../Engine";
-import { deepClone } from "../../clone/CloneManager";
+import { deepClone, defaultCloneMode } from "../../clone/CloneManager";
+import { CloneMode } from "../../clone/enums/CloneMode";
 import { RenderQueueType } from "../enums/RenderQueueType";
 import { RenderStateElementKey } from "../enums/RenderStateElementKey";
 import { BlendState } from "./BlendState";
@@ -12,6 +13,7 @@ import { StencilState } from "./StencilState";
 /**
  * Render state.
  */
+@defaultCloneMode(CloneMode.Deep)
 export class RenderState {
   /** Blend state. */
   @deepClone

packages/core/src/shader/state/RenderTargetBlendState.ts

@@ -1,10 +1,13 @@
+import { defaultCloneMode } from "../../clone/CloneManager";
+import { CloneMode } from "../../clone/enums/CloneMode";
 import { BlendOperation } from "../enums/BlendOperation";
 import { BlendFactor } from "../enums/BlendFactor";
 import { ColorWriteMask } from "../enums/ColorWriteMask";
 
 /**
  * The blend state of the render target.
  */
+@defaultCloneMode(CloneMode.Deep)
 export class RenderTargetBlendState {
   /** Whether to enable blend. */
   enabled: boolean = false;

packages/core/src/shader/state/StencilState.ts

@@ -1,5 +1,7 @@
 import { IHardwareRenderer } from "@galacean/engine-design";
 import { RenderStateElementMap } from "../../BasicResources";
+import { defaultCloneMode } from "../../clone/CloneManager";
+import { CloneMode } from "../../clone/enums/CloneMode";
 import { ShaderData } from "../ShaderData";
 import { ShaderProperty } from "../ShaderProperty";
 import { CompareFunction } from "../enums/CompareFunction";
@@ -10,6 +12,7 @@ import { RenderState } from "./RenderState";
 /**
  * Stencil state.
  */
+@defaultCloneMode(CloneMode.Deep)
 export class StencilState {
   private static _getGLCompareFunction(rhi: IHardwareRenderer, compareFunction: CompareFunction): number {
     const gl = rhi.gl;