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]

总结

fix/shaderlab 是一个 237 文件的集成分支，大多数变更已被拆成独立 sub-PR（#2987、#2988、#2991、#2992、#2993 等）单独审查。这个 PR 本身不应再作为独立变更合入。

建议

[P1] PR 描述为空，没有摘要、没有勾选 checklist，也没有标注 breaking changes。无法判断哪些变更是该 PR 独有的、哪些已经在 sub-PR 中覆盖。

建议处理方式：等所有 sub-PR 合入 dev/2.0 后，将此 PR 关闭而非合并。唯一独有的内容（e2e vite config 更新、physx WASM 二进制更新）通过干净的 cherry-pick PR 单独提交，避免将 237 文件 omnibus 合入主分支产生无法 bisect 的历史。

[P2] e2e/case/particleRenderer-dream.ts — updateForE2E 和 initScreenshot 被注释掉，该 e2e case 不会执行截图对比，PR 多轮 review 中已提及但未修复。

[GuoLei1990]

审查（2026-05-26）

已关闭问题清单（来自上轮 bde8c614 审查前的状态）

问题	状态
P1 Collider._onUpdate/_onPhysicsUpdate 循环	✅ 已修复
P1/P2 UIPointerEventEmitter._bubble currentTarget	✅ 已修复
cofactor-form 正常矩阵	✅ 已修复（_normalMatFromModel 使用 cross product 形式）
.aac/.flac AudioLoader 扩展名	✅ 已合入

以下问题仍未修复（历史多轮 CHANGES_REQUESTED 未处理）：

---

问题

[P0] e2e/config.ts 仍不存在，CI Playwright suite 无法启动

本 PR 当前 HEAD bde8c614 上 e2e/config.ts 不存在（或已被删除），而 e2e/tests/index.spec.ts 中硬编码 import { E2E_CONFIG } from "../config"。合并后 Playwright 测试立即报 import 失败。此问题已提 8+ 轮，仍未修复。

[P1] packages/core/src/animation/Animator.ts:237 — findAnimatorState 末尾 fallback 返回错误状态

// State exists in controller but not currently playing — return srcPlayData initialized with the state
return layerData.srcPlayData;  // ← state 不匹配，返回正在播放的另一个动画的 playData

注释自述"state 未在播放"，但实际返回 srcPlayData（其 .state 是正在播放的另一个动画），调用方若据此修改 speed，影响的是错误的动画。应返回 null：

return null;

[P1] tests/src/core/Animator.test.ts — crossfade 测试绕开公开 API，戳私有字段

const layerData = animator["_animatorLayersData"][0];  // 私有字段
layerData.srcPlayData.speed = 0.25;
layerData.destPlayData.speed = 0.25;

这个测试验证的是 crossfade 期间 src/dest 各自的 per-instance speed，应通过 findAnimatorState() 公开 API 获取，而不是绕开测试该 API 的存在意义。revert findAnimatorState 后测试仍然绿，说明它没有守住被测 bug。

---

本轮新增内容审查（自上轮 4a568170 以来的 commit）

子 PR 已在各自独立 PR 中审查：

• Clone 修复 → #2992 ✓
• Signal 修复 → #2987 ✓
• Camera 克隆 → #2988 ✓
• Entity clearChildren → #2991 ✓
• SceneLoader cache → #2993 ✓
• cofactor 正常矩阵 → 本 PR 已确认 ✓

P0 + P1 修复后合入。

[GuoLei1990]

增量审查（2026-05-28）

已关闭问题清单（来自上轮 bde8c614 审查）

问题	状态
P1 Collider._onUpdate/_onPhysicsUpdate 循环	✅ 已修复
P1 UIPointerEventEmitter._bubble currentTarget	✅ 已修复
cofactor-form 正常矩阵	✅ 已确认正确

以下问题仍未修复：

---

[P0] e2e/config.ts 缺失 — CI 必然失败（已提 10+ 轮，仍未修复）

当前 HEAD 07abbc4b 上 e2e/config.ts 不存在，而 e2e/tests/index.spec.ts:2 仍为：

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

硬编码 import，无 fallback。合并后 Playwright suite 立即报 import 失败，无法启动。

---

[P1] packages/core/src/animation/Animator.ts:241 — findAnimatorState 末尾 fallback 返回错误数据（已提 10+ 轮，仍未修复）

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;  // ← 注释自述"未在播放"，但返回的是正在播放的 srcPlayData，其 .state 是另一个动画

调用者 findAnimatorState("Idle") 在非 Idle 播放期间，拿到的 playData.state 是正在播放的另一个动画，修改其 .speed 会静默影响错误的动画。应返回 null：

return null;

---

[P1] tests/src/core/Animator.test.ts — crossfade 测试戳私有字段，绕开被测 API（已提 7+ 轮，仍未修复）

const layerData = animator["_animatorLayersData"][0];  // ← 私有字段
layerData.srcPlayData.speed = 0.25;
layerData.destPlayData.speed = 0.25;

crossfade 修复的核心路径是 findAnimatorState() 在 crossfade 期间为 src/dest 各返回正确的 per-instance playData。绕开公开 API 直接操作内部结构，导致 revert findAnimatorState 修复后测试仍然绿，无法守住回归。正确写法：

animator.play("Walk");
animator.crossFade("Run", 1.0, 0);
const walkPlayData = animator.findAnimatorState("Walk");
const runPlayData = animator.findAnimatorState("Run");
walkPlayData.speed = 0.25;
runPlayData.speed = 0.25;
sharedWalkState.speed = 10;
sharedRunState.speed = 10;
// 断言 playedTime 按 0.25× 推进而非 10×

---

本轮新增内容审查（bde8c614 → 07abbc4b）

fix(animation) — Animator destroy 时移除 clipChangedListener [正确，无问题]

AnimatorStateData 新增 clipChangedListener 字段，_reset() 调用 removeListener 后置 null，_onDestroy 调用 _reset()。内存泄漏修复方向正确，路径完整。

refactor(clone) — 用 ReferResource 判断 deep vs assignment [正确，无问题]

_inferCloneMode 新逻辑：ReferResource 走 Assignment（引用计数管理的共享资产保持引用共享），其余走 Deep。相比上轮基于"target 已有同类实例"的启发式，这个判断更精确，消除了将构造器创建的 value class 误判为 Assignment 的 bug。方向正确。

refactor(ui) — Text._updateBounds 改用缓存 localBounds [正确，无问题]

_updateBounds 直接 BoundingBox.transform(this._localBounds, worldMatrix, worldBounds)，消除 min/max 重复推导，与其他 UIRenderer 子类保持一致。无问题。

---

P0 + P1 修复后合入。

[GuoLei1990]

增量审查（2026-06-02 @ 8c5a07003）

已关闭问题清单（上轮 7c521e2a 遗留）

问题	状态
P0 e2e/config.ts 缺失 → CI import 失败	❌ 仍未修复（HEAD 上仍 404）
P1 Animator.findAnimatorState 末尾 fallback 返回错误 playData	❌ 仍未修复（Animator.ts:241 仍 return layerData.srcPlayData）
P1 crossfade 测试戳私有 _animatorLayersData	❌ 仍未修复（Animator.test.ts:252-254 仍走私有路径）

新增 commit（instancing sampler 守卫、animation weakmap、transform _isFrontFaceInvert cache、per-queue batch state 隔离、RT pool）方向独立合理，但都没碰上述 3 条历史遗留。

---

仍未修复（重申，非重复打补丁——这 3 条是 verified 仍 broken，不是已关闭）

[P0] e2e/config.ts 缺失 — CI 必然报错

e2e/tests/index.spec.ts:2 仍硬 import ../config 且无 fallback，文件在 HEAD 8c5a07003 上仍不存在。合并后 Playwright suite 立即 import 失败、整套 e2e 无法启动。这是合并的硬阻塞。

[P1] Animator.ts:241 — findAnimatorState fallback 语义错误（aspirational comment）

// State exists in controller but not currently playing — return srcPlayData initialized with the state
return layerData.srcPlayData;   // ← 注释说"未在播放"，实际返回正在播放的 srcPlayData，其 .state 是另一个动画

注释承诺的行为与代码相反。调用方在非目标 state 播放期间调用会拿到错误动画的 playData，静默改错动画速度。应 return null。

[P1] Animator.test.ts:252 — crossfade 测试绕开被测 API

测试直接 animator["_animatorLayersData"][0].srcPlayData.speed = ... 并断言私有字段，把 findAnimatorState 这条修复路径整个绕过 —— revert findAnimatorState 修复后测试仍绿，守不住回归。应改为从 animator.findAnimatorState("Walk"/"Run") 公开入口取 per-instance playData，断言 playedTime 按预期 speed 推进。

---

变更单元粒度（已提过，仅确认趋势）

本 PR 当前 242 文件 / +11.6k−2.5k，横跨 shader-lab / loader / gltf / physics-physx / physics-lite / rhi-webgl / ui / shader / scene-schema 九个域，标题仍是 "Fix/shaderlab"。这个体量无法作为单一变更单元被有效 review 或回滚。团队已在做拆分（#3014 "cherry-pick fixes from fix/shaderlab"、#2999 "从 #2983 抽离动画与 GLTF 加载器修复"、#3015 抽 RT pool）——方向正确，建议把剩余正交域继续抽成独立 PR，让本 branch 收敛或关闭。不再展开重复此点。

---

结论

P0（e2e/config 缺失）+ 2×P1（findAnimatorState 语义 / 测试绕过）均为 verified 仍未修复，继续 request changes。新增工作建议优先随拆分 PR（#3014/#2999/#3015）合入，而非继续堆进本 monolith。