lecodes-sdk 0.20.0 → 1.0.0

package/src/gl/Model.ts

@@ -9,6 +9,27 @@ import { Node } from "./Node"
 import { Animator, _pushLod, type LodMode } from "./animation/Animator"
 import { Material } from "./Material"
 
+/** One polygon under a screen point — what `Model.pickTriangle` returns. `bones` are the vertex's raw
+ *  JOINTS_0 / WEIGHTS_0 pairs (weight > 0; empty = unweighted), `bind` its position in mesh space,
+ *  `world` its skinned position this frame. */
+export interface TrianglePick {
+  /** the Model's root entity, and the mesh node's own entity (0 when the host has no entity for it) */
+  entity: number
+  node: number
+  nodeName: string
+  mesh: string
+  primitive: number
+  material: string
+  /** triangle index within the primitive (index-buffer order), and whether the ray came from behind */
+  triangle: number
+  backface: boolean
+  distance: number
+  point: [number, number, number]
+  bary: [number, number, number]
+  skin: string
+  vertices: { index: number, bind: [number, number, number], world: [number, number, number], bones: { name: string, weight: number }[] }[]
+}
+
 export class Model extends Node {
   /** 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, {...})`. */
@@ -69,6 +90,16 @@ export class Model extends Node {
   /** @internal both flags travel together — the bridge walks the instance once. */
   _applyShadows(): void { _creator.setGlbShadows?.(this.id, this._castShadows, this._receiveShadows) }
 
+  /** DEBUG: the closest polygon of this model under a screen point (logical px — `Input.mouse.position`,
+   *  a touch event's clientX/Y), tested against the CPU-skinned CURRENT pose, both faces. Names the
+   *  triangle, its three vertices (bind + skinned positions) and their raw bone weights, so a stretched
+   *  or misbound polygon can be traced to its binding. One full CPU skin of the model per call: click-rate
+   *  only. null = miss, or a host without the pick (desktop today). */
+  pickTriangle(screenX: number, screenY: number): TrianglePick | null {
+    const json = _creator.pickTriangle?.(this.id, screenX, screenY)
+    return json ? JSON.parse(json) as TrianglePick : null
+  }
+
   /** Duplicate this model — a deep copy of the GLB (meshes, skeleton, animation clips), attached to
    *  the same parent and scene and sharing this model's current transform. The clone has its own
    *  independent animation state (reach it via clone.anim). Mirrors this model's culling flag. */
@@ -110,7 +141,8 @@ export class Model extends Node {
     return new Promise<Model>((resolve, reject) => {
       const mode = options.lightmap ?? Model._lightmapDefault
       const lightmapped = !!mode && !!_creator.setNextGlbLightmapped
-      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()))
+      // the tier + its masked twin (alpha-MASK materials — foliage — take the lightmap shader too, 2026-09-11)
+      if (lightmapped) _creator.setNextGlbLightmapped!(Material.idOf(Material._lightmapTemplate()), Material.idOf(Material._lightmapMaskedTemplate()))
       _creator.createGlb((source as unknown as { _id: number })._id, (entityId: number) => {
         if (entityId === 0) { reject(new Error("Failed to load GLB")); return }
         const model = new Model(entityId)

package/src/gl/Node.ts

@@ -12,7 +12,7 @@ import { Quat, cw, type QuatLike } from "../math/quat"
 import { Mat4, type Mat4Like } from "../math/mat4"
 import type { Geometry } from "./Geometry"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
-import { ensurePhysicsEvents } from "./physicsEvents"
+import { ensurePhysicsEvents } from "./physics/physicsEvents"
 import { Material } from "./Material"
 import type { CompAxis, CompWriter } from "../core/compWrite"
 import type { ClickEvent, TouchStartEvent } from "../runtime/touch"

package/src/gl/Particles.ts

@@ -231,7 +231,15 @@ type Shape =
  *  birth direction (a burst that decays: `curve(4).to(0)`), `x`/`y`/`z` drift in the simulation
  *  space (rising smoke: `y: curve(2).from(0).to(1)`). Unity's velocityOverLifetime. */
 export type VelocityOverLife = { radial?: ParticleValue, x?: ParticleValue, y?: ParticleValue, z?: ParticleValue }
-type Noise = { strength?: number, frequency?: number, speed?: number }
+type Noise = {
+  strength?: number, frequency?: number, speed?: number,
+  /** How much of the displacement a particle earns with AGE (default 0 = all of it from birth).
+   *  The field is sampled by position, so at 0 every particle born at the same spot is pushed the
+   *  same way and a plume's root wanders off its emitter by up to `strength` metres; at 1 a particle
+   *  is born exactly where the emitter put it and drifts into the field over its life — what you
+   *  want whenever the source is visible (an exhaust pipe, a contact patch, a muzzle). */
+  ramp?: number,
+}
 
 /** Ground plane for bouncing particles (all render modes). `height` is in the simulation space:
  *  world y with `space: 'world'`, emitter-local y otherwise. */
@@ -283,6 +291,11 @@ export type ParticlesOptions = ParticlesMaterialOptions & {
    *  without this the engine picks who covers whom per frame (smoke popping over a fireball).
    *  Default 0; a fireball wants 2, its smoke 1, a smoke trail -1. */
   order?: number
+  /** Coarse draw order among ALL blended draws, 0 (first) … 7 (last) — see `Mesh.renderPriority`.
+   *  Default 5: meshes sit at 4 and decals at 3, so smoke covers a car's glass and its skid marks
+   *  whatever the camera does (the engine's depth sort compares object centres, and an emitter's
+   *  centre says nothing about where its cloud is). `order` breaks ties inside one priority. */
+  renderPriority?: number
   shape?: Shape
   /** Extra velocity over life (radial burst that decays, axis drift) — see `VelocityOverLife`. */
   velocityOverLife?: VelocityOverLife
@@ -437,6 +450,7 @@ export class Particles extends Node {
     super()
     this._material = options.material ?? (options.mesh ? Material.lit() : Material.particles(options))
     _creator.createParticleSystem(this.id, Material.idOf(this._material), options.maxParticles ?? 0)
+    this.renderPriority = options.renderPriority ?? 5
 
     const id = this.id
     this.custom = new Proxy([] as ParticleValue[], {
@@ -496,7 +510,7 @@ export class Particles extends Node {
     }
     if (options.noise !== undefined) {
       const n = options.noise
-      out.push(TAG_NOISE, 3, n ? n.strength ?? 1 : 0, n ? n.frequency ?? 1 : 0, n ? n.speed ?? 1 : 0)
+      out.push(TAG_NOISE, 4, n ? n.strength ?? 1 : 0, n ? n.frequency ?? 1 : 0, n ? n.speed ?? 1 : 0, n ? n.ramp ?? 0 : 0)
     }
     if (options.seed !== undefined) out.push(TAG_SEED, 1, options.seed)
 
@@ -517,6 +531,10 @@ export class Particles extends Node {
   set inheritVelocity(val: number) { this._send([ TAG_INHERIT_VELOCITY, 1, val ]) }
   set rateOverDistance(val: number) { this._send([ TAG_RATE_DISTANCE, 1, val ]) }
   set order(val: number) { this._send([ TAG_ORDER, 1, val ]) }
+  /** Coarse draw order, 0 … 7 — see `Mesh.renderPriority`. Write-only. */
+  set renderPriority(v: number) {
+    if (_creator.setRenderPriority) _creator.setRenderPriority(this.id, Math.max(0, Math.min(7, Math.round(v))))
+  }
 
   set velocityOverLife(v: VelocityOverLife) {
     const out: number[] = []
@@ -585,7 +603,7 @@ export class Particles extends Node {
 
   set noise(noise: Noise | null) {
     this._send(noise
-      ? [ TAG_NOISE, 3, noise.strength ?? 1, noise.frequency ?? 1, noise.speed ?? 1 ]
+      ? [ TAG_NOISE, 4, noise.strength ?? 1, noise.frequency ?? 1, noise.speed ?? 1, noise.ramp ?? 0 ]
       : [ TAG_NOISE, 3, 0, 0, 0 ])
   }
 }

package/src/gl/Scene.ts

@@ -13,8 +13,10 @@ import type { ClickEvent, TouchStartEvent } from "../runtime/touch"
 import type { FetchResponse } from "../runtime/fetch"
 import { _requestCameraPermission } from "../plugins/permission"
 import { Camera } from "./Camera"
+import { SceneAudio } from "./audio/SceneAudio"
 import { attachControls, type ControlsHandle, type ControlsOptions } from "./controls"
 import { Material } from "./Material"
+import { Texture } from "./Texture"
 import { Node, nodeRegistry } from "./Node"
 import { glState } from "./state"
 import { registerTouchEndEvent, registerTouchStartEvent } from "./touch"
@@ -107,6 +109,9 @@ export type SceneOptions = {
    *  takes over). Unset keeps the host default (desktop 4×, mobile/web off). The biggest single
    *  fill-rate cost after resolution — turn it down on big screens before anything else. */
   antialias?: boolean | 2 | 4
+  /** Keep a stencil buffer for this scene (off by default: it costs memory and a clear per frame).
+   *  Needed before any material's `stencil` test or write does anything. */
+  stencil?: boolean
   /** Render the 3D at this fraction of the viewport (0.25–1) and upscale; the UI stays at native
    *  resolution. A fixed, predictable cut of per-pixel GPU work — `0.75` is ~45 % cheaper and
    *  barely visible in motion, `0.5` quarters it. Headless renders ignore it. */
@@ -128,6 +133,10 @@ export type SceneOptions = {
    *  scene file — `env` is applied before the nodes build) and leaves already-loaded ones alone.
    *  On the desktop host `CREATOR_TEXTURE_ANISOTROPY` overrides it, for tuning without a rebuild. */
   anisotropy?: number
+  /** Engine-wide cap on texture size, 0 / unset = none (see `Texture.maxSize`): a KTX2 above it
+   *  loses its top mip levels on load, a glTF image is downsampled. Applied before this scene's
+   *  assets load; like `anisotropy` it does not touch textures already loaded. */
+  maxTextureSize?: number
   /** The look on an HDR display (a screen with headroom above SDR white — Apple XDR panels, the
    *  macOS host today); ignored on SDR. `strength` 0..1 is how much of the picture reaches for the
    *  display's headroom (0 only what SDR clipped, 1 nearly everything; default 0.35). `paperWhite`
@@ -148,17 +157,16 @@ const installRenderSyncedFrames = (): void => {
   framesInstalled = true
   _installAspectFrames((early, late) => {
     if (typeof _creator.setEarlyUpdate !== "function") return false
-    // the frame stamp invalidates every Node's local-matrix cache once per frame (physics / character
-    // controllers / animation rewrite transforms natively between frames)
-    _creator.setEarlyUpdate((dt: number) => { glState.frame++; early(dt) })
+    // (The per-phase read-cache stamp — `_phaseStamp` in core/Aspect.ts — advances inside the phase
+    // runners themselves, so it is right on this path and on the setLoop fallback alike.)
+    _creator.setEarlyUpdate(early)
     _creator.setLateUpdate(late)
     return true
   }, (fixed) => {
     // The fixed phase runs INSIDE the engine's substep loop (creator-physics' frame protocol) when the host has the
-    // hook; each substep moves bodies natively, so the frame stamp bumps per step too. Feature-detected:
-    // an older host returns false and the dispatcher steps its own 1/60 accumulator.
+    // hook. Feature-detected: an older host returns false and the dispatcher steps its own 1/60 accumulator.
     if (typeof _creator.setFixedUpdate !== "function") return false
-    _creator.setFixedUpdate((dt: number) => { glState.frame++; fixed(dt) })
+    _creator.setFixedUpdate(fixed)
     return true
   })
   // Time.scale / Time.paused reach the engine's own clocks (physics, animators, particles) through
@@ -172,6 +180,8 @@ export class Scene implements Presentable {
   /** @internal the IBL intensity this scene was built with (Lightmap.load's ambient floor). */
   _environmentIntensity = 20000
   readonly camera: Camera
+  /** The listener + global 3D audio knobs (docs/audio-plan.md). */
+  readonly audio: SceneAudio = new SceneAudio()
 
   /** @internal touch listeners, read by the dispatch system. */
   readonly _clickListeners: Array<(ev: ClickEvent<Node | null>) => void> = []
@@ -220,9 +230,11 @@ export class Scene implements Presentable {
       // `false` must reach the host: desktop defaults to 4× MSAA, so an explicit off is a real change.
       _creator.setSceneMultiSampleAntiAliasing(this._id, a !== false, typeof a === "number" ? a : 4)
     }
+    if (options.stencil !== undefined) this.setStencil(options.stencil)
     // Before anything else in this constructor that could load a texture: the value has to be in
     // place by the time assets bind their samplers.
-    if (options.anisotropy !== undefined) _creator.setTextureAnisotropy?.(options.anisotropy)
+    if (options.anisotropy !== undefined) Texture.anisotropy = options.anisotropy
+    if (options.maxTextureSize !== undefined) Texture.maxSize = options.maxTextureSize
     if (options.hdr) {
       if (options.hdr.strength !== undefined) device.hdr.strength = options.hdr.strength
       if (options.hdr.paperWhite !== undefined) device.hdr.paperWhite = options.hdr.paperWhite
@@ -280,6 +292,28 @@ export class Scene implements Presentable {
   setAntialias(enabled: boolean, scale = 4): void {
     _creator.setSceneMultiSampleAntiAliasing(this._id, enabled, scale)
   }
+  /** Depth-reading effects on / off (a graphics-settings menu): soft particles and projected decals
+   *  read the scene depth, which costs a depth pre-pass of every opaque draw (~12 % of a fill-bound
+   *  frame). Off = hard-edged particles, no decals, no pre-pass. Engine-wide, live. */
+  setDepthEffects(enabled: boolean): void {
+    _creator.setDepthEffects?.(enabled)
+  }
+  /** LOD distance (a graphics-settings menu): the engine's LOD thresholds × `bias`. 2 = every level
+   *  switches at half the distance (a model must look twice as big on screen to keep its detail),
+   *  0.5 = full detail twice as far, 1 = the defaults. Engine-wide, live. Only GLBs that carry
+   *  `_LOD<n>` meshes (`lecodes assets doctor --lod`) have levels to switch. */
+  setLodBias(bias: number): void {
+    _creator.setLodBias?.(bias)
+  }
+  /** Runtime form of `bloom` / `bloomIntensity` (a graphics-settings menu). */
+  setBloom(enabled: boolean, intensity = 0.2): void {
+    _creator.setBloomOptions(this._id, enabled, intensity, 1)
+  }
+  /** The scene's stencil buffer on / off (see `SceneOptions.stencil`). */
+  setStencil(enabled: boolean): void {
+    if (_creator.setSceneStencil) _creator.setSceneStencil(this._id, enabled)
+    else if (enabled) console.warn("[scene] this host has no setSceneStencil — stencil ignored")
+  }
 
   add(...nodes: Node[]): this {
     for (const n of nodes) _creator.addEntityToScene(this._id, n.id)

package/src/gl/Texture.ts

@@ -2,7 +2,41 @@
 
 import { fetch, type FetchResponse, type File } from "../runtime/fetch"
 
+/** `Texture.load` options. */
+export type TextureLoadOptions = {
+  /** `true` (default): colour, stored sRGB. `false`: data (normal map, mask, heightmap) — kept linear. */
+  srgb?: boolean
+  /** Ignore `Texture.maxSize` for this texture (a lightmap page, a lookup table). */
+  fullSize?: boolean
+}
+/** `_creator.createTexture` flags bit: linear data (creator-gl CREATOR_TEXTURE_LINEAR). */
+const TEXTURE_FLAG_LINEAR = 1
+/** `_creator.createTexture` flags bit: exempt from `Texture.maxSize` (creator-gl CREATOR_TEXTURE_FULL_SIZE). */
+const TEXTURE_FLAG_FULL_SIZE = 2
+
 export class Texture {
+  static _maxSize = 0
+  /** Engine-wide cap on texture size (a "texture quality" setting), 0 = none. A KTX2 wider or
+   *  taller than this loses its top mip levels on load (nothing resampled, less memory and
+   *  bandwidth), a glTF PNG/JPEG is downsampled. Reaches textures loaded AFTER it is set — a loaded
+   *  level keeps its textures — so set it up front (`SceneOptions.maxTextureSize`, or before the
+   *  level loads) and apply a menu change on the next level load. Lightmap pages are exempt
+   *  (`TextureLoadOptions.fullSize`). A host may pin it (desktop `CREATOR_TEXTURE_MAX_SIZE`). */
+  static _anisotropy = 2
+  /** Engine-wide anisotropic filtering, 1 (off) … 16 (default 2; `SceneOptions.anisotropy` sets it up
+   *  front). A sampler is baked when its texture is bound, so like `maxSize` this reaches textures
+   *  loaded AFTER it — set it before the level loads. Measured on a lightmapped interior at 720p:
+   *  4× costs ~20 % of the frame over 1× on an integrated GPU. A host may pin it. */
+  static get anisotropy(): number { return Texture._anisotropy }
+  static set anisotropy(level: number) {
+    Texture._anisotropy = level >= 1 ? Math.min(16, level) : 1
+    _creator.setTextureAnisotropy?.(Texture._anisotropy)
+  }
+  static get maxSize(): number { return Texture._maxSize }
+  static set maxSize(size: number) {
+    Texture._maxSize = size > 0 ? Math.floor(size) : 0
+    _creator.setTextureMaxSize?.(Texture._maxSize)
+  }
   /** @internal native texture handle. */
   readonly _id: number
   readonly width: number
@@ -47,17 +81,23 @@ export class Texture {
     _creator.updateTexturePixels?.(this._id, x, y, width, height, data)
   }
 
-  static load(source: string | FetchResponse | File): Promise<Texture> {
+  /** Decode an image (PNG / JPG, or a KTX2 the core transcodes) into a texture. `srgb` (default
+   *  true) says the bytes are COLOUR, stored sRGB so the GPU linearises them on sample; pass
+   *  `false` for DATA — a normal map, a mask, a heightmap — which must come back as stored (a
+   *  flat normal read through sRGB bends by ~35°). A KTX2 decides by its own header. Image
+   *  textures get a mip chain (trilinear) on hosts that build one. */
+  static load(source: string | FetchResponse | File, options: TextureLoadOptions = {}): Promise<Texture> {
     if (typeof source === "string") {
       return fetch(source, { useOnce: true }).then((resp) => {
         if (resp.status >= 400) {
           return Promise.reject(new Error(`Failed to fetch texture from ${source}. HTTP ${resp.status}`))
         }
-        return Texture.load(resp)
+        return Texture.load(resp, options)
       })
     }
+    const flags = (options.srgb === false ? TEXTURE_FLAG_LINEAR : 0) | (options.fullSize ? TEXTURE_FLAG_FULL_SIZE : 0)
     return new Promise<Texture>((resolve, reject) => {
-      _creator.createTexture((source as any)._id, (id, w, h) => resolve(new Texture(w, h, id)), reject)
+      _creator.createTexture((source as any)._id, (id, w, h) => resolve(new Texture(w, h, id)), reject, flags)
     })
   }
 }

package/src/gl/animation/AnimationClip.ts

@@ -10,7 +10,9 @@
 //     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]]] } } })
+//   const bob = AnimationClip.fromCurves({ tracks: { Hips: { position: [[0, [0,0,0]], [1, [0,0.05,0]]] } } })
+//   const stopM = AnimationClip.from(stop, { mirror: true })          // the other side of the body
+//   const kick = AnimationClip.from(take, { from: 0.2, to: 1.1 })    // a window of a longer take
 
 import { fetch, type FetchResponse } from "../../runtime/fetch"
 import type { Vec3Like } from "../../math/vec"
@@ -37,6 +39,20 @@ export type ClipDef = {
 
 export type ClipInfo = { name: string, duration: number, trackCount: number }
 
+/** What `AnimationClip.from(clip, …)` derives from a clip. */
+export type DeriveOptions = {
+  /** The clip MIRRORED — left ↔ right, the motion on the other side of the body (a stop that brakes on the
+   *  left foot brakes on the right). Derived on the rig of the clip's own file (joints pair by name, the
+   *  sagittal plane comes from the rest pose), so the result is the same on every model: its contacts,
+   *  phase, root motion and heading are the mirrored ones, its name is `<name>_M`. Only clips from a GLB
+   *  carry a rig; a curve-built clip cannot be mirrored. */
+  mirror?: boolean
+  /** Start of the window, seconds of the source (default 0). */
+  from?: number
+  /** End of the window, seconds of the source (default the clip's end). */
+  to?: number
+}
+
 const PATH = { position: 0, rotation: 1, scale: 2 } as const
 const INTERP = { linear: 0, step: 1 } as const
 
@@ -90,8 +106,8 @@ export class AnimationClip {
 
   /** 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. */
+   *  Events are part of the clip: every model playing it gets them; `AnimationClip.from(clip, { from, to })`
+   *  keeps the ones inside the window, 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)
@@ -128,7 +144,7 @@ export class AnimationClip {
 
   /** 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 {
+  static fromCurves(def: ClipDef): AnimationClip {
     const names: string[] = []
     const data: number[] = [0, 0]
     let trackCount = 0
@@ -153,30 +169,37 @@ export class AnimationClip {
     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")
+    if (setId === 0) throw new Error("AnimationClip.fromCurves: 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:
+  /** A NEW clip derived from `clip`: its mirror (`{ mirror: true }` — the other side of the body), a window
+   *  of it (`{ from, to }` seconds of the source, re-timed to 0; array-slice semantics), or both. Cut a
+   *  too-long take down to the action, carve several sub-clips out of one packed timeline, get the
+   *  left-footed stop from the right-footed one:
    *
-   *    clips: { Kick: kick.slice(0.2, 1.1) }
+   *    clips: { Kick: AnimationClip.from(kick, { from: 0.2, to: 1.1 }), StopM: AnimationClip.from(stop, { mirror: true }) }
    *
-   *  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 }
+   *  A window drops the keys outside it and interpolates exact boundary values in, so the clip starts and
+   *  ends precisely on the source's pose at the cut points. Everything downstream (blend spaces, events'
+   *  times, root motion, foot contacts, phase sync) sees a normal clip. */
+  static from(clip: AnimationClip, options: DeriveOptions): AnimationClip {
+    const mirror = options.mirror ?? false
+    const windowed = options.from !== undefined || options.to !== undefined
+    const st = windowed ? Math.max(0, options.from ?? 0) : -1
+    const e = windowed ? Math.min(options.to ?? clip.duration, clip.duration) : -1
+    const setId = _creator.deriveClip(clip._set, clip._index, mirror, st, e)
+    if (setId === 0) {
+      const what = windowed ? `bad range ${options.from ?? 0}–${options.to ?? clip.duration}` : "cannot mirror (no rig in the clip's file, or nothing to mirror)"
+      throw new Error(`AnimationClip.from: ${what} of '${clip.name}' (${clip.duration.toFixed(2)}s)`)
+    }
+    const info = readInfo(setId)[0] ?? { name: mirror ? `${clip.name}_M` : clip.name, duration: windowed ? e - st : clip.duration, trackCount: clip.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 }))
+    out._events = windowed
+      ? clip._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 }))
+      : clip._events.map((ev) => ({ ...ev }))
     return out
   }
 

package/src/gl/animation/Animator.ts

@@ -5,15 +5,16 @@
 //
 //   const hero = await Model.load(asset('./hero.glb'))
 //   hero.anim.playLoop('Idle')                                    // the loop: what the character rests on
-//   await hero.anim.play('Jump', { fadeIn: 0.1, fadeOut: 0.2 })   // a one-shot over it, back to the loop after
+//   await hero.anim.play('Jump', { fade: 0.2 })                   // a one-shot over it, back to the loop after
 //
 //   const loco = hero.anim.playLoop({ Idle: 0, Walk: 2, Run: 6 })  // a blend space as the loop
 //   loco.value = hero.controller.velocity.length                  // where we are on its axis
 //   const upper = hero.anim.addLayer({ mask: 'Spine1' })
 //   upper.playLoop('Aim')                                         // arms aim, legs keep walking
 //
-// Every switch is an inertialized transition: the pose shown does not fade away, its difference to the
-// new source decays over `fade` (default 0.2 s; 0 = cut). A clip may be replaced at any time.
+// Every switch is an inertialized transition: the pose shown (a loop, a one-shot, rest) does not fade
+// away, its difference to the new source decays over `fade` — and no `fade` means a cut, never a
+// default. A clip may be replaced at any time; a one-shot on a layer with no loop holds its last frame.
 //
 // The surface, top to bottom: clips → playing → root motion → the feet and the warp (`anim.feet`,
 // `anim.warp` — locomotion's post-processing of the pose) → level of detail → engine-facing.