lecodes-sdk 0.20.2 → 1.1.0

package/src/gl/animation/IK.ts

@@ -0,0 +1,214 @@
+// IK — chains the ENGINE solves in its late pass: after every aspect's update(dt) ran, before the
+// dynamic bones and the skin flush. Attach to the END bone of the chain (the chain is its parent and
+// grandparent); nothing runs in JS per frame — the aspect only describes the chain, the host reads the
+// target nodes itself each frame and creator-anim (anchors.cpp) solves.
+//
+//   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
+//
+// ANCHORED chains — hands on a weapon's grips (the gun-master rig): the chain rides a SOCKET of the
+// rig (`anim.sockets(...)`: named empties on a bone, a weapon's grip / magazine / bolt), keeping the
+// animated hand's pose RELATIVE to that socket on the gun the take was authored on and replaying it
+// relative to the socket on the gun in the hands — shifted and turned by the sockets' difference,
+// never re-authored. A clip's anchor spans (`clip.anchors(...)`) move the hand between sockets while
+// it plays (grip → magazine → free → bolt → grip through a reload):
+//
+//   arms.anim.sockets('ik_hand_gun', { grip_r: weapon.gripR, grip_l: weapon.gripL, mag: weapon.mag })
+//   arms.anim.sockets('ik_hand_gun', { grip_r: {...}, grip_l: {...}, mag: {...} }, { set: 'tr15' })  // the donor's
+//   arms.bone('hand_l')!.aspect(IK.TwoBone, { anchor: 'grip_l' })
+//   arms.anim.clip('R_ReloadEmpty')!.anchors('hand_l', { donor: 'tr15', spans: [[0.9, 1.4, 'mag'], [1.4, 2.0, ''], [2.0, 2.4, 'mag']] })
+//
+// Since the engine solves after the late phase, a target the game moves in its own update(dt) — the
+// gun bone placed for aiming and recoil — is reached the SAME frame.
+
+import { Aspect } from "../../core/Aspect"
+import { Vec3, type Vec3Like } from "../../math/vec"
+import { Quat } from "../../math/quat"
+import type { Node } from "../Node"
+import { Animator } from "./Animator"
+import type { Core } from "./core"
+
+type Target = Node | Vec3Like
+
+const isNode = (t: unknown): t is Node => typeof t === "object" && t !== null && typeof (t as Node).id === "number" && typeof (t as { worldMatrix?: unknown }).worldMatrix === "object"
+
+// CANIM_IK_* (creator-anim.h): the fixed-order parameter array of a chain.
+const P = { TARGET: 0, POLE: 3, HAS_POLE: 6, WEIGHT: 7, ROT: 8, ROT_WEIGHT: 12, AXIS: 13, LIMIT: 16, ENABLED: 17, ANCHOR_TIME: 18, ANCHOR_PIN: 19, COUNT: 20 }
+const stateBuf = new Float32Array(4)
+
+/** The rig a bone belongs to: the nearest ancestor carrying an Animator (every Model has one); a bare
+ *  node tree gets one on its topmost node. */
+const rigOf = (bone: Node): Core => {
+  let top: Node = bone
+  for (let n: Node | null = bone; n; n = n.parent) {
+    const anim = n.get(Animator)
+    if (anim) return anim._core
+    top = n
+  }
+  top.aspect(Animator)
+  return top.get(Animator)!._core
+}
+
+/** What both chains share: the native handle, the parameter push, the readback. */
+abstract class Chain<Name extends string> extends Aspect<Name, Node> {
+  protected _rig?: Core
+  protected _ik = 0
+  protected _weight = 1
+  protected _enabled = true
+  protected abstract readonly kind: 0 | 1
+
+  /** 0–1 contribution (blend in/out, e.g. foot planting only while grounded). */
+  get weight(): number { return this._weight }
+  set weight(v: number) { this._weight = v; this.push() }
+  /** Solve every frame (default). */
+  get enabled(): boolean { return this._enabled }
+  set enabled(v: boolean) { this._enabled = v; this.push() }
+  /** After the last solve: how far the end bone still is from its target, metres (0 = reached). */
+  get error(): number { return this._rig && this._ik && this._rig.ikState(this._ik, stateBuf) ? stateBuf[0]! : 0 }
+
+  onAttach(): void {
+    this._rig = rigOf(this.node)
+    this._ik = this._rig.ikCreate(this.kind, this.node.id)
+    if (!this._ik) console.warn(`IK: ${this.node.name || "the bone"} is no joint of its rig (or this host has no IK)`)
+    this.push()
+  }
+  onDetach(): void {
+    if (this._rig && this._ik) this._rig.ikDestroy(this._ik)
+    this._ik = 0
+    this._rig = undefined
+  }
+  onReconfigure(): void { this.push() }
+
+  protected params(): Float32Array {
+    const p = new Float32Array(P.COUNT)
+    p[P.WEIGHT] = this._weight
+    p[P.ENABLED] = this._enabled ? 1 : 0
+    p[P.LIMIT] = 80
+    p[P.AXIS + 2] = -1
+    p[P.ROT + 3] = 1
+    p[P.ANCHOR_TIME] = 0.05
+    return p
+  }
+  /** Push the description to the engine (a no-op until attached). */
+  protected abstract push(): void
+}
+
+/** 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; `anchor` makes it ride a socket of the rig instead (see the file
+ *  header). */
+class TwoBone extends Chain<"ik"> {
+  static readonly aspect = "ik"
+  protected readonly kind = 0 as const
+  private _target?: Target
+  private _pole?: Target
+  private _rotation?: Node | Quat
+  private _rotationWeight = 1
+  private _anchor = ""
+  private _anchorTime = 0.05
+  private _anchorPin = 0
+
+  /** Where the end bone should be (a Node — read by the engine every frame — or a world position). */
+  get target(): Target | undefined { return this._target }
+  set target(v: Target | undefined) { this._target = v; this.push() }
+  /** Bend hint — the mid joint is pulled toward it (a Node or a world point). */
+  get pole(): Target | undefined { return this._pole }
+  set pole(v: Target | undefined) { this._pole = v; this.push() }
+  /** World rotation the END bone takes after the solve — a Node (its world rotation) or a Quat. Unset =
+   *  the end bone keeps its animated rotation (a hand on a grip, a foot on a slope want it set). Blended
+   *  by `weight · rotationWeight`. An anchored chain takes its rotation from the socket instead. */
+  get rotation(): Node | Quat | undefined { return this._rotation }
+  set rotation(v: Node | Quat | undefined) { this._rotation = v; this.push() }
+  /** 0–1 contribution of `rotation` (on top of `weight`); for an anchored chain, of the socket's turn. */
+  get rotationWeight(): number { return this._rotationWeight }
+  set rotationWeight(v: number) { this._rotationWeight = v; this.push() }
+  /** ANCHORED: the name of the LIVE socket the end bone rides (`anim.sockets(...)`) — its target and
+   *  rotation come from the socket and the playing clips' anchor spans; `target` / `pole` / `rotation`
+   *  are ignored. '' = a plain chain. */
+  get anchor(): string { return this._anchor }
+  set anchor(v: string) { this._anchor = v ?? ""; this.push() }
+  /** Anchored: how fast the hand moves between sockets — the halflife (s) of the spring the applied
+   *  delta follows the wanted one with (default 0.05). */
+  get anchorTime(): number { return this._anchorTime }
+  set anchorTime(v: number) { this._anchorTime = v; this.push() }
+  /** Anchored: 0..1 how hard the end bone is PINNED on its socket while the playing clips leave it there
+   *  (a GAP in their spans — the hand is holding the gun). 1 = it sits exactly on the socket, so nothing
+   *  in the pose below can slide it along the gun; 0 (default) = it keeps the take's own relation to the
+   *  socket, moved by the delta. A clip's SPANS carry their own pin and default to 0, because a hand on
+   *  its way to a magazine must keep the take's motion — so this knob is about holding, not reaching. */
+  get anchorPin(): number { return this._anchorPin }
+  set anchorPin(v: number) { this._anchorPin = v; this.push() }
+  /** After the last solve: the anchor delta applied — how far (m) and how much (rad) the live socket
+   *  moved the hand off the take's own pose. 0 for a plain chain. */
+  get anchorDelta(): { distance: number, angle: number } {
+    if (!this._rig || !this._ik || !this._rig.ikState(this._ik, stateBuf)) return { distance: 0, angle: 0 }
+    return { distance: stateBuf[1]!, angle: stateBuf[2]! }
+  }
+
+  protected push(): void {
+    const rig = this._rig
+    if (!rig || !this._ik) return
+    const p = this.params()
+    p[P.ANCHOR_TIME] = this._anchorTime
+    p[P.ANCHOR_PIN] = this._anchorPin
+    const anchored = this._anchor !== ""
+    p[P.ROT_WEIGHT] = anchored || this._rotation !== undefined ? this._rotationWeight : 0
+    let targetNode = 0, poleNode = 0, rotNode = 0
+    if (!anchored) {
+      const t = this._target, pl = this._pole, r = this._rotation
+      if (isNode(t)) targetNode = t.id
+      else if (t !== undefined) { const v = new Vec3(t); p[P.TARGET] = v.x; p[P.TARGET + 1] = v.y; p[P.TARGET + 2] = v.z }
+      if (isNode(pl)) poleNode = pl.id
+      else if (pl !== undefined) { const v = new Vec3(pl); p[P.POLE] = v.x; p[P.POLE + 1] = v.y; p[P.POLE + 2] = v.z; p[P.HAS_POLE] = 1 }
+      if (isNode(r)) rotNode = r.id
+      else if (r !== undefined) { p[P.ROT] = r.x; p[P.ROT + 1] = r.y; p[P.ROT + 2] = r.z; p[P.ROT + 3] = r.w }
+    }
+    rig.ikSet(this._ik, p)
+    rig.ikNodes(this._ik, targetNode, poleNode, rotNode)
+    rig.ikAnchor(this._ik, this._anchor)
+  }
+}
+
+/** 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 Chain<"lookAt"> {
+  static readonly aspect = "lookAt"
+  protected readonly kind = 1 as const
+  private _target?: Target
+  private _axis: Vec3Like = [ 0, 0, -1 ]
+  private _limit = 80
+
+  /** What to look at (a Node — read by the engine every frame — or a world position). */
+  get target(): Target | undefined { return this._target }
+  set target(v: Target | undefined) { this._target = v; this.push() }
+  /** The bone's local axis that should point at the target. */
+  get axis(): Vec3Like { return this._axis }
+  set axis(v: Vec3Like) { this._axis = v; this.push() }
+  /** Max deflection from the animated direction, in degrees (default 80). */
+  get limit(): number { return this._limit }
+  set limit(v: number) { this._limit = v; this.push() }
+
+  protected push(): void {
+    const rig = this._rig
+    if (!rig || !this._ik) return
+    const p = this.params()
+    const a = new Vec3(this._axis)
+    p[P.AXIS] = a.x; p[P.AXIS + 1] = a.y; p[P.AXIS + 2] = a.z
+    p[P.LIMIT] = this._limit
+    let targetNode = 0
+    const t = this._target
+    if (isNode(t)) targetNode = t.id
+    else if (t !== undefined) { const v = new Vec3(t); p[P.TARGET] = v.x; p[P.TARGET + 1] = v.y; p[P.TARGET + 2] = v.z }
+    rig.ikSet(this._ik, p)
+    rig.ikNodes(this._ik, targetNode, 0, 0)
+  }
+}
+
+/** Inverse kinematics aspects — attach to bones (see file header). */
+export const IK = { TwoBone, LookAt }
+export type IKTwoBone = TwoBone
+export type IKLookAt = LookAt

package/src/gl/{Locomotion.ts → animation/Locomotion.ts}

@@ -27,13 +27,13 @@
 // how fast the gait moves, where its foot contacts fall), so nothing here is a hand-measured table.
 // Give `angle` / `speed` only to override a measurement.
 
-import { Aspect } from "../core/Aspect"
-import { Vec3, cx, cz, type Vec3Like } from "../math/vec"
-import { Animator } from "./animation/Animator"
-import type { FeetOptions } from "./animation/Feet"
-import type { WarpOptions } from "./animation/Warp"
-import { CharacterController } from "./CharacterController"
-import type { Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import { Vec3, cx, cz, type Vec3Like } from "../../math/vec"
+import { Animator } from "./Animator"
+import type { FeetOptions } from "./Feet"
+import type { WarpOptions } from "./Warp"
+import { CharacterController } from "../physics/CharacterController"
+import type { Node } from "../Node"
 
 /** How fast the character wants to go: the gait picks its clips and its speed. */
 export type Gait = "walk" | "run" | "sprint"

package/src/gl/animation/Playback.ts

@@ -1,8 +1,9 @@
 // Playback — the handle `play()` returns (docs/animator-plan.md). Thenable: `await anim.play('slash')`
-// resolves at the clip's HAND-OVER — where its fade-back starts (`end − fadeOut`; the end when there
-// is no fadeOut) — with `true`; `false` when it was cut short (replaced / stopped). What
-// you call right after the await is what the clip fades into: `anim.play(next)` (a chained one-shot,
-// crossfaded), `anim.playLoop(next)` — nothing = back to the loop (or hold, on a layer without one).
+// resolves at the clip's HAND-OVER — its end (the `end` of its window) — with `true`; `false` when it
+// was cut short (replaced / stopped). What you call right after the await is what its last pose
+// transitions into: `anim.play(next)` (a chained one-shot), `anim.playLoop(next)` — nothing = back to
+// the loop over `fadeOut` (or hold, on a layer without one). A cancel window is game logic (a clip
+// event, `progress`, `busy`), not a fade: play the next clip whenever the game says so.
 // Returning one from an `async` function flattens it into `Promise<boolean>` — return `p.done` (or
 // make the function sync) when the caller needs the handle.
 

package/src/gl/animation/Warp.ts

@@ -2,7 +2,9 @@
 // before the feet (docs/animation-v2-plan.md §2.7). `stride` scales each leg's step to the speed the body
 // really travels at (a walk played at 1.9 m/s stops skating); `orientation` turns the lower body toward
 // where the body really goes while the spine counter-turns (arcs and strafing without a clip per angle).
-// Both need the body's motion, which a `Locomotion` feeds every frame; without one leave it off. Off by
+// Both need the body's motion — a `Locomotion` feeds it every frame, or `anim.motion = velocity` when the
+// gait is driven by hand; without either leave it off — and the CLIP's motion: its root motion, or for an
+// in-place loop the pace its pack declared (`lecodes.velocity` in the GLB animation's extras). Off by
 // default. `step` is the STEP WARP: stride / lift / pitch / slope dials solved in the knee hinge plane.
 //
 //   model.anim.warp.set(true)                                       // both, with the defaults
@@ -16,7 +18,8 @@ import type { Core } from "./core"
 export type WarpOptions = {
   /** Fit the stride to the speed the body actually travels at. `[min, max]` clamps the scale (default
    *  0.85…1.2). A CORRECTION: a pack whose takes already read right at the speeds it is played at wants
-   *  none of this; open the range for a pack that must cover speeds it was never recorded at. */
+   *  none of this; open the range for a pack that must cover speeds it was never recorded at. The clip's
+   *  own speed is its root motion — an in-place loop takes part only with a declared pace (see above). */
   stride?: boolean | [number, number]
   /** Turn the lower body toward where the body really travels; a number caps the turn in degrees
    *  (default 20). The whole twist lives in one joint: a few degrees read as a lean, a lot as a broken

package/src/gl/animation/core.ts

@@ -25,15 +25,24 @@ export type PlayOptions = {
   fade?: number
   /** Transition seconds for the way in only (overrides `fade`). */
   fadeIn?: number
-  /** 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. */
+  /** One-shots: the transition BACK to the loop after the end (overrides `fade`; `0` = cut at the end).
+   *  The clip plays to its last frame; the loop then takes over and the difference between the two poses
+   *  (and their velocities) decays over this time, so no part of the clip is cut — to play less of it,
+   *  give it an `end`. 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
   /** Rewind even if the clip is already playing (default: rewind only if it isn't). */
   restart?: boolean
+  /** Play a WINDOW of the clip, seconds of the clip: enter at `start` (default 0; only when the play
+   *  rewinds — see `restart`) and treat `end` (default the clip's end) as the end — the hand-over fires
+   *  there, the last frame held there, events beyond it never fire. Only the swing of a longer take, the
+   *  wind-up without the recovery. A window that lives in the clip table belongs in
+   *  `AnimationClip.from(clip, { from, to })` instead. Not combined with `phase`. Hosts without the
+   *  window play the whole clip. */
+  start?: number
+  end?: number
   /** Enter the clip at a point in the GAIT CYCLE instead of at its start: `'match'` = the phase the
    *  layer shows right now (the walk's left foot is down → the turn clip starts where its left foot
    *  is down too, so nothing slides), or a number 0–1. Clips without a gait cycle ignore it. */
@@ -293,6 +302,12 @@ export class Core {
   ensure(): boolean {
     if (this.id) return true
     if (this.embedded().length === 0 && this.table.size === 0) { console.warn(`Animator: no clips on ${this.node.name || "the node"} — nothing to play`); return false }
+    return this.ensureRig()
+  }
+  /** The native animator for the RIG alone — an IK chain or a socket on a model that has no clips
+   *  still needs the joint tree described to the engine. False = no transform hierarchy (warned). */
+  ensureRig(): boolean {
+    if (this.id) return true
     ensureEvents()
     this.id = _creator.animatorCreate(this.node.id)
     if (!this.id) { console.warn("Animator: node has no transform hierarchy"); return false }
@@ -303,6 +318,7 @@ export class Core {
     if (this._feetParams && _creator.animatorSetFeetParams) _creator.animatorSetFeetParams(this.id, this._feetParams)
     if (this.speed !== 1) _creator.animatorSetGlobal(this.id, this.speed, false)
     for (const L of this.layers) if (L.index > 0) this.pushLayer(L)
+    for (const s of this._sockets.values()) this.pushSocket(s)
     return true
   }
   destroy(): void {
@@ -378,6 +394,11 @@ export class Core {
     s.playback = rec
     _creator.animatorPlay(this.id, s.slot, false, o.speed ?? 1, fadeIn, fadeOut, o.restart ?? false)
     if (o.turn !== undefined) _creator.animatorSlotSetTurn?.(this.id, s.slot, o.turn * Math.PI / 180, true)
+    if (o.start !== undefined || o.end !== undefined) {
+      const st = Math.max(0, o.start ?? 0), en = o.end === undefined ? -1 : Math.min(o.end, clip.duration)
+      if (en >= 0 && en <= st) console.warn(`Animator: '${name}' window ${st}–${o.end} is empty (${clip.duration.toFixed(2)}s clip)`)
+      _creator.animatorSlotSetWindow?.(this.id, s.slot, st, en)
+    }
     if (phase !== undefined) _creator.animatorSeekPhase(this.id, s.slot, phase)
     return new Playback(rec, this)
   }
@@ -671,6 +692,11 @@ export class Core {
     this._warp = params
     if (this.id) _creator.animatorSetWarpParams(this.id, params)
   }
+  /** The body's world velocity this frame (m/s) — the game side of the stride / orientation fit. Nothing
+   *  to feed before the animator exists; hosts without the warp stage have no method. */
+  setMotion(vx: number, vy: number, vz: number): void {
+    if (this.id && _creator.animatorSetMotion) _creator.animatorSetMotion(this.id, vx, vy, vz)
+  }
   /** The feet stage (lock / ground IK), as the engine's fixed-order parameter array. */
   private _feetParams?: Float32Array
   setFeetParams(params: Float32Array): void {
@@ -682,6 +708,41 @@ export class Core {
   footState(side: 0 | 1, out: Float32Array): boolean {
     return this.id !== 0 && _creator.animatorFootState !== undefined && _creator.animatorFootState(this.id, side, out)
   }
+  // ---- IK chains + sockets (creator-anim anchors.cpp; the aspects in IK.ts) ----
+  // Hosts without the chains (an engine predating them) get a warning once and inert chains.
+  private static _warnedIk = false
+  private hasIk(): boolean {
+    if (_creator.animatorIkCreate) return true
+    if (!Core._warnedIk) { Core._warnedIk = true; console.warn("IK: this host has no IK chains (engine predates them) — chains and sockets are inert") }
+    return false
+  }
+  /** A chain ending in `endEntity` (kind 0 two-bone: the bone, its parent, its grandparent; 1 look-at). 0 = none. */
+  ikCreate(kind: 0 | 1, endEntity: number): number {
+    if (!this.ensureRig() || !this.hasIk()) return 0
+    return _creator.animatorIkCreate!(this.id, kind, endEntity)
+  }
+  ikDestroy(ik: number): void { if (this.id && _creator.animatorIkDestroy) _creator.animatorIkDestroy(this.id, ik) }
+  ikSet(ik: number, params: Float32Array): void { if (this.id && _creator.animatorIkSet) _creator.animatorIkSet(this.id, ik, params) }
+  ikNodes(ik: number, target: number, pole: number, rotation: number): void { if (this.id && _creator.animatorIkNodes) _creator.animatorIkNodes(this.id, ik, target, pole, rotation) }
+  ikAnchor(ik: number, socket: string): void { if (this.id && _creator.animatorIkAnchor) _creator.animatorIkAnchor(this.id, ik, socket) }
+  ikState(ik: number, out: Float32Array): boolean { return this.id !== 0 && _creator.animatorIkState !== undefined && _creator.animatorIkState(this.id, ik, out) }
+  /** Sockets by "set/name", replayed when the animator is (re)created. */
+  private readonly _sockets = new Map<string, { set: string, name: string, joint: number, node: number, trs: Float32Array | null }>()
+  /** Define a socket on joint `joint` (a bone's entity): a NODE socket (read by the engine every frame) or a
+   *  fixed TRS in the joint's space. set "" = the live set, any other name = a donor's. */
+  setSocket(set: string, name: string, joint: number, node: number, trs: Float32Array | null): void {
+    const rec = { set, name, joint, node, trs }
+    this._sockets.set(`${set}/${name}`, rec)
+    if (this.ensureRig()) this.pushSocket(rec)
+  }
+  removeSocket(set: string, name: string): void {
+    this._sockets.delete(`${set}/${name}`)
+    if (this.id && _creator.animatorSetSocket) _creator.animatorSetSocket(this.id, set, name, 0, 0, null)
+  }
+  private pushSocket(s: { set: string, name: string, joint: number, node: number, trs: Float32Array | null }): void {
+    if (this.hasIk() && _creator.animatorSetSocket) _creator.animatorSetSocket(this.id, s.set, s.name, s.joint, s.node, s.trs)
+  }
+
   private readonly _steps = new Set<StepHandler>()
   onStepHandler(cb: StepHandler): void { this._steps.add(cb) }
   offStepHandler(cb: StepHandler): void { this._steps.delete(cb) }

package/src/gl/{AudioSource.ts → audio/AudioSource.ts}

@@ -11,13 +11,13 @@
 //
 // Without host audio the aspect is inert: `play` returns an inert Voice, nothing throws.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { audio, sourceParams, type PlaySoundOptions, type Rolloff } from "../audio/audio"
-import type { Sound } from "../audio/Sound"
-import { audioSupported } from "../audio/support"
-import type { Voice } from "../audio/Voice"
-import type { Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { audio, sourceParams, type PlaySoundOptions, type Rolloff } from "../../audio/audio"
+import type { Sound } from "../../audio/Sound"
+import { audioSupported } from "../../audio/support"
+import type { Voice } from "../../audio/Voice"
+import type { Node } from "../Node"
 
 export type AudioCone = {
   /** Degrees of full volume around the node's −Z. */

package/src/gl/{AudioZone.ts → audio/AudioZone.ts}

@@ -1,75 +1,75 @@
-// A reverb zone, as an aspect on a Node (docs/audio-plan.md §2): a box or sphere volume that
-// follows the node; while the listener is inside, the zone's reverb blends onto a bus (the bus's
-// own reverb outside it). Zones nest: the smallest one containing the listener wins. `blend` is
-// how many metres inside the border the crossfade takes — walking through a doorway is smooth.
-//
-//   new Node().aspect(AudioZone, { box: [6, 2.5, 6], reverb: 'hall', blend: 2 })
-//   corridor.aspect(Shape, { box: [1, 1.5, 8] }).aspect(AudioZone, { reverb: 'bathroom' })  // the Shape's box
-//
-// Sizes follow Shape's convention: `box` = HALF-extents, `sphere` = radius, in the node's local
-// units (the node's scale applies). Without host audio the aspect is inert.
-
-import { Aspect } from "../core/Aspect"
-import { reverbBlock, type ReverbParams, type ReverbPreset } from "../audio/Bus"
-import { audio } from "../audio/audio"
-import { audioSupported } from "../audio/support"
-import { cx, cy, cz, type Vec3Like } from "../math/vec"
-import type { Node } from "./Node"
-import { Shape } from "./Shape"
-
-export class AudioZone extends Aspect<"audioZone", Node> {
-  static readonly aspect = "audioZone"
-
-  private _box: Vec3Like | null = null
-  private _sphere: number | null = null
-  private _reverb: ReverbPreset | ReverbParams = "room"
-  private _blend = 1
-  private _bus = "sfx"
-  /** @internal engine zone id. */
-  _id = 0
-  /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
-  get id(): number { return this._id }
-
-  /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
-  get box(): Vec3Like | null { return this._box }
-  set box(v: Vec3Like | null) { this._box = v; if (v) this._sphere = null; this._push() }
-  /** Radius; falls back to the node's Shape sphere. */
-  get sphere(): number | null { return this._sphere }
-  set sphere(v: number | null) { this._sphere = v; if (v !== null) this._box = null; this._push() }
-  /** A preset name or explicit params (see Bus.reverb). */
-  get reverb(): ReverbPreset | ReverbParams { return this._reverb }
-  set reverb(v: ReverbPreset | ReverbParams) { this._reverb = v; this._push() }
-  /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
-  get blend(): number { return this._blend }
-  set blend(v: number) { this._blend = v; this._push() }
-  /** The bus the zone's reverb rides on. Default `sfx`. */
-  get bus(): string { return this._bus }
-  set bus(v: string) { this._bus = v; this._push() }
-
-  onAttach(): void {
-    if (!audioSupported) return
-    this._id = _creatorAudio.createZone()
-    if (!this._id) return
-    _creatorAudio.attachZone(this._id, this.node.id)
-    this._push()
-  }
-
-  onDetach(): void {
-    if (this._id && audioSupported) _creatorAudio.destroyZone(this._id)
-    this._id = 0
-  }
-
-  private _push(): void {
-    if (!this._id || !audioSupported) return
-    let box = this._box, sphere = this._sphere
-    if (!box && sphere === null) {
-      const shape = this.node.get(Shape)
-      if (shape?.sphere !== undefined) sphere = shape.sphere
-      else if (shape?.box) box = shape.box
-    }
-    const dims = sphere !== null
-      ? new Float32Array([ sphere * 2, sphere * 2, sphere * 2 ])
-      : new Float32Array(box ? [ cx(box) * 2, cy(box) * 2, cz(box) * 2 ] : [ 2, 2, 2 ])
-    _creatorAudio.setZone(this._id, sphere !== null ? 1 : 0, dims, this._blend, audio._busId(this._bus), reverbBlock(this._reverb))
-  }
-}
+// A reverb zone, as an aspect on a Node (docs/audio-plan.md §2): a box or sphere volume that
+// follows the node; while the listener is inside, the zone's reverb blends onto a bus (the bus's
+// own reverb outside it). Zones nest: the smallest one containing the listener wins. `blend` is
+// how many metres inside the border the crossfade takes — walking through a doorway is smooth.
+//
+//   new Node().aspect(AudioZone, { box: [6, 2.5, 6], reverb: 'hall', blend: 2 })
+//   corridor.aspect(Shape, { box: [1, 1.5, 8] }).aspect(AudioZone, { reverb: 'bathroom' })  // the Shape's box
+//
+// Sizes follow Shape's convention: `box` = HALF-extents, `sphere` = radius, in the node's local
+// units (the node's scale applies). Without host audio the aspect is inert.
+
+import { Aspect } from "../../core/Aspect"
+import { reverbBlock, type ReverbParams, type ReverbPreset } from "../../audio/Bus"
+import { audio } from "../../audio/audio"
+import { audioSupported } from "../../audio/support"
+import { cx, cy, cz, type Vec3Like } from "../../math/vec"
+import type { Node } from "../Node"
+import { Shape } from "../physics/Shape"
+
+export class AudioZone extends Aspect<"audioZone", Node> {
+  static readonly aspect = "audioZone"
+
+  private _box: Vec3Like | null = null
+  private _sphere: number | null = null
+  private _reverb: ReverbPreset | ReverbParams = "room"
+  private _blend = 1
+  private _bus = "sfx"
+  /** @internal engine zone id. */
+  _id = 0
+  /** The engine's zone id — what `audio.stats.listenerZone` reports while the listener is inside. */
+  get id(): number { return this._id }
+
+  /** Half-extents [hx, hy, hz]; falls back to the node's Shape box, then a 1 m cube. */
+  get box(): Vec3Like | null { return this._box }
+  set box(v: Vec3Like | null) { this._box = v; if (v) this._sphere = null; this._push() }
+  /** Radius; falls back to the node's Shape sphere. */
+  get sphere(): number | null { return this._sphere }
+  set sphere(v: number | null) { this._sphere = v; if (v !== null) this._box = null; this._push() }
+  /** A preset name or explicit params (see Bus.reverb). */
+  get reverb(): ReverbPreset | ReverbParams { return this._reverb }
+  set reverb(v: ReverbPreset | ReverbParams) { this._reverb = v; this._push() }
+  /** Crossfade depth in metres inside the border (0 = a hard edge). Default 1. */
+  get blend(): number { return this._blend }
+  set blend(v: number) { this._blend = v; this._push() }
+  /** The bus the zone's reverb rides on. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createZone()
+    if (!this._id) return
+    _creatorAudio.attachZone(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroyZone(this._id)
+    this._id = 0
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    let box = this._box, sphere = this._sphere
+    if (!box && sphere === null) {
+      const shape = this.node.get(Shape)
+      if (shape?.sphere !== undefined) sphere = shape.sphere
+      else if (shape?.box) box = shape.box
+    }
+    const dims = sphere !== null
+      ? new Float32Array([ sphere * 2, sphere * 2, sphere * 2 ])
+      : new Float32Array(box ? [ cx(box) * 2, cy(box) * 2, cz(box) * 2 ] : [ 2, 2, 2 ])
+    _creatorAudio.setZone(this._id, sphere !== null ? 1 : 0, dims, this._blend, audio._busId(this._bus), reverbBlock(this._reverb))
+  }
+}

package/src/gl/{SceneAudio.ts → audio/SceneAudio.ts}

@@ -3,8 +3,8 @@
 // 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"
+import { audioSupported } from "../../audio/support"
+import type { Node } from "../Node"
 
 export class SceneAudio {
   private _listener: Node | null = null

package/src/gl/{NavAgent.ts → nav/NavAgent.ts}

@@ -20,12 +20,12 @@
 // Without a loaded NavMesh the aspect is inert — `goTo` returns false, nothing throws — so a
 // project stays runnable on a host without navigation.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { CharacterController } from "./CharacterController"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { CharacterController } from "../physics/CharacterController"
 import { NavCrowd, NavMesh, NAV_AGENT, NAV_READ } from "./NavMesh"
-import type { Node } from "./Node"
+import type { Node } from "../Node"
 
 export type NavAgentState = "idle" | "moving" | "arrived" | "blocked" | "offmesh"
 export type NavAgentAvoidance = "off" | "low" | "medium" | "high"

package/src/gl/{NavMesh.ts → nav/NavMesh.ts}

@@ -18,14 +18,14 @@
 // (creator-nav) is the algorithms and the per-step hot path: ONE crowd update + ONE flat read per
 // fixed step for every agent in the scene (`NavCrowd`, a system the mesh attaches to its scene).
 
-import { fetch } from "../runtime/fetch"
-import { System } from "../core/Aspect"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { Geometry } from "./Geometry"
-import { Material } from "./Material"
-import { Mesh } from "./Mesh"
-import type { Node } from "./Node"
-import type { Scene } from "./Scene"
+import { fetch } from "../../runtime/fetch"
+import { System } from "../../core/Aspect"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { Geometry } from "../Geometry"
+import { Material } from "../Material"
+import { Mesh } from "../Mesh"
+import type { Node } from "../Node"
+import type { Scene } from "../Scene"
 import type { NavAgent } from "./NavAgent"
 
 // Fixed-order layouts — keep in step with creator-nav/creator-nav.h (CNAV_AGENT_* / CNAV_READ_*).

package/src/gl/{CharacterController.ts → physics/CharacterController.ts}

@@ -38,12 +38,12 @@
 // Note: it collides with solid bodies but PASSES THROUGH triggers, and (v1) is not itself detected by
 // triggers and isn't pointer-pickable while active.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import { Vec3, cx, cy, cz, type Vec2Like, type Vec3Like } from "../math/vec"
-import type { CompAxis, CompWriter } from "../core/compWrite"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import { Vec3, cx, cy, cz, type Vec2Like, type Vec3Like } from "../../math/vec"
+import type { CompAxis, CompWriter } from "../../core/compWrite"
 import { Shape } from "./Shape"
-import type { Node } from "./Node"
+import type { Node } from "../Node"
 
 /** Where the character's feet are, as reported by the solver after the last step. */
 export type GroundState = "ground" | "slope" | "unsupported" | "air"