diff --git a/docs/en/core/clone.mdx b/docs/en/core/clone.mdx
index 2453b0531d..40e5b3c5e8 100644
--- a/docs/en/core/clone.mdx
+++ b/docs/en/core/clone.mdx
@@ -8,24 +8,28 @@ label: Core
Node cloning is a common runtime feature, and node cloning also includes cloning its bound components. For example, during the initialization phase, dynamically create a certain number of identical entities based on configuration, and then place them in different positions in the scene according to logical rules. Here, the details of script cloning will be explained in detail.
## Entity Cloning
+
It's very simple, just call the entity's [clone()](/apis/design/#IClone-clone) method to complete the cloning of the entity and its attached components.
+
```typescript
const cloneEntity = entity.clone();
```
## Script Cloning
-Scripts are essentially components, so when we call the entity's [clone()](/apis/design/#IClone-clone) function, the engine will not only clone the built-in components but also clone custom scripts. The cloning rules for built-in components have been customized by the official team, and similarly, we have also opened up the cloning capabilities and rules for scripts to developers. The default cloning method for script fields is shallow copy. For example, if we modify the field values of the script and then clone it, the cloned script will retain the modified values without any additional coding. Below is an example of custom script cloning:
+
+Scripts are essentially components, so when we call the entity's [clone()](/apis/design/#IClone-clone) function, the engine will not only clone the built-in components but also clone custom scripts. The cloning rules for built-in components have been customized by the official team, and similarly, we have also opened up the cloning capabilities and rules for scripts to developers. Script fields are cloned automatically, and how each field value is cloned is resolved by the value's type (see the default rules below). For example, if we modify the field values of the script and then clone it, the cloned script will retain the modified values without any additional coding. Below is an example of custom script cloning:
+
```typescript
// define a custom script
-class CustomScript extends Script{
+class CustomScript extends Script {
/** boolean type.*/
- a:boolean = false;
-
+ a: boolean = false;
+
/** number type.*/
- b:number = 1;
-
+ b: number = 1;
+
/** class type.*/
- c:Vector3 = new Vector3(0,0,0);
+ c: Vector3 = new Vector3(0, 0, 0);
}
// Init entity and script
@@ -33,44 +37,99 @@ const entity = engine.createEntity();
const script = entity.addComponent(CustomScript);
script.a = true;
script.b = 2;
-script.c.set(1,1,1);
+script.c.set(1, 1, 1);
// Clone logic
const cloneEntity = entity.clone();
const cloneScript = cloneEntity.getComponent(CustomScript);
console.log(cloneScript.a); // output is true.
console.log(cloneScript.b); // output is 2.
-console.log(cloneScript.c); // output is (1,1,1).
+console.log(cloneScript.c); // output is (1,1,1), and it is an independent copy — Vector3 is a math value type and is deep cloned by default.
```
+
+### Default Cloning Rules
+
+When a field has no clone decorator, the engine resolves how to clone its value by the value's type:
+
+| Value Type | Default Cloning Behavior |
+| :-- | :-- |
+| Primitive types (`number`, `string`, `boolean`, ...) | Copy the value. |
+| Assets (`Texture`, `Mesh`, `Material`, `Sprite`, `Font` and other `ReferResource` types) | Share the reference — the clone uses the same asset as the source. |
+| `Entity` / `Component` references | Automatically remapped to the corresponding clone within the cloned subtree; references pointing outside the subtree keep the original reference. |
+| Math value types (`Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Matrix`, `Color`, ...) and other value-semantic data | Deep cloned — the clone gets a fully independent copy. |
+| Containers (`Array`, `Map`, `Set`, TypedArray, `DataView`, plain objects) | Deep cloned — a fresh container is created, and each member (for `Map`, keys included) is cloned again according to its own type semantics. |
+| Runtime containers (internal transient state such as `UpdateFlagManager`) | Ignored — the clone keeps its own constructor-built value. |
+| Function values | The clone keeps its own constructor-built function; if it has none, the source's function is shared. |
+| Other objects | Share the reference (assignment). |
+
+Deep-by-default behavior is explicit rather than inferred from method names. A custom data class can opt in by extending [DataObject](/apis/core/#DataObject), whose own enumerable string-keyed properties are cloned field by field. Engine math value types are registered internally and copied through their `copyFrom` implementations; merely adding a method named `copyFrom` does not opt a custom class in. A type cloned this way must support argument-less construction when no compatible preset exists: the engine creates it with `new Type()` before populating it, and throws if bare construction fails.
+
+So without any decorator, plain data objects and arrays get independent deep copies, assets remain shared, and entity references are automatically remapped:
+
+```typescript
+// define a custom script
+class CustomScript extends Script {
+ /** Entity reference.*/
+ target: Entity;
+
+ /** Plain data object.*/
+ config = { speed: 1, offsets: [0, 1, 2] };
+
+ /** Asset.*/
+ texture: Texture2D;
+}
+
+// Init entity and script
+const entity = engine.createEntity();
+const child = entity.createChild("child");
+const script = entity.addComponent(CustomScript);
+script.target = child;
+script.texture = new Texture2D(engine, 128, 128);
+
+// Clone logic
+const cloneEntity = entity.clone();
+const cloneScript = cloneEntity.getComponent(CustomScript);
+console.log(cloneScript.target === cloneEntity.findByName("child")); // output is true, entity references are remapped to the corresponding clone in the cloned subtree.
+console.log(cloneScript.config === script.config); // output is false, plain data objects are deep cloned into independent copies.
+console.log(cloneScript.texture === script.texture); // output is true, assets are shared between the source and the clone.
+```
+
### Clone Decorators
-In addition to the default cloning method, the engine also provides "clone decorators" to customize the cloning method for script fields. The engine has four built-in clone decorators:
+
+In addition to the default type-driven rules, the engine also provides "clone decorators" to customize the cloning method for script fields. Field decorators have the highest priority — they override the value type's default cloning behavior and apply wherever the clone walks fields: at the component's top level and inside any object that is itself deep cloned (no field walk happens inside a value that stays shared, so no decorator is consulted there). The engine has three built-in clone decorators:
| Decorator Name | Decorator Description |
-| :--- | :--- |
-| [ignoreClone](/apis/core/#ignoreClone) | Ignore the field during cloning. |
-| [assignmentClone](/apis/core/#assignmentClone) | (Default value, equivalent to not adding any clone decorator) Assign the field during cloning. If it is a basic type, the value will be copied; if it is a reference type, the reference address will be copied. |
-| [shallowClone](/apis/core/#shallowClone) | Shallow clone the field during cloning. After cloning, it will maintain its own independent reference and clone all its internal fields by assignment (if the internal field is a basic type, the value will be copied; if the internal field is a reference type, the reference address will be copied). |
-| [deepClone](/apis/core/#deepClone) | Deep clone the field during cloning. After cloning, it will maintain its own independent reference, and all its internal deep fields will remain completely independent. |
+| :-- | :-- |
+| [ignoreClone](/apis/core/#ignoreClone) | Ignore the field during cloning; the clone keeps its own constructor-built value. |
+| [assignmentClone](/apis/core/#assignmentClone) | Assign the field during cloning. If it is a basic type, the value will be copied; if it is a reference type, the clone will share the reference with the source. |
+| [deepClone](/apis/core/#deepClone) | Deep clone supported values throughout the field's subtree. The deep intent carries into field-cloneable members, while assets stay shared, entity references remap, runtime state keeps the clone's own, and unregistered opaque members keep their default assignment behavior. If the decorated value itself cannot honor a deep clone — for example an `Entity` / `Component`, asset, function, runtime-state object, or opaque platform object — cloning throws. |
+
+
+ `@shallowClone` has been removed. Its old semantics — copy the container itself but share its members — no longer
+ exist. Migrate by intent: use `@deepClone` if the field should be independent, or `@assignmentClone` if it should be
+ shared.
+
+
+We slightly modify the above example and add different "clone decorators" to the four fields in `CustomScript`. Since arrays are already deep cloned by default, we use `assignmentClone` on field `c` to force sharing, and `deepClone` on field `d` to make the default behavior explicit, with additional print output for further explanation.
-We slightly modify the above example and add different "clone decorators" to the four fields in `CustomScript`. Since `shallowClone` and `deepClone` are more complex, we add additional print output to the fields `c` and `d` for further explanation.
```typescript
// define a custom script
-class CustomScript extends Script{
+class CustomScript extends Script {
/** boolean type.*/
@ignoreClone
- a:boolean = false;
-
+ a: boolean = false;
+
/** number type.*/
@assignmentClone
- b:number = 1;
-
+ b: number = 1;
+
/** class type.*/
- @shallowClone
- c:Vector3[] = [new Vector3(0,0,0)];
-
+ @assignmentClone
+ c: Vector3[] = [new Vector3(0, 0, 0)];
+
/** class type.*/
@deepClone
- d:Vector3[] = [new Vector3(0,0,0)];
+ d: Vector3[] = [new Vector3(0, 0, 0)];
}
// Init entity and script
@@ -78,26 +137,32 @@ const entity = engine.createEntity();
const script = entity.addComponent(CustomScript);
script.a = true;
script.b = 2;
-script.c[0].set(1,1,1);
-script.d[0].set(1,1,1);
+script.c[0].set(1, 1, 1);
+script.d[0].set(1, 1, 1);
// Clone logic
const cloneEntity = entity.clone();
const cloneScript = cloneEntity.getComponent(CustomScript);
-console.log(cloneScript.a); // output is false,ignoreClone will ignore the value.
+console.log(cloneScript.a); // output is false,ignoreClone keeps the clone's own constructor-built value.
console.log(cloneScript.b); // output is 2,assignmentClone is just assignment the origin value.
-console.log(cloneScript.c[0]); // output is Vector3(1,1,1),shallowClone clone the array shell,but use the same element.
+console.log(cloneScript.c[0]); // output is Vector3(1,1,1),assignmentClone shares the same array instance with the source.
console.log(cloneScript.d[0]); // output is Vector3(1,1,1),deepClone clone the array shell and also clone the element.
-cloneScript.c[0].set(2,2,2); // change the field c[0] value to (2,2,2).
-cloneScript.d[0].set(2,2,2); // change the field d[0] value to (2,2,2).
+cloneScript.c[0].set(2, 2, 2); // change the field c[0] value to (2,2,2).
+cloneScript.d[0].set(2, 2, 2); // change the field d[0] value to (2,2,2).
-console.log(script.c[0]); // output is (2,2,2). bacause shallowClone let c[0] use the same reference with cloneScript's c[0].
-console.log(script.d[0]); // output is (1,1,1). bacause deepClone let d[0] use the different reference with cloneScript's d[0].
+console.log(script.c[0]); // output is (2,2,2), because assignmentClone lets c use the same array reference as cloneScript.c.
+console.log(script.d[0]); // output is (1,1,1), because deepClone gives d[0] a different reference from cloneScript.d[0].
```
+
- Note:
- - `shallowClone` and `deepClone` are usually used for *Object*, *Array*, and *Class* types.
- - `shallowClone` will maintain its own independent reference after cloning and clone all its internal fields by assignment (if the internal field is a basic type, the value will be copied; if the internal field is a reference type, the reference address will be copied).
- - `deepClone` is a deep clone that will recursively clone the properties deeply. How the sub-properties of the properties are cloned depends on the decorators of the sub-properties.
- - If the clone decorators do not meet the requirements, you can implement the [_cloneTo()](/apis/design/#IClone-cloneTo) method to add custom cloning.
+ - Field decorators have the highest priority and also apply to the fields of nested objects, wherever the clone walks fields.
+ - `deepClone` propagates through containers and field-cloneable members. An ordinary class instance without a deep default is copied by its fields and must support argument-less construction. Assets stay shared, entity references are remapped, runtime state keeps the clone's own, unregistered opaque members stay shared, and nested field decorators still win.
+ - Field cloning has a deliberately narrow contract: only an object's own enumerable string-keyed properties carry structural clone semantics. Private fields, non-enumerable properties, Symbol keys, and prototype/accessor state are not reconstructed. The engine does not attempt to recognize every possible form of opaque runtime state.
+ - `deepClone` cannot directly clone engine-bound or opaque values: `@deepClone` on an `Entity` / `Component` reference, an asset, engine runtime state, a function, or an unregistered platform object throws because the explicit intent can't be honored. Remove the decorator to fall back to the default, or use the value's own clone API for a real copy.
+ - If the clone decorators do not meet the requirements, implement [ICloneHook.\_onClone()](/apis/core/#ICloneHook-_onClone) to append type-specific behavior after automatic field cloning.
+
+## Cloning and Asset Reference Counting
+
+When a component's top-level field shares a ref-counted asset (a `ReferResource` such as `Texture`, `Mesh`, or `Material`) during cloning, the engine automatically adds one reference for the clone, so destroying the source never pulls the asset out from under it. Built-in components release their references when destroyed. An asset referenced by custom script fields is kept alive by its clones — destroy the asset itself via its `destroy()` when it is no longer needed.
diff --git a/docs/en/how-to-contribute.mdx b/docs/en/how-to-contribute.mdx
index 988d96a68e..b5f5e6319a 100644
--- a/docs/en/how-to-contribute.mdx
+++ b/docs/en/how-to-contribute.mdx
@@ -120,7 +120,7 @@ class CustomScript extends Script {
a:boolean = false;
@assignmentClone
b:number = 1;
- @shallowClone
+ @deepClone
c:Vector3[] = [new Vector3(0,0,0)];
}
```
@@ -133,7 +133,7 @@ class CustomScript extends Script{
a:boolean = false;
@assignmentClone
b:number = 1;
- @shallowClone
+ @deepClone
c:Vector3[] = [new Vector3(0,0,0)];
}
diff --git a/docs/zh/core/clone.mdx b/docs/zh/core/clone.mdx
index 4cf66c382d..aaa27f5c4b 100644
--- a/docs/zh/core/clone.mdx
+++ b/docs/zh/core/clone.mdx
@@ -5,28 +5,31 @@ type: 核心
label: Core
---
-
节点克隆是运行时的常用功能，同时节点克隆也会附带克隆其绑定的组件。例如在初始化阶段根据配置动态创建一定数量相同的实体,然后根据逻辑规则摆放到场景不同的位置。这里会对脚本的克隆细节进行详细讲解。
## 实体的克隆
-非常简单，直接调用实体的 [clone()](/apis/design/#IClone-clone) 方法即可完成实体以及附属组件的克隆。
+
+非常简单，直接调用实体的 [clone()](/apis/design/#IClone-clone) 方法即可完成实体以及附属组件的克隆。
+
```typescript
const cloneEntity = entity.clone();
```
## 脚本的克隆
-脚本的本质也是组件，所以当我们调用实体的 [clone()](/apis/design/#IClone-clone) 函数时，引擎不仅会对引擎内置组件进行克隆，还会对自定义脚本进行克隆。引擎内置组件的克隆规则官方已经完成定制，同样我们也将脚本的克隆能力和规则定制开放给了开发者。脚本字段默认的克隆方式为浅拷贝，例如我们对脚本的字段值进行修改后再克隆，克隆后的脚本将保持修改后的值,无需增加任何额外的编码。以下为自定义脚本的克隆案例：
+
+脚本的本质也是组件，所以当我们调用实体的 [clone()](/apis/design/#IClone-clone) 函数时，引擎不仅会对引擎内置组件进行克隆，还会对自定义脚本进行克隆。引擎内置组件的克隆规则官方已经完成定制，同样我们也将脚本的克隆能力和规则定制开放给了开发者。脚本字段会被自动克隆，每个字段值采用哪种克隆方式由值的类型决定（见下方默认克隆规则）。例如我们对脚本的字段值进行修改后再克隆，克隆后的脚本将保持修改后的值,无需增加任何额外的编码。以下为自定义脚本的克隆案例：
+
```typescript
// define a custom script
-class CustomScript extends Script{
+class CustomScript extends Script {
/** boolean type.*/
- a:boolean = false;
-
+ a: boolean = false;
+
/** number type.*/
- b:number = 1;
-
+ b: number = 1;
+
/** class type.*/
- c:Vector3 = new Vector3(0,0,0);
+ c: Vector3 = new Vector3(0, 0, 0);
}
// Init entity and script
@@ -34,44 +37,98 @@ const entity = engine.createEntity();
const script = entity.addComponent(CustomScript);
script.a = true;
script.b = 2;
-script.c.set(1,1,1);
+script.c.set(1, 1, 1);
// Clone logic
const cloneEntity = entity.clone();
const cloneScript = cloneEntity.getComponent(CustomScript);
console.log(cloneScript.a); // output is true.
console.log(cloneScript.b); // output is 2.
-console.log(cloneScript.c); // output is (1,1,1).
+console.log(cloneScript.c); // output is (1,1,1)，且是一份独立拷贝 —— Vector3 属于数学值类型，默认深克隆。
```
+
+### 默认克隆规则
+
+当字段没有添加任何克隆装饰器时，引擎会根据字段值的类型决定克隆方式：
+
+| 值类型 | 默认克隆行为 |
+| :-- | :-- |
+| 基本类型（`number`、`string`、`boolean` 等） | 拷贝值。 |
+| 资产（`Texture`、`Mesh`、`Material`、`Sprite`、`Font` 等 `ReferResource` 类型） | 共享引用 —— 克隆体与源使用同一份资产。 |
+| `Entity` / `Component` 引用 | 自动重映射到克隆子树内对应的克隆对象；指向子树外的引用保持原引用不变。 |
+| 数学值类型（`Vector2`、`Vector3`、`Vector4`、`Quaternion`、`Matrix`、`Color` 等）及其他值语义数据 | 深克隆 —— 克隆体获得完全独立的拷贝。 |
+| 容器（`Array`、`Map`、`Set`、TypedArray、`DataView`、普通对象） | 深克隆 —— 创建全新的容器，每个成员（`Map` 连键一起）再按各自的类型语义继续克隆。 |
+| 运行时容器（`UpdateFlagManager` 等内部瞬态状态） | 忽略 —— 克隆体保留自身构造时的值。 |
+| 函数值 | 克隆体保留自身构造时的函数；没有则共享源的函数。 |
+| 其他对象 | 共享引用（赋值）。 |
+
+“默认深克隆”是一项显式能力，不会根据方法名推断。自定义数据类可通过继承 [DataObject](/apis/core/#DataObject) 加入：引擎会逐字段克隆其自身可枚举的字符串键属性。引擎数学值类型则由内部显式注册，并通过各自的 `copyFrom` 实现复制；自定义类仅仅声明一个名为 `copyFrom` 的方法并不会自动加入。此类对象在没有兼容预置实例时必须支持无参构造：引擎会先通过 `new Type()` 创建实例再填充，裸构造失败会直接报错。
+
+因此在不加装饰器的情况下，普通数据对象和数组默认会得到独立的深拷贝，资产依旧共享，实体引用则自动重映射：
+
+```typescript
+// define a custom script
+class CustomScript extends Script {
+ /** Entity reference.*/
+ target: Entity;
+
+ /** Plain data object.*/
+ config = { speed: 1, offsets: [0, 1, 2] };
+
+ /** Asset.*/
+ texture: Texture2D;
+}
+
+// Init entity and script
+const entity = engine.createEntity();
+const child = entity.createChild("child");
+const script = entity.addComponent(CustomScript);
+script.target = child;
+script.texture = new Texture2D(engine, 128, 128);
+
+// Clone logic
+const cloneEntity = entity.clone();
+const cloneScript = cloneEntity.getComponent(CustomScript);
+console.log(cloneScript.target === cloneEntity.findByName("child")); // output is true，实体引用被重映射到克隆子树内对应的克隆对象。
+console.log(cloneScript.config === script.config); // output is false，普通数据对象被深克隆为独立拷贝。
+console.log(cloneScript.texture === script.texture); // output is true，资产在源与克隆体之间共享。
+```
+
### 克隆装饰器
-除了默认的克隆方式外，引擎还提供了“克隆装饰器“对脚本字段的克隆方式进行定制。引擎内置四种克隆装饰：
+
+除了默认的类型驱动规则外，引擎还提供了“克隆装饰器“对脚本字段的克隆方式进行定制。字段装饰器优先级最高 —— 会覆盖值类型的默认克隆行为，并在克隆走字段遍历的任何地方生效：组件顶层，以及任何本身被深克隆的对象内部（默认共享的值不会被逐字段遍历，其内部的装饰器也就不会被查询）。引擎内置三种克隆装饰：
| 装饰器名称 | 装饰器释义 |
-| :--- | :--- |
-| [ignoreClone](/apis/core/#ignoreClone) | 克隆时对字段进行忽略。 |
-| [assignmentClone](/apis/core/#assignmentClone) | ( 默认值，和不添加任何克隆装饰器等效) 克隆时对字段进行赋值。如果是基本类型则会拷贝值，如果是引用类型则会拷贝其引用地址。 |
-| [shallowClone](/apis/core/#shallowClone) | 克隆时对字段进行浅克隆。克隆后会保持自身引用独立，并使用赋值的方式克隆其内部所有字段（如果内部字段是基本类型则会拷贝值，如果内部字段是引用类型则会拷贝其引用地址）。|
-| [deepClone](/apis/core/#deepClone) | 克隆时对字段进行深克隆。克隆后会保持自身引用独立，并且其内部所有深层字段均保持完全独立。|
+| :-- | :-- |
+| [ignoreClone](/apis/core/#ignoreClone) | 克隆时对字段进行忽略，克隆体保留自身构造时的值。 |
+| [assignmentClone](/apis/core/#assignmentClone) | 克隆时对字段进行赋值。如果是基本类型则会拷贝值，如果是引用类型，克隆体将与源共享同一个引用。 |
+| [deepClone](/apis/core/#deepClone) | 深克隆字段子树中支持深克隆的值。深意图会传播进可按字段克隆的成员；资产保持共享、实体引用重映射、运行时状态保留克隆体自己的，未注册的不透明成员保持默认赋值行为。如果被装饰的值本身无法满足深克隆，例如 `Entity` / `Component`、资产、函数、运行时状态对象或不透明的平台对象，克隆会直接报错。 |
+
+
+ `@shallowClone` 已被移除。它旧有的“拷贝容器本身、共享内部成员”语义已不复存在。请按意图迁移：希望字段独立就使用
+ `@deepClone`，希望共享就使用 `@assignmentClone`。
+
+
+我们将上面的案例稍加修改,分别对 `CustomScript` 中的四个字段添加了不同的“克隆装饰器“。由于数组默认就会被深克隆，我们对字段 `c` 使用 `assignmentClone` 来强制共享，对字段 `d` 使用 `deepClone` 显式声明默认行为，并增加了额外的打印输出进行进一步讲解。
-我们将上面的案例稍加修改,分别对 `CustomScript` 中的四个字段添加了不同的“克隆装饰器“。由于 `shallowClone` 和 `deepCone` 较复杂，我们对字段 `c` 和 `d` 增加了额外的打印输出进行进一步讲解。
```typescript
// define a custom script
-class CustomScript extends Script{
+class CustomScript extends Script {
/** boolean type.*/
@ignoreClone
- a:boolean = false;
-
+ a: boolean = false;
+
/** number type.*/
@assignmentClone
- b:number = 1;
-
+ b: number = 1;
+
/** class type.*/
- @shallowClone
- c:Vector3[] = [new Vector3(0,0,0)];
-
+ @assignmentClone
+ c: Vector3[] = [new Vector3(0, 0, 0)];
+
/** class type.*/
@deepClone
- d:Vector3[] = [new Vector3(0,0,0)];
+ d: Vector3[] = [new Vector3(0, 0, 0)];
}
// Init entity and script
@@ -79,27 +136,32 @@ const entity = engine.createEntity();
const script = entity.addComponent(CustomScript);
script.a = true;
script.b = 2;
-script.c[0].set(1,1,1);
-script.d[0].set(1,1,1);
+script.c[0].set(1, 1, 1);
+script.d[0].set(1, 1, 1);
// Clone logic
const cloneEntity = entity.clone();
const cloneScript = cloneEntity.getComponent(CustomScript);
-console.log(cloneScript.a); // output is false,ignoreClone will ignore the value.
+console.log(cloneScript.a); // output is false,ignoreClone 使克隆体保留自身构造时的值。
console.log(cloneScript.b); // output is 2,assignmentClone is just assignment the origin value.
-console.log(cloneScript.c[0]); // output is Vector3(1,1,1),shallowClone clone the array shell,but use the same element.
+console.log(cloneScript.c[0]); // output is Vector3(1,1,1),assignmentClone 与源共享同一个数组实例。
console.log(cloneScript.d[0]); // output is Vector3(1,1,1),deepClone clone the array shell and also clone the element.
-cloneScript.c[0].set(2,2,2); // change the field c[0] value to (2,2,2).
-cloneScript.d[0].set(2,2,2); // change the field d[0] value to (2,2,2).
+cloneScript.c[0].set(2, 2, 2); // change the field c[0] value to (2,2,2).
+cloneScript.d[0].set(2, 2, 2); // change the field d[0] value to (2,2,2).
-console.log(script.c[0]); // output is (2,2,2). bacause shallowClone let c[0] use the same reference with cloneScript's c[0].
-console.log(script.d[0]); // output is (1,1,1). bacause deepClone let d[0] use the different reference with cloneScript's d[0].
+console.log(script.c[0]); // output is (2,2,2)，因为 assignmentClone 让 c 与 cloneScript.c 使用同一个数组引用。
+console.log(script.d[0]); // output is (1,1,1)，因为 deepClone 让 d[0] 与 cloneScript.d[0] 使用不同引用。
```
-- 注意:
- - `shallowClone` 和 `deepClone` 通常用于 *Object*、*Array* 和 *Class* 类型。
- - `shallowClone` 克隆后会保持自身引用独立，并使用赋值的方式克隆其内部所有字段（如果内部字段是基本类型则会拷贝值，如果内部字段是引用类型则会拷贝其引用地址）。
- - `deepClone` 为深克隆，会对属性进行深度递归，至于属性的子属性如何克隆，取决于子属性的装饰器。
- - 如果克隆装饰器不能满足诉求，可以通过实现 [_cloneTo()](/apis/design/#IClone-cloneTo) 方法追加自定义克隆。
+- 注意:
+
+ - 字段装饰器优先级最高，并且在克隆走字段遍历的任何地方对嵌套对象的字段同样生效。
+ - `deepClone` 会传播进容器和可按字段克隆的成员。没有深克隆默认的普通类实例会按字段复制，因此必须支持无参构造。资产保持共享，实体引用被重映射，运行时状态保留克隆体自己的，未注册的不透明成员保持共享，嵌套字段上的装饰器依然优先。
+ - 字段克隆采用刻意收窄的契约：只有对象自身可枚举的字符串键属性具有结构克隆语义。私有字段、不可枚举属性、Symbol 键以及原型或访问器状态不会被重建；引擎也不承诺识别运行时中所有可能的不透明状态。
+ - `deepClone` 无法直接克隆引擎绑定或不透明的值：对 `Entity` / `Component` 引用、资产、引擎运行时状态、函数或未注册的平台对象使用 `@deepClone` 会直接报错，因为这个显式意图无法被满足。请移除装饰器以回退到默认行为，或使用该值自身的克隆 API 得到真正的拷贝。
+ - 如果克隆装饰器不能满足诉求，可实现 [ICloneHook.\_onClone()](/apis/core/#ICloneHook-_onClone)，在字段自动克隆完成后追加类型特有的处理。
+
+## 克隆与资产引用计数
+克隆时，如果组件的顶层字段共享了一个引用计数资产（`ReferResource`，如 `Texture`、`Mesh`、`Material`），引擎会自动为克隆体增加一次引用计数，因此销毁源对象不会让资产在克隆体脚下被回收。内置组件会在销毁时释放自己持有的引用；被自定义脚本字段引用的资产则由克隆体一直保活 —— 不再需要时，调用资产自身的 `destroy()` 释放。
diff --git a/docs/zh/how-to-contribute.mdx b/docs/zh/how-to-contribute.mdx
index 6a995b5d89..e55d4c23c8 100644
--- a/docs/zh/how-to-contribute.mdx
+++ b/docs/zh/how-to-contribute.mdx
@@ -121,7 +121,7 @@ class CustomScript extends Script {
a:boolean = false;
@assignmentClone
b:number = 1;
- @shallowClone
+ @deepClone
c:Vector3[] = [new Vector3(0,0,0)];
}
```
@@ -135,7 +135,7 @@ class CustomScript extends Script{
a:boolean = false;
@assignmentClone
b:number = 1;
- @shallowClone
+ @deepClone
c:Vector3[] = [new Vector3(0,0,0)];
}
```
diff --git a/packages/core/src/2d/sprite/Sprite.ts b/packages/core/src/2d/sprite/Sprite.ts
index 5232001c9a..3021521f17 100644
--- a/packages/core/src/2d/sprite/Sprite.ts
+++ b/packages/core/src/2d/sprite/Sprite.ts
@@ -2,7 +2,7 @@ import { BoundingBox, MathUtil, Rect, Vector2, Vector4 } from "@galacean/engine-
import { Engine } from "../../Engine";
import { UpdateFlagManager } from "../../UpdateFlagManager";
import { ReferResource } from "../../asset/ReferResource";
-import { ignoreClone } from "../../clone/CloneManager";
+import { ignoreClone } from "../../clone/CloneDecorators";
import { Texture2D } from "../../texture/Texture2D";
import { SpriteAtlas } from "../atlas/SpriteAtlas";
import { SpriteModifyFlags } from "../enums/SpriteModifyFlags";
diff --git a/packages/core/src/2d/sprite/SpriteMask.ts b/packages/core/src/2d/sprite/SpriteMask.ts
index 1f740081f9..d61eec80cc 100644
--- a/packages/core/src/2d/sprite/SpriteMask.ts
+++ b/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/CloneDecorators";
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;
/**
@@ -191,10 +185,10 @@ export class SpriteMask extends Renderer implements ISpriteRenderer {
}
/**
- * @internal
+ * @inheritdoc
*/
- override _cloneTo(target: SpriteMask): void {
- super._cloneTo(target);
+ override _onClone(target: SpriteMask): void {
+ super._onClone(target);
target.sprite = this._sprite;
}
diff --git a/packages/core/src/2d/sprite/SpriteRenderer.ts b/packages/core/src/2d/sprite/SpriteRenderer.ts
index 2a6986af6a..ad0321b8a4 100644
--- a/packages/core/src/2d/sprite/SpriteRenderer.ts
+++ b/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/CloneDecorators";
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;
/**
@@ -284,10 +277,10 @@ export class SpriteRenderer extends Renderer implements ISpriteRenderer {
}
/**
- * @internal
+ * @inheritdoc
*/
- override _cloneTo(target: SpriteRenderer): void {
- super._cloneTo(target);
+ override _onClone(target: SpriteRenderer): void {
+ super._onClone(target);
target.sprite = this._sprite;
target.drawMode = this._drawMode;
}
diff --git a/packages/core/src/2d/text/TextRenderer.ts b/packages/core/src/2d/text/TextRenderer.ts
index 3649180c79..b18f370037 100644
--- a/packages/core/src/2d/text/TextRenderer.ts
+++ b/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/CloneDecorators";
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();
/** @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
*/
diff --git a/packages/core/src/Camera.ts b/packages/core/src/Camera.ts
index 55d904f6c9..a8f6e28530 100644
--- a/packages/core/src/Camera.ts
+++ b/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/CloneDecorators";
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
diff --git a/packages/core/src/Component.ts b/packages/core/src/Component.ts
index 2ebafbcd05..1c9bb68a71 100644
--- a/packages/core/src/Component.ts
+++ b/packages/core/src/Component.ts
@@ -1,7 +1,6 @@
import { IReferable } from "./asset/IReferable";
import { EngineObject } from "./base";
-import { assignmentClone, ignoreClone } from "./clone/CloneManager";
-import { CloneUtils } from "./clone/CloneUtils";
+import { CloneMode, ignoreClone, registerDefaultCloneMode } from "./clone/CloneDecorators";
import { Entity } from "./Entity";
import { ActiveChangeFlag } from "./enums/ActiveChangeFlag";
import { Scene } from "./Scene";
@@ -23,7 +22,6 @@ export class Component extends EngineObject {
@ignoreClone
private _phasedActive: boolean = false;
- @assignmentClone
private _enabled: boolean = true;
/**
@@ -154,13 +152,6 @@ export class Component extends EngineObject {
}
}
- /**
- * @internal
- */
- _remap(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);
}
@@ -178,3 +169,5 @@ export class Component extends EngineObject {
}
}
}
+
+registerDefaultCloneMode(Component, CloneMode.Remap);
diff --git a/packages/core/src/Entity.ts b/packages/core/src/Entity.ts
index eab8ce5aa2..c3cdbf43cf 100644
--- a/packages/core/src/Entity.ts
+++ b/packages/core/src/Entity.ts
@@ -10,7 +10,7 @@ import { Transform } from "./Transform";
import { UpdateFlagManager } from "./UpdateFlagManager";
import { ReferResource } from "./asset/ReferResource";
import { EngineObject } from "./base";
-import { CloneUtils } from "./clone/CloneUtils";
+import { CloneMode, registerDefaultCloneMode } from "./clone/CloneDecorators";
import { ComponentCloner } from "./clone/ComponentCloner";
import { ActiveChangeFlag } from "./enums/ActiveChangeFlag";
import { EntityModifyFlags } from "./enums/EntityModifyFlags";
@@ -421,8 +421,9 @@ export class Entity extends EngineObject {
* @returns Cloned entity
*/
clone(): Entity {
- const cloneEntity = this._createCloneEntity();
- this._parseCloneEntity(this, cloneEntity, this, cloneEntity, new Map());
+ const cloneMap = new Map();
+ const cloneEntity = this._createCloneEntity(cloneMap);
+ this._parseCloneEntity(this, cloneEntity, cloneMap);
return cloneEntity;
}
@@ -434,13 +435,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,7 +443,7 @@ export class Entity extends EngineObject {
this._templateResource = templateResource;
}
- private _createCloneEntity(): Entity {
+ private _createCloneEntity(cloneMap: Map): Entity {
const componentConstructors = Entity._tempComponentConstructors;
const components = this._components;
for (let i = 0, n = components.length; i < n; i++) {
@@ -457,6 +451,11 @@ export class Entity extends EngineObject {
}
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 +466,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
- ): void {
+ private _parseCloneEntity(src: Entity, target: Entity, cloneMap: Map): 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);
}
}
@@ -787,6 +780,8 @@ export class Entity extends EngineObject {
}
}
+registerDefaultCloneMode(Entity, CloneMode.Remap);
+
export type ComponentArguments Component> = T extends new (
entity: Entity,
...args: infer P
diff --git a/packages/core/src/Renderer.ts b/packages/core/src/Renderer.ts
index 5af1e71750..a9f368a7cc 100644
--- a/packages/core/src/Renderer.ts
+++ b/packages/core/src/Renderer.ts
@@ -7,7 +7,8 @@ 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/CloneDecorators";
+import type { ICloneHook } from "./clone/ICloneHook";
import { SpriteMaskLayer } from "./enums/SpriteMaskLayer";
import { Material } from "./material";
import { ShaderMacro, ShaderProperty } from "./shader";
@@ -20,7 +21,7 @@ import { ShaderDataGroup } from "./shader/enums/ShaderDataGroup";
* @decorator `@dependentComponents(Transform, DependentMode.CheckOnly)`
*/
@dependentComponents(Transform, DependentMode.CheckOnly)
-export class Renderer extends Component {
+export class Renderer extends Component implements ICloneHook {
private static _tempVector0 = new Vector3();
/** @internal */
@@ -48,9 +49,7 @@ export class Renderer extends Component {
@ignoreClone
_renderFrameCount: number;
/** @internal */
- @assignmentClone
_maskInteraction: SpriteMaskInteraction = SpriteMaskInteraction.None;
- @assignmentClone
_maskLayer: SpriteMaskLayer = SpriteMaskLayer.Layer0;
@ignoreClone
@@ -65,7 +64,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 +73,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;
/**
@@ -343,9 +339,9 @@ export class Renderer extends Component {
}
/**
- * @internal
+ * @inheritdoc
*/
- _cloneTo(target: Renderer): void {
+ _onClone(target: Renderer): void {
const materials = this._materials;
for (let i = 0, n = materials.length; i < n; i++) {
target._setMaterial(i, materials[i]);
diff --git a/packages/core/src/Script.ts b/packages/core/src/Script.ts
index 997901573d..4ee901e51a 100644
--- a/packages/core/src/Script.ts
+++ b/packages/core/src/Script.ts
@@ -1,6 +1,6 @@
import { Camera } from "./Camera";
import { Component } from "./Component";
-import { ignoreClone } from "./clone/CloneManager";
+import { ignoreClone } from "./clone/CloneDecorators";
import { PointerEventData } from "./input/pointer/PointerEventData";
import { ColliderShape } from "./physics";
import { Collision } from "./physics/Collision";
diff --git a/packages/core/src/Signal.ts b/packages/core/src/Signal.ts
index e337e03d9d..ca7c9c91ec 100644
--- a/packages/core/src/Signal.ts
+++ b/packages/core/src/Signal.ts
@@ -1,14 +1,16 @@
+import { DataObject } from "./base/DataObject";
+import { ignoreClone } from "./clone/CloneDecorators";
+import type { ICloneHook } from "./clone/ICloneHook";
import { Component } from "./Component";
import { Entity } from "./Entity";
-import { CloneUtils } from "./clone/CloneUtils";
-import { ignoreClone } from "./clone/CloneManager";
import { SafeLoopArray } from "./utils/SafeLoopArray";
/**
* Signal is a typed event mechanism for Galacean Engine.
* @typeParam T - Tuple type of the signal arguments
*/
-export class Signal {
+export class Signal extends DataObject implements ICloneHook> {
+ // Rebuilt by `_onClone`; must survive even a propagated @deepClone.
@ignoreClone
private _listeners: SafeLoopArray> = new SafeLoopArray>();
@@ -125,36 +127,31 @@ export class Signal {
}
/**
- * @internal
- * Clone listeners to target signal, remapping entity/component references.
+ * @inheritdoc
*/
- _cloneTo(target: Signal, srcRoot: Entity, targetRoot: Entity): void {
+ _onClone(target: Signal, cloneMap: ReadonlyMap): void {
const listeners = this._listeners.getLoopArray();
for (let i = 0, n = listeners.length; i < n; i++) {
const listener = listeners[i];
if (listener.destroyed || !listener.methodName) continue;
- const clonedTarget = CloneUtils.remapComponent(srcRoot, targetRoot, listener.target);
- if (clonedTarget) {
- const clonedArgs = this._cloneArguments(listener.arguments, srcRoot, targetRoot);
- if (listener.once) {
- target.once(clonedTarget, listener.methodName, ...clonedArgs);
- } else {
- target.on(clonedTarget, listener.methodName, ...clonedArgs);
- }
+ const clonedTarget = (cloneMap.get(listener.target) ?? listener.target);
+ const clonedArgs = this._cloneArguments(listener.arguments, cloneMap);
+ if (listener.once) {
+ target.once(clonedTarget, listener.methodName, ...clonedArgs);
+ } else {
+ target.on(clonedTarget, listener.methodName, ...clonedArgs);
}
}
}
- private _cloneArguments(args: any[], srcRoot: Entity, targetRoot: Entity): any[] {
+ private _cloneArguments(args: any[], cloneMap: ReadonlyMap): any[] {
if (!args || args.length === 0) return [];
const len = args.length;
const clonedArgs = new Array(len);
for (let i = 0; i < len; i++) {
const arg = args[i];
- if (arg instanceof Entity) {
- clonedArgs[i] = CloneUtils.remapEntity(srcRoot, targetRoot, arg);
- } else if (arg instanceof Component) {
- clonedArgs[i] = CloneUtils.remapComponent(srcRoot, targetRoot, arg);
+ if (arg instanceof Entity || arg instanceof Component) {
+ clonedArgs[i] = cloneMap.get(arg) ?? arg;
} else {
clonedArgs[i] = arg;
}
diff --git a/packages/core/src/Transform.ts b/packages/core/src/Transform.ts
index 5f1235caf0..234b3db8b9 100644
--- a/packages/core/src/Transform.ts
+++ b/packages/core/src/Transform.ts
@@ -2,12 +2,13 @@ import { MathUtil, Matrix, Matrix3x3, Quaternion, Vector3 } from "@galacean/engi
import { BoolUpdateFlag } from "./BoolUpdateFlag";
import { Component } from "./Component";
import { Entity } from "./Entity";
-import { assignmentClone, ignoreClone } from "./clone/CloneManager";
+import { ignoreClone } from "./clone/CloneDecorators";
+import type { ICloneHook } from "./clone/ICloneHook";
/**
* Used to implement transformation related functions.
*/
-export class Transform extends Component {
+export class Transform extends Component implements ICloneHook {
private static _tempQuat0: Quaternion = new Quaternion();
private static _tempVec30: Vector3 = new Vector3();
private static _tempVec31: Vector3 = new Vector3();
@@ -26,7 +27,6 @@ export class Transform extends Component {
private _rotationQuaternion: Quaternion = new Quaternion();
@ignoreClone
private _scale: Vector3 = new Vector3(1, 1, 1);
- @assignmentClone
private _localUniformScaling: boolean = true;
@ignoreClone
private _worldPosition: Vector3 = new Vector3();
@@ -579,9 +579,9 @@ export class Transform extends Component {
}
/**
- * @internal
+ * @inheritdoc
*/
- _cloneTo(target: Transform): void {
+ _onClone(target: Transform): void {
const { _position: position, _rotation: rotation, _scale: scale } = target;
// @ts-ignore
diff --git a/packages/core/src/UpdateFlag.ts b/packages/core/src/UpdateFlag.ts
index d926b47b8c..dd0798a42e 100644
--- a/packages/core/src/UpdateFlag.ts
+++ b/packages/core/src/UpdateFlag.ts
@@ -1,3 +1,4 @@
+import { CloneMode, registerDefaultCloneMode } from "./clone/CloneDecorators";
import { UpdateFlagManager } from "./UpdateFlagManager";
import { Utils } from "./Utils";
@@ -13,7 +14,7 @@ export abstract class UpdateFlag {
* @param bit - Bit
* @param param - Parameter
*/
- abstract dispatch(bit?: number, param?: Object): void;
+ abstract dispatch(bit?: number, param?: unknown): void;
/**
* Clear.
@@ -38,3 +39,5 @@ export abstract class UpdateFlag {
}
}
}
+
+registerDefaultCloneMode(UpdateFlag, CloneMode.Ignore);
diff --git a/packages/core/src/UpdateFlagManager.ts b/packages/core/src/UpdateFlagManager.ts
index 0e1e98ec90..154e85d66f 100644
--- a/packages/core/src/UpdateFlagManager.ts
+++ b/packages/core/src/UpdateFlagManager.ts
@@ -1,3 +1,4 @@
+import { CloneMode, registerDefaultCloneMode } from "./clone/CloneDecorators";
import { UpdateFlag } from "./UpdateFlag";
import { Utils } from "./Utils";
@@ -10,7 +11,7 @@ export class UpdateFlagManager {
_updateFlags: UpdateFlag[] = [];
- private _listeners: ((type?: number, param?: Object) => void)[] = [];
+ private _listeners: ((type?: number, param?: unknown) => void)[] = [];
/**
* Create a UpdateFlag.
@@ -46,7 +47,7 @@ export class UpdateFlagManager {
* Add a listener.
* @param listener - The listener
*/
- addListener(listener: (type?: number, param?: Object) => void): void {
+ addListener(listener: (type?: number, param?: unknown) => void): void {
this._listeners.push(listener);
}
@@ -54,7 +55,7 @@ export class UpdateFlagManager {
* Remove a listener.
* @param listener - The listener
*/
- removeListener(listener: (type?: number, param?: Object) => void): void {
+ removeListener(listener: (type?: number, param?: unknown) => void): void {
Utils.removeFromArray(this._listeners, listener);
}
@@ -63,7 +64,7 @@ export class UpdateFlagManager {
* @param type - Event type, usually in the form of enumeration
* @param param - Event param
*/
- dispatch(type?: number, param?: Object): void {
+ dispatch(type?: number, param?: unknown): void {
this.version++;
const updateFlags = this._updateFlags;
@@ -77,3 +78,5 @@ export class UpdateFlagManager {
}
}
}
+
+registerDefaultCloneMode(UpdateFlagManager, CloneMode.Ignore);
diff --git a/packages/core/src/VirtualCamera.ts b/packages/core/src/VirtualCamera.ts
index 4c8598888e..564fe473a3 100644
--- a/packages/core/src/VirtualCamera.ts
+++ b/packages/core/src/VirtualCamera.ts
@@ -1,10 +1,11 @@
+import { DataObject } from "./base/DataObject";
import { Matrix, Vector3 } from "@galacean/engine-math";
-import { ignoreClone } from "./clone/CloneManager";
+import { ignoreClone } from "./clone/CloneDecorators";
/**
* @internal
*/
-export class VirtualCamera {
+export class VirtualCamera extends DataObject {
isOrthographic: boolean = false;
nearClipPlane: number = 0.1;
farClipPlane: number = 100;
diff --git a/packages/core/src/animation/AnimationClip.ts b/packages/core/src/animation/AnimationClip.ts
index ef51647577..9238ce782c 100644
--- a/packages/core/src/animation/AnimationClip.ts
+++ b/packages/core/src/animation/AnimationClip.ts
@@ -55,7 +55,7 @@ export class AnimationClip extends EngineObject {
* @param time - The time when the event be triggered
* @param parameter - The parameter that is stored in the event and will be sent to the function
*/
- addEvent(functionName: string, time: number, parameter: Object): void;
+ addEvent(functionName: string, time: number, parameter: object): void;
/**
* Adds an animation event to the clip.
@@ -63,7 +63,7 @@ export class AnimationClip extends EngineObject {
*/
addEvent(event: AnimationEvent): void;
- addEvent(param: AnimationEvent | string, time?: number, parameter?: Object): void {
+ addEvent(param: AnimationEvent | string, time?: number, parameter?: object): void {
let newEvent: AnimationEvent;
if (typeof param === "string") {
const event = new AnimationEvent();
diff --git a/packages/core/src/animation/Animator.ts b/packages/core/src/animation/Animator.ts
index f58589955c..28031bcaf0 100644
--- a/packages/core/src/animation/Animator.ts
+++ b/packages/core/src/animation/Animator.ts
@@ -5,7 +5,8 @@ import { Entity } from "../Entity";
import { Renderer } from "../Renderer";
import { Script } from "../Script";
import { Logger } from "../base/Logger";
-import { assignmentClone, ignoreClone } from "../clone/CloneManager";
+import { ignoreClone } from "../clone/CloneDecorators";
+import type { ICloneHook } from "../clone/ICloneHook";
import { AnimatorController } from "./AnimatorController";
import { AnimatorControllerLayer } from "./AnimatorControllerLayer";
import { AnimatorControllerParameter, AnimatorControllerParameterValue } from "./AnimatorControllerParameter";
@@ -30,17 +31,15 @@ import { AnimationCurveOwner } from "./internal/animationCurveOwner/AnimationCur
/**
* The controller of the animation system.
*/
-export class Animator extends Component {
+export class Animator extends Component implements ICloneHook {
private static _passedTriggerParameterNames = new Array();
private static _tempScripts: Script[] = [];
/** Culling mode of this Animator. */
cullingMode: AnimatorCullingMode = AnimatorCullingMode.None;
/** The playback speed of the Animator, 1.0 is normal playback speed. */
- @assignmentClone
speed = 1.0;
/** Whether the Animator sends AnimationEvent callbacks. */
- @assignmentClone
fireEvents = true;
/** @internal */
@@ -48,9 +47,7 @@ export class Animator extends Component {
/** @internal */
_onUpdateIndex = -1;
- @assignmentClone
protected _animatorController: AnimatorController;
- @ignoreClone
protected _controllerUpdateFlag: BoolUpdateFlag;
@ignoreClone
protected _updateMark = 0;
@@ -348,12 +345,11 @@ export class Animator extends Component {
}
/**
- * @internal
+ * @inheritdoc
*/
- _cloneTo(target: Animator): void {
+ _onClone(target: Animator): void {
const animatorController = target._animatorController;
if (animatorController) {
- target._addResourceReferCount(animatorController, 1);
target._controllerUpdateFlag = animatorController._registerChangeFlag();
}
}
@@ -442,7 +438,7 @@ export class Animator extends Component {
layerIndex: number
): void {
const { entity, _curveOwnerPool: curveOwnerPool } = this;
- let { mask } = this._animatorController.layers[layerIndex];
+ const { mask } = this._animatorController.layers[layerIndex];
const { curveLayerOwner } = animatorStateData;
const { _curveBindings: curves } = animatorState.clip;
diff --git a/packages/core/src/animation/AnimatorController.ts b/packages/core/src/animation/AnimatorController.ts
index 1f8e91a01c..cda119f6d0 100644
--- a/packages/core/src/animation/AnimatorController.ts
+++ b/packages/core/src/animation/AnimatorController.ts
@@ -85,7 +85,7 @@ export class AnimatorController extends ReferResource {
*/
clearParameters(): void {
this._parameters.length = 0;
- for (let name in this._parametersMap) {
+ for (const name in this._parametersMap) {
delete this._parametersMap[name];
}
}
@@ -140,7 +140,7 @@ export class AnimatorController extends ReferResource {
}
layers.length = 0;
- for (let name in this._layersMap) {
+ for (const name in this._layersMap) {
delete this._layersMap[name];
}
this._updateFlagManager.dispatch();
diff --git a/packages/core/src/asset/ReferResource.ts b/packages/core/src/asset/ReferResource.ts
index 1460d048e8..87d52bdc43 100644
--- a/packages/core/src/asset/ReferResource.ts
+++ b/packages/core/src/asset/ReferResource.ts
@@ -1,4 +1,5 @@
import { EngineObject } from "../base/EngineObject";
+import { CloneMode, registerDefaultCloneMode } from "../clone/CloneDecorators";
import { Engine } from "../Engine";
import { IReferable } from "./IReferable";
@@ -109,3 +110,5 @@ export abstract class ReferResource extends EngineObject implements IReferable {
}
}
}
+
+registerDefaultCloneMode(ReferResource, CloneMode.Assignment);
diff --git a/packages/core/src/audio/AudioSource.ts b/packages/core/src/audio/AudioSource.ts
index b149e5609e..0157236a69 100644
--- a/packages/core/src/audio/AudioSource.ts
+++ b/packages/core/src/audio/AudioSource.ts
@@ -1,4 +1,4 @@
-import { assignmentClone, ignoreClone } from "../clone/CloneManager";
+import { ignoreClone } from "../clone/CloneDecorators";
import { Component } from "../Component";
import { Entity } from "../Entity";
import { AudioClip } from "./AudioClip";
@@ -16,7 +16,6 @@ export class AudioSource extends Component {
@ignoreClone
private _pendingPlay = false;
- @assignmentClone
private _clip: AudioClip;
@ignoreClone
private _gainNode: GainNode;
@@ -28,13 +27,9 @@ export class AudioSource extends Component {
@ignoreClone
private _playTime = -1;
- @assignmentClone
private _volume = 1;
- @assignmentClone
private _lastVolume = 1;
- @assignmentClone
private _playbackRate = 1;
- @assignmentClone
private _loop = false;
/**
@@ -220,14 +215,6 @@ export class AudioSource extends Component {
}
}
- /**
- * @internal
- */
- _cloneTo(target: AudioSource): void {
- target._clip?._addReferCount(1);
- // _volume is field-cloned; its gain node is applied lazily on first play
- }
-
/**
* @internal
*/
diff --git a/packages/core/src/base/DataObject.ts b/packages/core/src/base/DataObject.ts
new file mode 100644
index 0000000000..ba545b1cda
--- /dev/null
+++ b/packages/core/src/base/DataObject.ts
@@ -0,0 +1,9 @@
+import { CloneMode, registerDefaultCloneMode } from "../clone/CloneDecorators";
+
+/**
+ * Base class for objects whose own enumerable string-keyed properties are structurally cloned by default.
+ * Subclasses must support argument-less construction when no compatible preset exists.
+ */
+export abstract class DataObject {}
+
+registerDefaultCloneMode(DataObject, CloneMode.Deep);
diff --git a/packages/core/src/base/EngineObject.ts b/packages/core/src/base/EngineObject.ts
index 4354f3d61b..2783d29617 100644
--- a/packages/core/src/base/EngineObject.ts
+++ b/packages/core/src/base/EngineObject.ts
@@ -1,4 +1,4 @@
-import { ignoreClone } from "../clone/CloneManager";
+import { ignoreClone } from "../clone/CloneDecorators";
import { Engine } from "../Engine";
/**
diff --git a/packages/core/src/base/index.ts b/packages/core/src/base/index.ts
index 74cd4ac148..2870931b65 100644
--- a/packages/core/src/base/index.ts
+++ b/packages/core/src/base/index.ts
@@ -1,6 +1,7 @@
export { EventDispatcher } from "./EventDispatcher";
export { Logger } from "./Logger";
export { Time } from "./Time";
+export { DataObject } from "./DataObject";
export { EngineObject } from "./EngineObject";
export * from "./Constant";
diff --git a/packages/core/src/clone/CloneDecorators.ts b/packages/core/src/clone/CloneDecorators.ts
new file mode 100644
index 0000000000..71c88c3e13
--- /dev/null
+++ b/packages/core/src/clone/CloneDecorators.ts
@@ -0,0 +1,60 @@
+/** @internal */
+export const defaultCloneModeKey = Symbol("defaultCloneMode");
+/** @internal */
+export const fieldCloneModesKey = Symbol("fieldCloneModes");
+
+/**
+ * @internal
+ */
+export const enum CloneMode {
+ Ignore,
+ Assignment,
+ Remap,
+ Copy,
+ Deep
+}
+
+/**
+ * Property decorator — deep clone this field's whole subtree, overriding the value type's default
+ * clone mode (field-level decorators have the highest priority). The deep intent carries into
+ * field-cloneable members; engine-bound and platform objects keep their defaults. A decorator is
+ * an explicit intent: if the decorated value itself can't be deep cloned (an entity reference,
+ * asset, function, or object with opaque internal state), cloning throws rather than falling back.
+ * Field-cloned classes reproduce only their own enumerable string-keyed properties.
+ */
+export function deepClone(target: object, propertyKey: string): void {
+ CloneMetadata.registerFieldMode(target, propertyKey, CloneMode.Deep);
+}
+
+/**
+ * Property decorator — assign (share the reference) this field, overriding the value type's default clone mode.
+ */
+export function assignmentClone(target: object, propertyKey: string): void {
+ CloneMetadata.registerFieldMode(target, propertyKey, CloneMode.Assignment);
+}
+
+/**
+ * Property decorator — ignore this field when cloning; keep the clone's own constructor-built value.
+ */
+export function ignoreClone(target: object, propertyKey: string): void {
+ CloneMetadata.registerFieldMode(target, propertyKey, CloneMode.Ignore);
+}
+
+/**
+ * @internal
+ */
+export function registerDefaultCloneMode(target: { prototype: object }, mode: CloneMode): void {
+ Object.defineProperty(target.prototype, defaultCloneModeKey, { value: mode });
+}
+
+class CloneMetadata {
+ static registerFieldMode(target: any, propertyKey: string, mode: CloneMode): void {
+ if (!Object.prototype.hasOwnProperty.call(target, fieldCloneModesKey)) {
+ Object.defineProperty(target, fieldCloneModesKey, {
+ value: Object.create(target[fieldCloneModesKey] ?? null),
+ configurable: true
+ });
+ }
+ target[fieldCloneModesKey][propertyKey] = mode;
+ }
+}
diff --git a/packages/core/src/clone/CloneManager.ts b/packages/core/src/clone/CloneManager.ts
deleted file mode 100644
index be46462982..0000000000
--- a/packages/core/src/clone/CloneManager.ts
+++ /dev/null
@@ -1,198 +0,0 @@
-import { Entity } from "../Entity";
-import { TypedArray } from "../base/Constant";
-import { ICustomClone } from "./ComponentCloner";
-import { CloneMode } from "./enums/CloneMode";
-
-/**
- * Property decorator, ignore the property when cloning.
- */
-export function ignoreClone(target: Object, propertyKey: string): void {
- CloneManager.registerCloneMode(target, propertyKey, CloneMode.Ignore);
-}
-
-/**
- * Property decorator, assign value to the property when cloning.
- *
- * @remarks
- * If it's a primitive type, the value will be copied.
- * If it's a class type, the reference will be copied.
- */
-export function assignmentClone(target: Object, propertyKey: string): void {
- CloneManager.registerCloneMode(target, propertyKey, CloneMode.Assignment);
-}
-
-/**
- * Property decorator, shallow clone the property when cloning.
- * After cloning, it will keep its own reference independent, and use the method of assignment to clone all its internal properties.
- * if the internal property is a primitive type, the value will be copied, if the internal property is a reference type, its reference address will be copied.。
- *
- * @remarks
- * Applicable to Object, Array, TypedArray and Class types.
- */
-export function shallowClone(target: Object, propertyKey: string): void {
- CloneManager.registerCloneMode(target, propertyKey, CloneMode.Shallow);
-}
-
-/**
- * Property decorator, deep clone the property when cloning.
- * After cloning, it will maintain its own reference independence, and all its internal deep properties will remain completely independent.
- *
- * @remarks
- * Applicable to Object, Array, TypedArray and Class types.
- * If Class is encountered during the deep cloning process, the custom cloning function of the object will be called first.
- * Custom cloning requires the object to implement the IClone interface.
- */
-export function deepClone(target: Object, propertyKey: string): void {
- CloneManager.registerCloneMode(target, propertyKey, CloneMode.Deep);
-}
-
-/**
- * @internal
- * Clone manager.
- */
-export class CloneManager {
- /** @internal */
- static _subCloneModeMap = new Map();
- /** @internal */
- static _cloneModeMap = new Map();
-
- private static _objectType = Object.getPrototypeOf(Object);
-
- /**
- * Register clone mode.
- * @param target - Clone target
- * @param propertyKey - Clone property name
- * @param mode - Clone mode
- */
- static registerCloneMode(target: Object, propertyKey: string, mode: CloneMode): void {
- let targetMap = CloneManager._subCloneModeMap.get(target.constructor);
- if (!targetMap) {
- targetMap = Object.create(null);
- CloneManager._subCloneModeMap.set(target.constructor, targetMap);
- }
- targetMap[propertyKey] = mode;
- }
-
- /**
- * Get the clone mode according to the prototype chain.
- */
- static getCloneMode(type: Function): Object {
- let cloneModes = CloneManager._cloneModeMap.get(type);
- if (!cloneModes) {
- cloneModes = Object.create(null);
- CloneManager._cloneModeMap.set(type, cloneModes);
- const objectType = CloneManager._objectType;
- const cloneModeMap = CloneManager._subCloneModeMap;
- while (type !== objectType) {
- const subCloneModes = cloneModeMap.get(type);
- if (subCloneModes) {
- Object.assign(cloneModes, subCloneModes);
- }
- type = Object.getPrototypeOf(type);
- }
- }
- return cloneModes;
- }
-
- static cloneProperty(
- source: Object,
- target: Object,
- k: string | number,
- cloneMode: CloneMode,
- srcRoot: Entity,
- targetRoot: Entity,
- deepInstanceMap: Map
- ): void {
- const sourceProperty = source[k];
-
- // Remappable references (Entity/Component) are always remapped, regardless of clone decorator
- if (sourceProperty instanceof Object && (sourceProperty)._remap) {
- target[k] = (sourceProperty)._remap(srcRoot, targetRoot);
- return;
- }
-
- if (cloneMode === CloneMode.Ignore) return;
-
- // Primitives, undecorated, or @assignmentClone: direct assign
- if (!(sourceProperty instanceof Object) || cloneMode === undefined || cloneMode === CloneMode.Assignment) {
- target[k] = sourceProperty;
- return;
- }
-
- // @shallowClone / @deepClone: deep copy complex objects
- const type = sourceProperty.constructor;
- switch (type) {
- case Uint8Array:
- case Uint16Array:
- case Uint32Array:
- case Int8Array:
- case Int16Array:
- case Int32Array:
- case Float32Array:
- case Float64Array:
- let targetPropertyT = target[k];
- if (targetPropertyT == null || targetPropertyT.length !== (sourceProperty).length) {
- target[k] = (sourceProperty).slice();
- } else {
- targetPropertyT.set(sourceProperty);
- }
- break;
- case Array:
- let targetPropertyA = >target[k];
- const length = (>sourceProperty).length;
- if (targetPropertyA == null) {
- target[k] = targetPropertyA = new Array(length);
- } else {
- targetPropertyA.length = length;
- }
- for (let i = 0; i < length; i++) {
- CloneManager.cloneProperty(
- >sourceProperty,
- targetPropertyA,
- i,
- cloneMode,
- srcRoot,
- targetRoot,
- deepInstanceMap
- );
- }
- break;
- default:
- let targetProperty =