lecodes-sdk 1.0.0 → 1.2.0

package/src/gl/animation/core.ts

@@ -25,15 +25,24 @@ export type PlayOptions = {
   fade?: number
   /** Transition seconds for the way in only (overrides `fade`). */
   fadeIn?: number
-  /** One-shots: the transition BACK to the loop at the end (overrides `fade`; `0` = cut at the end).
-   *  It starts this long before the clip ends — while it still plays — so the hand-over lands on the
-   *  last pose, not after it. On a layer with no loop the clip HOLDS its last frame (a rock that broke
-   *  stays broken) — `anim.stop({ fade })` is the way back to rest. */
+  /** One-shots: the transition BACK to the loop after the end (overrides `fade`; `0` = cut at the end).
+   *  The clip plays to its last frame; the loop then takes over and the difference between the two poses
+   *  (and their velocities) decays over this time, so no part of the clip is cut — to play less of it,
+   *  give it an `end`. On a layer with no loop the clip HOLDS its last frame (a rock that broke stays
+   *  broken) — `anim.stop({ fade })` is the way back to rest. */
   fadeOut?: number
   /** Playback rate for this clip (default 1). */
   speed?: number
   /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
   restart?: boolean
+  /** Play a WINDOW of the clip, seconds of the clip: enter at `start` (default 0; only when the play
+   *  rewinds — see `restart`) and treat `end` (default the clip's end) as the end — the hand-over fires
+   *  there, the last frame held there, events beyond it never fire. Only the swing of a longer take, the
+   *  wind-up without the recovery. A window that lives in the clip table belongs in
+   *  `AnimationClip.from(clip, { from, to })` instead. Not combined with `phase`. Hosts without the
+   *  window play the whole clip. */
+  start?: number
+  end?: number
   /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
    *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
    *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
@@ -293,6 +302,12 @@ export class Core {
   ensure(): boolean {
     if (this.id) return true
     if (this.embedded().length === 0 && this.table.size === 0) { console.warn(`Animator: no clips on ${this.node.name || "the node"} — nothing to play`); return false }
+    return this.ensureRig()
+  }
+  /** The native animator for the RIG alone — an IK chain or a socket on a model that has no clips
+   *  still needs the joint tree described to the engine. False = no transform hierarchy (warned). */
+  ensureRig(): boolean {
+    if (this.id) return true
     ensureEvents()
     this.id = _creator.animatorCreate(this.node.id)
     if (!this.id) { console.warn("Animator: node has no transform hierarchy"); return false }
@@ -303,6 +318,7 @@ export class Core {
     if (this._feetParams && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, this._feetParams)
     if (this.speed !== 1) _creator.animatorSetGlobal(this.id, this.speed, false)
     for (const L of this.layers) if (L.index > 0) this.pushLayer(L)
+    for (const s of this._sockets.values()) this.pushSocket(s)
     return true
   }
   destroy(): void {
@@ -378,6 +394,11 @@ export class Core {
     s.playback = rec
     _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
     if (o.turn !== undefined) _creator.animatorSlotSetTurn?.(this.id, s.slot, o.turn * Math.PI / 180, true)
+    if (o.start !== undefined || o.end !== undefined) {
+      const st = Math.max(0, o.start ?? 0), en = o.end === undefined ? -1 : Math.min(o.end, clip.duration)
+      if (en >= 0 && en <= st) console.warn(`Animator: '${name}' window ${st}–${o.end} is empty (${clip.duration.toFixed(2)}s clip)`)
+      _creator.animatorSlotSetWindow?.(this.id, s.slot, st, en)
+    }
     if (phase !== undefined) _creator.animatorSeekPhase(this.id, s.slot, phase)
     return new Playback(rec, this)
   }
@@ -671,6 +692,11 @@ export class Core {
     this._warp = params
     if (this.id) _creator.animatorSetWarpParams(this.id, params)
   }
+  /** The body's world velocity this frame (m/s) — the game side of the stride / orientation fit. Nothing
+   *  to feed before the animator exists; hosts without the warp stage have no method. */
+  setMotion(vx: number, vy: number, vz: number): void {
+    if (this.id && _creator.animatorSetMotion) _creator.animatorSetMotion(this.id, vx, vy, vz)
+  }
   /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
   private _feetParams?: Float32Array
   setFeetParams(params: Float32Array): void {
@@ -682,6 +708,41 @@ export class Core {
   footState(side: 0 | 1, out: Float32Array): boolean {
     return this.id !== 0 && _creator.animatorFootState !== undefined && _creator.animatorFootState(this.id, side, out)
   }
+  // ---- IK chains + sockets (creator-anim anchors.cpp; the aspects in IK.ts) ----
+  // Hosts without the chains (an engine predating them) get a warning once and inert chains.
+  private static _warnedIk = false
+  private hasIk(): boolean {
+    if (_creator.animatorIkCreate) return true
+    if (!Core._warnedIk) { Core._warnedIk = true; console.warn("IK: this host has no IK chains (engine predates them) — chains and sockets are inert") }
+    return false
+  }
+  /** A chain ending in `endEntity` (kind 0 two-bone: the bone, its parent, its grandparent; 1 look-at). 0 = none. */
+  ikCreate(kind: 0 | 1, endEntity: number): number {
+    if (!this.ensureRig() || !this.hasIk()) return 0
+    return _creator.animatorIkCreate!(this.id, kind, endEntity)
+  }
+  ikDestroy(ik: number): void { if (this.id && _creator.animatorIkDestroy) _creator.animatorIkDestroy(this.id, ik) }
+  ikSet(ik: number, params: Float32Array): void { if (this.id && _creator.animatorIkSet) _creator.animatorIkSet(this.id, ik, params) }
+  ikNodes(ik: number, target: number, pole: number, rotation: number): void { if (this.id && _creator.animatorIkNodes) _creator.animatorIkNodes(this.id, ik, target, pole, rotation) }
+  ikAnchor(ik: number, socket: string): void { if (this.id && _creator.animatorIkAnchor) _creator.animatorIkAnchor(this.id, ik, socket) }
+  ikState(ik: number, out: Float32Array): boolean { return this.id !== 0 && _creator.animatorIkState !== undefined && _creator.animatorIkState(this.id, ik, out) }
+  /** Sockets by "set/name", replayed when the animator is (re)created. */
+  private readonly _sockets = new Map<string, { set: string, name: string, joint: number, node: number, trs: Float32Array | null }>()
+  /** Define a socket on joint `joint` (a bone's entity): a NODE socket (read by the engine every frame) or a
+   *  fixed TRS in the joint's space. set "" = the live set, any other name = a donor's. */
+  setSocket(set: string, name: string, joint: number, node: number, trs: Float32Array | null): void {
+    const rec = { set, name, joint, node, trs }
+    this._sockets.set(`${set}/${name}`, rec)
+    if (this.ensureRig()) this.pushSocket(rec)
+  }
+  removeSocket(set: string, name: string): void {
+    this._sockets.delete(`${set}/${name}`)
+    if (this.id && _creator.animatorSetSocket) _creator.animatorSetSocket(this.id, set, name, 0, 0, null)
+  }
+  private pushSocket(s: { set: string, name: string, joint: number, node: number, trs: Float32Array | null }): void {
+    if (this.hasIk() && _creator.animatorSetSocket) _creator.animatorSetSocket(this.id, s.set, s.name, s.joint, s.node, s.trs)
+  }
+
   private readonly _steps = new Set<StepHandler>()
   onStepHandler(cb: StepHandler): void { this._steps.add(cb) }
   offStepHandler(cb: StepHandler): void { this._steps.delete(cb) }