galacean · cptbtptpbcptdtptp · Jun 17, 2026 · Jun 17, 2026 · Jun 17, 2026 · Jun 22, 2026
diff --git a/docs/en/core/clone.mdx b/docs/en/core/clone.mdx
@@ -14,7 +14,7 @@ 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{
@@ -40,19 +40,62 @@ 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 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. |
+| Other objects | Share the reference (assignment). |
+
+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;
+
+// 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 take effect at any depth of the cloned object graph. 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 the field during cloning. The field gets a fresh, independent structure, and each inner member is cloned again according to its own semantics. Engine-bound values cannot be deep cloned: `Entity` / `Component` references fall back to remapping with a warning, and assets fall back to sharing with a warning. |
+
+<Callout type="negative">
+`@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.
+</Callout>
 
-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.
+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.
 ```typescript
 // define a custom script
 class CustomScript extends Script{
@@ -65,7 +108,7 @@ class CustomScript extends Script{
   b:number = 1;
 
   /** class type.*/
-  @shallowClone
+  @assignmentClone
   c:Vector3[] = [new Vector3(0,0,0)];
 
   /** class type.*/
@@ -84,20 +127,23 @@ 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).
 
-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.c[0]); // output is (2,2,2). bacause assignmentClone let c use the same array reference with cloneScript's c.
 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). bacause assignmentClone let c use the same array reference with cloneScript's c.
-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 let c use the same array reference with cloneScript's c.
+console.log(script.d[0]); // output is (1,1,1). because deepClone let d[0] use the different reference with cloneScript's d[0].
-console.log(script.c[0]); // output is (2,2,2). bacause assignmentClone let c use the same array reference with cloneScript's c.
-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 let c use the same array reference with cloneScript's c.
+console.log(script.d[0]); // output is (1,1,1). because deepClone let d[0] use the different reference with cloneScript's 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.
+  - Field decorators have the highest priority and also take effect on the fields of nested classes at any depth of the cloned object graph.
+  - `deepClone` recursively clones the structure, while each inner member is still cloned according to its own semantics: assets stay shared, entity references are remapped, and nested field decorators still apply.
+  - `deepClone` cannot deep clone engine-bound objects: `Entity` / `Component` references fall back to remapping and assets fall back to sharing, both with a warning. If you need a real copy of an asset, use the asset's own clone API.
   - If the clone decorators do not meet the requirements, you can implement the [_cloneTo()](/apis/design/#IClone-cloneTo) method to add custom 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. The class holding the field is responsible for releasing that reference when it is destroyed — built-in components already handle this; for custom scripts, release the resources you hold in `onDestroy`.
diff --git 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)];
 }