lecodes-cli 0.17.1 → 0.18.0

package/runtime/sdk/gl/CameraPlace.ts

@@ -0,0 +1,51 @@
+// CameraPlace: "the camera as a place". A scene has ONE camera (`scene.camera`); a CameraPlace marks
+// a node as somewhere that camera can be — with the lens it uses there. Nothing is created engine-
+// side (no second camera, no ABI): it is a pose + a projection record on any node: an empty, an
+// empty mounted on a bone (`mount:`), a node a path aspect moves (a dolly shot), a model node.
+//
+//   • In a scene FILE that runs (`open()` / `load()`), the `active: true` place drives
+//     `scene.camera` (exactly `scene.camera.follow(node)`); exactly one per file.
+//   • Inside a prefab or an `instantiate()`d subtree a place is inert DATA — the hosting scene
+//     owns its camera. The host reads it (`inst.nodes.eye.get(CameraPlace)` → world pose + fov)
+//     or anchors on it (`inst.alignTo(inst.nodes.eye)`).
+//   • From code: `scene.camera.follow(dolly.get(CameraPlace))` — a cutscene shot; `follow(null)`
+//     releases.
+//   • Edit mode: draws a frustum gizmo (the editor's camera preview reads the same place).
+// See docs/scene-camera-place-plan.md.
+
+import { Aspect } from "../core/Aspect"
+import type { FieldMeta } from "../core/fields"
+import { Gizmos } from "../scene/gizmos"
+import type { Camera } from "./Camera"
+import type { Node } from "./Node"
+
+export class CameraPlace extends Aspect<"cameraPlace", Node> {
+  static readonly aspect = "cameraPlace"
+  /** Vertical field of view in degrees (default 60) — smaller is a longer lens. */
+  fov = 60
+  /** Near clip distance. */
+  near = 0.01
+  /** Far clip distance = view range. */
+  far = 1000
+  /** The place that drives `scene.camera` when the file declaring it RUNS. Exactly one per file;
+   *  ignored inside prefabs / instantiated subtrees (the host scene owns its camera). */
+  active = false
+  /** Aspect ratio of the frustum gizmo only (the real aspect is the viewport's). */
+  static fields: FieldMeta<CameraPlace> = {
+    fov: { label: "FOV", min: 1, max: 179, step: 1 },
+    near: { min: 0.001, max: 10, step: 0.01 },
+    far: { min: 1, max: 100000, step: 1 },
+    active: { label: "Active camera" },
+  }
+  static editor = { rebuild: true }
+
+  /** Copy this place's projection onto a camera (`camera.follow(place)` does it for you). */
+  applyTo(camera: Camera): void {
+    camera.setProjection({ fov: this.fov, near: this.near, far: this.far })
+  }
+
+  /** Edit mode: the frustum marker (−Z = view). Play mode never calls this. */
+  rebuild(): void {
+    Gizmos.frustum(this.node.worldMatrix, this.fov, 16 / 9, 0.6, { color: this.active ? "#ffffff" : "#9aa3b2" })
+  }
+}

package/runtime/sdk/gl/CharacterController.ts

@@ -5,8 +5,9 @@
 //   const hero = new Mesh(capsuleGeometry(), material)
 //     .aspect(Shape, { capsule: { halfHeight: 0.6, radius: 0.3 } })
 //     .aspect(CharacterController, { speed: 6, jumpSpeed: 8 })
-//   Input.on('move', (x, z) => hero.controller.move(x, z))
-//   Input.on('jump', () => hero.controller.jump())
+//   setLoop(() => hero.controller.move((Input.key('KeyD') ? 1 : 0) - (Input.key('KeyA') ? 1 : 0),
+//                                       (Input.key('KeyS') ? 1 : 0) - (Input.key('KeyW') ? 1 : 0)))
+//   Input.on('keydown', e => { if (e.code === 'Space') hero.controller.jump() })
 //
 // You drive horizontal intent + jump; the controller integrates gravity and Jolt handles collision
 // against the world. `grounded` reports whether it's on walkable ground. It runs in the EARLY update
@@ -49,6 +50,9 @@ export class CharacterController extends Aspect<"controller", Node> {
     if (!shape) {
       throw new Error("CharacterController requires a Shape aspect (a capsule is recommended) — add it first: node.aspect(Shape, { capsule: {…} }).aspect(CharacterController)")
     }
+    if (shape._isTriangleMesh) {
+      throw new Error("CharacterController needs a convex Shape (capsule recommended) — { mesh: true } is a triangle mesh; use { mesh: 'convex' } or a capsule")
+    }
     const shapeId = shape._claim() // the character owns the shape; it is not a rigid body
     this._charId = _creator.characterCreate(this.node.id, shapeId, this.maxSlope)
   }

package/runtime/sdk/gl/IK.ts

@@ -1,174 +1,193 @@
-// 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))))
-    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
-    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
-    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
-    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
-    let axis = ba.cross(bc)
-    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
+// 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
+  /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat.
+   *  Unset = the end bone keeps its animated local rotation (a hand on a grip, a foot on a slope
+   *  want it set). Blended by `weight · rotationWeight`. */
+  rotation?: Node | Quat
+  /** 0–1 contribution of `rotation` (on top of `weight`). */
+  rotationWeight = 1
+  /** 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))))
+    // a positive rotation about ba × bc moves `bc` AWAY from `ba`, i.e. opens the joint — so rotating the
+    // mid bone by (want − cur) about it opens/closes exactly as needed. (bc × ba has the opposite sense:
+    // with it every already-bent limb — which is every animated limb — bends the wrong way; the straight
+    // case below picks its axis as ba × ref, the same sense as ba × bc for a limb barely bent toward ref.)
+    let axis = ba.cross(bc)
+    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)
+    }
+
+    // 5. end-bone rotation: take the target's world rotation (a hand stays on its grip, a foot
+    // flat on the slope) — the solve above only placed the end's ORIGIN
+    const r = this.rotation
+    if (r !== undefined && r !== null) {
+      const rw = w * Math.min(1, Math.max(0, this.rotationWeight))
+      if (rw > 0) {
+        const want = (r as Node).id !== undefined && typeof (r as Node).worldMatrix === "object" ? worldRot(r as Node) : (r as Quat)
+        const endLocal0 = end.quaternion
+        setWorldRot(end, want)
+        if (rw < 1) end.quaternion = endLocal0.slerp(end.quaternion, rw)
+      }
+    }
+  }
+}
+
+/** 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

@@ -45,6 +45,15 @@ export type ParticlesMaterialOptions = {
   sheet?: number | [number, number]
   /** Extra brightness multiplier for a glow look (0 = off). */
   emissive?: number
+  /** (`render` quad / stretch) a second sheet on the same grid, ADDED as `emissiveMap × emissiveColor`
+   *  — keyed by `map`'s alpha, not tinted by the particle colour. A fireball = a smoke `map` whose
+   *  colour curve goes dark + a fire `emissiveMap` that keeps glowing while alpha lasts. */
+  emissiveMap?: Texture | null
+  /** Multiplier for `emissiveMap`; an `[r, g, b]` array may exceed 1 (HDR glow). Default 0 (off). */
+  emissiveColor?: ColorInput
+  /** (`render` quad / stretch) crossfade each flipbook frame into the next by the fractional frame
+   *  index instead of snapping — smooth sheet playback at any frame rate. Default false. */
+  frameBlend?: boolean
   /** Compositing: `"alpha"` (default — smoke, dust) or `"add"` (fire, sparks, magic). */
   blend?: "alpha" | "add"
   /** Soft radial falloff toward the sprite edge. Defaults to true without a map, false with one. */
@@ -163,6 +172,9 @@ export class Material {
     if (quad) {
       m.uniforms.mode = options.render === "ribbon" ? 2 : options.render === "stretch" ? 1 : 0
       m.uniforms.stretch = options.stretch ?? (options.render === "stretch" ? 0.05 : 0)
+      if (options.emissiveMap) m.uniforms.emissiveMap = options.emissiveMap
+      if (options.emissiveColor !== undefined) m.uniforms.emissiveColor = Color.toRgb01(options.emissiveColor)
+      if (options.frameBlend) m.uniforms.frameBlend = 1
     }
     if (options.map) m.map = options.map
     return m
@@ -186,6 +198,17 @@ export class Material {
 
   /** Load a custom compiled shader (.mat URL) as a material. */
   static load(url: string): Promise<Material> {
+    // "id:<n>" — the artifact is a LOCAL file the host already resolved through fetchLocal (a
+    // compile with no asset server: the desktop host reads it from next to the bundle). There is
+    // nothing to fetch, so the material is ready synchronously; -1 means the host found no such
+    // file, which would otherwise reach createMaterial as a bad handle.
+    if (url.startsWith("id:")) {
+      const id = Number(url.slice(3))
+      if (!(id >= 0)) {
+        return Promise.reject(new Error(`Shader not found next to the app (${url}). Compile it with \`lecodes shaders compile\`.`))
+      }
+      return Promise.resolve(new Material({ _id: id } as any))
+    }
     return fetch(url, { useOnce: true }).then((resp) => {
       if (resp.status >= 400) return Promise.reject(new Error(`Failed to fetch shader from ${url}. HTTP ${resp.status}`))
       return new Material(resp)

package/runtime/sdk/gl/Model.ts

@@ -1,20 +1,21 @@
 // A loaded GLB model — its own node kind (a GLB is a node hierarchy with baked animation clips),
 // distinct from Mesh (raw primitives, no animation). Animation is always present, reached as
-// model.anim:
+// model.anim (an Animator over the GLB's clips — crossfades, blend spaces, layers when you need them):
 //   const hero = await Model.load(asset('./hero.glb'))
-//   hero.anim.play('Run')
+//   hero.anim.play('Run', { loop: true })
 
 import { fetch, type FetchResponse } from "../runtime/fetch"
 import { Node } from "./Node"
-import { ModelAnimation } from "./ModelAnimation"
+import { Animator } from "./animation/Animator"
 
 export class Model extends Node {
-  /** GLB skeletal animation — always present on a Model. */
-  declare readonly anim: ModelAnimation
+  /** The model's Animator — always present, its clip table = the GLB's embedded clips. Configure
+   *  more (external clips, blend spaces, layers) with `model.aspect(Animator, {...})`. */
+  declare readonly anim: Animator
 
   constructor(internalId: number) {
     super(internalId)
-    this.aspect(ModelAnimation)
+    this.aspect(Animator)
   }
 
   /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to