galacean · GuoLei1990 · Sep 5, 2025 · Jul 8, 2025 · Jul 9, 2025 · Jul 9, 2025
diff --git a/packages/core/src/Transform.ts b/packages/core/src/Transform.ts
@@ -50,7 +50,7 @@ export class Transform extends Component {
   private _worldUp: Vector3 = null;
 
   @ignoreClone
-  private _isParentDirty: boolean = true;
+  protected _isParentDirty: boolean = true;
   @ignoreClone
   private _parentTransformCache: Transform = null;
   private _dirtyFlag: number = TransformModifyFlags.WmWpWeWqWs;
@@ -261,16 +261,18 @@ export class Transform extends Component {
     const { _position: position, _rotationQuaternion: rotationQuaternion, _scale: scale } = this;
     // @ts-ignore
     position._onValueChanged = rotationQuaternion._onValueChanged = scale._onValueChanged = null;
-    this._localMatrix.decompose(position, rotationQuaternion, scale);
+
+    value.decompose(position, rotationQuaternion, scale);
+    this._onLocalMatrixChanging?.();
+    this._setDirtyFlagTrue(TransformModifyFlags.LocalEuler);
+    this._setDirtyFlagFalse(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
+
-    value.decompose(position, rotationQuaternion, scale);
-    this._onLocalMatrixChanging?.();
-    this._setDirtyFlagTrue(TransformModifyFlags.LocalEuler);
-    this._setDirtyFlagFalse(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
+    const ok = value.decompose(position, rotationQuaternion, scale);
+    this._onLocalMatrixChanging?.();
+    if (!ok) {
+      // Fallback: extract translation; reset rotation to identity and scale to defaults.
+      value.getTranslation(position);
+      rotationQuaternion.set(0, 0, 0, 1);
+      scale.set(1, 1, 1);
+    }
+    this._setDirtyFlagTrue(TransformModifyFlags.LocalEuler);
+    this._setDirtyFlagFalse(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
-    value.decompose(position, rotationQuaternion, scale);
-    this._onLocalMatrixChanging?.();
-    this._setDirtyFlagTrue(TransformModifyFlags.LocalEuler);
-    this._setDirtyFlagFalse(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
+    const ok = value.decompose(position, rotationQuaternion, scale);
+    this._onLocalMatrixChanging?.();
+    if (!ok) {
+      // Fallback: extract translation; reset rotation to identity and scale to defaults.
+      value.getTranslation(position);
+      rotationQuaternion.set(0, 0, 0, 1);
+      scale.set(1, 1, 1);
+    }
+    this._setDirtyFlagTrue(TransformModifyFlags.LocalEuler);
+    this._setDirtyFlagFalse(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
     // @ts-ignore
     position._onValueChanged = this._onPositionChanged;
     // @ts-ignore
     rotationQuaternion._onValueChanged = this._onRotationQuaternionChanged;
     // @ts-ignore
     scale._onValueChanged = this._onScaleChanged;
-
-    this._setDirtyFlagTrue(TransformModifyFlags.LocalEuler);
-    this._setDirtyFlagFalse(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
     const localUniformScaling = scale.x === scale.y && scale.y === scale.z;
     if (this._localUniformScaling !== localUniformScaling) {
       this._localUniformScaling = localUniformScaling;
@@ -309,7 +311,7 @@ export class Transform extends Component {
       this._localMatrix.copyFrom(value);
     }
     this.localMatrix = this._localMatrix;
-    this._setDirtyFlagFalse(TransformModifyFlags.WorldMatrix);
+    this._onWorldMatrixChange();
   }
 
   /**
@@ -584,22 +586,71 @@ export class Transform extends Component {
     target._scale.copyFrom(this.scale);
   }
 
-  protected override _onDestroy(): void {
-    super._onDestroy();
-    //@ts-ignore
-    this._worldPosition._onValueChanged = null;
-    //@ts-ignore
-    this._rotation._onValueChanged = null;
-    //@ts-ignore
-    this._worldRotation._onValueChanged = null;
-    //@ts-ignore
-    this._rotationQuaternion._onValueChanged = null;
-    //@ts-ignore
-    this._worldRotationQuaternion._onValueChanged = null;
-    //@ts-ignore
-    this._position._onValueChanged = null;
-    //@ts-ignore
-    this._scale._onValueChanged = null;
+  protected _onLocalMatrixChanging?(): void;
+
+  protected _onWorldMatrixChange() {
+    this._setDirtyFlagFalse(TransformModifyFlags.WorldMatrix);
+  }
+
+  protected _isContainDirtyFlags(targetDirtyFlags: number): boolean {
+    return (this._dirtyFlag & targetDirtyFlags) === targetDirtyFlags;
+  }
+
+  protected _isContainDirtyFlag(type: number): boolean {
+    return (this._dirtyFlag & type) != 0;
+  }
+
+  protected _setDirtyFlagTrue(type: number) {
+    this._dirtyFlag |= type;
+  }
+
+  protected _setDirtyFlagFalse(type: number) {
+    this._dirtyFlag &= ~type;
+  }
+
+  protected _worldAssociatedChange(type: number): void {
+    const dispatchFlags = type & ~this._dirtyFlag;
+    this._dirtyFlag |= type;
+    this._entity._updateFlagManager.dispatch(dispatchFlags);
+  }
+
+  protected _getParentTransform(): Transform | null {
+    if (!this._isParentDirty) {
+      return this._parentTransformCache;
+    }
+    let parentCache: Transform = null;
+    let parent = this._entity.parent;
+    while (parent) {
+      const transform = parent.transform;
+      if (transform) {
+        parentCache = transform;
+        break;
+      } else {
+        parent = parent.parent;
+      }
+    }
+    this._parentTransformCache = parentCache;
+    this._isParentDirty = false;
+    return parentCache;
+  }
+
+  @ignoreClone
+  protected _onPositionChanged(): void {
+    this._setDirtyFlagTrue(TransformModifyFlags.LocalMatrix);
+    this._updateWorldPositionFlag();
+  }
+
+  @ignoreClone
+  protected _onWorldPositionChanged(): void {
+    const worldPosition = this._worldPosition;
+    const parent = this._getParentTransform();
+    if (parent) {
+      Matrix.invert(parent.worldMatrix, Transform._tempMat41);
+      Vector3.transformCoordinate(worldPosition, Transform._tempMat41, this._position);
+    } else {
+      this._position.copyFrom(worldPosition);
+    }
+    this._setDirtyFlagFalse(TransformModifyFlags.WorldPosition);
   }
 
   /**
@@ -708,26 +759,6 @@ export class Transform extends Component {
     }
   }
 
-  private _getParentTransform(): Transform | null {
-    if (!this._isParentDirty) {
-      return this._parentTransformCache;
-    }
-    let parentCache: Transform = null;
-    let parent = this._entity.parent;
-    while (parent) {
-      const transform = parent.transform;
-      if (transform) {
-        parentCache = transform;
-        break;
-      } else {
-        parent = parent.parent;
-      }
-    }
-    this._parentTransformCache = parentCache;
-    this._isParentDirty = false;
-    return parentCache;
-  }
-
   private _getScaleMatrix(): Matrix3x3 {
     const invRotation = Transform._tempQuat0;
     const invRotationMat = Transform._tempMat30;
@@ -740,27 +771,6 @@ export class Transform extends Component {
     return scaMat;
   }
 
-  private _isContainDirtyFlags(targetDirtyFlags: number): boolean {
-    return (this._dirtyFlag & targetDirtyFlags) === targetDirtyFlags;
-  }
-
-  private _isContainDirtyFlag(type: number): boolean {
-    return (this._dirtyFlag & type) != 0;
-  }
-
-  private _setDirtyFlagTrue(type: number) {
-    this._dirtyFlag |= type;
-  }
-
-  private _setDirtyFlagFalse(type: number) {
-    this._dirtyFlag &= ~type;
-  }
-
-  private _worldAssociatedChange(type: number): void {
-    this._dirtyFlag |= type;
-    this._entity._updateFlagManager.dispatch(type);
-  }
-
   private _rotateByQuat(rotateQuat: Quaternion, relativeToLocal: boolean): void {
     if (relativeToLocal) {
       Quaternion.multiply(this.rotationQuaternion, rotateQuat, this._rotationQuaternion);
@@ -786,25 +796,6 @@ export class Transform extends Component {
     this._rotateByQuat(rotQuat, relativeToLocal);
   }
 
-  @ignoreClone
-  private _onPositionChanged(): void {
-    this._setDirtyFlagTrue(TransformModifyFlags.LocalMatrix);
-    this._updateWorldPositionFlag();
-  }
-
-  @ignoreClone
-  private _onWorldPositionChanged(): void {
-    const worldPosition = this._worldPosition;
-    const parent = this._getParentTransform();
-    if (parent) {
-      Matrix.invert(parent.worldMatrix, Transform._tempMat41);
-      Vector3.transformCoordinate(worldPosition, Transform._tempMat41, this._position);
-    } else {
-      this._position.copyFrom(worldPosition);
-    }
-    this._setDirtyFlagFalse(TransformModifyFlags.WorldPosition);
-  }
-
   @ignoreClone
   private _onRotationChanged(): void {
     this._setDirtyFlagTrue(TransformModifyFlags.LocalMatrix | TransformModifyFlags.LocalQuat);
@@ -884,7 +875,7 @@ export class Transform extends Component {
 }
 
 /**
- * @internal
+ * Dirty flag of transform.
  */
 export enum TransformModifyFlags {
   LocalEuler = 0x1,

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
@@ -14,7 +14,7 @@ export { Script } from "./Script";
 export { Renderer, RendererUpdateFlags } from "./Renderer";
 export { dependentComponents, DependentMode } from "./ComponentsDependencies";
 export { Camera } from "./Camera";
-export { Transform } from "./Transform";
+export { Transform, TransformModifyFlags } from "./Transform";
 export { BoolUpdateFlag } from "./BoolUpdateFlag";
 export type { EngineSettings } from "./EngineSettings";
 export type { EngineConfiguration } from "./Engine";