lecodes-sdk 0.20.0 → 1.0.0

package/src/gl/audio/AudioSource.ts

@@ -0,0 +1,113 @@
+// A 3D sound emitter, as an aspect on a Node (docs/audio-plan.md §2). The engine follows the node's
+// world pose every frame (position, facing for the cone, velocity for doppler); voices played
+// through it are spatialized against the scene's listener (scene.audio.listener, the camera by
+// default). Parented, animated and physics-driven nodes just work.
+//
+//   const gun = new Node().aspect(AudioSource, { minDistance: 1, maxDistance: 40 })
+//   gun.audio.play(shot, { pitch: 0.95 + Math.random() * 0.1 })
+//   const hum = car.audio.play(engineLoop, { loop: true }); hum.pitch = 0.8 + rpm * 0.6
+//   speaker.aspect(AudioSource, { cone: { inner: 60, outer: 120, outerGain: 0.3 } })   // facing −Z
+//   enemy.aspect(AudioSource, { occlusion: true })   // a wall between it and the listener muffles it
+//
+// 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"
+
+export type AudioCone = {
+  /** Degrees of full volume around the node's −Z. */
+  inner: number
+  /** Degrees where the volume has fallen to `outerGain`. */
+  outer: number
+  /** Volume behind the source, 0 … 1. */
+  outerGain?: number
+}
+
+export class AudioSource extends Aspect<"audio", Node> {
+  static readonly aspect = "audio"
+
+  static fields: FieldMeta<AudioSource> = {
+    minDistance: { min: 0.05, max: 100, step: 0.05 },
+    maxDistance: { min: 0.5, max: 1000, step: 0.5 },
+    doppler: { min: 0, max: 1, step: 0.05 },
+    spread: { min: 0, max: 1, step: 0.05 },
+  }
+
+  private _minDistance = 1
+  private _maxDistance = 50
+  private _rolloff: Rolloff = "inverse"
+  private _cone: AudioCone | null = null
+  private _doppler = 0
+  private _spread = 0
+  private _occlusion = false
+  private _bus = "sfx"
+  /** @internal engine source id (0 = not attached / no audio). */
+  _id = 0
+
+  /** Metres of full volume around the node. Default 1. */
+  get minDistance(): number { return this._minDistance }
+  set minDistance(v: number) { this._minDistance = v; this._push() }
+  /** Metres beyond which the source no longer gets quieter. Default 50. */
+  get maxDistance(): number { return this._maxDistance }
+  set maxDistance(v: number) { this._maxDistance = v; this._push() }
+  /** `inverse` (default), `linear`, `exponential`, `none`. */
+  get rolloff(): Rolloff { return this._rolloff }
+  set rolloff(v: Rolloff) { this._rolloff = v; this._push() }
+  /** Directional source along the node's −Z; null = omnidirectional (default). */
+  get cone(): AudioCone | null { return this._cone }
+  set cone(v: AudioCone | null) { this._cone = v; this._push() }
+  /** Doppler amount 0 … 1 (0 = off, the default) — needs the node to actually move. */
+  get doppler(): number { return this._doppler }
+  set doppler(v: number) { this._doppler = v; this._push() }
+  /** 0 = pin-point panning (default) … 1 = the same on every speaker (a big, close source). */
+  get spread(): number { return this._spread }
+  set spread(v: number) { this._spread = v; this._push() }
+  /** The engine raycasts listener → source (against solid bodies) and muffles the voices when
+   *  something is in the way. Default false. */
+  get occlusion(): boolean { return this._occlusion }
+  set occlusion(v: boolean) { this._occlusion = v; this._push() }
+  /** Default bus for voices on this source. Default `sfx`. */
+  get bus(): string { return this._bus }
+  set bus(v: string) { this._bus = v; this._push() }
+
+  /** Live voices on this source. */
+  get voices(): number { return this._id && audioSupported ? _creatorAudio.sourceVoices(this._id) : 0 }
+
+  onAttach(): void {
+    if (!audioSupported) return
+    this._id = _creatorAudio.createSource()
+    if (!this._id) return
+    _creatorAudio.attachSource(this._id, this.node.id)
+    this._push()
+  }
+
+  onDetach(): void {
+    if (this._id && audioSupported) _creatorAudio.destroySource(this._id)
+    this._id = 0
+  }
+
+  /** Play a clip from this node. */
+  play(sound: Sound, options: PlaySoundOptions = {}): Voice {
+    return audio._play(sound, this._id, options)
+  }
+
+  /** Stop every voice on this source (fade in seconds). */
+  stopAll(fade = 0): void {
+    if (this._id && audioSupported) _creatorAudio.stopSource(this._id, fade)
+  }
+
+  private _push(): void {
+    if (!this._id || !audioSupported) return
+    const cone = this._cone
+    _creatorAudio.setSourceParams(this._id, sourceParams({
+      minDistance: this._minDistance, maxDistance: this._maxDistance, rolloff: this._rolloff,
+      coneInner: cone ? cone.inner : 360, coneOuter: cone ? cone.outer : 360, coneOuterGain: cone ? cone.outerGain ?? 0.25 : 1,
+      doppler: this._doppler, spread: this._spread, occlusion: this._occlusion, bus: audio._busId(this._bus),
+    }))
+  }
+}

package/src/gl/audio/AudioZone.ts

@@ -0,0 +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 "../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/audio/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/{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"

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

@@ -11,11 +11,11 @@
 // velocity / applyImpulse. Reading node.position is free (native already wrote it). A `position` write
 // is a TELEPORT that reaches the body (Shape routes it), which is how a kinematic body is placed too.
 
-import { Aspect } from "../core/Aspect"
-import type { FieldMeta } from "../core/fields"
-import type { CompAxis, CompWriter } from "../core/compWrite"
-import { Vec3, cx, cy, cz, type Vec3Like } from "../math/vec"
-import { nodeRegistry, type Node } from "./Node"
+import { Aspect } from "../../core/Aspect"
+import type { FieldMeta } from "../../core/fields"
+import type { CompAxis, CompWriter } from "../../core/compWrite"
+import { Vec3, cx, cy, cz, type Vec3Like } from "../../math/vec"
+import { nodeRegistry, type Node } from "../Node"
 import { Shape } from "./Shape"
 
 export type MotionType = "static" | "dynamic" | "kinematic"
@@ -95,6 +95,7 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
   }
 
   private _bodyId = 0
+  private static _refusedWarned = false
 
   onAttach(): void {
     if (!_creator.physicsHasSupport || !_creator.physicsHasSupport()) return
@@ -107,6 +108,12 @@ export class Physics extends Aspect<"physics", Node> implements CompWriter {
     }
     const shapeId = shape._claim() // drop the pick-only body; reuse its shape
     this._bodyId = _creator.physicsCreateBody(this.node.id, shapeId, MOTION[this.motion], this.mass, false, false)
+    // The engine refuses a body past its limit (4 096 unless configured) — silently, and a level that
+    // crosses it loses whatever loads LAST (the terrain, streamed in after the props): say so once.
+    if (!this._bodyId && shapeId && !Physics._refusedWarned) {
+      Physics._refusedWarned = true
+      console.warn(`Physics: the engine refused a body for "${this.node.name}" — the body limit is reached? Raise it before the level loads: Physics.configure({ maxBodies })`)
+    }
     // A fresh body already carries DEFAULT_FRICTION host-side, so only a NAMED surface has to
     // travel — the common case costs no bridge call at all.
     if (this._friction !== DEFAULT_FRICTION) _creator.physicsSetFriction?.(this._bodyId, this._friction)