lecodes-cli 0.19.0 → 0.20.0

package/runtime/sdk/gl/Wheel.ts

@@ -1,240 +0,0 @@
-// One wheel of a `Vehicle`, as an aspect on the wheel's own node. The node's position IS the wheel's
-// position (where its centre rests on flat ground), and everything else about it lives here too:
-//
-//   const car = new Node('car')
-//     .add(body, wheelFL.aspect(Wheel), wheelFR.aspect(Wheel),
-//                wheelRL.aspect(Wheel), wheelRR.aspect(Wheel))
-//     .aspect(Shape, { box: [0.9, 0.4, 2.1] })
-//     .aspect(Vehicle, { mass: 1200 })
-//
-// That is the whole minimum: `Vehicle` collects every `Wheel` under itself, groups them into axles by
-// Z (front first), and the defaults fall out — the front axle steers, the rear one drives and carries
-// the handbrake. Override any of it per wheel.
-//
-// This aspect is also what POSES the wheel: it runs in the LATE phase (after the physics step, before
-// the frame draws) and writes the node's transform from the suspension length, steer angle and spin
-// the engine reports. Nothing else writes that transform — the engine deliberately does not, so a
-// wheel model's own conventions (which way its axle points, how big it looks) are settings here
-// rather than constants in C++, and a part that should steer but NOT spin is simply a sibling node.
-//
-// Chassis space is forward −Z / up +Y, the SDK's own convention (`node.forward`).
-
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Mat4 } from "../math/mat4"
-import { Quat } from "../math/quat"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { Gizmos } from "../scene/gizmos"
-import { Node } from "./Node"
-import { Shape } from "./Shape"
-import type { Vehicle } from "./Vehicle"
-
-/** Floats `vehicleGetState` writes before the per-wheel block: speed, rpm, contacts, vx, vy, vz. */
-export const STATE_HEADER = 6
-/** Floats per wheel: contact, slip, slipAngle, suspensionLength, steerDeg, spin. */
-export const WHEEL_STATE = 6
-
-/** How a tire behaves past its grip peak. `road` is Jolt's own curve — grip falls off after the peak,
- *  so the car can be made to let go. `arcade` holds the peak all the way out: much harder to spin. */
-export type TireCurve = "road" | "arcade"
-
-export interface WheelSuspension {
-  /** Total travel in metres, full droop to fully compressed (default 0.4). */
-  travel?: number
-  /** Spring frequency in Hz — bigger is stiffer (default 1.4; a race car ~2.5, a truck ~1). It also
-   *  sets the ride-height sag, and the sag is how far the wheel can still extend DOWN. */
-  stiffness?: number
-  /** Damping ratio 0..1 (default 0.5). Low values pogo. */
-  damping?: number
-}
-
-export interface WheelTire {
-  /** Grip multiplier on the friction curves (default 1). The grip a wheel actually gets is combined
-   *  with the ground it stands on as `sqrt(tire × groundFriction)`, and a body's friction defaults to
-   *  0.6 — so a road a car should really corner on wants `Physics { friction: 1 }`. */
-  grip?: number
-  /** Which friction curve (default `road`). */
-  curve?: TireCurve
-}
-
-export interface WheelVisual {
-  /** The MODEL's axle direction in its own space (default `[1, 0, 0]`). Set it instead of parenting
-   *  the mesh under a corrective node when the art points another way. */
-  axis?: Vec3Like
-  /** Drawn radius, if the art is not exactly the physical `radius` — sinks a wheel into its arch or
-   *  lets a fat tire overhang, with no effect on the simulation. Default: the physical radius. */
-  radius?: number
-  /** Let the model spin (default true). `false` keeps the steer angle and suspension travel but not
-   *  the rotation — a brake caliper. */
-  spin?: boolean
-}
-
-const DEG2RAD = Math.PI / 180
-const UP = new Vec3(0, 1, 0)
-
-export class Wheel extends Aspect<"wheel", Node> {
-  static readonly aspect = "wheel"
-
-  /** Wheel radius in metres. Default: measured from the node's rendered bounds, else 0.35. Too small
-   *  and the car scrapes, too large and it floats. */
-  radius?: number
-  /** Wheel width in metres. Default: measured, else 0.25. */
-  width?: number
-  /** Does this wheel steer? Default: the wheels on the front axle. */
-  steer?: boolean
-  /** Does the engine drive it? Default: from the vehicle's `drive` layout. */
-  drive?: boolean
-  /** Foot brake on this wheel. */
-  brake = true
-  /** Handbrake on this wheel. Default: every non-steering wheel (locking the front wheels of a moving
-   *  car is not a handbrake turn, it is a crash). */
-  handbrake?: boolean
-  /** Axle group, front to back. Default: derived from Z. Set it for a car whose wheels are not in neat
-   *  left/right pairs — an axle's wheels are paired for the differential and the anti-roll bar. */
-  axle?: number
-  /** Foot-brake torque in N·m (default 1500); the handbrake pulls 3× on the wheels that have it. */
-  brakeTorque = 1500
-
-  suspension: WheelSuspension = { travel: 0.4, stiffness: 1.4, damping: 0.5 }
-  tire: WheelTire = { grip: 1, curve: "road" }
-  visual: WheelVisual = {}
-
-  /** Scene-editor inspector. `steer` / `drive` / `handbrake` are deliberately absent: they are
-   *  tri-state (undefined = derive it from the axle), which a switch cannot express. */
-  static fields: FieldMeta<Wheel> = {
-    radius: { min: 0.05, step: 0.01 },
-    width: { min: 0.02, step: 0.01 },
-    axle: { min: 0, step: 1 },
-    brake: { label: "Foot brake" },
-    brakeTorque: { label: "Brake torque", min: 0, step: 50 },
-    suspension: { hidden: true },
-    tire: { hidden: true },
-    visual: { hidden: true },
-  }
-  static editor = { rebuild: true }
-
-  /** @internal Set by `Vehicle` at attach — the car this wheel belongs to, and its index in the blob. */
-  _vehicle: Vehicle | null = null
-  /** @internal */
-  _index = -1
-  /** @internal Suspension attachment point in chassis space; the wheel hangs below it. */
-  _attach = new Vec3()
-  /** @internal Resting centre in chassis space (what the author placed). */
-  _rest = new Vec3()
-
-  private _angle = 0                       // integrated spin, radians — the engine reports rate, not angle
-  private _scale = new Vec3(1, 1, 1)       // the node's own scale, preserved through the pose write
-  private _local = true                    // is the node a direct child of the chassis?
-
-  onAttach(): void {
-    this._scale = this.node.scale
-  }
-
-  onDetach(): void {
-    this._vehicle = null
-    this._index = -1
-  }
-
-  /** @internal Called by Vehicle once the car exists, with the geometry it resolved. */
-  _bind(vehicle: Vehicle, index: number, rest: Vec3, attach: Vec3): void {
-    this._vehicle = vehicle
-    this._index = index
-    this._rest = rest
-    this._attach = attach
-    this._scale = this.node.scale
-    this._local = this.node.parent === vehicle.node
-  }
-
-  // ---- live state ------------------------------------------------------------------------------
-  // Every getter reads the car's ONE shared state buffer, which is refreshed once per frame.
-
-  private _state(k: number): number {
-    const v = this._vehicle
-    if (!v || this._index < 0) return 0
-    return v._wheelState(this._index, k)
-  }
-
-  /** Touching the ground this step. */
-  get contact(): boolean { return this._state(0) !== 0 }
-  /** Longitudinal slip RATIO: 0 = rolling in sync with the ground, ~1 = spinning up or locked.
-   *  Unsigned — smoke, tire marks and wheelspin sound key off this. */
-  get slip(): number { return this._state(1) }
-  /** Slip ANGLE in degrees: how far the tire's travel direction is off from where it points.
-   *  Unsigned, 0..90 — past the curve's peak (~3°) the tire is sliding sideways. Drift particles. */
-  get slipAngle(): number { return this._state(2) }
-  /** Steer angle in degrees, positive to the right. */
-  get steerAngle(): number { return this._state(4) }
-  /** Wheel spin in rad/s (× radius ≈ the speed the tire is laying down). */
-  get spin(): number { return this._state(5) }
-  /** Suspension compression, 0 = fully extended (drooping) … 1 = fully compressed. */
-  get compression(): number {
-    const travel = this.suspension.travel ?? 0.4
-    if (travel <= 0) return 0
-    const len = this._state(3)
-    const min = travel * 0.4
-    return Math.max(0, Math.min(1, (travel - len) / (travel - min)))
-  }
-
-  // ---- the visual ------------------------------------------------------------------------------
-
-  /** LATE phase: after the step and the transform sync, right before the frame draws. */
-  update(dt: number): void {
-    const v = this._vehicle
-    if (!v || this._index < 0 || !v.id) return
-
-    if (this.visual.spin !== false) this._angle += this._state(5) * dt
-
-    // Down the suspension from the attachment point by however far it currently hangs.
-    const length = this._state(3)
-    const centre = new Vec3(this._attach.x, this._attach.y - length, this._attach.z)
-
-    // Steer about the chassis' up axis, then spin about the MODEL's own axle in the steered frame.
-    // Both reports are negated, for the same reason: the engine describes them in the DRIVER's terms
-    // and the scene is right-handed with forward on −Z. Steer is reported right-positive while a yaw
-    // about +Y turns left. Spin is reported positive-means-forward, but a positive turn about the
-    // right-hand axle carries the top of the wheel to +Z — which rolls the car backwards.
-    const steer = Quat.fromAxisAngle(UP, -this._state(4) * DEG2RAD)
-    const axis = this.visual.axis ?? [1, 0, 0]
-    const rotation = this.visual.spin === false ? steer : steer.mul(Quat.fromAxisAngle(axis, -this._angle))
-
-    // A model that draws bigger or smaller than it collides scales on top of the node's own scale.
-    const vr = this.visual.radius
-    const k = vr !== undefined && this.radius ? vr / this.radius : 1
-    const scale = k === 1 ? this._scale : new Vec3(this._scale.x * k, this._scale.y * k, this._scale.z * k)
-
-    const m = Mat4.compose(centre, rotation, scale)
-    // The common case is a direct child of the chassis, where chassis space IS the local space.
-    if (this._local) this.node.matrix = m
-    else this.node.worldMatrix = new Mat4(v.node.worldMatrix).mul(m)
-  }
-
-  /** Edit mode: this wheel's own circle at its resting height, its travel range, and a mark when the
-   *  engine drives it — enough to place a wheel without running the game. */
-  rebuild(): void {
-    const travel = this.suspension.travel ?? 0.4
-    const r = this.radius ?? this._measure().radius
-    const world = new Mat4(this.node.worldMatrix)
-    const P = (x: number, y: number, z: number): Vec3 => world.transformPoint([ x, y, z ])
-    const ring: Vec3[] = []
-    for (let i = 0; i < 24; i++) {
-      const t = (i / 24) * Math.PI * 2
-      ring.push(P(0, Math.sin(t) * r, Math.cos(t) * r))
-    }
-    Gizmos.polyline(ring, { color: this.steer === false ? "#9aa3b2" : "#5b8ef0", closed: true })
-    Gizmos.line(P(0, travel * 0.6, 0), P(0, -travel * 0.4, 0), { color: "#59606d" })
-    if (this.drive) Gizmos.cross(P(0, 0, 0), r * 0.35, { color: "#e0b25a" })
-  }
-
-  /** @internal Radius/width from the node's rendered bounds, so a placed model needs no numbers. */
-  _measure(): { radius: number, width: number } {
-    const b = Shape.boundsOf(this.node)
-    if (!b) return { radius: 0.35, width: 0.25 }
-    const size = new Vec3(cx(b.max) - cx(b.min), cy(b.max) - cy(b.min), cz(b.max) - cz(b.min))
-    // A wheel is a disc: its diameter is the larger of the two axes across the axle, and the width is
-    // the axle direction itself.
-    const axis = this.visual.axis ?? [1, 0, 0]
-    const along = Math.abs(cx(axis)) >= Math.abs(cz(axis)) ? size.x : size.z
-    const across = Math.max(Math.abs(cx(axis)) >= Math.abs(cz(axis)) ? size.z : size.x, size.y)
-    return { radius: across > 0 ? across * 0.5 : 0.35, width: along > 0 ? along : 0.25 }
-  }
-}

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

@@ -1,204 +0,0 @@
-// AnimationClip — the unit of the animation system: immutable data (name, duration, tracks that
-// target bone NAMES, not entities). One representation for a GLB's embedded clips (model.anim.clips),
-// clips loaded from other files (Mixamo: one GLB per animation) and procedural clips built from
-// curves. An Animator binds clips to a skeleton by name. Clip EVENTS (`addEvent`) live here too —
-// a fact about the clip's timeline, shared wherever it plays. See docs/animator-plan.md.
-//
-//   const [hero, idle, run] = await Promise.all([
-//     Model.load(asset('./hero.glb')),
-//     AnimationClip.load(asset('./idle.glb')),            // the file's only/first clip
-//     AnimationClip.load(asset('./run.glb')),
-//   ])
-//   const slash = await AnimationClip.load(asset('./attacks.glb'), 'Slash')   // one out of many
-//   const bob = AnimationClip.from({ tracks: { Hips: { position: [[0, [0,0,0]], [1, [0,0.05,0]]] } } })
-
-import { fetch, type FetchResponse } from "../../runtime/fetch"
-import type { Vec3Like } from "../../math/vec"
-import type { QuatLike } from "../../math/quat"
-
-/** A keyframe: `[time (s), value]`. */
-export type ClipKey<V> = [number, V]
-export type ClipInterpolation = "linear" | "step"
-
-/** Curves for one target node (bone name), any subset of the three channels. */
-export type ClipTrackDef = {
-  position?: ClipKey<Vec3Like | [number, number, number]>[]
-  rotation?: ClipKey<QuatLike | [number, number, number, number]>[]
-  scale?: ClipKey<Vec3Like | [number, number, number]>[]
-  interpolation?: ClipInterpolation
-}
-
-export type ClipDef = {
-  /** Clip length in seconds — defaults to the last key time across all tracks. */
-  duration?: number
-  /** Target node name → its curves. Names bind to bones (or any child node) at Animator attach. */
-  tracks: Record<string, ClipTrackDef>
-}
-
-export type ClipInfo = { name: string, duration: number, trackCount: number }
-
-const PATH = { position: 0, rotation: 1, scale: 2 } as const
-const INTERP = { linear: 0, step: 1 } as const
-
-const setCache = new Map<number, AnimationClip[]>()
-
-const readInfo = (setId: number): ClipInfo[] =>
-  ((_creator.getClipSetInfo(setId) ?? []) as ClipInfo[]).map((c) => ({ name: c.name, duration: c.duration, trackCount: c.trackCount ?? 0 }))
-
-const readValue = (v: unknown, comps: number, out: number[]): void => {
-  if (Array.isArray(v)) { for (let i = 0; i < comps; i++) out.push(Number(v[i] ?? (i === 3 ? 1 : 0))); return }
-  const o = v as Record<string, number>
-  out.push(o.x ?? 0, o.y ?? 0, o.z ?? 0)
-  if (comps === 4) out.push(o.w ?? 1)
-}
-
-export class AnimationClip {
-  /** Source name (the clip's name inside its file; `"clip"` for procedural clips). Informational —
-   *  an Animator addresses clips by the key YOU give it. */
-  readonly name: string
-  /** Length in seconds. */
-  readonly duration: number
-  /** Number of animated (node, channel) tracks. */
-  readonly trackCount: number
-  /** @internal native clip set + index inside it. */
-  readonly _set: number
-  /** @internal */
-  readonly _index: number
-  /** @internal events: seconds + name, sorted (the engine gets them normalized via setClipEvents). */
-  _events: { t: number, name: string }[] = []
-
-  private constructor(set: number, index: number, info: ClipInfo) {
-    this._set = set
-    this._index = index
-    this.name = info.name
-    this.duration = info.duration
-    this.trackCount = info.trackCount
-  }
-
-  /** @internal — a placeholder for a Playback that never started (unknown clip). */
-  static _none(): AnimationClip { return new AnimationClip(0, 0, { name: "", duration: 0, trackCount: 0 }) }
-
-  /** @internal — wrap the clips of an existing native set (a GLB's embedded clips). Cached per set
-   *  so every model / clone sharing the set gets the SAME objects (events added on one apply to all —
-   *  as they do in the engine). */
-  static _ofSet(setId: number): AnimationClip[] {
-    if (!setId) return []
-    let clips = setCache.get(setId)
-    if (!clips) { clips = readInfo(setId).map((info, i) => new AnimationClip(setId, i, info)); setCache.set(setId, clips) }
-    return clips
-  }
-
-  /** Mark a moment of the clip (SECONDS from its start) with an event name: `kick.addEvent(0.4, 'hit')`
-   *  → `anim.on('hit', (clip, layer) => …)` fires when the playhead crosses it, loops included.
-   *  Events are part of the clip: every model playing it gets them; `slice()` keeps the ones inside
-   *  the range, re-timed. Chainable. */
-  addEvent(time: number, name: string): this {
-    this._events.push({ t: Math.min(Math.max(0, time), this.duration), name })
-    this._events.sort((a, b) => a.t - b.t)
-    this._pushEvents()
-    return this
-  }
-  private _pushEvents(): void {
-    const d = this.duration
-    _creator.setClipEvents(this._set, this._index, new Float32Array(this._events.map((e) => (d > 0 ? e.t / d : 0))))
-  }
-
-  /** Load ONE clip from a GLB: the file's only/first clip, or the one named / at the given index. */
-  static load(source: string | FetchResponse, clip?: string | number): Promise<AnimationClip> {
-    return AnimationClip._loadSet(source).then(([setId, infos]) => {
-      let index = 0
-      if (typeof clip === "number") index = clip
-      else if (typeof clip === "string") index = infos.findIndex((c) => c.name === clip)
-      if (index < 0 || index >= infos.length) {
-        _creator.destroyClipSet(setId)
-        throw new Error(`AnimationClip.load: no clip ${JSON.stringify(clip)} in ${AnimationClip._label(source)} — clips: ${infos.map((c) => c.name).join(", ") || "(none)"}`)
-      }
-      return new AnimationClip(setId, index, infos[index])
-    })
-  }
-
-  /** Load EVERY clip of a GLB (library files), keyed by clip name. */
-  static loadAll(source: string | FetchResponse): Promise<Record<string, AnimationClip>> {
-    return AnimationClip._loadSet(source).then(([setId, infos]) => {
-      const out: Record<string, AnimationClip> = {}
-      infos.forEach((info, i) => { out[info.name] = new AnimationClip(setId, i, info) })
-      return out
-    })
-  }
-
-  /** Build a clip from curves in code — no DCC needed. Keys are `[time, value]`; a track binds to the
-   *  node of that name when the clip is used by an Animator (bones, or any child node). */
-  static from(def: ClipDef): AnimationClip {
-    const names: string[] = []
-    const data: number[] = [0, 0]
-    let trackCount = 0
-    let duration = 0
-    for (const [target, track] of Object.entries(def.tracks)) {
-      const interp = INTERP[track.interpolation ?? "linear"] ?? 0
-      const emit = (path: 0 | 1 | 2, comps: 3 | 4, keys: ClipKey<unknown>[] | undefined) => {
-        if (!keys || keys.length === 0) return
-        const sorted = keys.slice().sort((a, b) => a[0] - b[0])
-        names.push(target)
-        data.push(path, interp, comps, sorted.length)
-        for (const k of sorted) data.push(k[0])
-        for (const k of sorted) readValue(k[1], comps, data)
-        duration = Math.max(duration, sorted[sorted.length - 1][0])
-        trackCount++
-      }
-      emit(PATH.position, 3, track.position)
-      emit(PATH.rotation, 4, track.rotation)
-      emit(PATH.scale, 3, track.scale)
-    }
-    data[0] = trackCount
-    if (def.duration !== undefined) duration = def.duration
-    data[1] = duration
-    const setId = _creator.createClipFromTracks(names.join("\n"), new Float32Array(data))
-    if (setId === 0) throw new Error("AnimationClip.from: invalid track data")
-    const info = readInfo(setId)[0] ?? { name: "clip", duration, trackCount }
-    return new AnimationClip(setId, 0, info)
-  }
-
-  /** A sub-range of this clip as a NEW clip — `[start, end]` seconds of the source, re-timed to 0
-   *  (`end` defaults to the clip's end; array-slice semantics). Cut a too-long take down to the
-   *  action, or carve several sub-clips out of one packed timeline:
-   *
-   *    clips: { Kick: kick.slice(0.2, 1.1) }
-   *
-   *  Keys outside the range are dropped and exact boundary values are interpolated in, so the
-   *  sliced clip starts and ends precisely on the source's pose at the cut points. Everything
-   *  downstream (blend spaces, events' 0–1 times, root motion, phase sync) sees a normal clip of
-   *  the new duration. */
-  slice(start: number, end?: number): AnimationClip {
-    const e = Math.min(end ?? this.duration, this.duration)
-    const st = Math.max(0, start)
-    const setId = _creator.sliceClip(this._set, this._index, st, e)
-    if (setId === 0) throw new Error(`AnimationClip.slice: bad range ${start}${end !== undefined ? `–${end}` : ""} of '${this.name}' (${this.duration.toFixed(2)}s)`)
-    const info = readInfo(setId)[0] ?? { name: this.name, duration: e - st, trackCount: this.trackCount }
-    const out = new AnimationClip(setId, 0, info)
-    // the engine re-timed the event TIMES; carry the names the same way
-    out._events = this._events.filter((ev) => ev.t >= st - 1e-6 && ev.t <= e + 1e-6).map((ev) => ({ t: Math.min(Math.max(0, ev.t - st), e - st), name: ev.name }))
-    return out
-  }
-
-  private static _label(source: string | FetchResponse): string {
-    return typeof source === "string" ? source : "response"
-  }
-
-  private static _loadSet(source: string | FetchResponse): Promise<[number, ClipInfo[]]> {
-    if (typeof _creator.loadClips !== "function") {
-      return Promise.reject(new Error("AnimationClip.load: this host has no animation-clip support yet"))
-    }
-    if (typeof source === "string") {
-      return fetch(source, { useOnce: true }).then((resp) => {
-        if (resp.status >= 400) throw new Error(`AnimationClip.load: failed to load ${source}. HTTP ${resp.status}`)
-        return AnimationClip._loadSet(resp)
-      })
-    }
-    return new Promise<[number, ClipInfo[]]>((resolve, reject) => {
-      _creator.loadClips((source as unknown as { _id: number })._id, (setId: number) => {
-        if (setId === 0) { reject(new Error("AnimationClip.load: the file has no animations (or is not a GLB)")); return }
-        resolve([setId, readInfo(setId)])
-      }, reject)
-    })
-  }
-}

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

@@ -1,120 +0,0 @@
-// 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 ActiveClip, 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"
-
-/** Level of detail for a GLB instance (docs/lod-plan.md): `'auto'` = the engine's pick by screen size and
- *  visibility, or a fixed level 0 (full) … 3 (coarsest mesh, animation every 4th frame without fingers). */
-export type LodMode = "auto" | 0 | 1 | 2 | 3
-
-/** @internal Push a node's LOD override to the host: the Model's mesh level and the Animator's rate
- *  (an Animator set to 'full' wins over a model level — the pose stays exact, the mesh may still coarsen). */
-export const _pushLod = (node: Node): void => {
-  if (!_creator.setLod) return
-  const mesh = (node as { _lodMesh?: number })._lodMesh ?? -1
-  const anim = node.get(Animator)
-  _creator.setLod(node.id, mesh, anim?._lod === "full" ? 0 : mesh)
-}
-
-export class Animator extends Aspect<"anim", Node> {
-  static readonly aspect = "anim"
-  private _c!: Core
-  private _rootMotion = false
-  private _rootRotation = false
-  /** @internal */
-  _lod: "auto" | "full" = "auto"
-
-  /** Animation level of detail. `'auto'` (default): a character small on screen or out of view is
-   *  evaluated every 2nd / 4th frame and stops sampling its finger, toe and twist joints; `'full'`:
-   *  every frame, every joint, whatever the distance — a hero seen through a scope, a cutscene actor.
-   *  Independent of `Model.lod` (the mesh level). No-op on hosts without the LOD pass. */
-  get lod(): "auto" | "full" { return this._lod }
-  set lod(v: "auto" | "full") { this._lod = v; _pushLod(this.node) }
-
-  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]) }
-  /** Every clip shown this frame, all layers, with its weight — the crossfades' state (a debug overlay's list). */
-  get active(): ActiveClip[] { return this._c.layers.flatMap((L) => this._c.active(L)) }
-
-  // ---- 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, this._rootRotation) }
-  /** With `rootMotion`, the root bone's TURN (its yaw about the node's up, since the clip's first
-   *  frame) is root motion too: it comes off the pose and turns the node the travel lands on — the
-   *  character (or the model) faces where a turn-start / turn-in-place / arc clip took it, and the
-   *  crossfade into the next clip keeps that heading instead of swinging back. Off by default: a
-   *  walk cycle's hip sway is a turn too, and most rigs want it in the pose; turn it on for a rig
-   *  whose root bone carries the heading (`lecodes assets retarget --root-rotation yaw`). */
-  get rootRotation(): boolean { return this._rootRotation }
-  set rootRotation(on: boolean) { this._rootRotation = on; if (this._rootMotion) this._c.setRootMotion(true, on) }
-}

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

@@ -1,31 +0,0 @@
-// 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 { ActiveClip, 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) }
-  /** Every clip this layer shows this frame with its weight — the crossfades' state, for a debug overlay. */
-  get active(): ActiveClip[] { return this._c.active(this._r) }
-}

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

@@ -1,30 +0,0 @@
-// 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) }
-  /** Where the loop is in its cycle, 0–1 — one clock for every member (a blend cycles over its
-   *  weighted period). Set it to jump the cycle: `playLoop(def, { phase })` on the way in, or here
-   *  to re-sync with something else (a clip whose pose matches the cycle at that phase). */
-  get phase(): number { return this._c.loopPhase(this._r) }
-  set phase(v: number) { this._c.setLoopPhase(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
-  }
-}