lecodes-sdk 0.20.0 → 0.20.2

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 "./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/SceneAudio.ts

@@ -0,0 +1,26 @@
+// `scene.audio` (docs/audio-plan.md §2): the listener and the global 3D knobs. The listener is the
+// scene's active camera by default — a `CameraPlace` switch or a follow rig changes nothing, the
+// engine reads whatever camera it renders with. Set a node to listen from somewhere else (the
+// player's head in a third-person game, so sounds pan around the character, not the camera).
+
+import { audioSupported } from "../audio/support"
+import type { Node } from "./Node"
+
+export class SceneAudio {
+  private _listener: Node | null = null
+  private _doppler = 1
+
+  /** The node the engine listens from; null (default) = the active camera. */
+  get listener(): Node | null { return this._listener }
+  set listener(node: Node | null) {
+    this._listener = node
+    if (audioSupported) _creatorAudio.setListener(node ? node.id : 0)
+  }
+
+  /** Multiplies every source's doppler amount (0 = off everywhere). Default 1. */
+  get dopplerFactor(): number { return this._doppler }
+  set dopplerFactor(v: number) {
+    this._doppler = v
+    if (audioSupported) _creatorAudio.setListenerOptions(v)
+  }
+}

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/Trigger.ts

@@ -1,45 +1,45 @@
-// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
-// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
-// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
-//
-//   const goal = new Mesh(box(), material)
-//     .aspect(Shape, { box: [1, 2, 1] })
-//     .aspect(Trigger)
-//   goal.addEventListener('enter', other => win(other))
-//   goal.addEventListener('exit',  other => …)
-
-import { Aspect } from "../core/Aspect"
-import { Shape } from "./Shape"
-import { ensurePhysicsEvents } from "./physicsEvents"
-import type { Node } from "./Node"
-
-export class Trigger extends Aspect<"trigger", Node> {
-  static readonly aspect = "trigger"
-
-  private _bodyId = 0
-  /** Native body id (0 if no physics support). */
-  get id(): number { return this._bodyId }
-
-  onAttach(): void {
-    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
-    const shape = this.node.get(Shape)
-    if (!shape) {
-      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
-    }
-    const shapeId = shape._claim()
-    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
-    shape._ownBody(this._bodyId)
-    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
-  }
-
-  onDetach(): void {
-    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
-    const shape = this.node.get(Shape)
-    if (shape) {
-      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
-      shape._recreatePickBody()
-    }
-  }
-
-  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
-}
+// A trigger zone, as an aspect on a 3D Node. Requires a Shape (its geometry); creates a static SENSOR
+// body from it, so a physics body overlapping the zone fires the node's 'enter' / 'exit' events
+// instead of colliding. A trigger does not block movement, and is still pointer-pickable.
+//
+//   const goal = new Mesh(box(), material)
+//     .aspect(Shape, { box: [1, 2, 1] })
+//     .aspect(Trigger)
+//   goal.addEventListener('enter', other => win(other))
+//   goal.addEventListener('exit',  other => …)
+
+import { Aspect } from "../core/Aspect"
+import { Shape } from "./Shape"
+import { ensurePhysicsEvents } from "./physicsEvents"
+import type { Node } from "./Node"
+
+export class Trigger extends Aspect<"trigger", Node> {
+  static readonly aspect = "trigger"
+
+  private _bodyId = 0
+  /** Native body id (0 if no physics support). */
+  get id(): number { return this._bodyId }
+
+  onAttach(): void {
+    if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
+    const shape = this.node.get(Shape)
+    if (!shape) {
+      throw new Error("Trigger requires a Shape aspect — add it first: node.aspect(Shape, {…}).aspect(Trigger)")
+    }
+    const shapeId = shape._claim()
+    this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, 0 /* static */, 0, true /* sensor */, false)
+    shape._ownBody(this._bodyId)
+    ensurePhysicsEvents() // routes overlap events → the node's 'enter' / 'exit'
+  }
+
+  onDetach(): void {
+    if (this._bodyId) { _creator.physicsRemoveBody(this._bodyId); this._bodyId = 0 }
+    const shape = this.node.get(Shape)
+    if (shape) {
+      shape._ownBody(0)          // the Shape held OUR body id — forget it, or its own detach removes it twice (native crash)
+      shape._recreatePickBody()
+    }
+  }
+
+  // No moveTo(): `node.position = p` moves the node AND the sensor body it owns (see Node._xf).
+}

package/src/gl/Vehicle.ts

@@ -25,13 +25,12 @@
 //
 // Layering, and why it is where it is: docs/vehicle-rework-plan.md.
 
-import { Aspect } from "../core/Aspect"
+import { Aspect, _phaseStamp } from "../core/Aspect"
 import type { FieldMeta } from "../core/fields"
 import { Mat4 } from "../math/mat4"
 import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
 import { cw, type QuatLike } from "../math/quat"
 import { Gizmos } from "../scene/gizmos"
-import { glState } from "./state"
 import { Gearbox } from "./Gearbox"
 import { Node } from "./Node"
 import { DEFAULT_FRICTION, Physics } from "./Physics"
@@ -314,12 +313,13 @@ export class Vehicle extends Aspect<"vehicle", Node> {
     if (this._id) _creator.vehicleSetTransmission(this._id, ratio, clamp(clutch, 0, 1))
   }
 
-  // --- readouts (one native read per frame, shared by the car and every wheel) -------------------
+  // --- readouts (one native read per PHASE — early sees the pre-step state, late the settled one —
+  //     shared by the car and every wheel; keyed on core/Aspect's _phaseStamp) -------------------
 
   private _read(): Float32Array {
-    if (this._id && this._stateFrame !== glState.frame) {
+    if (this._id && this._stateFrame !== _phaseStamp.value) {
       _creator.vehicleGetState(this._id, this._state)
-      this._stateFrame = glState.frame
+      this._stateFrame = _phaseStamp.value
     }
     return this._state
   }

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.

package/src/gl/animation/core.ts

@@ -18,19 +18,17 @@ import type { Node } from "../Node"
 /** A position on a blend axis (1D) or plane (2D). */
 export type BlendPosition = number | readonly [number, number]
 
-/** The transition time (seconds) a play / playLoop without `fade` uses. */
-export const DEFAULT_FADE = 0.2
-
 export type PlayOptions = {
-  /** Transition seconds — how long the difference to the pose the layer SHOWED takes to decay
-   *  (default 0.2; `0` = cut). Also the transition back at the end unless `fadeOut` overrides it. */
+  /** Transition seconds — how long the difference to the pose the layer SHOWED (its loop, a one-shot,
+   *  or rest) takes to decay. Default `0` = cut: a fade is always asked for, never implied. Also the
+   *  transition back to the loop at the end unless `fadeOut` overrides it. */
   fade?: number
   /** Transition seconds for the way in only (overrides `fade`). */
   fadeIn?: number
-  /** One-shots: the transition BACK at the end (overrides `fade`). It starts this long before the
-   *  clip ends — while it still plays — so the hand-over lands on the last pose, not after it. On a
-   *  layer with no loop to return to, giving `fadeOut` releases the layer at the end instead of
-   *  holding the last frame. */
+  /** One-shots: the transition BACK to the loop at the end (overrides `fade`; `0` = cut at the end).
+   *  It starts this long before the clip ends — while it still plays — so the hand-over lands on the
+   *  last pose, not after it. On a layer with no loop the clip HOLDS its last frame (a rock that broke
+   *  stays broken) — `anim.stop({ fade })` is the way back to rest. */
   fadeOut?: number
   /** Playback rate for this clip (default 1). */
   speed?: number
@@ -52,8 +50,8 @@ export type PlayOptions = {
 export type StopOptions = { fade?: number }
 
 export type LoopOptions = {
-  /** Transition seconds from whatever the layer shows — its previous loop, or a one-shot still
-   *  playing (default 0.2; `0` = cut). */
+  /** Transition seconds from whatever the layer shows — its previous loop, a one-shot still playing,
+   *  or rest. Default `0` = cut: a loop wanting a transition asks for one (`{ fade: 0.2 }`). */
   fade?: number
   /** Playback rate of the loop's clips (default 1). */
   speed?: number
@@ -145,6 +143,12 @@ export type ClipInfo = {
   turnAt(time: number): number
   /** the root's own speed at `time`, m/s — how fast the clip is moving the body right there */
   speedAt(time: number): number
+  /** the PELVIS' yaw relative to the clip's heading at `time` (rad, + = left, wrapped to ±π): the stance twist
+   *  the heading leaves out — an idle stands ~43° off the course it starts along, a stop's tail turns into that
+   *  stance while the heading holds. A controller that switches clips mid-pose can keep the PELVIS continuous
+   *  (turn the node by the difference between the two clips' values) where keeping the course would swing
+   *  the body. Without a baked heading: the pelvis' yaw at frame 0 throughout. */
+  pelvisYawAt(time: number): number
   /** the unit travel direction at `time` ([x, z], model space, held through stills) — integrate
    *  direction × d(travel) to reconstruct the root's 2D path (a treadmill display, a turn's arc) */
   directionAt(time: number): [number, number]
@@ -215,7 +219,7 @@ const ensureEvents = (): void => {
   if (eventsInstalled) return
   eventsInstalled = true
   _creator.setOnAnimatorEvent((animatorId, slot, type) => handlers.get(animatorId)?.(slot, type))
-  _creator.setOnAnimatorStep((animatorId, side, x, y, z) => stepHandlers.get(animatorId)?.(side, x, y, z))
+  _creator.setOnAnimatorStep?.((animatorId, side, x, y, z) => stepHandlers.get(animatorId)?.(side, x, y, z))
 }
 
 const settled = (slot: SlotRec): PlaybackRec => {
@@ -364,8 +368,8 @@ export class Core {
     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 ?? DEFAULT_FADE
-    const fadeOut = o.fadeOut ?? o.fade ?? DEFAULT_FADE
+    const fadeIn = o.fadeIn ?? o.fade ?? 0
+    const fadeOut = o.fadeOut ?? o.fade ?? 0
     const phase = this.entryPhase(L, o.phase)   // read BEFORE the play: what the layer shows now
     this.settleLayer(L)   // the layer had one source: whatever it was, this play takes over from it
     let resolve = (_n: boolean): void => {}
@@ -399,7 +403,7 @@ export class Core {
   // ---- loop ----
   loop(L: LayerRec, def: LoopDef, o: LoopOptions): Loop | undefined {
     if (!this.ensure()) return undefined
-    const fade = o.fade ?? DEFAULT_FADE
+    const fade = o.fade ?? 0
     const phase = this.entryPhase(L, o.phase)   // read BEFORE the members replace the layer's source
     if (L.loop) { L.loop.dead = true; for (const m of L.loop.members) m.slot.inBlend = false; L.loop = undefined }
     this.settleLayer(L)   // a one-shot on the layer is cut short by the new loop
@@ -576,6 +580,7 @@ export class Core {
       travelAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 1, time),
       turnAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 2, time),
       speedAt: (time: number) => _creator.animatorSlotCurveAt(id, slot, 3, time),
+      pelvisYawAt: (time: number) => { const v = _creator.animatorSlotCurveAt(id, slot, 6, time); return Math.atan2(Math.sin(v), Math.cos(v)) },
       directionAt: (time: number) => [ _creator.animatorSlotCurveAt(id, slot, 4, time), _creator.animatorSlotCurveAt(id, slot, 5, time) ] as [number, number],
       timeAtTurn: (yaw: number) => _creator.animatorSlotTimeAtTurn(id, slot, yaw),
       kneePoleAt: (side: "left" | "right", time: number) => {