lecodes-sdk 0.19.2 → 0.20.2

package/package.json

@@ -33,7 +33,7 @@
     "typescript": "~5.8.3",
     "gl-matrix": "^3.4.4"
   },
-  "version": "0.19.2",
+  "version": "0.20.2",
   "files": [
     "src",
     "dist",

package/src/audio/Bus.ts

@@ -0,0 +1,102 @@
+// Mixer buses (docs/audio-plan.md §2): every voice plays through one. `master`, `sfx`, `music`,
+// `ui`, `voice` exist from the start; `audio.bus('footsteps')` creates one under master. A bus
+// carries an insert chain — low-pass → echo → reverb — set as plain values; the engine smooths
+// every change, so `bus.reverb = 'cave'` at a doorway does not click.
+//
+//   audio.bus('sfx').volume = 0.7
+//   audio.bus('sfx').reverb = 'hall'
+//   audio.bus('sfx').reverb = { roomSize: 0.8, damping: 0.3, mix: 0.25 }
+//   audio.bus('sfx').echo = { delay: 0.35, decay: 0.4, mix: 0.3 }
+//   audio.bus('sfx').lowpass = 1200            // Hz; null = off
+//   audio.master.muted = true
+
+import { audioSupported } from "./support"
+
+export type ReverbPreset = "room" | "hall" | "cave" | "arena" | "bathroom" | "outdoor"
+
+export type ReverbParams = {
+  /** 0 (a closet) … 1 (a cathedral). */
+  roomSize?: number
+  /** High-frequency loss per reflection, 0 … 1. */
+  damping?: number
+  /** Stereo width of the tail, 0 … 1. */
+  width?: number
+  /** Wet amount, 0 … 1. */
+  mix?: number
+  /** Seconds before the tail starts (a big hall: 0.02 … 0.05). */
+  preDelay?: number
+}
+
+export type EchoParams = {
+  /** Seconds between repeats (up to 2). */
+  delay?: number
+  /** Feedback, 0 … 0.95 — how many repeats survive. */
+  decay?: number
+  /** Wet amount, 0 … 1. */
+  mix?: number
+}
+
+export const REVERB_PRESETS: Record<ReverbPreset, Required<ReverbParams>> = {
+  room:     { roomSize: 0.45, damping: 0.6, width: 0.8, mix: 0.18, preDelay: 0.005 },
+  bathroom: { roomSize: 0.55, damping: 0.15, width: 0.6, mix: 0.35, preDelay: 0.002 },
+  hall:     { roomSize: 0.82, damping: 0.4, width: 1.0, mix: 0.3, preDelay: 0.025 },
+  cave:     { roomSize: 0.9, damping: 0.25, width: 1.0, mix: 0.45, preDelay: 0.04 },
+  arena:    { roomSize: 0.95, damping: 0.5, width: 1.0, mix: 0.3, preDelay: 0.06 },
+  outdoor:  { roomSize: 0.3, damping: 0.8, width: 1.0, mix: 0.06, preDelay: 0.0 },
+}
+
+/** @internal the engine's 5-float reverb block from a preset name or params. */
+export function reverbBlock(v: ReverbPreset | ReverbParams): Float32Array {
+  const p = typeof v === "string" ? REVERB_PRESETS[v] ?? REVERB_PRESETS.room : { ...REVERB_PRESETS.room, ...v }
+  return new Float32Array([ p.roomSize, p.damping, p.width, p.mix, p.preDelay ])
+}
+
+const FX_REVERB = 1, FX_ECHO = 2, FX_LOWPASS = 3
+
+export class Bus {
+  readonly name: string
+  /** @internal engine bus id (-1 when the host has no audio). */
+  readonly _id: number
+  private _volume = 1
+  private _muted = false
+  private _reverb: ReverbPreset | ReverbParams | null = null
+  private _echo: EchoParams | null = null
+  private _lowpass: number | null = null
+
+  /** @internal */
+  constructor(name: string, id: number) {
+    this.name = name
+    this._id = id
+  }
+
+  private get _live(): boolean { return audioSupported && this._id >= 0 }
+
+  get volume(): number { return this._volume }
+  set volume(v: number) { this._volume = v; if (this._live) _creatorAudio.setBusVolume(this._id, v) }
+  get muted(): boolean { return this._muted }
+  set muted(v: boolean) { this._muted = v; if (this._live) _creatorAudio.setBusMuted(this._id, v) }
+
+  /** A preset name, explicit params, or null (off). */
+  get reverb(): ReverbPreset | ReverbParams | null { return this._reverb }
+  set reverb(v: ReverbPreset | ReverbParams | null) {
+    this._reverb = v
+    if (this._live) _creatorAudio.setBusEffect(this._id, FX_REVERB, v === null ? new Float32Array(0) : reverbBlock(v))
+  }
+
+  get echo(): EchoParams | null { return this._echo }
+  set echo(v: EchoParams | null) {
+    this._echo = v
+    if (!this._live) return
+    _creatorAudio.setBusEffect(this._id, FX_ECHO, v === null ? new Float32Array(0) : new Float32Array([ v.delay ?? 0.3, v.decay ?? 0.4, v.mix ?? 0.3 ]))
+  }
+
+  /** Low-pass cutoff in Hz (20 … 20000), null = off. */
+  get lowpass(): number | null { return this._lowpass }
+  set lowpass(v: number | null) {
+    this._lowpass = v
+    if (this._live) _creatorAudio.setBusEffect(this._id, FX_LOWPASS, v === null ? new Float32Array(0) : new Float32Array([ v ]))
+  }
+
+  /** Stop every voice on this bus (fade in seconds). */
+  stopAll(fade = 0): void { if (this._live) _creatorAudio.stopBus(this._id, fade) }
+}

package/src/audio/Sound.ts

@@ -0,0 +1,96 @@
+// A decoded clip (docs/audio-plan.md §2): the whole file fetched through the SDK's `fetch` (asset /
+// http / `id:` local) and decoded up front to PCM inside the engine, so playing it later costs
+// nothing — footsteps, shots, impacts, UI clicks. Long streams (music, voice-over) stay with
+// `AudioPlayer`, the platform-native player.
+//
+//   const shot  = await Sound.load(asset('./sfx/shot.ogg'))
+//   const steps = await Sound.load([asset('./sfx/step1.ogg'), asset('./sfx/step2.ogg')])  // variants
+//   audio.play(shot)                 // 2D
+//   gun.audio.play(shot)             // 3D, through an AudioSource aspect
+//
+// A Sound is APP-scoped (the menu and the level share one `shot`); the engine drops every clip
+// when `_creatorUtils.run()` swaps worlds. Without host support `load` resolves to a silent clip.
+
+import { fetch } from "../runtime/fetch"
+import { audioSupported } from "./support"
+
+export type SoundOptions = {
+  /** Keep two channels (2D playback of stereo material — music beds, ambiences). Default: the clip
+   *  is decoded MONO, which is what 3D spatialization needs and what SFX are anyway. */
+  stereo?: boolean
+}
+
+export class Sound {
+  /** The urls this clip was loaded from (one per variant). */
+  readonly urls: readonly string[]
+  /** @internal engine clip ids per variant (0 = silent). */
+  readonly _clips: number[]
+  private readonly _durations: number[]
+  private _channels = 1
+  private _disposed = false
+  private _last = -1
+
+  private constructor(urls: string[], clips: number[], durations: number[], channels: number) {
+    this.urls = urls
+    this._clips = clips
+    this._durations = durations
+    this._channels = channels
+  }
+
+  /** Fetch + decode. An array = variants: `play` picks a random one (never the same twice in a row
+   *  when there are 3 or more). Rejects with the failing url when a file cannot be decoded. */
+  static async load(src: string | string[], options: SoundOptions = {}): Promise<Sound> {
+    const urls = Array.isArray(src) ? src.slice() : [ src ]
+    if (urls.length === 0) throw new Error("Sound.load: no urls")
+    if (!audioSupported) return new Sound(urls, urls.map(() => 0), urls.map(() => 0), options.stereo ? 2 : 1)
+    const clips: number[] = []
+    const durations: number[] = []
+    let channels = 1
+    for (const url of urls) {
+      const resp = await fetch(url, { useOnce: true })
+      const systemId = (resp as unknown as { _id: number })._id
+      try {
+        const [ clipId, duration, ch ] = await new Promise<[number, number, number]>((resolve, reject) => {
+          _creatorAudio.loadClip(systemId, !!options.stereo,
+            (id, d, c) => resolve([ id, d, c ]),
+            (message) => reject(new Error(`Sound.load: ${url}: ${message}`)))
+        })
+        clips.push(clipId)
+        durations.push(duration)
+        channels = ch
+      } finally {
+        resp.dispose()
+      }
+    }
+    return new Sound(urls, clips, durations, channels)
+  }
+
+  /** Seconds (the first variant's). 0 for a silent clip. */
+  get duration(): number { return this._durations[0] ?? 0 }
+  /** Decoded channel count: 1, or 2 with `{ stereo: true }`. */
+  get channels(): number { return this._channels }
+  /** How many variants this clip carries. */
+  get variants(): number { return this._clips.length }
+  /** True when the engine has this clip (false on hosts without audio, or after dispose). */
+  get ready(): boolean { return !this._disposed && this._clips[0] > 0 }
+  get disposed(): boolean { return this._disposed }
+
+  /** @internal the clip id to play now (random variant, no immediate repeats). */
+  _pick(): number {
+    const n = this._clips.length
+    if (n <= 1) return this._clips[0] ?? 0
+    let i = Math.floor(Math.random() * n)
+    if (n >= 3 && i === this._last) i = (i + 1 + Math.floor(Math.random() * (n - 1))) % n
+    this._last = i
+    return this._clips[i]
+  }
+
+  /** Free the engine's PCM. Voices playing it stop at once. Idempotent. */
+  dispose(): void {
+    if (this._disposed) return
+    this._disposed = true
+    if (!audioSupported) return
+    for (const id of this._clips) if (id) _creatorAudio.releaseClip(id)
+    this._clips.fill(0)
+  }
+}

package/src/audio/Voice.ts

@@ -0,0 +1,102 @@
+// The handle `play` returns (docs/audio-plan.md §2): a token into the engine's voice pool. Most
+// callers drop it (fire and forget); a loop keeps it to change pitch / volume and to stop it. A
+// voice that ended (naturally, by stop, or stolen by a louder one) reads `playing === false`; every
+// setter on it is a silent no-op — the pool slot may already belong to a newer sound, and the
+// token's generation bits make that impossible to address.
+//
+//   const hum = car.audio.play(engineLoop, { loop: true })
+//   hum.pitch = 0.8 + rpm * 0.6
+//   hum.stop({ fade: 0.2 })
+//   shot.addEventListener('ended', () => …)   // registered with the engine only when asked for
+
+import { Emitter } from "../core/events"
+import { audioSupported } from "./support"
+
+export type VoiceEvents = {
+  /** The voice is over: the clip ended, `stop` completed, or the pool reused the slot. */
+  ended: () => void
+}
+
+const watched = new Map<number, Voice>()
+let endedInstalled = false
+
+function installEnded(): void {
+  if (endedInstalled || !audioSupported) return
+  endedInstalled = true
+  _creatorAudio.setOnEnded((tokens) => {
+    for (let i = 0; i < tokens.length; i++) {
+      const v = watched.get(tokens[i])
+      if (!v) continue
+      watched.delete(tokens[i])
+      v._ended()
+    }
+  })
+}
+
+export class Voice extends Emitter<VoiceEvents> {
+  /** @internal engine token, 0 = inert. */
+  readonly _tok: number
+  private _volume: number
+  private _pitch: number
+  private _pan: number
+  private _over = false
+  /** @internal a transient source (playAt) to destroy when the voice ends. */
+  _ownSource = 0
+
+  /** @internal */
+  constructor(token: number, volume: number, pitch: number, pan: number) {
+    super()
+    this._tok = token
+    this._volume = volume
+    this._pitch = pitch
+    this._pan = pan
+    if (token === 0) this._over = true
+  }
+
+  /** @internal watch the token so `ended` fires (also used by playAt's source cleanup). */
+  _watch(): void {
+    if (this._over || this._tok === 0) return
+    installEnded()
+    watched.set(this._tok, this)
+  }
+
+  addEventListener<K extends keyof VoiceEvents>(channel: K, callback: VoiceEvents[K]): void {
+    super.addEventListener(channel, callback)
+    if (channel === "ended") {
+      if (this._over) callback()
+      else this._watch()
+    }
+  }
+
+  /** @internal */
+  _ended(): void {
+    if (this._over) return
+    this._over = true
+    if (this._ownSource && audioSupported) { _creatorAudio.destroySource(this._ownSource); this._ownSource = 0 }
+    this.dispatch("ended")
+    this.clearListeners()
+  }
+
+  /** True while the engine plays this voice. */
+  get playing(): boolean {
+    if (this._over) return false
+    return audioSupported && _creatorAudio.voicePlaying(this._tok)
+  }
+  /** Seconds into the clip. */
+  get time(): number { return this._over || !audioSupported ? 0 : _creatorAudio.voiceTime(this._tok) }
+
+  get volume(): number { return this._volume }
+  set volume(v: number) { this._volume = v; if (!this._over && audioSupported) _creatorAudio.setVoiceVolume(this._tok, v) }
+  get pitch(): number { return this._pitch }
+  set pitch(v: number) { this._pitch = v; if (!this._over && audioSupported) _creatorAudio.setVoicePitch(this._tok, v) }
+  /** 2D voices only: -1 left … 1 right. */
+  get pan(): number { return this._pan }
+  set pan(v: number) { this._pan = v; if (!this._over && audioSupported) _creatorAudio.setVoicePan(this._tok, v) }
+
+  /** Stop now, or fade out over `fade` seconds. `ended` fires from the engine afterwards. */
+  stop(options: { fade?: number } = {}): void {
+    if (this._over || !audioSupported) return
+    _creatorAudio.stopVoice(this._tok, options.fade ?? 0)
+    if (this._ownSource || this.hasListeners("ended")) this._watch()
+  }
+}

package/src/audio/audio.ts

@@ -0,0 +1,161 @@
+// The `audio` global (docs/audio-plan.md §2): 2D playback, one-shots at a world point, buses.
+// 3D playback from a node goes through the AudioSource aspect (gl/AudioSource.ts), which calls
+// back into `_play` here with its source id; the listener lives on `scene.audio`.
+//
+//   audio.play(click, { bus: 'ui' })
+//   audio.playAt(impact, hit.point, { maxDistance: 25 })
+//   audio.bus('sfx').reverb = 'cave'
+//   audio.stopAll(0.2)
+
+import { cx, cy, cz, type Vec3Like } from "../math/vec"
+import { Bus } from "./Bus"
+import type { Sound } from "./Sound"
+import { audioSupported } from "./support"
+import { Voice } from "./Voice"
+
+export type PlaySoundOptions = {
+  /** 0 … 1 (and above, at your own risk). Default 1. */
+  volume?: number
+  /** Playback rate, 1 = unchanged. Default 1. */
+  pitch?: number
+  loop?: boolean
+  /** Bus name; default: the source's bus, `sfx` for 2D. */
+  bus?: string
+  /** Higher survives voice stealing when the pool is full. Default 0. */
+  priority?: number
+  /** Fade-in seconds. Default 0. */
+  fade?: number
+  /** Seconds into the clip to start from. */
+  startAt?: number
+  /** 2D only: -1 left … 1 right. */
+  pan?: number
+}
+
+export type Rolloff = "none" | "inverse" | "linear" | "exponential"
+
+/** Distance model of an AudioSource / playAt. */
+export type SpatialOptions = {
+  /** Metres of full volume around the source. Default 1. */
+  minDistance?: number
+  /** Metres beyond which the source no longer gets quieter. Default 50. */
+  maxDistance?: number
+  /** How volume falls between the two: `inverse` (default, physical), `linear`, `exponential`, `none`. */
+  rolloff?: Rolloff
+}
+
+export const ROLLOFF: Record<Rolloff, number> = { none: 0, inverse: 1, linear: 2, exponential: 3 }
+
+/** @internal CAUD_SRC_* order. */
+export function sourceParams(o: { minDistance: number, maxDistance: number, rolloff: Rolloff, coneInner: number, coneOuter: number, coneOuterGain: number, doppler: number, spread: number, occlusion: boolean, bus: number }): Float32Array {
+  return new Float32Array([ o.minDistance, o.maxDistance, ROLLOFF[o.rolloff] ?? 1, o.coneInner, o.coneOuter, o.coneOuterGain, o.doppler, o.spread, o.occlusion ? 1 : 0, o.bus ])
+}
+
+export type AudioStats = {
+  voicesPlaying: number
+  voicesMono: number
+  voicesStereo: number
+  /** Voices displaced (or dropped) by a fuller pool since start. */
+  stolen: number
+  clips: number
+  clipBytes: number
+  /** Master peak since the previous read, linear (1 = full scale). */
+  peak: number
+  sampleRate: number
+  /** The reverb zone the listener is in (0 = none) and how far inside (0 … 1). */
+  listenerZone: number
+  zoneBlend: number
+  /** Voices rendered binaurally right now (see `audio.hrtf`). */
+  hrtfVoices: number
+}
+
+const DEFAULT_BUSES = [ "master", "sfx", "music", "ui", "voice" ]
+
+class AudioSystem {
+  private readonly _buses = new Map<string, Bus>()
+  private _hrtf = false
+  private _hrtfVoices = 16
+  private _timeScalePitch = false
+
+  /** True when this host mixes sound. Everything below is a silent no-op otherwise. */
+  get supported(): boolean { return audioSupported }
+
+  /** HRTF binaural rendering (MIT KEMAR filters on the CPU): sounds get a real up / down / behind in
+   *  HEADPHONES. Off by default — on speakers it only smears the image. Applies to the `hrtfVoices`
+   *  nearest 3D voices; the rest keep plain panning. */
+  get hrtf(): boolean { return this._hrtf }
+  set hrtf(v: boolean) { this._hrtf = v; if (audioSupported) _creatorAudio.setHrtf(v, this._hrtfVoices) }
+  /** `Time.scale` also pitches the sfx bus: slow motion drops every effect's tone, like a film. Default
+   *  false — a pause only mutes sfx, the menu click keeps its pitch. */
+  get timeScalePitch(): boolean { return this._timeScalePitch }
+  set timeScalePitch(v: boolean) { this._timeScalePitch = v; if (audioSupported) _creatorAudio.setTimeScalePitch(v) }
+  /** How many voices get the (CPU-heavier) binaural path. Default 16. */
+  get hrtfVoices(): number { return this._hrtfVoices }
+  set hrtfVoices(n: number) { this._hrtfVoices = n; if (audioSupported && this._hrtf) _creatorAudio.setHrtf(true, n) }
+
+  /** A bus by name — the five built-ins, or an app-defined one created on first use. */
+  bus(name: string): Bus {
+    let b = this._buses.get(name)
+    if (b) return b
+    let id = -1
+    if (audioSupported) {
+      id = _creatorAudio.busId(name)
+      if (id < 0 && !DEFAULT_BUSES.includes(name)) id = _creatorAudio.createBus(name)
+      if (id < 0) console.warn(`audio.bus('${name}'): no free bus slot (16 max)`)
+    }
+    b = new Bus(name, id)
+    this._buses.set(name, b)
+    return b
+  }
+  get master(): Bus { return this.bus("master") }
+
+  /** @internal the bus id for an options object (or -1 = the source's). */
+  _busId(name: string | undefined): number {
+    if (name === undefined) return -1
+    return this.bus(name)._id
+  }
+
+  /** 2D playback (UI, stingers, music one-shots). */
+  play(sound: Sound, options: PlaySoundOptions = {}): Voice {
+    return this._play(sound, 0, options)
+  }
+
+  /** A one-shot at a world position with its own transient source — impacts, ricochets, debris.
+   *  The source is freed when the voice ends. */
+  playAt(sound: Sound, position: Vec3Like, options: PlaySoundOptions & SpatialOptions = {}): Voice {
+    if (!audioSupported || !sound.ready) return new Voice(0, options.volume ?? 1, options.pitch ?? 1, 0)
+    const src = _creatorAudio.createSource()
+    _creatorAudio.setSourceParams(src, sourceParams({
+      minDistance: options.minDistance ?? 1, maxDistance: options.maxDistance ?? 50, rolloff: options.rolloff ?? "inverse",
+      coneInner: 360, coneOuter: 360, coneOuterGain: 1, doppler: 0, spread: 0, occlusion: false, bus: this._busId(options.bus ?? "sfx"),
+    }))
+    _creatorAudio.setSourcePosition(src, cx(position), cy(position), cz(position))
+    const v = this._play(sound, src, options)
+    if (v._tok === 0) { _creatorAudio.destroySource(src); return v }
+    v._ownSource = src
+    v._watch()
+    return v
+  }
+
+  /** @internal shared by play / playAt / AudioSource.play. */
+  _play(sound: Sound, sourceId: number, options: PlaySoundOptions): Voice {
+    const volume = options.volume ?? 1, pitch = options.pitch ?? 1, pan = options.pan ?? 0
+    if (!audioSupported || !sound.ready) return new Voice(0, volume, pitch, pan)
+    const clip = sound._pick()
+    if (clip === 0) return new Voice(0, volume, pitch, pan)
+    const tok = _creatorAudio.play(clip, sourceId, this._busId(options.bus), volume, pitch, !!options.loop,
+      options.priority ?? 0, options.fade ?? 0, options.startAt ?? 0, pan)
+    return new Voice(tok, volume, pitch, pan)
+  }
+
+  /** Stop every voice on every bus (fade in seconds). */
+  stopAll(fade = 0): void { if (audioSupported) _creatorAudio.stopAll(fade) }
+
+  /** Engine counters for a debug overlay or a perf log. */
+  get stats(): AudioStats {
+    const s = audioSupported ? _creatorAudio.stats() : new Float32Array(11)
+    return { voicesPlaying: s[0], voicesMono: s[1], voicesStereo: s[2], stolen: s[3], clips: s[4], clipBytes: s[5], peak: s[6], sampleRate: s[7], listenerZone: s[8], zoneBlend: s[9], hrtfVoices: s[10] ?? 0 }
+  }
+}
+
+export const audio = new AudioSystem()
+export type { AudioSystem }

package/src/audio/support.ts

@@ -0,0 +1,6 @@
+// Feature gate for the game audio system (docs/audio-plan.md). `_creatorAudio` is OPTIONAL as a
+// block: a host without it (or whose engine failed to open a device) makes every Sound silent and
+// every Voice inert — a project stays runnable, nothing throws.
+
+export const audioSupported: boolean =
+  typeof _creatorAudio !== "undefined" && !!_creatorAudio && typeof _creatorAudio.hasSupport === "function" && _creatorAudio.hasSupport()