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

packages/core/src/2d/sprite/SpriteMask.ts

@@ -6,7 +6,7 @@ import { RenderContext } from "../../RenderPipeline/RenderContext";
 import { SubPrimitiveChunk } from "../../RenderPipeline/SubPrimitiveChunk";
 import { RenderElement } from "../../RenderPipeline/RenderElement";
 import { Renderer, RendererUpdateFlags } from "../../Renderer";
-import { assignmentClone, ignoreClone } from "../../clone/CloneManager";
+import { ignoreClone } from "../../clone/CloneManager";
 import { SpriteMaskLayer } from "../../enums/SpriteMaskLayer";
 import { ShaderProperty } from "../../shader/ShaderProperty";
 import { ISpriteRenderer } from "../assembler/ISpriteRenderer";
@@ -24,7 +24,6 @@ export class SpriteMask extends Renderer implements ISpriteRenderer {
   static _alphaCutoffProperty: ShaderProperty = ShaderProperty.getByName("renderer_MaskAlphaCutoff");
 
   /** The mask layers the sprite mask influence to. */
-  @assignmentClone
   influenceLayers: SpriteMaskLayer = SpriteMaskLayer.Everything;
   /** @internal */
   @ignoreClone
@@ -44,16 +43,11 @@ export class SpriteMask extends Renderer implements ISpriteRenderer {
   private _automaticWidth: number = 0;
   @ignoreClone
   private _automaticHeight: number = 0;
-  @assignmentClone
   private _customWidth: number = undefined;
-  @assignmentClone
   private _customHeight: number = undefined;
-  @assignmentClone
   private _flipX: boolean = false;
-  @assignmentClone
   private _flipY: boolean = false;
 
-  @assignmentClone
   private _alphaCutoff: number = 0.5;
 
   /**

packages/core/src/2d/sprite/SpriteRenderer.ts

@@ -6,7 +6,7 @@ import { RenderContext } from "../../RenderPipeline/RenderContext";
 import { SubPrimitiveChunk } from "../../RenderPipeline/SubPrimitiveChunk";
 import { RenderElement } from "../../RenderPipeline/RenderElement";
 import { Renderer, RendererUpdateFlags } from "../../Renderer";
-import { assignmentClone, deepClone, ignoreClone } from "../../clone/CloneManager";
+import { ignoreClone } from "../../clone/CloneManager";
 import { ShaderProperty } from "../../shader/ShaderProperty";
 import { ISpriteAssembler } from "../assembler/ISpriteAssembler";
 import { ISpriteRenderer } from "../assembler/ISpriteRenderer";
@@ -35,12 +35,9 @@ export class SpriteRenderer extends Renderer implements ISpriteRenderer {
   private _drawMode: SpriteDrawMode;
   @ignoreClone
   private _assembler: ISpriteAssembler;
-  @assignmentClone
   private _tileMode: SpriteTileMode = SpriteTileMode.Continuous;
-  @assignmentClone
   private _tiledAdaptiveThreshold: number = 0.5;
 
-  @deepClone
   private _color: Color = new Color(1, 1, 1, 1);
   @ignoreClone
   private _sprite: Sprite = null;
@@ -49,13 +46,9 @@ export class SpriteRenderer extends Renderer implements ISpriteRenderer {
   private _automaticWidth: number = 0;
   @ignoreClone
   private _automaticHeight: number = 0;
-  @assignmentClone
   private _customWidth: number = undefined;
-  @assignmentClone
   private _customHeight: number = undefined;
-  @assignmentClone
   private _flipX: boolean = false;
-  @assignmentClone
   private _flipY: boolean = false;
 
   /**

packages/core/src/2d/text/TextRenderer.ts

@@ -8,7 +8,7 @@ import { SubPrimitiveChunk } from "../../RenderPipeline/SubPrimitiveChunk";
 import { RenderElement } from "../../RenderPipeline/RenderElement";
 import { Renderer } from "../../Renderer";
 import { TransformModifyFlags } from "../../Transform";
-import { assignmentClone, deepClone, ignoreClone } from "../../clone/CloneManager";
+import { ignoreClone } from "../../clone/CloneManager";
 import { ShaderData, ShaderProperty } from "../../shader";
 import { ShaderDataGroup } from "../../shader/enums/ShaderDataGroup";
 import { Texture2D } from "../../texture";
@@ -36,38 +36,24 @@ export class TextRenderer extends Renderer implements ITextRenderer {
   @ignoreClone
   private _textChunks = Array<TextChunk>();
   /** @internal */
-  @assignmentClone
   _subFont: SubFont = null;
   /** @internal */
   @ignoreClone
   _dirtyFlag = DirtyFlag.Font;
-  @deepClone
   private _color = new Color(1, 1, 1, 1);
-  @assignmentClone
   private _text = "";
-  @assignmentClone
   private _width = 0;
-  @assignmentClone
   private _height = 0;
   @ignoreClone
   private _localBounds = new BoundingBox();
-  @assignmentClone
   private _font: Font = null;
-  @assignmentClone
   private _fontSize = 24;
-  @assignmentClone
   private _fontStyle = FontStyle.None;
-  @assignmentClone
   private _lineSpacing = 0;
-  @assignmentClone
   private _characterSpacing = 0;
-  @assignmentClone
   private _horizontalAlignment = TextHorizontalAlignment.Center;
-  @assignmentClone
   private _verticalAlignment = TextVerticalAlignment.Center;
-  @assignmentClone
   private _enableWrapping = false;
-  @assignmentClone
   private _overflowMode = OverflowMode.Overflow;
 
   /**
@@ -330,15 +316,6 @@ export class TextRenderer extends Renderer implements ITextRenderer {
     this._subFont && (this._subFont = null);
   }
 
-  /**
-   * @internal
-   */
-  override _cloneTo(target: TextRenderer): void {
-    super._cloneTo(target);
-    target.font = this._font;
-    target._subFont = this._subFont;
-  }
-
   /**
    * @internal
    */

packages/core/src/Camera.ts

@@ -9,7 +9,7 @@ import { Transform } from "./Transform";
 import { UpdateFlagManager } from "./UpdateFlagManager";
 import { VirtualCamera } from "./VirtualCamera";
 import { GLCapabilityType, Logger } from "./base";
-import { deepClone, ignoreClone } from "./clone/CloneManager";
+import { ignoreClone } from "./clone/CloneManager";
 import { AntiAliasing } from "./enums/AntiAliasing";
 import { CameraClearFlags } from "./enums/CameraClearFlags";
 import { CameraModifyFlags } from "./enums/CameraModifyFlags";
@@ -116,13 +116,11 @@ export class Camera extends Component {
   @ignoreClone
   _globalShaderMacro: ShaderMacroCollection = new ShaderMacroCollection();
   /** @internal */
-  @deepClone
   _frustum: BoundingFrustum = new BoundingFrustum();
   /** @internal */
   @ignoreClone
   _renderPipeline: BasicRenderPipeline;
   /** @internal */
-  @deepClone
   _virtualCamera: VirtualCamera = new VirtualCamera();
   /** @internal */
   _replacementShader: Shader = null;
@@ -148,25 +146,16 @@ export class Camera extends Component {
   private _msaaSamples: MSAASamples;
 
   private _renderTarget: RenderTarget = null;
-  @ignoreClone
   private _updateFlagManager: UpdateFlagManager;
-  @ignoreClone
   private _frustumChangeFlag: BoolUpdateFlag;
-  @ignoreClone
   private _isViewMatrixDirty: BoolUpdateFlag;
-  @ignoreClone
   private _isInvViewProjDirty: BoolUpdateFlag;
-  @deepClone
   private _shaderData: ShaderData = new ShaderData(ShaderDataGroup.Camera);
   @ignoreClone
   private _depthBufferParams: Vector4 = new Vector4();
-  @deepClone
   private _viewport: Vector4 = new Vector4(0, 0, 1, 1);
-  @deepClone
   private _pixelViewport: Rect = new Rect(0, 0, 0, 0);
-  @deepClone
   private _inverseProjectionMatrix: Matrix = new Matrix();
-  @deepClone
   private _invViewProjMat: Matrix = new Matrix();
 
   /**
@@ -826,13 +815,6 @@ export class Camera extends Component {
     this._updateFlagManager?.removeListener(onChange);
   }
 
-  /**
-   * @internal
-   */
-  _cloneTo(target: Camera): void {
-    this._renderTarget?._addReferCount(1);
-  }
-
   /**
    * @internal
    * @inheritdoc

packages/core/src/Component.ts

@@ -1,14 +1,15 @@
 import { IReferable } from "./asset/IReferable";
 import { EngineObject } from "./base";
-import { assignmentClone, ignoreClone } from "./clone/CloneManager";
-import { CloneUtils } from "./clone/CloneUtils";
+import { defaultCloneMode, ignoreClone } from "./clone/CloneManager";
+import { CloneMode } from "./clone/enums/CloneMode";
 import { Entity } from "./Entity";
 import { ActiveChangeFlag } from "./enums/ActiveChangeFlag";
 import { Scene } from "./Scene";
 
 /**
  * The base class of the components.
  */
+@defaultCloneMode(CloneMode.Remap)
 export class Component extends EngineObject {
   /** @internal */
   _entity: Entity;
@@ -23,7 +24,6 @@ export class Component extends EngineObject {
   @ignoreClone
   private _phasedActive: boolean = false;
 
-  @assignmentClone
   private _enabled: boolean = true;
 
   /**
@@ -154,13 +154,6 @@ export class Component extends EngineObject {
     }
   }
 
-  /**
-   * @internal
-   */
-  _remap<T extends Component>(srcRoot: Entity, targetRoot: Entity): T {
-    return CloneUtils.remapComponent(srcRoot, targetRoot, this) as unknown as T;
-  }
-
   protected _addResourceReferCount(resource: IReferable, count: number): void {
     this._entity._isTemplate || resource._addReferCount(count);
   }

packages/core/src/Entity.ts

@@ -10,15 +10,17 @@ import { Transform } from "./Transform";
 import { UpdateFlagManager } from "./UpdateFlagManager";
 import { ReferResource } from "./asset/ReferResource";
 import { EngineObject } from "./base";
-import { CloneUtils } from "./clone/CloneUtils";
+import { defaultCloneMode } from "./clone/CloneManager";
 import { ComponentCloner } from "./clone/ComponentCloner";
+import { CloneMode } from "./clone/enums/CloneMode";
 import { ActiveChangeFlag } from "./enums/ActiveChangeFlag";
 import { EntityModifyFlags } from "./enums/EntityModifyFlags";
 import { DisorderedArray } from "./utils/DisorderedArray";
 
 /**
  * Entity, be used as components container.
  */
+@defaultCloneMode(CloneMode.Remap)
 export class Entity extends EngineObject {
   /** @internal */
   static _tempComponentConstructors: ComponentConstructor[] = [];
@@ -421,8 +423,9 @@ export class Entity extends EngineObject {
    * @returns Cloned entity
    */
   clone(): Entity {
-    const cloneEntity = this._createCloneEntity();
-    this._parseCloneEntity(this, cloneEntity, this, cloneEntity, new Map<Object, Object>());
+    const cloneMap = new Map<Object, Object>();
+    const cloneEntity = this._createCloneEntity(cloneMap);
+    this._parseCloneEntity(this, cloneEntity, cloneMap);
     return cloneEntity;
   }
 
@@ -434,13 +437,6 @@ export class Entity extends EngineObject {
     return this._updateFlagManager.createFlag(BoolUpdateFlag);
   }
 
-  /**
-   * @internal
-   */
-  _remap(srcRoot: Entity, targetRoot: Entity): Entity {
-    return CloneUtils.remapEntity(srcRoot, targetRoot, this);
-  }
-
   /**
    * @internal
    */
@@ -449,14 +445,26 @@ export class Entity extends EngineObject {
     this._templateResource = templateResource;
   }
 
-  private _createCloneEntity(): Entity {
+  /**
+   * Build the clone's entity/component tree and register every source entity/component to its
+   * clone in the identity map, so the value-copy pass (`_parseCloneEntity`) can remap references —
+   * including ones nested in arrays / maps / objects — through the clone gate. Registration
+   * completes for the whole subtree before any value is copied, because a component anywhere in
+   * the tree may reference an entity anywhere else in it.
+   */
+  private _createCloneEntity(cloneMap: Map<Object, Object>): Entity {
     const componentConstructors = Entity._tempComponentConstructors;
     const components = this._components;
     for (let i = 0, n = components.length; i < n; i++) {
       componentConstructors[i] = components[i].constructor as ComponentConstructor;
     }
     const cloneEntity = new Entity(this.engine, this.name, ...componentConstructors);
     componentConstructors.length = 0;
+    cloneMap.set(this, cloneEntity);
+    const targetComponents = cloneEntity._components;
+    for (let i = 0, n = components.length; i < n; i++) {
+      cloneMap.set(components[i], targetComponents[i]);
+    }
     const templateResource = this._templateResource;
     if (templateResource) {
       cloneEntity._templateResource = templateResource;
@@ -467,27 +475,21 @@ export class Entity extends EngineObject {
     cloneEntity._isActive = this._isActive;
     const srcChildren = this._children;
     for (let i = 0, n = srcChildren.length; i < n; i++) {
-      cloneEntity.addChild(srcChildren[i]._createCloneEntity());
+      cloneEntity.addChild(srcChildren[i]._createCloneEntity(cloneMap));
     }
     return cloneEntity;
   }
 
-  private _parseCloneEntity(
-    src: Entity,
-    target: Entity,
-    srcRoot: Entity,
-    targetRoot: Entity,
-    deepInstanceMap: Map<Object, Object>
-  ): void {
+  private _parseCloneEntity(src: Entity, target: Entity, cloneMap: Map<Object, Object>): void {
     const srcChildren = src._children;
     const targetChildren = target._children;
     for (let i = 0, n = srcChildren.length; i < n; i++) {
-      this._parseCloneEntity(srcChildren[i], targetChildren[i], srcRoot, targetRoot, deepInstanceMap);
+      this._parseCloneEntity(srcChildren[i], targetChildren[i], cloneMap);
     }
 
     const components = src._components;
     for (let i = 0, n = components.length; i < n; i++) {
-      ComponentCloner.cloneComponent(components[i], target._components[i], srcRoot, targetRoot, deepInstanceMap);
+      ComponentCloner.cloneComponent(components[i], target._components[i], cloneMap);
     }
   }
 

packages/core/src/Renderer.ts

@@ -7,7 +7,7 @@ import { Entity } from "./Entity";
 import { RenderContext } from "./RenderPipeline/RenderContext";
 import { RenderElement } from "./RenderPipeline/RenderElement";
 import { Transform, TransformModifyFlags } from "./Transform";
-import { assignmentClone, deepClone, ignoreClone } from "./clone/CloneManager";
+import { ignoreClone } from "./clone/CloneManager";
 import { SpriteMaskLayer } from "./enums/SpriteMaskLayer";
 import { Material } from "./material";
 import { ShaderMacro, ShaderProperty } from "./shader";
@@ -48,9 +48,7 @@ export class Renderer extends Component {
   @ignoreClone
   _renderFrameCount: number;
   /** @internal */
-  @assignmentClone
   _maskInteraction: SpriteMaskInteraction = SpriteMaskInteraction.None;
-  @assignmentClone
   _maskLayer: SpriteMaskLayer = SpriteMaskLayer.Layer0;
 
   @ignoreClone
@@ -65,7 +63,6 @@ export class Renderer extends Component {
   protected _bounds: BoundingBox = new BoundingBox();
   protected _transformEntity: Entity;
 
-  @deepClone
   private _shaderData: ShaderData = new ShaderData(ShaderDataGroup.Renderer);
   @ignoreClone
   private _mvMatrix: Matrix = new Matrix();
@@ -75,9 +72,7 @@ export class Renderer extends Component {
   private _normalMatrix: Matrix = new Matrix();
   @ignoreClone
   private _materialsInstanced: boolean[] = [];
-  @assignmentClone
   private _priority: number = 0;
-  @assignmentClone
   private _receiveShadows: boolean = true;
 
   /**