lecodes-cli 0.16.1 → 0.16.2

package/runtime/sdk/gl/Animator.ts

@@ -0,0 +1,634 @@
+// Animator — the full animation system as an OPT-IN aspect (model.anim stays the simple baked-clip
+// player). A clip TABLE (the model's embedded clips ∪ your `clips`) bound by bone name to this
+// node's hierarchy, evaluated natively every frame as weighted slots grouped in LAYERS: crossfades,
+// 1D/2D blend spaces (phase-synced members), one-shots that return to the blend, masked / additive
+// layers, clip events, completion promises. Owns the skeleton while attached (model.anim is
+// suspended). See docs/animation-plan.md.
+//
+//   const [hero, idle, run, slash] = await Promise.all([
+//     Model.load(asset('./hero.glb')),
+//     AnimationClip.load(asset('./idle.glb')), AnimationClip.load(asset('./run.glb')),
+//     AnimationClip.load(asset('./attacks.glb'), 'Slash'),
+//   ])
+//   hero.aspect(Animator, { clips: { idle, run, slash }, blend: { idle: 0, run: 6 } })
+//   hero.animator.value = hero.controller.velocity.length      // where we are on the blend axis
+//   await hero.animator.play('slash', { fade: 0.1 })           // one-shot; the blend fades back after
+//   hero.animator.on('completed', (name) => ...)
+//
+//   // layers: the flat API above IS the 'base' layer; more layers stack on top of it
+//   hero.aspect(Animator, {
+//     clips: { idle, walk, run, aim, breathe },
+//     layers: {
+//       base:  { blend: { idle: [0, 0], walk: [0, 1], run: [0, 2], strafeL: [-1, 1] } },   // 2D: value = [x, y]
+//       upper: { mask: 'Spine1' },                        // override layer over the upper body only
+//       body:  { additive: true, clip: 'breathe' },       // delta clip on top of everything
+//     },
+//   })
+//   hero.animator.layer('upper').play('aim', { loop: true })  // arms aim, legs keep walking
+//   hero.animator.layer('upper').stop()
+//
+// Any Node hierarchy works, not just Models: tracks bind to child names (a robot arm of meshes).
+
+import { Aspect } from "../core/Aspect"
+import { Emitter } from "../core/events"
+import { Registry } from "../core/registry"
+import { AnimationClip } from "./AnimationClip"
+import type { Node } from "./Node"
+import type { ModelAnimation } from "./ModelAnimation"
+import type { CharacterController } from "./CharacterController"
+import { Vec3 } from "../math/vec"
+
+/** A position on a layer's blend axis (1D) or plane (2D). */
+export type BlendPosition = number | readonly [number, number]
+
+export type AnimatorPlayOptions = {
+  /** Crossfade seconds for BOTH ends (default: `animator.fade`, 0.2). 0 = cut. */
+  fade?: number
+  /** Fade-in seconds (overrides `fade`). */
+  fadeIn?: number
+  /** One-shots only: fade-back seconds at the END (overrides `fade`). The return fade starts this
+   *  long BEFORE the clip ends, while it still plays — no freeze-frame on the last pose. On a layer
+   *  with no blend to return to, an explicit `fadeOut` releases the layer at the end instead of
+   *  holding the last frame. */
+  fadeOut?: number
+  /** Loop the clip (default false for one-shots; blend members always loop). */
+  loop?: boolean
+  /** Playback rate for this clip (default 1). */
+  speed?: number
+  /** Restart from t=0 even if the clip is already playing (default: restart only if it isn't). */
+  restart?: boolean
+}
+
+export type AnimatorLayerOptions = {
+  /** Blend space: clip name → position, 1D (`{ idle: 0, run: 6 }`) or 2D (`{ idle: [0,0], fwd: [0,1] }`).
+   *  Members loop in phase with each other; the layer's `value` picks the mix. */
+  blend?: Record<string, BlendPosition>
+  /** A clip to start looping at attach (an ambient layer: breathing, an aim pose). */
+  clip?: string
+  /** Bone name(s): the layer drives only these subtrees (`'Spine1'` = upper body). Default: the whole rig. */
+  mask?: string | string[]
+  /** Blend each clip's DELTA from its own first frame on top of the layers below (lean, breathe, recoil)
+   *  instead of overriding them. */
+  additive?: boolean
+  /** Layer contribution 0–1 (default 1). A layer with nothing playing contributes nothing regardless. */
+  weight?: number
+}
+
+type AnimatorEvents = {
+  /** A non-looping clip reached its end. */
+  completed: (clip: string, layer: string) => void
+  /** A looping clip wrapped around (once per cycle for a blend space). */
+  loop: (clip: string, layer: string) => void
+  /** Clip events declared in `events: { clip: { 0.4: 'hit' } }`. */
+  [event: string]: (clip: string, layer: string) => void
+}
+
+class AnimatorEmitter extends Emitter<AnimatorEvents> {
+  emit<K extends keyof AnimatorEvents>(channel: K, ...args: Parameters<AnimatorEvents[K]>): void { this.dispatch(channel, ...args) }
+}
+
+type SlotState = {
+  name: string
+  clip: AnimationClip
+  slot: number
+  layer: AnimatorLayer
+  /** current / target contribution (0–1); blend members use blendW × the layer's blend group weight */
+  weight: number
+  target: number
+  rate: number         // weight units per second toward target (Infinity = cut)
+  blendW: number       // this frame's blend-space weight (members only)
+  playing: boolean
+  loop: boolean
+  inBlend: boolean
+  events: string[]     // clip event names, index = native event type − 2
+  evTimes: number[]    // the declared events' normalized times (to re-push with the fade-out sentinel)
+  outNorm: number      // fade-out sentinel's normalized time as pushed (−1 = none)
+  fadeOut: number      // seconds for this play's scheduled fade-back
+  explicitOut: boolean // options.fadeOut was given → release even on a blendless layer
+  resolvers: (() => void)[]
+}
+
+const animatorRegistry = new Registry<Animator>()
+let eventsInstalled = false
+const ensureEvents = (): void => {
+  if (eventsInstalled) return
+  eventsInstalled = true
+  _creator.setOnAnimatorEvent((animatorId, slot, type) => animatorRegistry.get(animatorId)?._onSlotEvent(slot, type))
+}
+
+const EPS = 0.0005
+const asXY = (p: BlendPosition): [number, number] => typeof p === "number" ? [p, 0] : [p[0], p[1]]
+
+/** One layer of an Animator. The Animator's own play/stop/value/… ARE its `base` layer. */
+export class AnimatorLayer {
+  /** Position on the blend axis (number) or plane ([x, y]) — units are whatever `blend` uses. */
+  value: BlendPosition = 0
+  /** Layer contribution 0–1. */
+  weight = 1
+  /** Bone name(s) whose subtrees this layer drives; undefined = the whole rig. */
+  mask?: string | string[]
+  /** Blend deltas (vs each clip's first frame) on top of the layers below instead of overriding. */
+  additive = false
+  /** The blend space this layer was declared with (read at attach). */
+  blend?: Record<string, BlendPosition>
+
+  /** @internal */ _clip?: string
+  /** @internal */ _slots: SlotState[] = []
+  /** @internal */ _byName = new Map<string, SlotState>()
+  /** @internal */ _members: { at: [number, number], slot: SlotState }[] = []
+  /** @internal */ _is2D = false
+  /** @internal */ _blendWeight = 1
+  /** @internal */ _blendTarget = 1
+  /** @internal */ _blendRate = Infinity
+  /** @internal */ _lastValue: [number, number] = [NaN, NaN]
+  /** @internal */ _lastWeight = NaN
+  /** @internal */ _lastMask = ""
+  /** @internal */ _lastAdditive: boolean | undefined
+
+  /** The layer's name (`'base'` for the Animator's own). */
+  readonly name: string
+  /** @internal native layer index (0 = base) */
+  readonly index: number
+  private readonly _a: Animator
+
+  /** @internal — created by the Animator (`animator.layer(name)`), never by hand. */
+  constructor(name: string, index: number, animator: Animator) { this.name = name; this.index = index; this._a = animator }
+
+  /** The clip names bound on this layer so far. */
+  get names(): string[] { return [...this._byName.keys()] }
+
+  /** Play a clip on this layer (crossfading from whatever it plays). A blend member brings the whole
+   *  blend back; anything else is a one-shot that returns to the blend when it ends (unless `loop`),
+   *  or holds its last frame on a layer without a blend (call `stop()`). Resolves when the clip
+   *  completes or is faded out by a later play()/stop(). */
+  play(name: string, options: AnimatorPlayOptions = {}): Promise<void> {
+    const s = this._resolve(name)
+    if (!s) return Promise.resolve()
+    const fade = options.fadeIn ?? options.fade ?? this._a.fade
+    const restart = options.restart ?? !s.playing
+    if (!s.inBlend) s.loop = options.loop ?? false
+    s.playing = true
+    _creator.animatorSetSlot(this._a._id, s.slot, true, s.loop, options.speed ?? 1, restart ? 0 : -1)
+    this._scheduleOut(s, options)
+    const rate = fade > 0 ? 1 / fade : Infinity
+    for (const o of this._slots) {
+      if (o.inBlend || o === s) continue
+      if (o.target !== 0) { o.target = 0; o.rate = rate }
+    }
+    if (s.inBlend) { this._blendTarget = 1; this._blendRate = rate }
+    else { s.target = 1; s.rate = rate; this._blendTarget = 0; this._blendRate = rate }
+    return new Promise<void>((resolve) => { s.resolvers.push(resolve) })
+  }
+
+  /** Fade a clip out (or, with no name, everything on this layer — the blend included). */
+  stop(name?: string, options: { fade?: number, fadeOut?: number } = {}): this {
+    const fade = options.fadeOut ?? options.fade ?? this._a.fade
+    const rate = fade > 0 ? 1 / fade : Infinity
+    if (name === undefined) {
+      for (const o of this._slots) if (!o.inBlend) { o.target = 0; o.rate = rate }
+      this._blendTarget = 0; this._blendRate = rate
+      return this
+    }
+    const s = this._byName.get(name)
+    if (!s) return this
+    if (s.inBlend) { this._blendTarget = 0; this._blendRate = rate; return this }
+    s.target = 0; s.rate = rate
+    // nothing else on the way in → the blend returns
+    if (this._members.length > 0 && !this._slots.some((o) => !o.inBlend && o.target > 0)) { this._blendTarget = 1; this._blendRate = rate }
+    return this
+  }
+
+  /** Whether the clip is playing on this layer (its clock advancing). No name = anything on this layer. */
+  playing(name?: string): boolean {
+    if (name === undefined) return this._slots.some((s) => s.playing && this._effective(s) > 0)
+    const s = this._byName.get(name)
+    return !!s && s.playing
+  }
+  /** Current time (s) of a clip's clock. */
+  time(name: string): number {
+    const s = this._byName.get(name)
+    return s ? _creator.animatorGetSlotTime(this._a._id, s.slot) : 0
+  }
+  /** Set a clip's clock (s). Seeking a blend member moves the whole blend (they share one phase). */
+  seek(name: string, time: number): this {
+    const s = this._byName.get(name)
+    if (s) _creator.animatorSetSlot(this._a._id, s.slot, s.playing, s.loop, 1, Math.max(0, time))
+    return this
+  }
+  /** 0–1 progress through a clip. */
+  progress(name: string): number {
+    const s = this._byName.get(name)
+    return s && s.clip.duration > 0 ? this.time(name) / s.clip.duration : 0
+  }
+  /** Current contribution (0–1) of a clip to this layer's pose. */
+  weightOf(name: string): number {
+    const s = this._byName.get(name)
+    return s ? this._effective(s) : 0
+  }
+
+  // ---- internals ----
+  /** @internal */
+  _attach(opts: AnimatorLayerOptions | undefined): void {
+    if (opts) {
+      if (opts.blend) this.blend = opts.blend
+      if (opts.mask !== undefined) this.mask = opts.mask
+      if (opts.additive !== undefined) this.additive = opts.additive
+      if (opts.weight !== undefined) this.weight = opts.weight
+      this._clip = opts.clip
+    }
+    if (this.blend) {
+      this._is2D = Object.values(this.blend).some((p) => typeof p !== "number")
+      for (const [name, at] of Object.entries(this.blend)) {
+        const clip = this._a._table.get(name)
+        if (!clip) { console.warn(`Animator: blend clip '${name}' is not in the clip table`); continue }
+        const s = this._a._bind(name, clip, this, this.index + 1)   // phase group per layer
+        if (!s) continue
+        s.inBlend = true
+        s.loop = true
+        s.playing = true
+        _creator.animatorSetSlot(this._a._id, s.slot, true, true, 1, 0)
+        this._members.push({ at: asXY(at), slot: s })
+      }
+      if (!this._is2D) this._members.sort((a, b) => a.at[0] - b.at[0])
+      this._computeBlend()
+    }
+    if (this._clip) {
+      const s = this._resolve(this._clip)
+      if (s) {
+        s.loop = true; s.playing = true; s.weight = 1; s.target = 1
+        _creator.animatorSetSlot(this._a._id, s.slot, true, true, 1, 0)
+      }
+    }
+    this._pushLayer()
+  }
+
+  /** @internal — advance fades / blend value / layer config; true if slot weights changed. */
+  _tick(dt: number): boolean {
+    let changed = false
+    for (const s of this._slots) {
+      if (s.inBlend || s.weight === s.target) continue
+      s.weight = step(s.weight, s.target, s.rate * dt)
+      changed = true
+      if (s.weight === 0 && s.target === 0) this._a._settle(s)
+    }
+    if (this._blendWeight !== this._blendTarget) {
+      this._blendWeight = step(this._blendWeight, this._blendTarget, this._blendRate * dt)
+      changed = true
+    }
+    if (this._members.length > 0) {
+      const [x, y] = asXY(this.value)
+      if (x !== this._lastValue[0] || y !== this._lastValue[1]) { this._computeBlend(); changed = true }
+    }
+    const mask = this._maskString()
+    if (this.weight !== this._lastWeight || this.additive !== this._lastAdditive || mask !== this._lastMask) this._pushLayer()
+    return changed
+  }
+
+  /** @internal */
+  _effective(s: SlotState): number { return s.inBlend ? s.blendW * this._blendWeight : s.weight }
+
+  private _maskString(): string {
+    const m = this.mask
+    return m === undefined ? "" : Array.isArray(m) ? m.join("\n") : (m as string)
+  }
+
+  private _pushLayer(): void {
+    const mask = this._maskString()
+    if (mask !== this._lastMask) {
+      for (const m of mask.split("\n")) if (m && !this._a.node.bone(m)) console.warn(`Animator: layer '${this.name}' mask bone '${m}' not found under ${this._a.node.name || "the node"}`)
+    }
+    this._lastWeight = this.weight; this._lastAdditive = this.additive; this._lastMask = mask
+    _creator.animatorSetLayer(this._a._id, this.index, this.weight, this.additive, mask)
+  }
+
+  /** One-shots: plant a hidden slot event where the fade-back must START so the return crossfade
+   *  finishes right at the clip's end while it is still moving (no freeze-frame). Loops and blend
+   *  members get none; `_onSlotEvent` keeps the reactive at-completion fade as the fallback. */
+  private _scheduleOut(s: SlotState, options: AnimatorPlayOptions): void {
+    s.fadeOut = options.fadeOut ?? options.fade ?? this._a.fade
+    s.explicitOut = options.fadeOut !== undefined
+    const auto = !s.inBlend && !s.loop && (this._members.length > 0 || s.explicitOut)
+    const dur = s.clip.duration
+    let norm = -1
+    if (auto && s.fadeOut > 0 && dur > 0) norm = Math.min(0.999, Math.max(0.001, 1 - (s.fadeOut * (options.speed ?? 1)) / dur))
+    if (norm === s.outNorm) return
+    s.outNorm = norm
+    const times = norm >= 0 ? [...s.evTimes, norm] : s.evTimes
+    _creator.animatorSetSlotEvents(this._a._id, s.slot, new Float32Array(times))
+  }
+
+  private _resolve(name: string): SlotState | undefined {
+    let s = this._byName.get(name)
+    if (!s) {
+      const clip = this._a._table.get(name) ?? this._a.clips[name]
+      if (clip) s = this._a._bind(name, clip, this, 0)
+    }
+    if (!s) console.warn(`Animator: no clip '${name}' — table: ${[...this._a._table.keys()].join(", ") || "(empty)"}`)
+    return s
+  }
+
+  /** Blend-space weights for the current value → each member's blendW. 1D: linear between the two
+   *  neighbours. 2D: gradient-band interpolation (exact at samples, smooth in between, no triangulation). */
+  private _computeBlend(): void {
+    const ms = this._members
+    const [x, y] = asXY(this.value)
+    this._lastValue = [x, y]
+    if (ms.length === 0) return
+    if (ms.length === 1) { ms[0].slot.blendW = 1; return }
+    if (!this._is2D) {
+      const v = Math.min(Math.max(x, ms[0].at[0]), ms[ms.length - 1].at[0])
+      for (const m of ms) m.slot.blendW = 0
+      for (let i = 0; i < ms.length - 1; i++) {
+        const a = ms[i], b = ms[i + 1]
+        if (v <= b.at[0]) {
+          const t = b.at[0] > a.at[0] ? (v - a.at[0]) / (b.at[0] - a.at[0]) : 0
+          a.slot.blendW = 1 - t; b.slot.blendW += t
+          return
+        }
+      }
+      ms[ms.length - 1].slot.blendW = 1
+      return
+    }
+    let sum = 0
+    let nearest = ms[0], nearestD = Infinity
+    for (const mi of ms) {
+      const [px, py] = mi.at
+      const dx = x - px, dy = y - py
+      const d2 = dx * dx + dy * dy
+      if (d2 < nearestD) { nearestD = d2; nearest = mi }
+      let h = 1
+      for (const mj of ms) {
+        if (mj === mi) continue
+        const ex = mj.at[0] - px, ey = mj.at[1] - py
+        const len2 = ex * ex + ey * ey
+        if (len2 === 0) continue
+        const t = 1 - (dx * ex + dy * ey) / len2
+        h = Math.min(h, Math.max(0, Math.min(1, t)))
+        if (h === 0) break
+      }
+      mi.slot.blendW = h
+      sum += h
+    }
+    if (sum > 0) for (const m of ms) m.slot.blendW /= sum
+    else { for (const m of ms) m.slot.blendW = 0; nearest.slot.blendW = 1 }
+  }
+}
+
+export class Animator extends Aspect<"animator", Node> {
+  static readonly aspect = "animator"
+
+  /** Clips from other files / procedural clips, keyed by the name you play them with. Read at attach;
+   *  the table also contains the model's embedded clips under their own names. */
+  clips: Record<string, AnimationClip> = {}
+  /** Blend space of the base layer (shorthand for `layers: { base: { blend } }`). Read at attach. */
+  blend?: Record<string, BlendPosition>
+  /** Layers on top of `base` (declared in stacking order). Read at attach; `layer(name)` reaches them —
+   *  and creates an undeclared one on first use. */
+  layers?: Record<string, AnimatorLayerOptions>
+  /** Clip events: clip name → { normalizedTime: eventName } → `animator.on(eventName, (clip) => …)`. Read at attach. */
+  events?: Record<string, Record<number | string, string>>
+  /** Global playback rate (slow-mo). */
+  speed = 1
+  /** Freeze every clock (game pause). */
+  paused = false
+  /** Default crossfade seconds for play()/stop(). */
+  fade = 0.2
+  /** Root motion: strip the root bone's horizontal travel from the pose and move the NODE with it
+   *  instead (or drive its CharacterController when it has one) — for clips whose hips actually travel
+   *  (Mixamo without "In Place", lunges, rolls). `true` = auto-detect the root bone (the shallowest bone
+   *  a clip translates), or a bone name. Read at attach. */
+  rootMotion?: boolean | string
+  /** Apply the extracted root motion to the node/controller each frame (default). Set false to read
+   *  `rootDelta` yourself. */
+  applyRootMotion = true
+
+  updateBeforePhysics = true   // push this frame's weights BEFORE the native evaluator runs
+  order = -10                  // and before CharacterController (root motion feeds its velocity)
+
+  private _rootBuf = new Float32Array(3)
+  private _rootDelta = new Vec3()
+  /** Last frame's root-motion delta in the node's local space (zero without `rootMotion`). */
+  get rootDelta(): Vec3 { return this._rootDelta }
+
+  /** @internal */ _id = 0
+  /** @internal */ _table = new Map<string, AnimationClip>()
+  private _base = new AnimatorLayer("base", 0, this)
+  private _layers: AnimatorLayer[] = [ this._base ]
+  private _all: SlotState[] = []      // by native slot index
+  private _lastSpeed = 1
+  private _lastPaused = false
+  private _weights = new Float32Array(0)
+  private _events = new AnimatorEmitter()
+
+  /** Position on the base layer's blend axis/plane. */
+  get value(): BlendPosition { return this._base.value }
+  set value(v: BlendPosition) { this._base.value = v }
+
+  onAttach(): void {
+    if (typeof _creator.animatorCreate !== "function") {
+      console.warn("Animator: this host has no Animator support yet — falling back to model.anim where possible")
+      return
+    }
+    ensureEvents()
+    this._id = _creator.animatorCreate(this.node.id)
+    if (this._id === 0) { console.warn("Animator: node has no transform hierarchy"); return }
+    animatorRegistry.set(this._id, this)
+
+    // clip table = embedded ∪ clips (yours override)
+    for (const c of AnimationClip._ofSet(_creator.getGlbClipSet(this.node.id))) this._table.set(c.name, c)
+    for (const [name, clip] of Object.entries(this.clips)) if (clip) this._table.set(name, clip)
+
+    // suspend the base player — one writer
+    const anim = (this.node as unknown as { anim?: ModelAnimation }).anim
+    anim?._suspend(true)
+
+    // layers: base (flat `blend` or layers.base) + the rest in declaration order
+    const declared = this.layers ?? {}
+    const baseOpts: AnimatorLayerOptions = { ...(declared.base ?? {}) }
+    if (!baseOpts.blend && this.blend) baseOpts.blend = this.blend
+    this._base._attach(baseOpts)
+    for (const [name, opts] of Object.entries(declared)) {
+      if (name === "base") continue
+      this.layer(name)._attach(opts)
+    }
+    // clips not bound by any layer yet get bound on base on first play(); bind the rest eagerly so
+    // warnings about unbound tracks show up at attach, not mid-game
+    for (const [name, clip] of this._table) if (!this._base._byName.has(name) && !this._layers.some((l) => l._byName.has(name))) this._bind(name, clip, this._base, 0)
+
+    this._lastSpeed = this.speed
+    this._lastPaused = this.paused
+    _creator.animatorSetGlobal(this._id, this.speed, this.paused)
+    if (this.rootMotion) _creator.animatorSetRootMotion?.(this._id, this.rootMotion === true ? "*" : this.rootMotion)
+    this._push(true)
+  }
+
+  onDetach(): void {
+    if (this._id === 0) return
+    for (const s of this._all) this._settle(s)
+    this._controller()?._setExternalVelocity(0, 0, 0)
+    _creator.animatorDestroy(this._id)
+    animatorRegistry.delete(this._id)
+    this._id = 0
+    const anim = (this.node as unknown as { anim?: ModelAnimation }).anim
+    anim?._suspend(false)
+  }
+
+  /** The names in the clip table. */
+  get names(): string[] { return [...this._table.keys()] }
+
+  /** A layer by name (`'base'` is the Animator itself). An undeclared name creates a new override
+   *  layer on top; configure it through its properties (`mask`, `additive`, `weight`). */
+  layer(name: string): AnimatorLayer {
+    for (const l of this._layers) if (l.name === name) return l
+    if (this._layers.length >= 255) { console.warn("Animator: too many layers"); return this._base }
+    const l = new AnimatorLayer(name, this._layers.length, this)
+    this._layers.push(l)
+    return l
+  }
+  /** All layers, bottom to top. */
+  get layerList(): readonly AnimatorLayer[] { return this._layers }
+
+  /** Play a clip on the base layer (crossfading from whatever is playing there). A blend member brings
+   *  the whole blend back; anything else is a one-shot that returns to the blend when it ends (unless
+   *  `loop`). Resolves when the clip completes or is faded out by a later play()/stop(). */
+  play(name: string, options: AnimatorPlayOptions = {}): Promise<void> { return this._base.play(name, options) }
+  /** Fade a clip out on the base layer — or, with no name, everything on every layer. */
+  stop(name?: string, options: { fade?: number } = {}): this {
+    if (name === undefined) { for (const l of this._layers) l.stop(undefined, options); return this }
+    this._base.stop(name, options)
+    return this
+  }
+  /** Whether the clip is playing on the base layer. No name = anything playing on any layer. */
+  playing(name?: string): boolean {
+    if (name === undefined) return this._layers.some((l) => l.playing())
+    return this._base.playing(name)
+  }
+  /** Current time (s) of a base-layer clip's clock. */
+  time(name: string): number { return this._base.time(name) }
+  /** Set a base-layer clip's clock (s). */
+  seek(name: string, time: number): this { this._base.seek(name, time); return this }
+  /** 0–1 progress through a base-layer clip. */
+  progress(name: string): number { return this._base.progress(name) }
+  /** Current contribution (0–1) of a base-layer clip to the pose. */
+  weightOf(name: string): number { return this._base.weightOf(name) }
+
+  on<K extends keyof AnimatorEvents>(channel: K, cb: AnimatorEvents[K]): this { this._events.addEventListener(channel, cb); return this }
+  off<K extends keyof AnimatorEvents>(channel: K, cb: AnimatorEvents[K]): this { this._events.removeEventListener(channel, cb); return this }
+
+  // ---- per frame (EARLY phase: weights land before the native evaluator) ----
+  update(dt: number): void {
+    if (this._id === 0) return
+    let changed = false
+    for (const l of this._layers) if (l._tick(dt)) changed = true
+    if (this.speed !== this._lastSpeed || this.paused !== this._lastPaused) {
+      this._lastSpeed = this.speed; this._lastPaused = this.paused
+      _creator.animatorSetGlobal(this._id, this.speed, this.paused)
+    }
+    if (changed) this._push(false)
+    if (this.rootMotion) this._applyRootMotion(dt)
+  }
+
+  private _controller(): CharacterController | undefined {
+    return (this.node as unknown as { controller?: CharacterController }).controller
+  }
+
+  /** Root motion (last native frame's delta, node-local, horizontal): move the node, or feed the
+   *  CharacterController's velocity so it collides/slides like any other movement. */
+  private _applyRootMotion(dt: number): void {
+    if (typeof _creator.animatorGetRootMotion !== "function") return
+    const b = this._rootBuf
+    _creator.animatorGetRootMotion(this._id, b)
+    this._rootDelta = new Vec3(b[0], b[1], b[2])
+    if (!this.applyRootMotion || (b[0] === 0 && b[1] === 0 && b[2] === 0)) { this._controller()?._setExternalVelocity(0, 0, 0); return }
+    const controller = this._controller()
+    if (controller && controller.id) {
+      const w = this.node.worldMatrix.transformDirection(this._rootDelta)
+      const inv = dt > 0 ? 1 / dt : 0
+      controller._setExternalVelocity(w.x * inv, 0, w.z * inv)
+    } else {
+      const d = this.node.matrix.transformDirection(this._rootDelta)   // → the parent's space (rotation + scale)
+      this.node.position = this.node.position.add(d)
+    }
+  }
+
+  // ---- internals ----
+  /** @internal */
+  _bind(name: string, clip: AnimationClip, layer: AnimatorLayer, sync: number): SlotState | undefined {
+    if (this._id === 0) return undefined                     // host without Animator support (warned at attach)
+    const slot = _creator.animatorBind(this._id, clip._set, clip._index, layer.index, sync)
+    if (slot < 0) { console.warn(`Animator: could not bind clip '${name}'`); return undefined }
+    const bound = _creator.animatorBoundTracks(this._id, slot)
+    if (clip.trackCount > 0 && bound === 0) console.warn(`Animator: '${name}' — no track matched a node name under ${this.node.name || "the node"} (different rig?)`)
+    else if (bound < clip.trackCount) console.warn(`Animator: '${name}' — ${clip.trackCount - bound}/${clip.trackCount} tracks unbound (bone names not found)`)
+    const s: SlotState = { name, clip, slot, layer, weight: 0, target: 0, rate: Infinity, blendW: 0, playing: false, loop: false, inBlend: false, events: [], evTimes: [], outNorm: -1, fadeOut: 0, explicitOut: false, resolvers: [] }
+    while (this._all.length < slot) this._all.push(undefined as unknown as SlotState)
+    this._all[slot] = s
+    layer._slots.push(s)
+    layer._byName.set(name, s)
+    this._weights = new Float32Array(this._all.length)
+    const ev = this.events?.[name]
+    if (ev) {
+      const entries = Object.entries(ev).map(([t, e]) => [ Number(t), e ] as [number, string]).filter(([t]) => isFinite(t)).sort((a, b) => a[0] - b[0])
+      s.events = entries.map(([, e]) => e)
+      s.evTimes = entries.map(([t]) => Math.min(1, Math.max(0, t)))
+      _creator.animatorSetSlotEvents(this._id, slot, new Float32Array(s.evTimes))
+    }
+    return s
+  }
+
+  /** @internal — a faded-out one-shot: stop its clock and settle awaiting promises. */
+  _settle(s: SlotState): void {
+    if (s.playing && !s.inBlend) { s.playing = false; _creator.animatorSetSlot(this._id, s.slot, false, s.loop, 1, -1) }
+    const rs = s.resolvers; s.resolvers = []
+    for (const r of rs) r()
+  }
+
+  private _push(force: boolean): void {
+    const w = this._weights
+    let any = force
+    for (let i = 0; i < this._all.length; i++) {
+      const s = this._all[i]
+      const v = s ? s.layer._effective(s) : 0
+      if (Math.abs(w[i] - v) > EPS || (v === 0 && w[i] !== 0)) { w[i] = v; any = true }
+    }
+    if (any) _creator.animatorSetWeights(this._id, w)
+  }
+
+  /** @internal — native slot event: 0 completed (non-loop end), 1 loop wrapped, 2+i clip event i. */
+  _onSlotEvent(slot: number, type: number): void {
+    const s = this._all[slot]
+    if (!s) return
+    if (type === 1) { this._events.emit("loop", s.name, s.layer.name); return }
+    if (type >= 2) {
+      const i = type - 2
+      if (i === s.evTimes.length && s.outNorm >= 0) {              // the fade-out sentinel
+        if (s.playing && !s.inBlend && !s.loop && s.target > 0) this._startOut(s)
+        return
+      }
+      const ev = s.events[i]
+      if (ev) this._events.emit(ev, s.name, s.layer.name)
+      return
+    }
+    // completed: hold the last frame only if nothing returns; with a blend, fade back to it
+    s.playing = false
+    this._events.emit("completed", s.name, s.layer.name)
+    const rs = s.resolvers; s.resolvers = []
+    for (const r of rs) r()
+    if ((s.layer._members.length > 0 || s.explicitOut) && s.target > 0) this._startOut(s)   // fallback (resumed past the sentinel / cut)
+  }
+
+  /** @internal — begin a one-shot's fade-back: the slot out over its fadeOut, the blend (if any) in. */
+  _startOut(s: SlotState): void {
+    const rate = s.fadeOut > 0 ? 1 / s.fadeOut : Infinity
+    s.target = 0; s.rate = rate
+    const L = s.layer
+    if (L._members.length > 0) { L._blendTarget = 1; L._blendRate = rate }
+  }
+}
+
+const step = (v: number, target: number, maxDelta: number): number => {
+  if (!isFinite(maxDelta)) return target
+  const d = target - v
+  if (Math.abs(d) <= maxDelta) return target
+  return v + Math.sign(d) * maxDelta
+}

package/runtime/sdk/gl/CharacterController.ts

@@ -40,6 +40,8 @@ export class CharacterController extends Aspect<"controller", Node> {
   private _mz = 0
   private _jumpQueued = false
   private _vy = 0
+  private _ex = 0   // external horizontal velocity (world units/s) — root motion from an Animator
+  private _ez = 0
 
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
@@ -65,6 +67,9 @@ export class CharacterController extends Aspect<"controller", Node> {
   /** Queue a jump; consumed on the next frame if grounded. */
   jump(): void { this._jumpQueued = true }
 
+  /** @internal — extra world-space horizontal velocity added on top of `move()` this frame (root motion). */
+  _setExternalVelocity(x: number, _y: number, z: number): void { this._ex = x; this._ez = z }
+
   /** True while standing on walkable ground (OnGround). */
   get grounded(): boolean {
     return this._charId ? _creator.characterGetGroundState(this._charId) === 0 : false
@@ -96,6 +101,6 @@ export class CharacterController extends Aspect<"controller", Node> {
     if (this._jumpQueued && grounded) this._vy = this.jumpSpeed
     this._jumpQueued = false
     this._vy += this.gravity * dt                        // integrate gravity (CharacterVirtual is kinematic)
-    _creator.characterSetVelocity(this._charId, this._mx * this.speed, this._vy, this._mz * this.speed)
+    _creator.characterSetVelocity(this._charId, this._mx * this.speed + this._ex, this._vy, this._mz * this.speed + this._ez)
   }
 }