lecodes-cli 0.17.2 → 0.18.0

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

@@ -0,0 +1,87 @@
+// Animator — THE animation system, reached as `node.anim`. Every Model carries one pre-attached (its
+// clip list = the GLB's embedded clips; nothing native exists until the first play()). The whole
+// per-frame loop — fades, blend spaces, one-shot fade-back, root motion — runs in the engine; the
+// SDK only issues calls. See docs/animator-plan.md.
+//
+//   const hero = await Model.load(asset('./hero.glb'))
+//   hero.anim.playLoop('Idle')                             // the layer's LOOP: what it rests on
+//   await hero.anim.play('Jump', { fadeIn: 0.1, fadeOut: 0.2 })   // a one-shot over it, back to the loop after
+//
+//   hero.anim.addClip('slash', slash)                      // clips from other files / procedural / sliced
+//   const loco = hero.anim.playLoop({ Idle: 0, Walking: 2, 'Fast Run': 6 })   // a blend as the loop
+//   loco.value = hero.controller.velocity.length           // where we are on the blend axis
+//   const kick = hero.anim.play('slash', { fadeIn: 0.1, fadeOut: 0.3 })   // resolves at its hand-over
+//   kick.clip.addEvent(0.4, 'hit'); hero.anim.on('hit', () => …)
+//   if (await kick) hero.anim.playLoop('Crouch', { fade: 0.3 })   // resolved at the hand-over: what you start now is what it fades into
+//   const upper = hero.anim.addLayer({ mask: 'Spine1' })
+//   upper.playLoop('Aim', { fade: 0.3 })                   // arms aim, legs keep walking
+//
+// Any Node hierarchy works, not just Models: tracks bind to child names (a robot arm of meshes).
+
+import { Aspect } from "../../core/Aspect"
+import type { Node } from "../Node"
+import type { AnimationClip } from "./AnimationClip"
+import { Core, type ClipEventHandler, type LayerOptions, type LoopDef, type LoopOptions, type PlayOptions, type StopOptions } from "./core"
+import type { Loop } from "./Loop"
+import type { Layer } from "./Layer"
+import type { Playback } from "./Playback"
+
+export class Animator extends Aspect<"anim", Node> {
+  static readonly aspect = "anim"
+  private _c!: Core
+  private _rootMotion = false
+
+  onAttach(): void { this._c = new Core(this.node) }
+  onDetach(): void { this._c.destroy() }
+
+  // ---- clips ----
+  /** The clip list, in order: the GLB's embedded clips (file order), then the clips you added. An
+   *  added clip with an embedded clip's name takes its place. */
+  get clips(): readonly AnimationClip[] { return this._c.clips() }
+  /** One clip by name, or by index into `clips` — e.g. to `slice()` it. `undefined` if there is none. */
+  clip(ref: string | number): AnimationClip | undefined { return this._c.resolveClip(ref)?.[1] }
+  /** Add a clip under a name (default: its own `name`) — from another file, procedural, or sliced.
+   *  Overrides an embedded clip of the same name. Chainable. */
+  addClip(name: string | AnimationClip, clip?: AnimationClip): this {
+    const c = typeof name === "string" ? clip : name
+    const n = typeof name === "string" ? name : name.name
+    if (!c) { console.warn(`Animator.addClip('${n}'): no clip`); return this }
+    this._c.addClip(n, c)
+    return this
+  }
+
+  // ---- playing (the base layer) ----
+  /** Play a one-shot on the base layer — by name, index, or the first clip with no argument.
+   *  Crossfades per the options (default: cut). Returns a Playback: `await` it — it resolves at the
+   *  clip's hand-over (`true`; `false` if cut short), and what you start right after is what the clip
+   *  fades into (another one-shot, `playLoop(next)`; nothing = back to the loop). */
+  play(clip?: string | number, options: PlayOptions = {}): Playback { return this._c.play(this._c.layers[0], clip, options) }
+  /** Set the base layer's LOOP — what it shows when no one-shot plays: a clip (`playLoop('Idle')`) or
+   *  a blend space (`playLoop({ Idle: 0, Run: 6 })`, drive the returned object's `value`). Crossfades
+   *  over `fade` from whatever plays — a one-shot included (it is cut short). `stop()` removes it. */
+  playLoop(def: LoopDef, options: LoopOptions = {}): Loop | undefined { return this._c.loop(this._c.layers[0], def, options) }
+  /** Fade everything out, on every layer (loops included) → rest pose. */
+  stop(options: StopOptions = {}): this { this._c.stopAll(options.fade ?? 0); return this }
+  /** The base layer's current loop (the object the last `playLoop()` returned), if any. */
+  get loop(): Loop | undefined { return this._c.layers[0].loop?.view }
+  /** A one-shot on the base layer hasn't handed over yet. */
+  get busy(): boolean { return this._c.busy(this._c.layers[0]) }
+
+  // ---- layers ----
+  /** A new layer on top (masked override / additive). The returned object is its handle. */
+  addLayer(options: LayerOptions = {}): Layer { return this._c.addLayer(options) }
+
+  // ---- clip events (`clip.addEvent(0.4, 'hit')`) ----
+  on(event: string, cb: ClipEventHandler): this { this._c.on(event, cb); return this }
+  off(event: string, cb: ClipEventHandler): this { this._c.off(event, cb); return this }
+
+  // ---- props ----
+  /** Global playback rate: 0.3 = slow-mo, 0 = pause. */
+  get speed(): number { return this._c.speed }
+  set speed(v: number) { this._c.setSpeed(v) }
+  /** Root motion: the root bone's horizontal travel comes OFF the pose and moves the node instead —
+   *  or its CharacterController (on this node or an ancestor) as a velocity, so it collides. For
+   *  clips whose hips actually travel (Mixamo without "In Place", lunges, rolls). */
+  get rootMotion(): boolean { return this._rootMotion }
+  set rootMotion(on: boolean) { this._rootMotion = on; this._c.setRootMotion(on) }
+}

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

@@ -0,0 +1,29 @@
+// Layer — one layer of an Animator (`anim.addLayer({ mask: 'Spine1' })` for the upper body,
+// `{ additive: true }` for deltas stacked on top). The Animator's own play/stop/playLoop ARE its base
+// layer; extra layers composite over it in creation order. The object is the layer's only handle.
+
+import type { Core, LayerRec, LoopDef, LoopOptions, PlayOptions, StopOptions } from "./core"
+import type { Loop } from "./Loop"
+import type { Playback } from "./Playback"
+
+export class Layer {
+  private readonly _r: LayerRec
+  private readonly _c: Core
+  /** @internal — created by the Animator. */
+  constructor(rec: LayerRec, core: Core) { this._r = rec; this._c = core }
+
+  /** Play a one-shot on this layer (crossfading per the options); resolves at its hand-over. */
+  play(clip?: string | number, options: PlayOptions = {}): Playback { return this._c.play(this._r, clip, options) }
+  /** Set / transition this layer's loop (a clip, or a blend space) — crossfades over `fade` from whatever
+   *  the layer shows, a one-shot included (it is cut short). */
+  playLoop(def: LoopDef, options: LoopOptions = {}): Loop | undefined { return this._c.loop(this._r, def, options) }
+  /** Fade everything on this layer out — one-shots and its loop. */
+  stop(options: StopOptions = {}): this { this._c.stopLayer(this._r, options.fade ?? 0); return this }
+  /** This layer's current loop (the object the last `playLoop()` returned), if any. */
+  get loop(): Loop | undefined { return this._r.loop?.view }
+  /** Layer contribution 0–1. */
+  get weight(): number { return this._r.weight }
+  set weight(v: number) { this._r.weight = v; this._c.pushLayer(this._r) }
+  /** A one-shot on this layer hasn't handed over yet. */
+  get busy(): boolean { return this._c.busy(this._r) }
+}

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

@@ -0,0 +1,25 @@
+// 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 loop in phase and `value`
+// picks the mix: 1D linear between neighbours, `[x, y]` positions = a 2D gradient band). One-shots fade
+// it out and return to it; `playLoop(next)` crossfades to another; `stop()` removes it. The object
+// returned by `playLoop()` (also `anim.loop`) is the handle; a replaced loop's object goes dead.
+
+import type { BlendPosition, Core, LoopRec } from "./core"
+
+export class Loop {
+  private readonly _r: LoopRec
+  private readonly _c: Core
+  /** @internal — created by playLoop(). */
+  constructor(rec: LoopRec, core: Core) { this._r = rec; this._c = core }
+
+  /** Position on the axis (number) or plane (`[x, y]`) — units are whatever the positions use. Live
+   *  even while a one-shot plays (the loop returns at the new mix). */
+  get value(): BlendPosition { return this._r.value }
+  set value(v: BlendPosition) { this._c.setLoopValue(this._r, v) }
+  /** Each member's current contribution, 0–1 (fades included). */
+  get weights(): Record<string, number> {
+    const out: Record<string, number> = {}
+    for (const m of this._r.members) out[m.name] = this._c.slotWeight(m.slot)
+    return out
+  }
+}

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

@@ -0,0 +1,43 @@
+// Playback — the handle `play()` returns (docs/animator-plan.md). Thenable: `await anim.play('slash')`
+// resolves at the clip's HAND-OVER — where its fade-back starts (`end − fadeOut`; the end when there
+// is no fadeOut) — with `true`; `false` when it was cut short (replaced / stopped). What
+// you call right after the await is what the clip fades into: `anim.play(next)` (a chained one-shot,
+// crossfaded), `anim.playLoop(next)` — nothing = back to the loop (or hold, on a layer without one).
+// Returning one from an `async` function flattens it into `Promise<boolean>` — return `p.done` (or
+// make the function sync) when the caller needs the handle.
+
+import type { AnimationClip } from "./AnimationClip"
+import type { Core, PlaybackRec, StopOptions } from "./core"
+import type { Layer } from "./Layer"
+
+export class Playback implements PromiseLike<boolean> {
+  private readonly _r: PlaybackRec
+  private readonly _c: Core
+  /** @internal — created by play(). */
+  constructor(rec: PlaybackRec, core: Core) { this._r = rec; this._c = core }
+
+  /** The clip that plays. */
+  get clip(): AnimationClip { return this._r.slot.clip }
+  /** The layer it plays on. */
+  get layer(): Layer { return this._r.slot.layer.view }
+  /** Clock (s). */
+  get time(): number { return this._c.slotTime(this._r.slot) }
+  /** 0–1 through the clip (the current cycle, when looping). */
+  get progress(): number { const d = this.clip.duration; return d > 0 ? this.time / d : 0 }
+  /** Not handed over yet (the clip still owns the layer). */
+  get playing(): boolean { return this._r.playing }
+  /** Current contribution to the pose, 0–1 — moves during crossfades. */
+  get weight(): number { return this._r.slot.playback === this._r ? this._c.slotWeight(this._r.slot) : 0 }
+  /** Resolves at the hand-over (`true`) or when cut short (`false`) — the promise `await playback`
+   *  uses; the one to return from async functions or put in `Promise.all`. */
+  get done(): Promise<boolean> { return this._r.done }
+
+  then<A = boolean, B = never>(onFulfilled?: ((v: boolean) => A | PromiseLike<A>) | null, onRejected?: ((e: unknown) => B | PromiseLike<B>) | null): Promise<A | B> {
+    return this._r.done.then(onFulfilled, onRejected)
+  }
+
+  /** Move the clock (s). */
+  seek(time: number): this { this._c.seek(this._r.slot, time); return this }
+  /** Cut this clip short: fade it out (the layer's loop returns if nothing else is coming in). */
+  stop(options: StopOptions = {}): this { this._c.stopSlot(this._r.slot, options.fade ?? 0); return this }
+}

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

@@ -0,0 +1,294 @@
+// 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/scenarios.ts

@@ -1,9 +1,9 @@
 // No-code scenario aspects: ready-made behaviors a scene builder attaches in the editor without
 // writing any code — move to a target, travel a waypoint path, spin, face something, start a GLB
 // animation. They are ordinary aspects (work from hand-written code too); in the scene editor the
-// movement ones double as `static editor` generators that draw their paths as editor-only lines
-// (edges meshes under `this.generated` — play mode never calls rebuild(), so the lines cost
-// nothing at runtime).
+// movement ones double as `static editor` generators that draw their paths as editor gizmos
+// (`Gizmos.*` in rebuild() — overlay lines, never scene content; play mode never calls rebuild(),
+// so they cost nothing at runtime).
 //
 // Conventions shared by the family:
 //   • targets/waypoints are scene nodes — place an Empty, then pick it in the inspector (`ref()`);
@@ -18,8 +18,10 @@ import { Quat } from "../math/quat"
 import { Node } from "./Node"
 import { Mesh } from "./Mesh"
 import { Model } from "./Model"
+import type { Playback } from "./animation/Playback"
 import { Geometry } from "./Geometry"
 import { Material } from "./Material"
+import { Gizmos } from "../scene/gizmos"
 
 const MOVE_LINE = "#5b8ef0"
 const LOOK_LINE = "#d9a13f"
@@ -47,10 +49,10 @@ const toParentLocal = (node: Node, world: Vec3): Vec3 => {
   return parent ? parent.worldMatrix.invert().transformPoint(world) : world
 }
 
-// ---- editor line drawing (edit mode only — see rebuild() on the aspects below) -------------------
+// ---- editor marker meshes (defineScene's empty/camera markers — real meshes, so they pick) -------
 
 /** @internal An "edges" line mesh from flat segment endpoints ([x,y,z, x,y,z] per segment) —
- *  editor-only visuals (path lines here, node markers in defineScene). */
+ *  the scene editor's node markers (defineScene). Path lines are `Gizmos` calls instead. */
 export const edgesMesh = (segments: number[], color: string): Mesh => {
   const vertices = new Float32Array(segments)
   const count = vertices.length / 3
@@ -66,25 +68,6 @@ export const edgesMesh = (segments: number[], color: string): Mesh => {
   return mesh
 }
 
-const pushCross = (segments: number[], p: Vec3, s: number): void => {
-  segments.push(p.x - s, p.y, p.z, p.x + s, p.y, p.z)
-  segments.push(p.x, p.y - s, p.z, p.x, p.y + s, p.z)
-  segments.push(p.x, p.y, p.z - s, p.x, p.y, p.z + s)
-}
-
-/** `this.generated` hangs UNDER the host node, so line points (world space) must be expressed in
- *  the host's local frame; the host is an editor-run dep of its own aspects, so dragging it
- *  re-runs rebuild() and the conversion stays fresh. */
-const worldSegmentsToLocal = (node: Node, segments: number[]): number[] => {
-  const inv = node.worldMatrix.invert()
-  const out: number[] = []
-  for (let i = 0; i < segments.length; i += 3) {
-    const p = inv.transformPoint([ segments[i]!, segments[i + 1]!, segments[i + 2]! ])
-    out.push(p.x, p.y, p.z)
-  }
-  return out
-}
-
 /** A path node's waypoints: its children in scene-FILE order (`_sceneChildOrder`, stamped by
  *  defineScene — the engine's live child order is insertion-based and may differ), editor helper
  *  nodes (`__`-prefixed) excluded. Runtime-added children append in engine order. */
@@ -143,14 +126,10 @@ export class MoveTo extends Aspect<"moveTo"> {
 
   /** Editor-only path line (edit mode; play mode never calls this). */
   rebuild(): void {
-    this.generated.clear()
     if (!this.target) return
-    const segments: number[] = []
-    const a = this.node.worldPosition
     const b = this.target.worldPosition
-    segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
-    pushCross(segments, b, 0.09)
-    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), MOVE_LINE))
+    Gizmos.line(this.node.worldPosition, b, { color: MOVE_LINE })
+    Gizmos.cross(b, 0.09, { color: MOVE_LINE })
   }
 }
 
@@ -223,16 +202,9 @@ export class FollowPath extends Aspect<"followPath"> {
 
   /** Editor-only waypoint polyline (edit mode; play mode never calls this). */
   rebuild(): void {
-    this.generated.clear()
-    const points = this._points()
-    if (points.length < 2) return
-    const segments: number[] = []
-    for (let i = 0; i < points.length - 1; i++) {
-      const a = points[i]!, b = points[i + 1]!
-      segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
-    }
-    for (const p of points) pushCross(segments, p, 0.07)
-    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), MOVE_LINE))
+    const points = this._points()   // loop mode already appends the first point again
+    Gizmos.polyline(points, { color: MOVE_LINE })
+    for (const p of points) Gizmos.cross(p, 0.07, { color: MOVE_LINE })
   }
 }
 
@@ -289,14 +261,10 @@ export class LookAt extends Aspect<"facing"> {
 
   /** Editor-only sight line (edit mode; play mode never calls this). */
   rebuild(): void {
-    this.generated.clear()
     if (!this.target) return
-    const segments: number[] = []
-    const a = this.node.worldPosition
     const b = this.target.worldPosition
-    segments.push(a.x, a.y, a.z, b.x, b.y, b.z)
-    pushCross(segments, b, 0.07)
-    this.generated.add(edgesMesh(worldSegmentsToLocal(this.node, segments), LOOK_LINE))
+    Gizmos.line(this.node.worldPosition, b, { color: LOOK_LINE })
+    Gizmos.cross(b, 0.07, { color: LOOK_LINE })
   }
 }
 
@@ -316,16 +284,18 @@ export class PlayAnimation extends Aspect<"playAnimation", Model> {
     speed: { min: 0.05, max: 5, step: 0.05 },
   }
 
+  private _preview?: Playback
+
   onAttach(): void {
     const anim = (this.node as Model | undefined)?.anim
     if (!anim) return
-    anim.speed = this.speed
-    anim.play(this.clip === "" ? 0 : this.clip, { loop: this.loop })
+    if (this.loop) anim.playLoop(this.clip === "" ? 0 : this.clip, { speed: this.speed })
+    else anim.play(this.clip === "" ? 0 : this.clip, { speed: this.speed })
   }
 
   static inspector(ui: InspectorUI, a: PlayAnimation): void {
     const anim = (a.node as Model | undefined)?.anim
-    const clips = anim?.clips ?? []
+    const clips = anim ? anim.clips : []
     if (clips.length === 0) {
       ui.warn("No animation clips — attach this to a GLB model node")
       return
@@ -333,17 +303,15 @@ export class PlayAnimation extends Aspect<"playAnimation", Model> {
     ui.select("clip", clips.map((c) => c.name))
     ui.auto("loop", "speed")
     if (anim) {
-      if (ui.button(anim.playing ? "Restart preview" : "Preview")) {
-        anim.speed = a.speed
-        anim.play(a.clip === "" ? 0 : a.clip, { loop: a.loop })
-      }
-      if (anim.playing && ui.button("Stop")) {
-        anim.stop()
-        anim.time = 0
-      }
       const clip = a.clip === "" ? clips[0]?.name : a.clip
+      const playing = a._preview?.playing === true
+      if (ui.button(playing ? "Restart preview" : "Preview")) {
+        if (a.loop) { anim.playLoop(clip, { speed: a.speed }); a._preview = undefined }
+        else a._preview = anim.play(clip, { speed: a.speed, restart: true })
+      }
+      if (playing && ui.button("Stop")) { anim.stop(); a._preview = undefined }
       const duration = clips.find((c) => c.name === clip)?.duration
-      ui.info(anim.playing ? "previewing…" : duration !== undefined ? `${duration.toFixed(2)}s` : "")
+      ui.info(playing ? "previewing…" : duration !== undefined ? `${duration.toFixed(2)}s` : "")
     }
   }
 }