Fix/shaderlab

[luzhuang]

Please check if the PR fulfills these requirements

• The commit message follows our guidelines
• Tests for the changes have been added (for bug fixes / features)
• Docs have been added / updated (for bug fixes / features)

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

What is the current behavior? (You can also link to an open issue here)

What is the new behavior (if this is a feature change)?

Does this PR introduce a breaking change? (What changes might users need to make in their application due to this PR?)

Other information:

[GuoLei1990]

总结

本轮 PR 已经历大规模 rebase，diff 收敛到 221 个文件（packages/ 141 个，tests/ 36 个，e2e/ 21 个）。物理/UI clone 等子模块独立改动已包含在内，并有配套测试。主要新增内容：GLTFSceneParser 始终包装 GLTF_ROOT、AnimatorStatePlayData per-instance speed、UI RectMask2D / Mask 新组件、CloneManager 自动深克隆推断。

---

问题

[P0] e2e/config.ts 删除后 e2e/tests/index.spec.ts 仍然 import "../config" — CI 必然报错

PR diff 将 e2e/config.ts 整体删除（-518 行），但 e2e/tests/index.spec.ts（SHA 未变）仍有：

import { E2E_CONFIG } from "../config";
// ...
Object.entries(E2E_CONFIG).forEach(...)

合并后 e2e/tests/ 目录下找不到 ../config，playwright 跑 e2e suite 时会立即 import 失败，测试无法启动。e2e/global-setup.ts 虽然有 try-catch 降级（文件不存在时打印警告并继续），但 tests/index.spec.ts 没有任何降级，是硬依赖。

请二选一：

• 保留 e2e/config.ts（或迁移为新格式），并更新 tests/index.spec.ts 的 import 路径
• 如果 e2e 测试体系已整体迁移，同步删除 tests/index.spec.ts 或重写为不依赖 config 的格式

---

[P1] UIPointerEventEmitter._bubble — 冒泡结束后 currentTarget 未清空（已提 4 轮，持续未修复）

private _bubble(path: Entity[], pointer: Pointer, fireEvent: FireEvent): void {
  const length = path.length;
  if (length <= 0) return;
  const eventData = this._createEventData(pointer, path[0]);
  for (let i = 0; i < length; i++) {
    eventData.currentTarget = path[i];
    fireEvent(path[i], eventData);
  }
  // 缺少：eventData.currentTarget = null;
}

循环结束后 currentTarget 停留在 path[length - 1]。DOM 标准在 dispatch 结束后将 currentTarget 设为 null，请在循环后补一行：

eventData.currentTarget = null;

---

[P1] Collider._onUpdate — _onPhysicsUpdate 每帧对所有 shape 无条件调用（已提 2 轮，持续未修复）

// packages/core/src/physics/Collider.ts
for (let i = 0, n = shapes.length; i < n; i++) {
  shapes[i]._onPhysicsUpdate();
}

基类 ColliderShape._onPhysicsUpdate() 是空函数，仅 MeshColliderShape 且 _pendingNativeShapeCreation=true 时才有实际逻辑。每帧对每个 shape 执行虚调用是可避免的热路径开销。

最低成本修复：在 Collider 上加一个标记 _hasPendingShapeUpdate，仅在 MeshColliderShape 设置 _pendingNativeShapeCreation = true 时置为 true，创建成功后清除，_onUpdate 用该标记做 guard：

if (this._hasPendingShapeUpdate) {
  for (let i = 0, n = shapes.length; i < n; i++) {
    shapes[i]._onPhysicsUpdate();
  }
}

---

[P1] findAnimatorState 返回类型从 AnimatorState 改为 AnimatorStatePlayData — Breaking API Change，且"state 未在播放"时返回值语义不明确

// 新实现
findAnimatorState(stateName: string, layerIndex: number = -1): AnimatorStatePlayData {
  const { state, layerIndex: foundLayer } = this._getAnimatorStateInfo(stateName, layerIndex);
  if (!state || foundLayer < 0) return null;
  // ...
  if (layerData.srcPlayData.state === state) return layerData.srcPlayData;
  if (layerData.destPlayData.state === state) return layerData.destPlayData;
  // State exists in controller but not currently playing — return srcPlayData initialized with the state
  return layerData.srcPlayData;  // ← 当 state 未在播放时，返回当前正在播放的 srcPlayData！
}

当目标 state 存在于 controller 但当前未播放时（比如用户通过 findAnimatorState("Idle") 想预先修改 speed），返回的是当前正在播放的 srcPlayData（其 .state 可能是完全不同的动画）。这不仅语义错误，还会让用户误修改了正在播放的 state 的 speed。

建议：未在播放时返回 null，并在 JSDoc 中说明这一点；若需要支持预修改未播放状态的 speed，应提供独立 API。

另外，返回类型从 AnimatorState 改为 AnimatorStatePlayData 是 breaking change，需要 changelog 标注。

---

简化建议

DynamicCollider.applyForceAtPosition 缺少 isKinematic guard（已提 1 轮）

applyForceAtPosition(force: Vector3, position: Vector3): void {
  if (!this._phasedActiveInScene) return;
  const nativeCollider = <IDynamicCollider>this._nativeCollider;
  const localCoM = DynamicCollider._tempVector3;
  nativeCollider.getCenterOfMass(localCoM);  // ← kinematic 时这里仍会执行
  // ...
  nativeCollider.addForce(force);   // PhysX 层 _isKinematic guard 会拦截
  nativeCollider.addTorque(torque); // 同上
}

getCenterOfMass 跨 WASM 边界的调用在 kinematic actor 上是无意义的。建议和 addForce/addTorque 保持一致，在开头加 _isKinematic guard：

if (!this._phasedActiveInScene || this._isKinematic) return;

---

[P2] PointerEventData.target / currentTarget 类型声明不含 null（已提 4 轮，持续未修复）

target: Entity = null;
currentTarget: Entity = null;

应改为：

target: Entity | null = null;
currentTarget: Entity | null = null;