fix(animation, loader): 从 #2983 抽离动画与 GLTF 加载器修复

[luzhuang]

Summary

从 #2983 抽离动画 + GLTF 加载器修复，独立 PR 便于 review 与合入 dev/2.0。

物理 raycast/sweep 修复同步抽离至 #2998。

动画 — Shared asset + per-Animator view

把 AnimatorState 一分为二：共享资产（AnimatorState，继续是 controller 持有的资源）和 per-Animator 视图（AnimatorStateInstance，新增类型）。视图按 (Animator, state) 对惰性创建，放在 AnimatorLayerData 的 WeakMap 里；视图上的 override 只影响所属 Animator，其它共享同一 controller 的 Animator 不受影响。

公开 API

• findAnimatorState(name, layerIdx?): AnimatorStateInstance | null — 返回该 Animator 上的视图（lazy create on first access）；controller mutation 后失效，需要重新调用获取新视图
• getCurrentAnimatorState(layerIndex): AnimatorStateInstance | null — 返回当前正在播的视图；同样在 controller mutation 后失效
• AnimatorStateInstance.speed / wrapMode — per-instance overrideable；未覆盖时 fall-through 到底层 AnimatorState 资产（编辑器调 asset 仍能传递到未声明 override 的 instance），覆盖后该 instance 独立持有自己的值
• AnimatorStateInstance.name / clip / clipStartTime / clipEndTime — 透传访问底层资产字段

真 Bug 修复（用户视角）

每条均以"用户场景 → 现象 → 修复后"描述。

1. 越界 layerIndex 调用 API 时崩溃

   • 用户：animator.play("walk", 99) / crossFade("walk", 0.3, 99) / findAnimatorState("walk", 99) / getCurrentAnimatorState(99)
   • 旧：layers[99].stateMachine 抛 TypeError: Cannot read property 'stateMachine' of undefined
   • 新：safe no-op（play/crossFade 不动，find/getCurrent 返回 null）

2. state 没绑 clip 时调 findAnimatorState 崩溃

   • 用户：在 state 还没设置 clip 之前查这个 state（编辑器/异步加载场景常见）
   • 旧：访问 state.clip.length 抛 NPE
   • 新：正常返回 instance；播放时改为 logger warn

3. 暂停状态（instance.speed = 0）transition 时下一帧目标 state 卡住

   • 用户：把某个 state 的 speed 设为 0 当暂停，然后 transition 到下一个 state
   • 旧：剩余 deltaTime 计算 0 / 0 = NaN，目标 state 这一帧 deltaTime 完全丢失，看起来卡了一帧
   • 新：speed=0 时整个 deltaTime 直接传给目标，过渡平滑

4. play("A") 中断 fade 后，再 crossFade 到原 fade 目标失效

   • 用户：A→B fade 进行中改主意 play("C")，之后又想 crossFade("B")
   • 旧：残留的 destPlayData 触发 active-dest guard，第二次 crossFade 被静默吞掉
   • 新：play 自动清理残留 fade 状态，后续 crossFade 正常生效

5. 同名 removeState + addState 后新 state 用旧 state 的曲线播放

   • 用户：stateMachine.removeState(oldWalk); stateMachine.addState("walk"); animator.play("walk")
   • 旧：string-key 缓存命中旧 state 的 curveLayerOwner，动画行为错误
   • 新：identity-based WeakMap cache，新 state 必然 miss 重建

6. 删了 defaultState 之后自动播放仍指向已删 state

   • 用户：stateMachine.removeState(stateMachine.defaultState)
   • 旧：defaultState 字段仍持有被删 state 引用，下次 controller 重启/onEnable 尝试播放已删 state
   • 新：removeState 自动把 defaultState 置 null

7. play() 后再 addComponent(Script)，clip 里已存在的事件不触发

   • 用户：state.clip.addEvent(...) → animator.play(...) → entity.addComponent(MyScript)
   • 旧：lazy cache 仅跟踪 clip version，scripts 集合变化未触发重建，MyScript 永不收事件
   • 新：scripts 维度也纳入失效信号（Entity._scriptsVersion）

8. runtime 替换 state.clip 后，旧 clip 的事件仍触发

   • 用户：state.clip = newClip
   • 旧：cache key 读 clip._updateFlagManager.version，新旧 clip version 巧合相等时 cache 误命中，eventHandlers 仍用旧 clip
   • 新：cache key 改读 state._updateFlagManager.version（state 自己 funnel 了 clip swap + events 变两路）

9. instance.speed override 在 crossFade 阶段被忽略

   • 用户：findAnimatorState("X").speed = 0.5; animator.crossFade("X", 0.3)
   • 旧：_updateCrossFadeState 用 state.speed 而非 instance.speed，fade 阶段不遵守 per-instance override
   • 新：fade 阶段也用 instance.speed

10. crossFade 到当前正在播放/正在 fade 的 state 导致动画错乱

    • 用户：A→B fade 进行中再 crossFade("B") 或 crossFade("A")
    • 旧：PlayData 持久化设计下，src/dest 别名同一对象，resetForPlay 覆盖活跃运行轨迹 + update 被调两次 → 时间错乱、速度翻倍
    • 新：guard 拦截，self/active-dest crossFade 退化为 no-op（完整支持留作 follow-up）

11. 多 root 骨骼 GLTF 加载 rootBone 解析错误或抛错

    • 用户：加载带 skin、但 skin.skeleton 缺失、且 joints 跨多个 scene root 的 GLTF
    • 旧：_findSkeletonRootBone fallback 抛错或挂错 root entity
    • 新：joints LCA 算法稳定解析（converged joints → 真实 skeleton root；spanning joints → GLTF_ROOT wrapper）

12. GLTF skin.skeleton 索引越界静默失败

    • 用户：GLTF 文件中 skin.skeleton 指向不存在的节点索引（外部数据错误或工具导出 bug）
    • 旧：entities[skeleton] 静默 undefined → skin.rootBone = undefined → 后续蒙皮渲染报远离根因的错
    • 新：加载时 throw 明确错误 Skin skeleton index N is out of range.

13. controller 增删 layer 后，getCurrentAnimatorState / findAnimatorState 返回失效引用

    • 用户：animator.animatorController.addLayer/removeLayer/clearLayers 之后查这两个 API
    • 旧：返回旧 layer data 上的 instance，可能指向已被移除的 state（dangling）
    • 新：API 入口走 _resetIfControllerUpdated()，结构变化后正确返回 null 或新 instance

架构简化

• lazy version pull 替代 listener push — UpdateFlagManager 加 monotonic _version 计数器；AnimatorStateData.eventsBuiltVersion 快照式记录上次构建版本。clip events 变化触发 _version++，Animator 在 update/play 路径上 pull-check version 决定是否重建。消除了原来 listener push 路径上的反向引用 leak 风险，以及 clipChangedListener 注册/注销/dispose 一整套基础设施
• WeakMap 替代 Object Map — AnimatorLayerData 上 animatorStateDataMap / instanceMap 都用 WeakMap<AnimatorState, T>；state 被 GC 时 entry 自动消失，无需手动清理
• 删除 ClearableObjectPool<AnimationEventHandler> — 在我们的多 stateData 共享 + 各自独立失效语义下，pool 永远单调增长，从未起到复用作用；直接 new 更简单且无差异
• stateMachine → controller dispatch 转发链 — WeakMap 改造后变得不必要，一并删除
• cross-fade slot 字段管理收敛 — 引入 AnimatorLayerData.completeCrossFade() / clearCrossFadeSlot() 把散落在 Animator 的 slot 字段管理收回 LayerData 内部
• self/active-dest crossFade no-op — 每个 state 一个持久视图，self-cross-fade 会让 src/dest alias，故 alias guard 把这种调用 no-op；完整 self-cross-fade 支持需要拆 persistent override view / transient runtime track，留作 follow-up

Lifecycle 不变量

• Animator 持有的 instance 在 controller 结构变化时失效 — addLayer / removeLayer / clearLayers 触发 controller updateFlag → Animator 下次访问入口走 _reset()，丢弃所有 _animatorLayersData（包含 instanceMap）。Public API JSDoc 明示这条契约，用户必须重新调用 findAnimatorState / getCurrentAnimatorState 获取新视图
• per-instance override 跨 transition 保留 — 一个 state 进出 fade 后再次进入时，instance 上的 speed / wrapMode override 不会被 PlayData.reset() 清掉（它们物理上在 AnimatorStateInstance 上，PlayData.reset 只重置运行时游标）

GLTF 加载器

• fix(loader): resolve skin rootBone by joint LCA — GLTFSkinParser._findSkeletonRootBone 重写为 _findSkeletonRootBoneByLCA：没有显式 skin.skeleton 时，rootBone 一律通过 joints 的最近公共祖先算出来。删除之前"无 skeleton 时 fallback 抛错"分支。GLTF_ROOT wrapping 由 dev/2.0 已合入的 GLTFSceneParser: Always create container root node for consistent animation bone paths #2942/fix(loader): always create GLTF_ROOT container for consistent animation paths #2943 保证，multi-root spanning joints 自然解析为 wrapper，converged joints 解析为真实 skeleton root（如 Character_Root）
• GLTFSceneParser 同步写 _sceneRoots[i] — 已随 LCA-only rootBone 方案移除（LCA 不依赖 _sceneRoots），post-load 仍由 _handleSubAsset 异步填充
• GLTFParserContext Scene-before-Skin parse order — 把 Scene 从并行 parse 列表的尾部前置到 Skin 之前；显式注释 LCA 依赖 wrapper 已挂 parent chain 的不变量，并警告 Skin parser 不能 await full Scene（避免 _createRenderer 反向请求 Skin 造成循环依赖）
• GLTFSkinParser skin.skeleton 越界 guard — 显式 throw Skin skeleton index N is out of range.，不再静默 undefined

用户文档 + 示例

• docs/{en,zh}/animation/animator.mdx — 同步新 API：findAnimatorState 返回 AnimatorStateInstance | null 加 null guard、getCurrentAnimatorState 返回 AnimatorStateInstance | null 加 null guard、instance.speed 暂停/恢复示例
• e2e/case/animator-*.ts（5 个文件） — 适配 findAnimatorState 新返回类型，调用点加 null check；视图字段命名 idleState / walkState / runState（变量名指代视图本身，而不是 def 资产）
• 测试（tests/src/core/Animator.test.ts，+775/-256 行） — 新增 51 个测试覆盖 per-instance override / fall-through / crossFade 保留语义 / lazy version 重建 / WeakMap 等行为

抽离说明

• 跳过 Fix/shaderlab #2983 中已合入 dev/2.0 的 commit（GLTF_ROOT 容器 GLTFSceneParser: Always create container root node for consistent animation bone paths #2942/fix(loader): always create GLTF_ROOT container for consistent animation paths #2943、blendShape e2e 适配）
• 跳过 Fix/shaderlab #2983 中互相抵消的 single-root restore + revert 对
• 不带 Fix/shaderlab #2983 中 clone / UI / audio / shader-lab 等无关修复
• 物理 raycast/sweep 修复抽离至 fix(physics-physx): skip initial overlap in raycast/sweep + reuse query callbacks #2998 独立合入

Breaking changes (2.0)

• 新增 AnimatorStateInstance 类型，从 @galacean/engine-core 公开导出
• Animator.findAnimatorState() 返回 AnimatorStateInstance | null（旧返回 AnimatorState）
• Animator.getCurrentAnimatorState() 返回 AnimatorStateInstance | null（旧返回 AnimatorState，且 out-of-range layer 会抛错）
• AnimatorStateInstance 上的 override：speed / wrapMode 是 per-Animator 字段，fall-through 到底层 AnimatorState；视图上的 override 不影响其它 Animator
• 视图生命周期：AnimatorStateInstance 在 controller 结构变化（addLayer / removeLayer / clearLayers）后失效；用户持有的旧引用变成 orphan，必须重新调用 findAnimatorState / getCurrentAnimatorState 获取
• AnimatorStateMachine.defaultState 类型从 AnimatorState 改为 AnimatorState | null；removeState 删除当前 default state 时自动置 null
• AnimatorStateMachine.removeState 行为更精确：state 不在 array 中时整体跳过（包括 _statesMap 清理），避免误删同名 entry
• Animator.findAnimatorState/play/crossFade 对 out-of-range layerIndex 改为 safe no-op（旧实现会抛错）

量化

• animation 范围：8 files，+883 / -256（包含测试）
• 全部 13 个包 b:types 通过
• 全部 52 个 Animator 测试通过

[luzhuang]

@GuoLei1990 整体方向都正确（AnimatorStateInstance 拆分、WeakMap<AnimatorState, ...> identity cache、crossFade slot 收敛到 AnimatorLayerData、getCurrentAnimatorState 加 controller-update reset、loader 改 LCA-only 后回退 _sceneRoots[i] 同步写入），没看到把已有修复改坏的地方。合入前还有 1 个 bug、1 个 corner case 想确认，外加 1 个 PR Summary 与代码不一致。

---

1. _ensureEventHandlers 对 "play 后 addComponent(Script)" 漏 rebuild

engine/packages/core/src/animation/Animator.ts

Lines 1591 to 1594 in 7394e32

	// Re-check whether the clip events/scripts changed since the last build —
	// play()/crossFade() entry points already ensure on enter, but addEvent()
	// or addComponent(Script) after play() must also flow through.
	this._ensureEventHandlers(state, playData.stateData);

这段注释明确写了 addComponent(Script) after play() must also flow through，但实际 _ensureEventHandlers 的 early return 只比较 state.clip._updateFlagManager._version：

engine/packages/core/src/animation/Animator.ts

Lines 481 to 508 in 7394e32

	private _ensureEventHandlers(state: AnimatorState, animatorStateData: AnimatorStateData): void {
	const clipFlag = state.clip._updateFlagManager;
	if (animatorStateData.eventsBuiltVersion === clipFlag._version) {
	return;
	}
	const scripts = [];
	this._entity.getComponents(Script, scripts);
	const scriptCount = scripts.length;
	const { events } = state.clip;
	const { eventHandlers } = animatorStateData;
	eventHandlers.length = 0;
	for (let i = 0, n = events.length; i < n; i++) {
	const event = events[i];
	const eventHandler = new AnimationEventHandler();
	const funcName = event.functionName;
	const { handlers } = eventHandler;
	eventHandler.event = event;
	for (let j = scriptCount - 1; j >= 0; j--) {
	const script = scripts[j];
	const handler = <Function>script[funcName]?.bind(script);
	handler && handlers.push(handler);
	}
	eventHandlers.push(eventHandler);
	}
	animatorStateData.eventsBuiltVersion = clipFlag._version;
	}

Entity.addComponent 不会 dispatch clip flag。所以 “事件已在 clip 上 → play → addComponent(Script) → update” 这个顺序下，handlers 不会重建，新 Script 永远收不到事件。

现有 animation event 测试顺序是 play → addComponent → addEvent → update，第三步 addEvent 顺手把 clip _version bump 了，把这个漏报盖住了：

engine/tests/src/core/Animator.test.ts

Lines 350 to 368 in 7394e32

	it("animation event", () => {
	animator.play("Walk");
	class TestScript extends Script {
	event0(): void {}
	}
	const testScript = animator.entity.addComponent(TestScript);
	const testScriptSpy = vi.spyOn(testScript, "event0");
	const event0 = new AnimationEvent();
	event0.functionName = "event0";
	event0.time = 0;
	const state = animator.findAnimatorState("Walk");
	state.clip.addEvent(event0);
	animator.update(10);
	expect(testScriptSpy).toHaveBeenCalledTimes(1);
	});

新增的 eventHandlers rebuild lazily when state.clip events change 也只覆盖 clip flag dispatch 路径，没覆盖 Script 集合变化：

engine/tests/src/core/Animator.test.ts

Lines 1538 to 1561 in 7394e32

	it("eventHandlers rebuild lazily when state.clip events change", () => {
	const survey = animator.findAnimatorState("Survey");
	expect(survey).not.to.eq(null);
	const surveyState = (survey as any)._state;
	animator.play("Survey");
	// @ts-ignore — internal layerData / stateData
	const layerData = animator._animatorLayersData[0];
	const stateData = layerData.animatorStateDataMap.get(surveyState);
	expect(stateData, "stateData should exist after play").to.not.eq(undefined);
	const versionBefore = stateData.eventsBuiltVersion;
	expect(versionBefore).to.be.greaterThanOrEqual(0);
	// Dispatching the clip flag bumps clip's version → next access invalidates eventsBuiltVersion.
	surveyState.clip._updateFlagManager.dispatch();
	// Next play / state-data access triggers _ensureEventHandlersUpToDate and rebuilds.
	animator.play("Survey");
	// @ts-ignore
	const layerDataAfter = animator._animatorLayersData[0];
	const stateDataAfter = layerDataAfter.animatorStateDataMap.get(surveyState);
	expect(stateDataAfter.eventsBuiltVersion).to.be.greaterThan(versionBefore);
	});

建议补一个红测，大致形态：

it("eventHandlers rebuild when Script is added after play (no clip event mutation)", () => {
  const event = new AnimationEvent();
  event.functionName = "event0";
  event.time = 0;
  const state = animator.findAnimatorState("Walk")!;
  state.clip.addEvent(event); // 事件先存在

  animator.play("Walk");      // 此时 Script 还没挂

  class TestScript extends Script {
    event0(): void {}
  }
  const script = animator.entity.addComponent(TestScript); // 不 bump clip _version
  const spy = vi.spyOn(script, "event0");

  animator.engine.time._frameCount++;
  animator.update(0.1);
  expect(spy).toHaveBeenCalledTimes(1); // 当前会失败
});

实现上最小改动：_ensureEventHandlers 同时记录 script 集合快照（数量 + instanceId hash），Script 集合变化时强制重建。

---

2. 同一 state 替换 clip 可能漏触发 rebuild（corner case）

engine/packages/core/src/animation/AnimatorState.ts

Lines 46 to 62 in 7394e32

	set clip(clip: AnimationClip) {
	const lastClip = this._clip;
	if (lastClip === clip) {
	return;
	}
	if (lastClip) {
	lastClip._updateFlagManager.removeListener(this._onClipChanged);
	}
	this._clip = clip;
	this._clipEndTime = Math.min(this._clipEndTime, 1);
	this._onClipChanged();
	clip && clip._updateFlagManager.addListener(this._onClipChanged);
	}

clip setter 只 dispatch state._updateFlagManager，Animator 全文不 listen state-level flag。_ensureEventHandlers 比的是 state.clip._updateFlagManager._version（swap 后已指向新 clip）。如果新 clip 是 fresh（_version === 0），而旧快照恰好也是 0，会误命中 early return，把旧 clip 构建的 eventHandlers 留着用。实战概率低但语义不正确。

最小修法：把 snapshot 改成 “clip identity + clip version” 复合 key；或改用 state._updateFlagManager._version（state 自己在 clip 变化时已 dispatch）。可以放 follow-up，但建议至少有 issue 跟踪。

---

3. PR Summary 与代码不一致

PR body 还保留：

GLTFSceneParser 同步写 _sceneRoots[i] — 与 _defaultSceneRoot 在同 tick 可见 ...

但最终 GLTFSceneParser.ts 已没有这个写入（LCA-only 后不依赖）：

engine/packages/loader/src/gltf/parser/GLTFSceneParser.ts

Lines 20 to 55 in 7394e32

	export class GLTFSceneParser extends GLTFParser {
	parse(context: GLTFParserContext, index: number): AssetPromise<Entity> {
	const {
	glTF: { scenes, scene = 0 },
	glTFResource
	} = context;
	const sceneInfo = scenes[index];
	const sceneExtensions = sceneInfo.extensions;
	const engine = glTFResource.engine;
	const isDefaultScene = scene === index;
	const sceneNodes = sceneInfo.nodes || [];
	let sceneRoot: Entity;
	sceneRoot = new Entity(engine, "GLTF_ROOT");
	// @ts-ignore
	sceneRoot._markAsTemplate(glTFResource);
	for (let i = 0; i < sceneNodes.length; i++) {
	sceneRoot.addChild(context.get<Entity>(GLTFParserType.Entity, sceneNodes[i]));
	}
	if (isDefaultScene) {
	glTFResource._defaultSceneRoot = sceneRoot;
	}
	const promises = new Array<AssetPromise<void[]>>();
	for (let i = 0; i < sceneNodes.length; i++) {
	promises.push(this._parseEntityComponent(context, sceneNodes[i]));
	}
	return AssetPromise.all(promises).then(() => {
	GLTFParser.executeExtensionsAdditiveAndParse(sceneExtensions, context, sceneRoot, sceneInfo);
	return sceneRoot;
	});
	}

建议 Summary 那条改成 “_sceneRoots[i] 同步写入已随 LCA-only rootBone 方案移除，post-load 仍由 _handleSubAsset 异步填充”，免得后续 reviewer 误以为最终代码还包含这个行为。

[GuoLei1990]

@luzhuang 三条都处理了,逐条确认:

---

1. ✅ _ensureEventHandlers script-add 漏 rebuild

按你的方向落地了。设计上选了让 source-of-truth 提供失效信号而不是消费者 hash:

• Entity 上加 _scriptsVersion = 0,_addScript / _removeScript 时单调 bump(O(1))
• AnimatorStateData 上加 eventsBuiltScriptsVersion = -1 快照
• _ensureEventHandlers 复合判定: eventsBuiltVersion === stateVersion && eventsBuiltScriptsVersion === scriptsVersion

为什么走 entity-level version 而不是 Animator-local hash:

• scripts 集合的 owner 是 Entity,失效信号挂在 owner 上是正确归属
• 与 _renderCount / _blendShapeCount 等已有 internal counter 风格一致
• 任何其它需要监听 scripts 变化的消费者都能复用
• swap 同类型 script 场景下,hash 方案需要 instanceId 兜底,version 方案天然覆盖

你的 red test 一字不改加进去了,以及补了 afterEach 清 clip events 防跨 test 污染。

2. ✅ clip swap corner case

走的是你建议的方案 B(改用 state-level dispatch),不是复合 key:

• cache key 从 state.clip._updateFlagManager._version 改为 state._updateFlagManager.version
• 理由:state._updateFlagManager 在 _onClipChanged 里同时处理 ① clip-swap 自身触发 + ② clip 内 events 变 via listener 转发;state 是事件绑定的语义 funnel,它的 version 单一覆盖两路输入
• 比"clip identity + clip version 复合 key"更干净 — 消费者不需要维护两份元数据,信号收口在 state 这层抽象上

顺带把 UpdateFlagManager._version 改为 version(@internal class 内,加了 JSDoc 说明它是 lazy pull-style cache invalidation 信号)。

补了 red test: eventHandlers rebuild when state.clip is swapped (state version covers clip swap),通过把 walkState.clip 换成 runState.clip 验证 swap 触发重建(原 cache key 在两个 clip version 巧合相等时会漏报)。

3. ✅ PR Summary 已更新

按你建议的措辞改了:

GLTFSceneParser 同步写 _sceneRoots[i] — 已随 LCA-only rootBone 方案移除(LCA 不依赖 _sceneRoots),post-load 仍由 _handleSubAsset 异步填充

用删除线保留历史诉求 + 明确说明已移除原因,避免后续 reviewer 误读。

---

新增 commit: 524e8f81 fix(animation): cover script-add and clip-swap invalidation paths for eventHandlers cache

测试: 54/54 Animator tests pass(原 52 + 2 个新增 red test)
Build: 全部 13 个包 type-check 通过

请再 check 一下方向是否对得上。

[cptbtptpbcptdtptp]

这个数组可以缓存一下，不需要每次都新生成。

[GuoLei1990]

已修复 (commit 4699ea5)。

Animator._tempScripts 静态字段复用，参照引擎里 PostProcessManager._tempColliders 的同模式。使用前后都 scripts.length = 0 清空，避免持有 stale script 引用造成弱 leak。

private static _tempScripts: Script[] = [];

private _ensureEventHandlers(...) {
  // ...
  const scripts = Animator._tempScripts;
  this._entity.getComponents(Script, scripts);
  // ... build handlers ...
  scripts.length = 0;
}

顺带一起处理了同段代码的另一个用户感知 bug：disabled Script 仍收事件 — handlers 数组以前存 Function[] (bind 出来的 closure)，丢失 script 引用所以 fire 时无法查 script.enabled。改成 { script, fn }[]，fire 时 script.enabled && fn.call(script, parameter)，对齐 Unity 行为基线。

[GuoLei1990]

增量审查（2026-05-18）

已关闭问题清单

所有历史跟踪问题均已修复，无遗留。上轮（2026-05-18T08:09:57Z HEAD c303355）结论 LGTM。

本轮新增 commits（fca884515 和 1851c1e8f）

均为纯文档变更，仅涉及 AnimatorStateInstance.ts，无实现代码改动。

fca884515 docs(animation): trim AnimatorStateInstance JSDoc

• 将 class 级注释从 4 行精简为 2 行，保留核心语义（override 字段作用域 + 未设置时透传）。
• 移除了 name / clip / clipStartTime / clipEndTime 四个 pass-through getter 的 JSDoc，认为其自说明；将 speed / wrapMode 的注释各缩为单行。

1851c1e8f docs(animation): restore JSDoc on pass-through public getters

• 立即撤回了上一 commit 对 4 个透传 getter 移除 JSDoc 的决策。理由正确：这四个 getter 是 @galacean/engine-core 对外导出的公开 API，用户依赖 VSCode hover 和 TypeDoc 产物，不能无注释。
• 每个 getter 补回了一行说明（The name/clip/... of the underlying state）。
• 最终状态：所有公开 getter 均有 JSDoc，类级注释简洁且准确，speed / wrapMode 的单行描述也正确传达了 override 语义。

检查结论：

• 两个 commit 组合后语义自洽，最终文件状态正确。
• 注释内容与实现一致：speed/wrapMode 确实是 _speed ?? _state.speed 透传逻辑；类级 JSDoc 与实际 API 契约匹配。
• 无新增实现风险点。

总结

本轮变更纯属文档调整，最终 AnimatorStateInstance 的 JSDoc 状态规范、准确、完整。LGTM，无新问题。