[Design experiment, based on #2999] Split AnimatorState asset and AnimatorStateInstance view

[GuoLei1990]

⚠️ This is a design-experiment PR, not intended for direct merge.

This PR is opened against `dev/2.0` for design discussion only. The
diff includes the full content of #2999 (luzhuang's per-state PlayData
work) because this design builds on top of that PR. Once this design
stabilizes here, the final form will be ported back to #2999 (e.g. as
a follow-up PR targeting `luzhuang:fix/animation-loader`).

Background

#2999 promotes the per-state `AnimatorStatePlayData` handle to a public
type so users can do `findAnimatorState("Walk").speed = 0.5` without
polluting the shared `AnimatorController` asset. The direction is
right, but the public surface leaves two issues open:

1. Two public types (`AnimatorState` + `AnimatorStatePlayData`):
   users have to learn which one they get from where and what
   `playData.state.xxx` does semantically.

2. Dual mutation paths on the same handle:

   • `playData.speed = 0.5` writes per-instance
   • `playData.state.speed = 0.5` writes the shared asset (broadcasts
     to every Animator using the same controller)

   Code review can't tell which is intended without context.

The Design

Split `AnimatorStatePlayData` into three concerns that were previously
tangled in one class:

Type	Visibility	Role
`AnimatorState` (new public class)	public	Per-Animator runtime view. Users get this from `findAnimatorState`. Surface: `speed` (per-instance), `name`/`clip`/`wrapMode`/`clipStartTime`/`clipEndTime` (readonly forwards from the shared asset).
`AnimatorStateDef` (former `AnimatorState` renamed)	public (editor/asset construction)	Shared asset on the controller. Returned by `AnimatorStateMachine.findStateByName` / `addState`; carried on `AnimatorStateTransition.destinationState`; consumed by `StateMachineScript` callbacks.
`AnimatorStateRuntime` (internal)	not exported	Engine-owned runtime bookkeeping (former `_playedTime` / `_clipTime` / `_playState` etc. underscore-prefixed fields on `AnimatorStatePlayData`).

User surface

```ts
const state = animator.findAnimatorState("Walk"); // AnimatorState | null

state.speed = 0.5; // ✅ per-instance, isolated
state.clip.length; // ✅ readonly view of shared asset
state.wrapMode; // ✅ readonly view
// state has no .def — no short-circuit to mutate the shared asset
```

To mutate the shared asset (broadcast — typical for editor / asset
construction), take the controller path. The longer path is a
deliberate visual reminder that the change is global:

```ts
animator.animatorController
.layers[0].stateMachine
.findStateByName("Walk")
.wrapMode = WrapMode.Once;
```

Why this is the right end state

• One public type for users (`AnimatorState`). No
  `AnimatorStatePlayData` / `AnimatorStateInstance` / `Handle`
  intermediate concept.
• `Animator` itself is already a per-component instance, so the
  object returned from `animator.xxx` is naturally per-Animator —
  no `Instance` suffix needed on the function or the type.
• Single mutation path on the view: `state.speed = ...` is the
  only write entry, and it is unambiguously per-instance.
• Asset mutation deliberately requires the long controller path,
  which is itself the visual warning that the change is broadcast.
• Industry-aligned: same shape as Unreal's
  `UAnimBlueprint` (shared asset) ↔ `UAnimInstance` (per-component
  view); same lazy-create pattern as Galacean's own
  `Renderer.getInstanceMaterial`.

Diff Composition

Three commits on top of #2999:

1. `fe78f5ecb` — Split AnimatorState into Def + view; introduce internal Runtime; drop `AnimatorStatePlayData`.
2. `e94f0366d` — Adapt tests / e2e / docs to the new view API.
3. `47fc4ba96` — Demote `AnimatorState.def` to `@internal _def` (the controller path is the only public way to reach the shared asset).

(The 51+ commits below those are #2999's own history; this PR only adds
those three on top.)

Status

• ✅ `npm run b:types` passes for all 13 packages
• ✅ `npm run b:module` builds clean
• ✅ Tests / e2e / docs type-check
• ⚠️ `tests/src/core/Animator.test.ts` reached 47/53 passing in
  one full run before local vitest+playwright went into a navigation
  timeout loop (test-infra issue, not the code). The remaining 6 were
  all stale `_playedTime` references already fixed in commit 2.

Outcome

If the design here lands as good, the final form will be ported back
to #2999 (`luzhuang:fix/animation-loader`) — either by cherry-pick or
by an explicit follow-up PR there, depending on what works best for
the author.

Summary by CodeRabbit

• New Features

  • Per-Animator state instances allowing animator-specific speed overrides.

• Bug Fixes

  • State query APIs now return null when missing; callers guard/throw accordingly.
  • More robust playback/crossfade handling, safer reverse/resume timing, and listener cleanup to prevent leaks.

• Documentation

  • Clarified pause/resume and per-instance vs shared state guidance with guarded examples.

• Tests

  • Expanded e2e and unit coverage for animator runtime, state-machine, skin/root handling, and edge cases.

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (1)

packages/core/src/animation/Animator.ts (1)

214-215: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Refresh controller-updated caches before returning the current state.

getCurrentAnimatorState() still bypasses _resetIfControllerUpdated(), so it can return a stale per-layer instance immediately after controller mutations.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/core/src/animation/Animator.ts` around lines 214 - 215,
getCurrentAnimatorState currently returns the per-layer instance without
refreshing controller-updated caches; call this._resetIfControllerUpdated() at
the start of getCurrentAnimatorState (before reading this._animatorLayersData)
so any controller mutations update internal caches first, then proceed to return
this._animatorLayersData[layerIndex]?.srcRuntime?.instance ?? null while
preserving the existing bounds/null behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/core/src/animation/Animator.ts`:
- Around line 831-838: The cross-fade progress currently uses
destRuntime.playedTime so if dstPlaySpeed === 0 the fade never completes;
instead introduce and advance an independent transition elapsed time (e.g.,
elapsedCrossTime) using the computed actualCostTime (or deltaTime) and derive
crossWeight = elapsedCrossTime / transitionDuration (clamped to 1.0), replacing
the use of Math.abs(destRuntime.playedTime) in the crossWeight calculation;
apply the same change to both places mentioned (the block around
actualCostTime/srcRuntime.update/destRuntime.update and the similar logic at
lines ~958-963) so fades complete even when destination playback is paused.

---

Duplicate comments:
In `@packages/core/src/animation/Animator.ts`:
- Around line 214-215: getCurrentAnimatorState currently returns the per-layer
instance without refreshing controller-updated caches; call
this._resetIfControllerUpdated() at the start of getCurrentAnimatorState (before
reading this._animatorLayersData) so any controller mutations update internal
caches first, then proceed to return
this._animatorLayersData[layerIndex]?.srcRuntime?.instance ?? null while
preserving the existing bounds/null behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 073aaf9b-53cb-4ab8-9e39-a7bcd735620d

📥 Commits

Reviewing files that changed from the base of the PR and between 47fc4ba and a4a6974.

📒 Files selected for processing (11)

• docs/en/animation/animator.mdx
• docs/zh/animation/animator.mdx
• e2e/case/animator-stateMachine.ts
• e2e/case/animator-stateMachineScript.ts
• packages/core/src/animation/Animator.ts
• packages/core/src/animation/AnimatorStateInstance.ts
• packages/core/src/animation/index.ts
• packages/core/src/animation/internal/AnimatorLayerData.ts
• packages/core/src/animation/internal/AnimatorStateData.ts
• packages/core/src/animation/internal/AnimatorStateRuntime.ts
• tests/src/core/Animator.test.ts

🚧 Files skipped from review as they are similar to previous changes (5)

• packages/core/src/animation/internal/AnimatorStateData.ts
• e2e/case/animator-stateMachine.ts
• docs/en/animation/animator.mdx
• docs/zh/animation/animator.mdx
• tests/src/core/Animator.test.ts

[GuoLei1990]

已关闭问题清单

问题	关闭原因
docs wrapMode 显示为可写	已修复
test 混淆 view vs def 断言 (._def)	已修复
srcRuntime.state 在 23 处引用为 undefined	已修复

---

总结

本轮引入了完整、成熟的三层架构（AnimatorStateInstance 公开视图 / AnimatorState 共享资产 / AnimatorStatePlayData 内部运行时），新增了大量高质量测试（clone 隔离、crossFade 别名守卫、self-transition no-op、out-of-range 边界、事件处理器懒刷新、GLTF skin LCA），架构方向和整体代码质量均已显著提升。

但以下问题连续五轮报告，仍未修复：2 个 P0（测试必然 fail）、2 个 P1（其中 1 个是五轮前标为"已修复"后被回归的生产 bug）。

---

问题

[P0] tests/src/core/Animator.test.ts:1365 — srcPlayData.speed 属性不存在（五轮持续未修复）

AnimatorStatePlayData 只有 instance 属性，没有 speed 属性。"per-instance speed survives crossFade out and back" 测试末尾：

expect(srcPlayData.speed).to.eq(0.5);  // 永远 undefined，断言必然 fail

修复：

expect(srcPlayData.instance.speed).to.eq(0.5);

---

[P0] tests/src/core/Animator.test.ts:1661, 1752 — destPlayData?.state.name 属性不存在（五轮持续未修复）

AnimatorStatePlayData 只有 instance 属性，没有 state 属性。?.state 为 undefined，expect(undefined).to.eq("Run") 必然 fail：

// 行 1661 — "play during crossFade clears stale destPlayData"
expect(layerData.destPlayData?.state.name).to.eq("Run");

// 行 1752 — "no-exit transition out of speed=0 source..."
expect(layerData.destPlayData?.state.name).to.eq("Walk");

修复：

expect(layerData.destPlayData?.instance.name).to.eq("Run");
expect(layerData.destPlayData?.instance.name).to.eq("Walk");

---

[P1] Animator.ts:207 — getCurrentAnimatorState 仍然缺少 _resetIfControllerUpdated（回归）

之前某轮标记为"已修复"，但当前代码里没有：

getCurrentAnimatorState(layerIndex: number): AnimatorStateInstance | null {
  // 缺少 this._resetIfControllerUpdated();
  return this._animatorLayersData[layerIndex]?.srcPlayData?.instance ?? null;
}

findAnimatorState（行 219）已调用 _resetIfControllerUpdated，两者语义对称。测试 "findAnimatorState resets stale layer data after controller mutation" 也验证了 findAnimatorState 在 controller 变更后 reset 并返回新 handle，但 getCurrentAnimatorState 相同路径没有覆盖。

修复：

getCurrentAnimatorState(layerIndex: number): AnimatorStateInstance | null {
+   this._resetIfControllerUpdated();
  return this._animatorLayersData[layerIndex]?.srcPlayData?.instance ?? null;
}

同一测试文件行 205 区域的断言 (animatorState as any)._state vs currentAnimatorState 类型不匹配：_state 是 AnimatorState（共享资产），currentAnimatorState 是 AnimatorStateInstance | null，永远不等。正确写法：

expect(animatorState).to.eq(currentAnimatorState);
// 行 209：
expect(animatorState).not.to.eq(currentAnimatorState);
expect(animatorState.name).to.eq(expectedStateName);

---

[P1] Animator.ts:799, 924 — dest state speed=0 时 cross-fade 永远无法完成（五轮持续未修复）

_updateCrossFadeState（行 799）和 _updateFixedCrossFadeState（行 924）：

let crossWeight = Math.abs(destPlayData.playedTime) / transitionDuration;

当 dstPlaySpeed === 0 时，destPlayData.update(0) 使 playedTime 永不增加，crossWeight 永远为 0，过渡卡死。actualCostTime 已正确计算出挂钟时间（dstPlaySpeed === 0 ? deltaTime : ...），但从未用来驱动 crossWeight。

新测试 "transition out of a state with per-instance speed 0..." 覆盖的是 src speed=0 的路径，不是 dest speed=0 的路径，且断言只检查 playedTime > 0，没有验证 crossWeight 能否达到 1.0（过渡是否能完成）。

根本修复：在 AnimatorLayerData 引入独立的 transitionElapsed 字段，每帧累加 actualCostTime，替换 destPlayData.playedTime 驱动 crossWeight：

// AnimatorLayerData.ts
transitionElapsed: number = 0;

// completeCrossFade / clearCrossFadeSlot 中将其清零：
completeCrossFade(): void {
  this.transitionElapsed = 0;
  // ...
}
clearCrossFadeSlot(): void {
  this.transitionElapsed = 0;
  // ...
}

// Animator.ts — _updateCrossFadeState & _updateFixedCrossFadeState
layerData.transitionElapsed += actualCostTime;
let crossWeight = Math.abs(layerData.transitionElapsed) / transitionDuration;

[GuoLei1990]

已将本 PR 的所有 commits 直接 push 到 PR #2999 的分支 (luzhuang/engine:fix/animation-loader),保留 @luzhuang 作为 PR #2999 的原作者署名。本 PR 工作完整合并到 #2999,关闭。