lecodes-cli 0.16.1 → 0.17.0

package/runtime/sdk/gl/IK.ts

@@ -0,0 +1,170 @@
+// IK — precise character actions as late-phase aspects on BONES (docs/animation-plan.md §2.5).
+// They run after the animation wrote the pose (base anim or Animator) and before the skin is
+// flushed, so their bone writes land in the skin. Attach to the END bone of the chain; the chain is
+// walked up through parents — one instance per end effector, any Node hierarchy works.
+//
+//   const foot = hero.bone('LeftFoot')!
+//   foot.aspect(IK.TwoBone, { target: footTarget, pole: kneeHint })     // upLeg → leg → foot
+//   foot.ik.weight = grounded ? 1 : 0                                    // blend in/out
+//   hero.bone('Head')!.aspect(IK.LookAt, { target: camera, limit: 70 })  // head tracks the camera
+//
+// Pure SDK/JS: a handful of world-matrix reads + two quaternion writes per solve. A native solver can
+// slot in later behind the same API.
+
+import { Aspect } from "../core/Aspect"
+import { Vec3, type Vec3Like } from "../math/vec"
+import { Quat } from "../math/quat"
+import type { Node } from "./Node"
+
+type Target = Node | Vec3Like
+
+const targetPos = (t: Target | undefined): Vec3 | null => {
+  if (t === undefined || t === null) return null
+  const n = t as Node
+  if (typeof (n as { worldPosition?: unknown }).worldPosition === "object" && typeof n.id === "number") return n.worldPosition
+  return new Vec3(t as Vec3Like)
+}
+
+/** World rotation of a node (parent chain composed natively). */
+const worldRot = (n: Node): Quat => n.worldMatrix.rotation
+
+/** Write a WORLD rotation to a node by converting through the parent's world rotation. */
+const setWorldRot = (n: Node, q: Quat): void => {
+  const p = n.parent
+  n.quaternion = p ? worldRot(p).invert().mul(q).normalize() : q.normalize()
+}
+
+const clampAngle = (q: Quat, maxRad: number): Quat => {
+  // angle of a unit quaternion = 2·acos(|w|)
+  const w = Math.min(1, Math.abs(q.w))
+  const ang = 2 * Math.acos(w)
+  if (ang <= maxRad || ang < 1e-6) return q
+  const s = Math.sqrt(1 - w * w)
+  const axis = new Vec3(q.x / s, q.y / s, q.z / s)
+  return Quat.fromAxisAngle(axis, q.w < 0 ? -maxRad : maxRad)
+}
+
+/** Two-bone analytic IK (limbs). Attach to the END bone: `foot.aspect(IK.TwoBone, { target })`
+ *  solves upper (grandparent) + mid (parent) so the end reaches `target`; `pole` steers the bend
+ *  (knee/elbow) — a Node or world point. */
+class TwoBone extends Aspect<"ik", Node> {
+  static readonly aspect = "ik"
+
+  /** Where the end bone should be (Node or world position). */
+  target?: Target
+  /** Bend hint — the mid joint is pulled toward it (Node or world position). */
+  pole?: Target
+  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+  weight = 1
+  /** Solve every frame (default). Set false to drive `solve()` yourself. */
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  /** One solve at the current pose. Safe to call manually (e.g. from a later-ordered aspect). */
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const end = this.node
+    const mid = end.parent
+    const root = mid?.parent
+    if (!mid || !root) return
+
+    const w = Math.min(1, this.weight)
+    const midLocal0 = mid.quaternion
+    const rootLocal0 = root.quaternion
+
+    const a = root.worldPosition, b = mid.worldPosition, c = end.worldPosition
+    const l1 = a.distanceTo(b), l2 = b.distanceTo(c)
+    if (l1 < 1e-6 || l2 < 1e-6) return
+    const eps = 1e-4
+    const toT = t.sub(a)
+    const d = Math.min(Math.max(toT.length(), eps), l1 + l2 - eps)
+
+    // 1. bend the mid joint to the angle the target distance demands (law of cosines)
+    const ba = a.sub(b), bc = c.sub(b)
+    const cur = ba.angle(bc)
+    const want = Math.acos(Math.min(1, Math.max(-1, (l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2))))
+    let axis = bc.cross(ba)
+    if (axis.lengthSq() < 1e-10) {
+      // straight limb: bend toward the pole (or any perpendicular)
+      const p = targetPos(this.pole)
+      const ref = p ? p.sub(b) : new Vec3(0, 0, 1)
+      axis = ba.cross(ref)
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(0, 1, 0))
+      if (axis.lengthSq() < 1e-10) axis = ba.cross(new Vec3(1, 0, 0))
+    }
+    axis = axis.normalize()
+    // rotating mid by (want - cur) about `axis` opens/closes the angle between ba and bc
+    const midWorld = worldRot(mid)
+    setWorldRot(mid, Quat.fromAxisAngle(axis, want - cur).mul(midWorld))
+
+    // 2. swing the root so the end lands on the target direction
+    const c2 = end.worldPosition
+    const rootWorld = worldRot(root)
+    setWorldRot(root, Quat.fromTo(c2.sub(a), toT).mul(rootWorld))
+
+    // 3. pole: spin the root about the root→target axis so the mid joint lies toward the pole
+    const p = targetPos(this.pole)
+    if (p) {
+      const dir = toT.normalize()
+      const b2 = mid.worldPosition
+      const midProj = b2.sub(a).sub(dir.scale(b2.sub(a).dot(dir)))
+      const poleProj = p.sub(a).sub(dir.scale(p.sub(a).dot(dir)))
+      if (midProj.lengthSq() > 1e-10 && poleProj.lengthSq() > 1e-10) {
+        setWorldRot(root, Quat.fromTo(midProj, poleProj).mul(worldRot(root)))
+      }
+    }
+
+    // 4. weight: blend from the animated pose to the solved one
+    if (w < 1) {
+      root.quaternion = rootLocal0.slerp(root.quaternion, w)
+      mid.quaternion = midLocal0.slerp(mid.quaternion, w)
+    }
+  }
+}
+
+/** Aim a bone at a target (head / eyes / turret). Attach to the bone itself:
+ *  `head.aspect(IK.LookAt, { target: camera, limit: 70 })`. `axis` is the bone's LOCAL forward
+ *  (the direction that should point at the target) — rigs differ; default −Z, Mixamo heads look
+ *  along +Z of the head bone in most exports, so pass `axis: [0, 0, 1]` there if it faces backwards. */
+class LookAt extends Aspect<"lookAt", Node> {
+  static readonly aspect = "lookAt"
+
+  target?: Target
+  /** The bone's local axis that should point at the target. */
+  axis: Vec3Like = [ 0, 0, -1 ]
+  /** Max deflection from the animated direction, in degrees (default 80). */
+  limit = 80
+  /** 0–1 contribution. */
+  weight = 1
+  enabled = true
+
+  update(): void {
+    if (this.enabled) this.solve()
+  }
+
+  solve(): void {
+    const t = targetPos(this.target)
+    if (!t || this.weight <= 0) return
+    const bone = this.node
+    const w = Math.min(1, this.weight)
+    const local0 = bone.quaternion
+    const from = bone.worldPosition
+    const dir = t.sub(from)
+    if (dir.lengthSq() < 1e-10) return
+    const rot = worldRot(bone)
+    const current = new Vec3(this.axis).rotate(rot)
+    let delta = Quat.fromTo(current, dir)
+    delta = clampAngle(delta, (this.limit * Math.PI) / 180)
+    setWorldRot(bone, delta.mul(rot))
+    if (w < 1) bone.quaternion = local0.slerp(bone.quaternion, w)
+  }
+}
+
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export const IK = { TwoBone, LookAt }
+export type IKTwoBone = TwoBone
+export type IKLookAt = LookAt

package/runtime/sdk/gl/Material.ts

@@ -81,7 +81,7 @@ export class Material {
   readonly uniforms: Record<string, UniformValue>
 
   private _colorKey: string | null = null
-  private _useMapFlag = true
+  private _useMapFlag = false
 
   constructor(shader: FetchResponse | number) {
     if (typeof shader === "number") {

package/runtime/sdk/gl/ModelAnimation.ts

@@ -1,8 +1,12 @@
 // GLB skeletal animation as an aspect. Auto-attached by Model (a glb always has its clips), so you
 // reach it directly: model.anim.play('Run'). Clips come baked in the glb; play by name or index.
+// This is the BASE player (one clip at a time, Filament's Animator underneath). For crossfades,
+// blend spaces, layers and clips from other files attach the Animator aspect — it takes the skeleton
+// over while attached and this player is suspended (docs/animation-plan.md).
 
 import { Aspect } from "../core/Aspect"
 import { nodeRegistry } from "./Node"
+import { AnimationClip } from "./AnimationClip"
 import type { Model } from "./Model"
 
 let animatorRegistered = false
@@ -19,6 +23,8 @@ export class ModelAnimation extends Aspect<"anim", Model> {
   private _clip = 0
   private _speed = 1
   private _loop = false
+  private _suspended = false
+  private _clips?: AnimationClip[]
 
   onAttach(): void {
     this.node._animComplete = (clipIndex) => {
@@ -29,17 +35,41 @@ export class ModelAnimation extends Aspect<"anim", Model> {
     }
   }
 
-  /** The clips baked into the glb. */
-  get clips(): { name: string, duration: number }[] { return _creator.getGlbAnimations(this.node.id) }
+  /** The clips baked into the glb, as AnimationClip objects (usable in an Animator's clip table —
+   *  e.g. share one model's baked clip with another model of the same rig). */
+  get clips(): AnimationClip[] {
+    if (this._clips) return this._clips
+    const setId = typeof _creator.getGlbClipSet === "function" ? _creator.getGlbClipSet(this.node.id) : 0
+    if (setId) this._clips = AnimationClip._ofSet(setId)
+    else {
+      // no embedded set (older / lite hosts, or a GLB without animations): name + duration only
+      this._clips = ((_creator.getGlbAnimations(this.node.id) ?? []) as { name: string, duration: number }[])
+        .map((c) => ({ name: c.name, duration: c.duration, trackCount: 0 }) as unknown as AnimationClip)
+    }
+    return this._clips
+  }
+
+  /** @internal — an Animator owns the skeleton while attached; this player goes quiet. */
+  _suspend(on: boolean): void {
+    this._suspended = on
+    if (on && this._playing) { this._playing = false }
+  }
+  private _blocked(): boolean {
+    if (!this._suspended) return false
+    console.warn("model.anim is suspended while an Animator is attached — use model.animator")
+    return true
+  }
 
   get playing(): boolean { return this._playing }
   set playing(value: boolean) {
+    if (this._blocked()) return
     this._playing = value
     _creator.setAnimation(this.node.id, value, this._clip, this._speed)
   }
 
   /** Play a clip by name or index. Chainable. */
   play(clip?: string | number, options: { loop?: boolean } = {}): this {
+    if (this._blocked()) return this
     if (typeof clip === "number") this._clip = clip
     else if (typeof clip === "string") {
       const i = this.clips.findIndex((c) => c.name === clip)
@@ -57,8 +87,9 @@ export class ModelAnimation extends Aspect<"anim", Model> {
   get speed(): number { return this._speed }
   set speed(v: number) {
     this._speed = v
+    if (this._suspended) return
     _creator.setAnimation(this.node.id, this._playing, this._clip, v)
   }
   get time(): number { return _creator.getAnimationTime(this.node.id) }
-  set time(v: number) { _creator.setAnimationTime(this.node.id, this._clip, v) }
+  set time(v: number) { if (!this._blocked()) _creator.setAnimationTime(this.node.id, this._clip, v) }
 }

package/runtime/sdk/gl/Node.ts

@@ -13,6 +13,7 @@ import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
 import { ensurePhysicsEvents } from "./physicsEvents"
+import { glState } from "./state"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 
 /** id → Node, so host callbacks (touch hits, animation events) route back to the owning object. */
@@ -45,8 +46,10 @@ export class Node extends AspectHost<NodeEvents> {
 
   private _matrix?: Float32Array
   private _lastSync = 0
+  private _syncFrame = -1
   private _worldMatrix?: Float32Array
   private _scaleCache?: [number, number, number]
+  private _boneCache?: Map<string, Node | null>
 
   /** @internal — the active animation aspect's clip-complete handler (installed by ModelAnimation). */
   _animComplete?: (clipIndex: number) => boolean
@@ -73,10 +76,13 @@ export class Node extends AspectHost<NodeEvents> {
   // hot path that returns the cache directly for cheap component reads.
   private _sync(): Float32Array {
     if (!this._matrix) this._matrix = new Float32Array(16)
-    if (this._lastSync === 0 || Date.now() - this._lastSync > 10) {
+    // stale once per render frame (glState.frame — physics/controllers/animation rewrite transforms
+    // between frames), or after 10 ms of wall time when no scene loop is running
+    if (this._lastSync === 0 || this._syncFrame !== glState.frame || Date.now() - this._lastSync > 10) {
       _creator.getMatrix(this.id, this._matrix)
       this._scaleCache = undefined
       this._lastSync = Date.now()
+      this._syncFrame = glState.frame
     }
     return this._matrix
   }
@@ -178,6 +184,26 @@ export class Node extends AspectHost<NodeEvents> {
     callback(this)
     _creator.traverse(this.id, (id) => callback(nodeRegistry.get(id) ?? new Node(id)))
   }
+  /** Find a descendant by name — bones of a loaded Model included (`hero.bone('RightHand').add(sword)`).
+   *  Exact name first, then the part after the last `:` / `|` (Mixamo `mixamorig:Hips` matches `Hips`).
+   *  Cached per name; null if absent. */
+  bone(name: string): Node | null {
+    const cache = (this._boneCache ??= new Map<string, Node | null>())
+    const hit = cache.get(name)
+    if (hit !== undefined) return hit
+    let exact: Node | null = null
+    let loose: Node | null = null
+    const want = name.slice(name.search(/[^:|]*$/))
+    _creator.traverse(this.id, (id) => {
+      if (exact) return
+      const n = _creator.getName(id)
+      if (n === name) exact = nodeRegistry.get(id) ?? new Node(id)
+      else if (!loose && n.slice(n.search(/[^:|]*$/)) === want) loose = nodeRegistry.get(id) ?? new Node(id)
+    })
+    const found = exact ?? loose
+    cache.set(name, found)
+    return found
+  }
 
   // --- behaviors are aspects: node.aspect(Shape, …) / node.aspect(Physics, …) ---