lecodes-cli 0.18.2 → 0.19.2

package/runtime/sdk/gl/animation/core.ts

@@ -1,294 +0,0 @@
-// The engine-facing core behind Animator / Layer / Blend / Playback (docs/animator-plan.md). NOT exported
-// from the SDK: the public classes are thin views over the records here. The engine runs the whole
-// per-frame loop (fades, blend spaces, one-shot fade-back, root motion); this file binds clips,
-// issues play/stop/blend calls and routes the engine's slot events back to playbacks.
-
-import { AnimationClip } from "./AnimationClip"
-import { Loop } from "./Loop"
-import { Layer } from "./Layer"
-import { Playback } from "./Playback"
-import type { Node } from "../Node"
-
-/** A position on a blend axis (1D) or plane (2D). */
-export type BlendPosition = number | readonly [number, number]
-
-export type PlayOptions = {
-  /** Crossfade seconds for BOTH ends (default 0 = cut). */
-  fade?: number
-  /** Fade-in seconds (overrides `fade`). */
-  fadeIn?: number
-  /** One-shots: 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, giving `fadeOut` releases the layer at the end instead of holding the
-   *  last frame. */
-  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
-}
-
-export type StopOptions = { fade?: number }
-
-export type LoopOptions = {
-  /** Crossfade seconds from whatever the layer shows — the previous loop, or a one-shot still playing
-   *  (default 0 = cut). */
-  fade?: number
-  /** Playback rate of the loop's clips (default 1). */
-  speed?: number
-}
-/** What a layer loops: one clip (name / index), or a blend space `{ name: position }`. */
-export type LoopDef = string | number | Record<string, BlendPosition>
-
-export type LayerOptions = {
-  /** 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). */
-  weight?: number
-}
-
-export type ClipEventHandler = (clip: string, layer: Layer) => void
-
-// ---- records -------------------------------------------------------------------------------------
-
-export type SlotRec = { name: string, clip: AnimationClip, slot: number, layer: LayerRec, inBlend: boolean, playback?: PlaybackRec }
-export type PlaybackRec = { slot: SlotRec, playing: boolean, done: Promise<boolean>, resolve: (natural: boolean) => void }
-export type LayerRec = { index: number, view: Layer, slots: SlotRec[], byName: Map<string, SlotRec>, loop?: LoopRec, weight: number, mask: string, additive: boolean }
-export type LoopRec = { layer: LayerRec, members: { name: string, slot: SlotRec }[], value: BlendPosition, view: Loop, dead: boolean }
-
-const handlers = new Map<number, (slot: number, type: number) => void>()
-let eventsInstalled = false
-const ensureEvents = (): void => {
-  if (eventsInstalled) return
-  eventsInstalled = true
-  _creator.setOnAnimatorEvent((animatorId, slot, type) => handlers.get(animatorId)?.(slot, type))
-}
-
-const settled = (slot: SlotRec): PlaybackRec => {
-  let resolve = (_n: boolean): void => {}
-  const done = new Promise<boolean>((r) => { resolve = r })
-  resolve(false)
-  return { slot, playing: false, done, resolve }
-}
-
-export class Core {
-  id = 0
-  /** Added clips by name (`addClip`) — the lookup index; an added name overrides an embedded one. */
-  readonly table = new Map<string, AnimationClip>()
-  readonly layers: LayerRec[] = []
-  speed = 1
-  private _embedded?: AnimationClip[]
-  private readonly _added: { name: string, clip: AnimationClip }[] = []
-  private _list?: AnimationClip[]
-  private readonly _listeners = new Map<string, Set<ClipEventHandler>>()
-
-  readonly node: Node
-  constructor(node: Node) { this.node = node; this.layers.push(this.newLayer()) }
-
-  // ---- clips ----
-  embedded(): AnimationClip[] {
-    if (!this._embedded) {
-      this._embedded = AnimationClip._ofSet(_creator.getGlbClipSet(this.node.id))
-      const seen = new Set<string>()
-      for (const c of this._embedded) {
-        if (seen.has(c.name)) console.warn(`Animator: ${this.node.name || "the node"} has several clips named '${c.name}' — by name you get the first; reach the others by index (anim.clip(n))`)
-        seen.add(c.name)
-      }
-    }
-    return this._embedded
-  }
-  /** The ordered clip list: the GLB's clips in file order (an added clip of the same name takes the
-   *  embedded one's place), then the remaining added clips in insertion order. Cached until addClip. */
-  clips(): AnimationClip[] {
-    if (this._list) return this._list
-    const out: AnimationClip[] = []
-    const placed = new Set<string>()
-    for (const c of this.embedded()) {
-      const override = this.table.get(c.name)
-      if (override && !placed.has(c.name)) { out.push(override); placed.add(c.name) }
-      else out.push(c)
-    }
-    for (const a of this._added) if (!placed.has(a.name)) { out.push(a.clip); placed.add(a.name) }
-    return this._list = out
-  }
-  addClip(name: string, clip: AnimationClip): void {
-    const i = this._added.findIndex((a) => a.name === name)
-    if (i >= 0) this._added[i] = { name, clip }
-    else this._added.push({ name, clip })
-    this.table.set(name, clip)
-    this._list = undefined
-  }
-  /** A clip by name (added first, then embedded), or by index into `clips()` (none = the first). */
-  resolveClip(ref: string | number | undefined): [string, AnimationClip] | undefined {
-    if (ref === undefined || typeof ref === "number") { const c = this.clips()[ref ?? 0]; return c ? [ c.name, c ] : undefined }
-    const c = this.table.get(ref) ?? this.embedded().find((e) => e.name === ref)
-    return c ? [ ref, c ] : undefined
-  }
-  private clipNames(): string { return this.clips().map((c) => c.name).join(", ") || "(empty)" }
-
-  // ---- lifecycle ----
-  /** Create the native animator on demand. False = nothing to animate (warned). */
-  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 }
-    ensureEvents()
-    this.id = _creator.animatorCreate(this.node.id)
-    if (!this.id) { console.warn("Animator: node has no transform hierarchy"); return false }
-    handlers.set(this.id, (slot, type) => this.onEvent(slot, type))
-    if (this.speed !== 1) _creator.animatorSetGlobal(this.id, this.speed, false)
-    for (const L of this.layers) if (L.index > 0) this.pushLayer(L)
-    return true
-  }
-  destroy(): void {
-    for (const L of this.layers) for (const s of L.slots) if (s.playback) this.settle(s.playback, false)
-    if (this.id) { _creator.animatorDestroy(this.id); handlers.delete(this.id); this.id = 0 }
-    for (const L of this.layers) { L.slots = []; L.byName.clear(); if (L.loop) { L.loop.dead = true; L.loop = undefined } }
-  }
-
-  // ---- layers ----
-  newLayer(options?: LayerOptions): LayerRec {
-    const rec: LayerRec = { index: this.layers.length, view: undefined as unknown as Layer, slots: [], byName: new Map(), weight: options?.weight ?? 1, mask: "", additive: options?.additive ?? false }
-    if (options?.mask !== undefined) rec.mask = Array.isArray(options.mask) ? options.mask.join("\n") : options.mask
-    rec.view = new Layer(rec, this)
-    return rec
-  }
-  addLayer(options: LayerOptions): Layer {
-    if (this.layers.length >= 255) { console.warn("Animator: too many layers"); return this.layers[this.layers.length - 1].view }
-    const rec = this.newLayer(options)
-    this.layers.push(rec)
-    if (this.id) this.pushLayer(rec)
-    return rec.view
-  }
-  pushLayer(L: LayerRec): void {
-    if (!this.id) return
-    for (const m of L.mask.split("\n")) if (m && !this.node.bone(m)) console.warn(`Animator: layer mask bone '${m}' not found under ${this.node.name || "the node"}`)
-    _creator.animatorSetLayer(this.id, L.index, L.weight, L.additive, L.mask)
-  }
-
-  // ---- slots ----
-  /** Bind a clip on a layer (once per name). */
-  slotFor(L: LayerRec, name: string, clip: AnimationClip): SlotRec | undefined {
-    const have = L.byName.get(name)
-    if (have && have.clip === clip) return have
-    const slot = _creator.animatorBind(this.id, clip._set, clip._index, L.index)
-    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 rec: SlotRec = { name, clip, slot, layer: L, inBlend: false }
-    L.slots.push(rec)
-    L.byName.set(name, rec)
-    return rec
-  }
-
-  // ---- play / stop ----
-  play(L: LayerRec, ref: string | number | undefined, o: PlayOptions): Playback {
-    const found = this.resolveClip(ref)
-    if (!found) {
-      console.warn(`Animator: no clip ${ref === undefined ? "to play" : JSON.stringify(ref)} on ${this.node.name || "the node"} — table: ${this.clipNames()}`)
-      return new Playback(settled({ name: "", clip: AnimationClip._none(), slot: -1, layer: L, inBlend: false }), this)
-    }
-    const [name, clip] = found
-    if (!this.ensure()) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
-    const s = this.slotFor(L, name, clip)
-    if (!s) return new Playback(settled({ name, clip, slot: -1, layer: L, inBlend: false }), this)
-    if (s.inBlend) { console.warn(`Animator: '${name}' is part of this layer's loop — use playLoop() to change what it rests on`); return new Playback(settled(s), this) }
-    const fadeIn = o.fadeIn ?? o.fade ?? 0
-    const fadeOut = o.fadeOut ?? o.fade ?? -1
-    // the other one-shots on this layer are cut short (their promises resolve false)
-    for (const other of L.slots) if (other.playback) this.settle(other.playback, false)
-    let resolve = (_n: boolean): void => {}
-    const done = new Promise<boolean>((r) => { resolve = r })
-    const rec: PlaybackRec = { slot: s, playing: true, done, resolve }
-    s.playback = rec
-    _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
-    return new Playback(rec, this)
-  }
-  /** A one-shot on the layer hasn't handed over yet. */
-  busy(L: LayerRec): boolean { return L.slots.some((s) => s.playback?.playing) }
-  settle(p: PlaybackRec, natural: boolean): void {
-    p.playing = false
-    if (p.slot.playback === p) p.slot.playback = undefined
-    p.resolve(natural)
-  }
-  stopSlot(s: SlotRec, fade: number): void {
-    if (s.playback) this.settle(s.playback, false)
-    if (this.id && s.slot >= 0) _creator.animatorStop(this.id, s.layer.index, s.slot, fade)
-  }
-  stopLayer(L: LayerRec, fade: number): void {
-    for (const s of L.slots) if (s.playback) this.settle(s.playback, false)
-    if (L.loop) { L.loop.dead = true; L.loop = undefined }
-    if (this.id) _creator.animatorStop(this.id, L.index, -1, fade)
-  }
-  stopAll(fade: number): void { for (const L of this.layers) this.stopLayer(L, fade) }
-
-  // ---- loop ----
-  loop(L: LayerRec, def: LoopDef, o: LoopOptions): Loop | undefined {
-    if (!this.ensure()) return undefined
-    const fade = o.fade ?? 0
-    if (L.loop) { L.loop.dead = true; for (const m of L.loop.members) m.slot.inBlend = false; L.loop = undefined }
-    for (const s of L.slots) if (s.playback) this.settle(s.playback, false)   // one-shots on the layer are cut short
-    const space: Record<string, BlendPosition> = typeof def === "object" ? def : {}
-    if (typeof def !== "object") {
-      const found = this.resolveClip(def)
-      if (!found) { console.warn(`Animator: no clip ${JSON.stringify(def)} to loop — table: ${this.clipNames()}`); return undefined }
-      space[found[0]] = 0
-    }
-    const rec: LoopRec = { layer: L, members: [], value: 0, view: undefined as unknown as Loop, dead: false }
-    rec.view = new Loop(rec, this)
-    const slots: number[] = [], positions: number[] = []
-    const is2D = Object.values(space).some((p) => typeof p !== "number")
-    for (const [name, at] of Object.entries(space)) {
-      const found = this.resolveClip(name)
-      if (!found) { console.warn(`Animator: loop clip '${name}' is not in the clip table`); continue }
-      const s = this.slotFor(L, name, found[1])
-      if (!s) continue
-      if (s.playback) this.settle(s.playback, false)
-      s.inBlend = true
-      rec.members.push({ name, slot: s })
-      slots.push(s.slot)
-      if (is2D) positions.push(typeof at === "number" ? at : at[0], typeof at === "number" ? 0 : at[1])
-      else positions.push(at as number)
-    }
-    L.loop = rec
-    _creator.animatorSetBlend(this.id, L.index, is2D ? 2 : 1, new Uint16Array(slots), new Float32Array(positions), fade, o.speed ?? 1)
-    return rec.view
-  }
-  setLoopValue(b: LoopRec, v: BlendPosition): void {
-    if (b.dead) { console.warn("Animator: this loop was replaced — use the object the latest playLoop() returned"); return }
-    b.value = v
-    if (!this.id) return
-    const [x, y] = typeof v === "number" ? [ v, 0 ] : [ v[0], v[1] ]
-    _creator.animatorSetBlendValue(this.id, b.layer.index, x, y)
-  }
-  slotWeight(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotWeight(this.id, s.slot) : 0 }
-  slotTime(s: SlotRec): number { return this.id && s.slot >= 0 ? _creator.animatorGetSlotTime(this.id, s.slot) : 0 }
-  seek(s: SlotRec, time: number): void { if (this.id && s.slot >= 0) _creator.animatorSeek(this.id, s.slot, time) }
-
-  // ---- props ----
-  setSpeed(v: number): void { this.speed = v; if (this.id) _creator.animatorSetGlobal(this.id, v, false) }
-  setRootMotion(on: boolean): void { if (this.ensure()) _creator.animatorSetRootMotion(this.id, on ? "*" : "", on ? 2 : 0) }
-
-  // ---- events ----
-  on(event: string, cb: ClipEventHandler): void { (this._listeners.get(event) ?? this._listeners.set(event, new Set()).get(event)!).add(cb) }
-  off(event: string, cb: ClipEventHandler): void { this._listeners.get(event)?.delete(cb) }
-  /** Native slot event: 0 completed / 1 loop / 2 settled (faded to 0) / 3 hand-over / 4+i clip event i. */
-  private onEvent(slotIndex: number, type: number): void {
-    let s: SlotRec | undefined
-    for (const L of this.layers) { s = L.slots.find((x) => x.slot === slotIndex); if (s) break }
-    if (!s) return
-    if (type >= 4) {
-      const name = s.clip._events[type - 4]?.name
-      const cbs = name ? this._listeners.get(name) : undefined
-      if (cbs) for (const cb of [ ...cbs ]) cb(s.name, s.layer.view)
-      return
-    }
-    const p = s.playback
-    if (!p) return
-    if (type === 3) this.settle(p, true)          // hand-over: the clip is over; the app's next call redirects the fade
-    else if (type === 2) this.settle(p, false)    // faded out after a stop / replacement before handing over
-  }
-}

package/runtime/sdk/gl/controls.ts

@@ -1,95 +0,0 @@
-// AR object-placement controls — the classic "drop a model in the room and manipulate it" gesture
-// recipe: ONE finger drags the target across the ground plane (camera-relative), TWO fingers pinch to
-// scale and twist to rotate (yaw). Lives on ARScene (see Scene.ts) because it orchestrates the scene's
-// camera + touch input against a target node; it's built entirely on the public API (no native calls
-// the user couldn't make), so it's a convenience, not a primitive.
-
-import { Vec2, Vec3 } from "../math/vec"
-import { Quat } from "../math/quat"
-import type { Node } from "./Node"
-import type { Scene } from "./Scene"
-import type { TouchStartEvent } from "../runtime/touch"
-
-export type ControlsOptions = {
-  /** Smallest uniform scale the pinch gesture allows (default 0.08). */
-  minScale?: number
-  /** Largest uniform scale the pinch gesture allows (default 2). */
-  maxScale?: number
-  /** One-finger drag moves the target across the ground plane (default true). */
-  pan?: boolean
-  /** Two-finger pinch scales the target (default true). */
-  pinch?: boolean
-  /** Two-finger twist rotates the target around its Y axis (default true). */
-  twist?: boolean
-}
-
-/** Returned by `addControls` — call `remove()` to detach the gesture listeners. */
-export type ControlsHandle = { remove(): void }
-
-type ActiveTouch = { pointerId: number, x: number, y: number }
-
-const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
-
-export const attachControls = (scene: Scene, target: Node, options: ControlsOptions = {}): ControlsHandle => {
-  const minScale = options.minScale ?? 0.08
-  const maxScale = options.maxScale ?? 2
-  const pan = options.pan ?? true
-  const pinch = options.pinch ?? true
-  const twist = options.twist ?? true
-
-  const active: ActiveTouch[] = []
-
-  const onTouchStart = (e: TouchStartEvent<Node | null>): void => {
-    const touch: ActiveTouch = { pointerId: e.pointerId, x: e.clientX, y: e.clientY }
-    active.push(touch)
-    e.track({
-      onMove(m) {
-        if (active.length === 2) {
-          // --- two-finger: pinch-scale + twist-rotate about the gesture axis ---
-          const other = active.find((t) => t !== touch)
-          if (other) {
-            const axis = new Vec2(other.x - touch.x, other.y - touch.y)
-            const span = axis.length()
-            if (span > 1e-3) {
-              const dir = axis.scale(1 / span)
-              const delta = new Vec2(m.deltaX, m.deltaY)
-              if (pinch) {
-                const along = -dir.dot(delta) // movement along the pinch axis
-                target.scale = clamp(target.scale.x * (span + along) / span, minScale * 0.4, maxScale * 1.5)
-              }
-              if (twist) {
-                const tangent = dir.perp().dot(delta) // movement across the axis
-                target.quaternion = target.quaternion.mul(Quat.fromAxisAngle(Vec3.up, Math.atan2(tangent, span)))
-              }
-            }
-          }
-        } else if (active.length === 1 && pan) {
-          // --- one-finger: drag across the ground plane, relative to where the camera looks ---
-          let dir = scene.camera.forward
-          const parent = target.parent
-          if (parent) dir = dir.rotate(parent.quaternion.invert()) // into the parent's local frame
-          dir = dir.withY(0)
-          const k = Math.hypot(dir.x, dir.z)
-          const screen = Math.max(...scene.camera.displaySize)
-          if (k > 1e-4 && screen > 0) {
-            const dist = target.worldPosition.distanceTo(scene.camera.worldPosition)
-            const right = new Vec3(-dir.z, 0, dir.x).scale(m.deltaX / k / screen * dist)
-            const fwd = dir.scale(-m.deltaY / k / screen * dist)
-            const move = right.add(fwd)
-            const p = target.position
-            target.position = new Vec3(p.x + move.x, p.y, p.z + move.z) // keep height fixed
-          }
-        }
-        touch.x = m.clientX
-        touch.y = m.clientY
-      },
-      onEnd() {
-        const i = active.indexOf(touch)
-        if (i >= 0) active.splice(i, 1)
-      },
-    })
-  }
-
-  scene.addEventListener("touchstart", onTouchStart)
-  return { remove() { scene.removeEventListener("touchstart", onTouchStart); active.length = 0 } }
-}

package/runtime/sdk/gl/physicsEvents.ts

@@ -1,20 +0,0 @@
-// Routes native physics contact/sensor events to the owning nodes' 'enter'/'exit' events. Each event
-// is delivered to BOTH nodes with the other as the argument. type: 0 = enter (contact/overlap began),
-// 1 = exit (ended). Registered lazily on the first trigger/physics body or 'enter'/'exit' listener.
-
-import { nodeRegistry } from "./Node"
-
-let registered = false
-export const ensurePhysicsEvents = (): void => {
-  if (registered) return
-  if (!_creator.setOnPhysicsEvent) return // physics-less build / bridge without the hook
-  registered = true
-  _creator.setOnPhysicsEvent((a, b, type) => {
-    const na = nodeRegistry.get(a)
-    const nb = nodeRegistry.get(b)
-    if (!na || !nb) return
-    const channel = type === 1 ? "exit" : "enter"
-    na._emitCollision(channel, nb)
-    nb._emitCollision(channel, na)
-  })
-}