AnimatorState.speed is part of the shared AnimatorController asset.
Modifying it at runtime pollutes all Animator instances sharing the
same controller, causing animation speed corruption after cloning.

- Add speed field to AnimatorStatePlayData, initialized from AnimatorState.speed on reset
- Add proxy properties (name/clip/wrapMode/transitions/addStateMachineScript)
- Change speed calculation to playData.speed * animator.speed
- findAnimatorState now returns per-instance AnimatorStatePlayData
- Export AnimatorStatePlayData for consumer code

Promote AnimatorStatePlayData from a play-slot object to a per-Animator
per-state persistent handle. Each AnimatorLayerData holds a state→PlayData
map; srcPlayData/destPlayData become nullable references into the map.

API:
- findAnimatorState(name, layerIdx?) returns AnimatorStatePlayData|null,
  lazy-creating the handle on first access (works even when the state has
  never played)
- playData.speed is a getter/setter backed by _speedOverride; reads
  fall back to state.speed (live binding); clearSpeedOverride() resumes
  tracking the shared default
- playData.state.xxx for shared asset access (no proxy properties)
- resetForPlay() resets runtime fields only; user overrides survive
  transitions

Bugs fixed:
- _updateCrossFadeState now multiplies by playData.speed (was state.speed),
  so per-instance speed applies during cross-fade
- findAnimatorState no longer returns the wrong state's playData when the
  queried state isn't currently playing (was: fell back to srcPlayData)

Lifecycle changes:
- AnimatorLayerData.statePlayDataMap caches per-state handles
- switchPlayData() replaced by promoteDest() (src ← dest, dest = null)
- _preparePlay/_prepareCrossFade get-or-create from the map and assign
  references rather than reset slot objects

Cleanup:
- Remove AnimatorStatePlayData proxy properties (name/clip/wrapMode/
  transitions/addStateMachineScript) — use playData.state.xxx instead
- Drop @todo on findLayerByName and duplicate JSDoc on findAnimatorState

…ernal/

Address code quality review on 57da59a:

- AnimatorStatePlayData constructor no longer reads state.clip; clipTime
  defers to resetForPlay so findAnimatorState doesn't crash for states
  with no clip yet
- Move AnimatorStatePlayData from internal/ to animation/ root since it
  is now public API returned by findAnimatorState; update imports
- Annotate findAnimatorState and getCurrentAnimatorState return types as
  | null to match runtime behavior
- Remove dead && guards in _updateCrossFadeState (layerState guarantees
  non-null entry)
- Tighten AnimatorLayerData field comments

Add 6 regression tests covering the new findAnimatorState handle:
- lazy create on first access (state never played)
- speed override set before play applies on first play
- override survives crossFade out and back
- override is per-Animator (clone isolation, shared asset unmutated)
- crossFade phase uses playData.speed (was state.speed before fix)
- clearSpeedOverride resumes live tracking of state.speed

Fix existing call sites broken by proxy removal: tests that accessed
state.clip / state.clearTransitions / state.clipStartTime etc. now go
through state.state.xxx (the shared AnimatorState). state.speed reads
and writes remain on the per-instance handle.

Address code quality review:
- Test #1 now uses a cloned animator (no afterEach pre-population) so it
  actually verifies lazy PlayData creation; rename to match intent
- Test #2 drops @ts-ignore on _animatorLayersData by reading the override
  through the same handle returned by findAnimatorState
- Test #5 tightens >0.1 threshold to closeTo(0.2, 0.05) so a regression
  reducing the multiplier wouldn't slip past
- Align .eq/.greaterThan calls with the file's .to.eq/.to.be convention

Previously walk-up went all the way to GLTF_ROOT (the wrapper, no parent),
but sceneRootChildren contains GLTF_ROOT's direct children — never
GLTF_ROOT itself. Result: function always returned null, making multi-root
skin wrapper detection a no-op.

Stop the walk as soon as the entity is a direct child of the scene root.
The final check then succeeds for joints under any sceneNode, returning
the wrapper sceneRoot as rootBone.

Verified via standalone reproduction matching the test fixture.

When entity X had a child also named X, findByPath("X") short-circuited to
return self due to the GLTF self-name prefix branch — making the same-name
child unreachable.

Try direct child lookup first; fall back to the self-name prefix only when
the child path doesn't match. Both the GLTF normalized-prefix case and the
same-name child case work correctly.

PR galacean#2984 changed Animator.findAnimatorState() to return
AnimatorStatePlayData instead of AnimatorState. Unit tests were already
updated to access shared-asset members via `.state.xxx`; e2e cases were
missed and would TypeError at runtime when playwright loaded them.

Convert each shared-asset access on findAnimatorState() results:
- .clip -> .state.clip (animator-event, animator-additive)
- .addTransition / .addExitTransition / ._getDuration -> .state.xxx
  (animator-stateMachine)
- .addStateMachineScript -> .state.addStateMachineScript
  (animator-stateMachineScript)

.speed reads/writes are intentionally preserved on the per-instance
handle (the whole point of the API change).

…n flag

- _prepareCrossFadeByTransition guards against crossFade to current src
  or dest state, since statePlayDataMap holds a single PlayData per
  AnimatorState; without the guard, dest aliases to src, resetForPlay
  clobbers the active runtime, and _updateCrossFadeState updates the
  same object twice
- AnimatorStatePlayData.resetForPlay also resets _changedOrientation so
  re-entering a state doesn't carry the previous track's orientation
  flag into the new playback window

True self-crossfade support requires splitting persistent override fields
from transient src/dest runtime tracks; out of scope for this PR.

When the entity has a child with the same name as splits[0], findByPath
must not fallback to the self-prefix interpretation: the user clearly
intends to descend into the child, and a deeper-path miss should return
null rather than silently re-resolve the path against the entity itself.

PR galacean#2984 changed findAnimatorState to return AnimatorStatePlayData | null.
Update both EN and ZH docs to reflect:
- Per-instance speed override (playData.speed)
- Shared asset access (playData.state.xxx)
- Nullable return guard
- clearSpeedOverride() to resume live binding to state.speed

findAnimatorState now returns AnimatorStatePlayData | null. e2e cases
were dereferencing without a guard, which would surface as
"Cannot read properties of null" if a state name doesn't match the
asset. Add fail-fast guards naming the missing state for actionable
errors.

… multiple roots

Previously: if all joints were under any sceneNodes' subtrees,
_findSceneRootBone returned GLTF_ROOT, even when joints converged to a
single top-level child. That over-promoted the rootBone to include
unrelated sibling nodes (lights, cameras, props), affecting bounds.

Now: track which top-level child each joint resolves to. Only return
sceneRoot when joints span >1 different top-level children. Otherwise
fall through to _findSkeletonRootBone for the LCA.

When play() interrupts a cross-fade, destPlayData and crossFadeTransition
were left dangling. With persistent statePlayDataMap, this caused the
self-crossFade alias guard to wrongly no-op subsequent crossFade calls
to the previously-fading state.

Clear destPlayData and crossFadeTransition on play() entry so the layer
state matches reality.

If the requested state name doesn't match any layer, _getAnimatorLayerData
was being called with playLayerIndex = -1, which would write a junk
AnimatorLayerData entry at array index -1 (JS array negative indexing
creates a property). Guard the lookup at the entry point.

Bring the JSDoc tag in line with the other engine-managed runtime fields
on AnimatorStatePlayData (playedTime/clipTime/etc.) so docs/IDE filtering
treats them uniformly.

Self-prefix fallback called _findChildByName with pathIndex=1, whose
not-found backtrack path recursed into entity.parent — for detached or
root entities, that's null and crashes on null._children. Use
splits.slice(1) with pathIndex=0 so the recursion stays within the
entity's subtree and returns null cleanly when the deeper path misses.

Also retitle the fallback comment to a generic path-semantics
description, since core/Entity should not carry GLTF-specific framing.

When called with an out-of-range layerIndex, _getAnimatorStateInfo
accessed layers[idx].stateMachine and threw. This propagated to
findAnimatorState (which is supposed to return null) and to play /
crossFade entry points. Bound-check the index and return a stateInfo
with layerIndex = -1 / state = null so all three callers see safe
behavior.

When per-instance state speed is 0 (paused) and a transition fires,
playCostTime / playSpeed produced NaN, which made remainDeltaTime > 0
evaluate false and the destination state silently dropped the remaining
delta on that frame. Treat speed=0 as "no time consumed by this state"
and pass deltaTime through to the destination instead.

GLTFSkinParser._findSceneRootBone reads glTFResource._sceneRoots which
GLTFSceneParser populates synchronously. The current AssetPromise.all
ordering preserves this; document the invariant so a future array
reorder doesn't silently break skin root resolution.

…hine

Bring local AnimatorStateTransition declarations into line with the
project's camelCase convention.

…cess

…te(null) idiom

AnimatorLayerData already used Record-style maps for animatorStateDataMap
and curveOwnerPool; statePlayDataMap was the only Map in the animation
module. Layer-internal stateName is canonical (AnimatorStateMachine
deduplicates by name). Switch to the project's standard pattern for
intra-class consistency and v8 hidden-class friendliness on small caches.

Also normalize animatorStateDataMap initialization to Object.create(null)
for the same null-prototype safety as curveOwnerPool.

The example showed `playData.speed = 0` immediately followed by
`playData.clearSpeedOverride()`, which silently cancels the override.
Comment out the resume call and label it as a later-stage operation so
copy-pasting actually pauses the state.

The previous comment phrased the guard as a temporary workaround. The
behavior is in fact deliberate: per-state persistent PlayData makes
self-cross-fade structurally inexpressible without a separate transient
track. Phrase the comment so future readers understand it as policy.

Replace per-scene Set<Entity> creation with parent-walk identity checks.
Tracks first-encountered top-level joint root and compares subsequent
joints by reference, returning sceneRoot the moment a divergent root is
found.

Replace splits.slice(1) + _findChildByName(pathIndex=1) with a dedicated
subtree-only path-search helper. Two improvements: no array allocation
on every fallback, and the "fallback never backtracks to siblings"
semantic is now expressed in the helper's contract instead of relying
on the caller to neutralize backtracking via slicing.