lecodes-sdk 0.19.1 → 0.20.0

package/src/gl/animation/Feet.ts

@@ -0,0 +1,134 @@
+// Feet — `anim.feet`: which bones the feet are, and what the engine does with them after the clips are
+// composited — the foot LOCK (a planted foot stays where it landed while the body moves on) and GROUND
+// IK (each foot on the ground probed under it, the pelvis lowered). Docs: docs/animation-v2-plan.md §2.9.
+//
+//   model.anim.feet.lock = true                                   // (a Locomotion does this itself)
+//   model.anim.feet.set({ lock: true, ik: true, pelvis: 0.3 })    // stairs and slopes
+//   model.anim.feet.set({ left: 'LeftFoot', right: 'RightFoot' }) // a rig the classifier misses
+//   model.anim.feet.onStep(({ side, position }) => dust(position))
+//
+// The engine probes the ground itself (against what a character can stand on) and reads the
+// CharacterController's ground state; nothing is fed per frame.
+
+import { Vec3 } from "../../math/vec"
+import type { Core, KneeAxisReport, StepHandler } from "./core"
+
+/** The feet settings (`anim.feet.set()` / the properties of `anim.feet`). Distances are metres, times
+ *  seconds. Every key is optional and only the keys given change. */
+export type FeetOptions = {
+  /** The contact bones per side — `'LeftFoot'`, or with a toe / ball `['LeftFoot', 'LeftToeBase']`.
+   *  Default: classified from the bone names (Mixamo / Unity / Blender / UE). Setting them re-bakes
+   *  every clip's contacts and phase. */
+  left?: string | string[]
+  right?: string | string[]
+  /** FOOT LOCK: a foot the shown clip calls planted is pinned where it landed — heel to ball, rolling
+   *  as the clip rolls — and the leg re-solved to keep it there while the body moves on. Off by default. */
+  lock?: boolean
+  /** GROUND IK: each foot is put on the ground the engine probes under it (stairs, a slope, a kerb),
+   *  aligned to its normal, the pelvis lowered so the leg can reach. Needs a physics world to probe;
+   *  without one the ground is the node's own plane. Off by default. */
+  ik?: boolean
+  /** How far the pelvis may drop for the ground (default 0.35). */
+  pelvis?: number
+  /** A locked foot never absorbs more residual than this — beyond it the anchor follows the animation
+   *  instead of fighting it (default 0.10). */
+  unlockDistance?: number
+  /** The lock's ease in / out, seconds (default 0.08 / 0.12). */
+  lockIn?: number
+  lockOut?: number
+  /** 0..1: how much the foot tilts onto the ground normal (default 1). */
+  align?: number
+  /** The probe ray's reach above and below the ankle (default 0.6). */
+  probe?: number
+  /** The lock plants only once the animated ankle moves slower than this, m/s (default 0.2). Raise it
+   *  to pin a foot a transition is still dragging. */
+  plantSpeed?: number
+}
+
+/** One foot after this frame's evaluation (`anim.feet.state(side)`): whether the lock holds it, the
+ *  lock's weight (eased 0…1), where it was pinned and where the leg was asked to put the ankle — all world. */
+export type FootState = { locked: boolean, weight: number, anchor: Vec3, target: Vec3 }
+
+const P = { IK: 0, LOCK: 1, PELVIS: 2, UNLOCK_DIST: 3, LOCK_IN: 4, LOCK_OUT: 5, PELVIS_TIME: 6, ALIGN: 7, PROBE: 8, DETECT_SPEED: 9, DETECT_HEIGHT: 10, PLANT_SPEED: 11, COUNT: 12 }
+const DEFAULTS = { pelvis: 0.35, unlockDistance: 0.10, lockIn: 0.08, lockOut: 0.12, align: 1, probe: 0.6, plantSpeed: 0.2 }
+const footBuf = new Float32Array(8)
+
+export class Feet {
+  private readonly _c: Core
+  private readonly _o: FeetOptions = {}
+  /** @internal — created by the Animator. */
+  constructor(core: Core) { this._c = core }
+
+  /** Change several settings at once; only the keys given change. Chainable. */
+  set(options: FeetOptions): this {
+    Object.assign(this._o, options)
+    if (options.left !== undefined || options.right !== undefined) this.pushBones()
+    this.push()
+    return this
+  }
+  /** The current settings (what was set; unset keys are the engine's defaults). */
+  get options(): Readonly<FeetOptions> { return this._o }
+
+  get lock(): boolean { return !!this._o.lock }
+  set lock(v: boolean) { this._o.lock = v; this.push() }
+  get ik(): boolean { return !!this._o.ik }
+  set ik(v: boolean) { this._o.ik = v; this.push() }
+  get pelvis(): number { return this._o.pelvis ?? DEFAULTS.pelvis }
+  set pelvis(v: number) { this._o.pelvis = v; this.push() }
+  get unlockDistance(): number { return this._o.unlockDistance ?? DEFAULTS.unlockDistance }
+  set unlockDistance(v: number) { this._o.unlockDistance = v; this.push() }
+  get lockIn(): number { return this._o.lockIn ?? DEFAULTS.lockIn }
+  set lockIn(v: number) { this._o.lockIn = v; this.push() }
+  get lockOut(): number { return this._o.lockOut ?? DEFAULTS.lockOut }
+  set lockOut(v: number) { this._o.lockOut = v; this.push() }
+  get align(): number { return this._o.align ?? DEFAULTS.align }
+  set align(v: number) { this._o.align = v; this.push() }
+  get probe(): number { return this._o.probe ?? DEFAULTS.probe }
+  set probe(v: number) { this._o.probe = v; this.push() }
+  get plantSpeed(): number { return this._o.plantSpeed ?? DEFAULTS.plantSpeed }
+  set plantSpeed(v: number) { this._o.plantSpeed = v; this.push() }
+  /** The contact bones (`undefined` = classified from the names). */
+  get left(): string | string[] | undefined { return this._o.left }
+  set left(v: string | string[] | undefined) { this._o.left = v; this.pushBones() }
+  get right(): string | string[] | undefined { return this._o.right }
+  set right(v: string | string[] | undefined) { this._o.right = v; this.pushBones() }
+
+  /** One foot's state after this frame's evaluation — where the lock holds it and with what weight
+   *  (a debug beam under the foot). `undefined` on a host without the feet stage, or before anything played. */
+  state(side: "left" | "right"): FootState | undefined {
+    if (!this._c.footState(side === "left" ? 0 : 1, footBuf)) return undefined
+    return { locked: footBuf[0]! > 0.5, weight: footBuf[1]!, anchor: new Vec3(footBuf[2]!, footBuf[3]!, footBuf[4]!), target: new Vec3(footBuf[5]!, footBuf[6]!, footBuf[7]!) }
+  }
+  /** The skeleton's calibrated KNEE HINGE AXIS for a side (thigh-local, unit) with its confidence report —
+   *  measured once over every bound clip's knee rotation track. `undefined` = no leg chain, or no knee
+   *  motion bound to calibrate from. */
+  kneeAxis(side: "left" | "right"): KneeAxisReport | undefined { return this._c.kneeAxis(side) }
+
+  /** A foot planted (world position) — audio, dust, decals. Fires for what the BASE layer shows, from
+   *  the clip's own contacts; a clip with no contacts fires nothing. */
+  onStep(cb: StepHandler): this { this._c.onStepHandler(cb); return this }
+  offStep(cb: StepHandler): this { this._c.offStepHandler(cb); return this }
+
+  private pushBones(): void {
+    const join = (v: string | string[] | undefined): string => v === undefined ? "" : Array.isArray(v) ? v.join("\n") : v
+    this._c.setFeet(join(this._o.left), join(this._o.right))
+  }
+  private push(): void {
+    const o = this._o
+    const p = new Float32Array(P.COUNT)
+    // the engine's own defaults (canimAnimatorFeetDefaults)
+    p[P.PELVIS] = DEFAULTS.pelvis; p[P.UNLOCK_DIST] = DEFAULTS.unlockDistance; p[P.LOCK_IN] = DEFAULTS.lockIn; p[P.LOCK_OUT] = DEFAULTS.lockOut
+    p[P.PELVIS_TIME] = 0.15; p[P.ALIGN] = DEFAULTS.align; p[P.PROBE] = DEFAULTS.probe; p[P.DETECT_SPEED] = 0.35; p[P.DETECT_HEIGHT] = 0.12
+    p[P.PLANT_SPEED] = DEFAULTS.plantSpeed
+    if (o.ik) p[P.IK] = 1
+    if (o.lock) p[P.LOCK] = 1
+    if (o.pelvis !== undefined) p[P.PELVIS] = o.pelvis
+    if (o.unlockDistance !== undefined) p[P.UNLOCK_DIST] = o.unlockDistance
+    if (o.lockIn !== undefined) p[P.LOCK_IN] = o.lockIn
+    if (o.lockOut !== undefined) p[P.LOCK_OUT] = o.lockOut
+    if (o.align !== undefined) p[P.ALIGN] = o.align
+    if (o.probe !== undefined) p[P.PROBE] = o.probe
+    if (o.plantSpeed !== undefined) p[P.PLANT_SPEED] = o.plantSpeed
+    this._c.setFeetParams(p)
+  }
+}

package/src/gl/animation/Loop.ts

@@ -1,6 +1,8 @@
 // Loop — a layer's LOOP: what it shows when no one-shot plays (`anim.playLoop('Idle')` — one looping clip,
 // or `anim.playLoop({ Idle: 0, Walking: 2, Run: 6 })` — a blend whose members cycle in phase and `value`
-// picks the mix: 1D linear between neighbours, `[x, y]` positions = a 2D gradient band). A one-shot takes
+// picks the mix: 1D linear between neighbours, `[x, y]` positions = a 2D gradient band; a member given as
+// `{ at, offset, cycles }` carries its gait cycle, measured offline from its foot marks; a bare position
+// = normalized time, no cycle). A one-shot takes
 // the layer over and hands it back; `playLoop(next)` transitions to another; `stop()` removes it. The
 // object returned by `playLoop()` (also `anim.loop`) is the handle; a replaced loop's object goes dead.
 

package/src/gl/animation/Warp.ts

@@ -0,0 +1,96 @@
+// Warp — `anim.warp`: the pose fitted to what the body actually does, after the clips are composited and
+// before the feet (docs/animation-v2-plan.md §2.7). `stride` scales each leg's step to the speed the body
+// really travels at (a walk played at 1.9 m/s stops skating); `orientation` turns the lower body toward
+// where the body really goes while the spine counter-turns (arcs and strafing without a clip per angle).
+// Both need the body's motion, which a `Locomotion` feeds every frame; without one leave it off. Off by
+// default. `step` is the STEP WARP: stride / lift / pitch / slope dials solved in the knee hinge plane.
+//
+//   model.anim.warp.set(true)                                       // both, with the defaults
+//   model.anim.warp.set({ stride: [0.7, 1.4], orientation: 45 })
+//   model.anim.warp.orientation = 12                                // a lean only
+//   model.anim.warp.step = { slope: 15 }                            // an invisible staircase
+
+import type { Core } from "./core"
+
+/** What `anim.warp` turns on. Speeds are m/s, angles degrees, distances metres. */
+export type WarpOptions = {
+  /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale (default
+   *  0.85…1.2). A CORRECTION: a pack whose takes already read right at the speeds it is played at wants
+   *  none of this; open the range for a pack that must cover speeds it was never recorded at. */
+  stride?: boolean | [number, number]
+  /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
+   *  (default 20). The whole twist lives in one joint: a few degrees read as a lean, a lot as a broken
+   *  back. Only applied while the gait LOOP shows — a start, a turn or a stop walks a path of its own. */
+  orientation?: boolean | number
+  /** Below this speed — the game's or the clip's — both warps are off (default 0.2). */
+  minSpeed?: number
+  /** How far the pelvis may drop to keep a stretched leg from locking straight (default 0.25). */
+  pelvis?: number
+  /** The stride scale's own spring, seconds (default 0.15): the shown clip's recorded speed steps at every
+   *  switch, so the scale is smoothed rather than followed. */
+  strideTime?: number
+}
+
+/** STEP WARP dials (`anim.warp.step`): `stride` scales each foot's travel-direction offset from its hip,
+ *  `lift` = metres ADDED to its height (swing-gated; negative = a shuffle; half of it raises the pelvis),
+ *  `pitch` (degrees, + = toes up) rotates each foot about its lateral axis, `slope` (degrees, + = ascending)
+ *  the invisible staircase — feet on the incline, auto pitch, the character raised to hold each planted
+ *  foot on its tread. A tuning bench's dial; locomotion will drive this itself later. */
+export type StepWarpOptions = { stride?: number, lift?: number, pitch?: number, slope?: number }
+
+const P = { STRIDE: 0, STRIDE_MIN: 1, STRIDE_MAX: 2, ORIENT: 3, ORIENT_MAX: 4, ORIENT_TIME: 5, MIN_SPEED: 6, PELVIS: 7, STRIDE_TIME: 8, COUNT: 9 }
+const DEFAULTS = { strideMin: 0.85, strideMax: 1.2, orientMax: 20, minSpeed: 0.2, pelvis: 0.25, strideTime: 0.15 }
+
+export class Warp {
+  private readonly _c: Core
+  private _o: WarpOptions = {}
+  private _step: StepWarpOptions | null = null
+  /** @internal — created by the Animator. */
+  constructor(core: Core) { this._c = core }
+
+  /** Replace the settings: `true` = both warps with the defaults, `false` / `{}` = off, or the options.
+   *  (Replaces, does not merge — what is not asked for is off.) Chainable. */
+  set(w: WarpOptions | boolean): this {
+    this._o = w === true ? { stride: true, orientation: true } : w === false ? {} : { ...w }
+    this.push()
+    return this
+  }
+  /** The current settings. */
+  get options(): Readonly<WarpOptions> { return this._o }
+
+  get stride(): boolean | [number, number] { return this._o.stride ?? false }
+  set stride(v: boolean | [number, number]) { this._o.stride = v; this.push() }
+  get orientation(): boolean | number { return this._o.orientation ?? false }
+  set orientation(v: boolean | number) { this._o.orientation = v; this.push() }
+  get minSpeed(): number { return this._o.minSpeed ?? DEFAULTS.minSpeed }
+  set minSpeed(v: number) { this._o.minSpeed = v; this.push() }
+  get pelvis(): number { return this._o.pelvis ?? DEFAULTS.pelvis }
+  set pelvis(v: number) { this._o.pelvis = v; this.push() }
+  get strideTime(): number { return this._o.strideTime ?? DEFAULTS.strideTime }
+  set strideTime(v: number) { this._o.strideTime = v; this.push() }
+
+  /** The step warp dials; `null` = off. */
+  get step(): StepWarpOptions | null { return this._step }
+  set step(v: StepWarpOptions | null | undefined) { this._step = v ?? null; this._c.setStepWarp(this._step) }
+
+  private push(): void {
+    const o = this._o
+    const p = new Float32Array(P.COUNT)
+    // the engine's own defaults (canimAnimatorWarpDefaults): what is not asked for stays neutral
+    p[P.STRIDE_MIN] = DEFAULTS.strideMin; p[P.STRIDE_MAX] = DEFAULTS.strideMax; p[P.ORIENT_MAX] = DEFAULTS.orientMax
+    p[P.ORIENT_TIME] = 0.15; p[P.MIN_SPEED] = DEFAULTS.minSpeed; p[P.PELVIS] = DEFAULTS.pelvis
+    p[P.STRIDE_TIME] = DEFAULTS.strideTime
+    if (o.stride) {
+      p[P.STRIDE] = 1
+      if (Array.isArray(o.stride)) { p[P.STRIDE_MIN] = o.stride[0]; p[P.STRIDE_MAX] = o.stride[1] }
+    }
+    if (o.orientation) {
+      p[P.ORIENT] = 1
+      if (typeof o.orientation === "number") p[P.ORIENT_MAX] = o.orientation
+    }
+    if (o.minSpeed !== undefined) p[P.MIN_SPEED] = o.minSpeed
+    if (o.pelvis !== undefined) p[P.PELVIS] = o.pelvis
+    if (o.strideTime !== undefined) p[P.STRIDE_TIME] = o.strideTime
+    this._c.setWarp(p)
+  }
+}