@vgai/engine 0.2.0

package/src/audio/ambient.ts

@@ -0,0 +1,300 @@
+/**
+ * Ambient sounds — continuous environmental audio.
+ *
+ * Each returns play/stop/dispose. These are designed to loop indefinitely.
+ */
+
+function createNoiseBuffer(ctx: AudioContext, duration = 2): AudioBuffer {
+  const length = ctx.sampleRate * duration;
+  const buffer = ctx.createBuffer(1, length, ctx.sampleRate);
+  const data = buffer.getChannelData(0);
+  for (let i = 0; i < length; i++) data[i] = Math.random() * 2 - 1;
+  return buffer;
+}
+
+/** Wind — filtered noise with slow LFO modulation on cutoff frequency. */
+export function wind(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { volume?: number; speed?: number },
+) {
+  const volume = options?.volume ?? 0.15;
+  const speed = options?.speed ?? 0.3;
+  const noiseBuffer = createNoiseBuffer(ctx, 2);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  const filter = ctx.createBiquadFilter();
+  filter.type = 'lowpass';
+  filter.frequency.value = 500;
+  filter.connect(out);
+
+  // LFO modulates filter cutoff for "gusts"
+  const lfo = ctx.createOscillator();
+  lfo.type = 'sine';
+  lfo.frequency.value = speed;
+  const lfoGain = ctx.createGain();
+  lfoGain.gain.value = 300; // ±300 Hz modulation
+  lfo.connect(lfoGain);
+  lfoGain.connect(filter.frequency);
+
+  let src: AudioBufferSourceNode | null = null;
+  let lfoStarted = false;
+
+  return {
+    play() {
+      if (src) return;
+      src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+      src.loop = true;
+      src.connect(filter);
+      src.start();
+      if (!lfoStarted) {
+        lfo.start();
+        lfoStarted = true;
+      }
+    },
+    stop() {
+      if (!src) return;
+      const ref = src;
+      src = null;
+      try {
+        ref.stop();
+      } catch {
+        /* already stopped */
+      }
+      ref.disconnect();
+    },
+    dispose() {
+      if (src) {
+        try {
+          src.stop();
+        } catch {
+          /* already stopped */
+        }
+        src.disconnect();
+      }
+      try {
+        lfo.stop();
+      } catch {
+        /* already stopped */
+      }
+      lfo.disconnect();
+      lfoGain.disconnect();
+      filter.disconnect();
+      out.disconnect();
+    },
+  };
+}
+
+/** Rain — high-frequency filtered noise. */
+export function rain(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { volume?: number; intensity?: number },
+) {
+  const volume = options?.volume ?? 0.2;
+  const intensity = options?.intensity ?? 0.5;
+  const noiseBuffer = createNoiseBuffer(ctx, 2);
+
+  const out = ctx.createGain();
+  out.gain.value = 0.05 + intensity * volume;
+  out.connect(dest);
+
+  const hp = ctx.createBiquadFilter();
+  hp.type = 'highpass';
+  hp.frequency.value = 1000 + intensity * 3000;
+  hp.connect(out);
+
+  let src: AudioBufferSourceNode | null = null;
+
+  return {
+    play() {
+      if (src) return;
+      src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+      src.loop = true;
+      src.connect(hp);
+      src.start();
+    },
+    stop() {
+      if (!src) return;
+      const ref = src;
+      src = null;
+      try {
+        ref.stop();
+      } catch {
+        /* already stopped */
+      }
+      ref.disconnect();
+    },
+    dispose() {
+      if (src) {
+        try {
+          src.stop();
+        } catch {
+          /* already stopped */
+        }
+        src.disconnect();
+      }
+      hp.disconnect();
+      out.disconnect();
+    },
+  };
+}
+
+/** Hum — low continuous drone with optional harmonics. */
+export function hum(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { frequency?: number; volume?: number; harmonics?: number },
+) {
+  const frequency = options?.frequency ?? 60;
+  const volume = options?.volume ?? 0.1;
+  const harmonics = options?.harmonics ?? 2;
+
+  const out = ctx.createGain();
+  out.gain.value = 0;
+  out.connect(dest);
+
+  const oscillators: OscillatorNode[] = [];
+
+  return {
+    play() {
+      if (oscillators.length > 0) return;
+      for (let h = 0; h <= harmonics; h++) {
+        const osc = ctx.createOscillator();
+        osc.type = 'sine';
+        osc.frequency.value = frequency * (h + 1);
+        const gain = ctx.createGain();
+        // Each harmonic is quieter
+        gain.gain.value = 1 / (h + 1);
+        osc.connect(gain);
+        gain.connect(out);
+        osc.start();
+        oscillators.push(osc);
+      }
+      out.gain.setTargetAtTime(volume, ctx.currentTime, 0.1);
+    },
+    stop() {
+      out.gain.setTargetAtTime(0, ctx.currentTime, 0.1);
+      setTimeout(() => {
+        for (const osc of oscillators) {
+          try {
+            osc.stop();
+          } catch {
+            /* already stopped */
+          }
+          osc.disconnect();
+        }
+        oscillators.length = 0;
+      }, 300);
+    },
+    dispose() {
+      for (const osc of oscillators) {
+        try {
+          osc.stop();
+        } catch {
+          /* already stopped */
+        }
+        osc.disconnect();
+      }
+      oscillators.length = 0;
+      out.disconnect();
+    },
+  };
+}
+
+/** Nature — gentle noise base with random bird-like sine chirps. */
+export function nature(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { volume?: number; birdRate?: number },
+) {
+  const volume = options?.volume ?? 0.15;
+  const birdRate = options?.birdRate ?? 0.5;
+  const noiseBuffer = createNoiseBuffer(ctx, 2);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  const lp = ctx.createBiquadFilter();
+  lp.type = 'lowpass';
+  lp.frequency.value = 400;
+  lp.connect(out);
+
+  let src: AudioBufferSourceNode | null = null;
+  let birdInterval: ReturnType<typeof setInterval> | null = null;
+
+  function chirp() {
+    const now = ctx.currentTime;
+    const freq = 2000 + Math.random() * 2000;
+    const dur = 0.05 + Math.random() * 0.05;
+
+    const osc = ctx.createOscillator();
+    osc.type = 'sine';
+    osc.frequency.setValueAtTime(freq, now);
+    osc.frequency.exponentialRampToValueAtTime(freq * 1.3, now + dur * 0.5);
+    osc.frequency.exponentialRampToValueAtTime(freq * 0.8, now + dur);
+
+    const env = ctx.createGain();
+    env.gain.setValueAtTime(0.001, now);
+    env.gain.linearRampToValueAtTime(0.6, now + dur * 0.2);
+    env.gain.exponentialRampToValueAtTime(0.001, now + dur);
+
+    osc.connect(env);
+    env.connect(out);
+    osc.start(now);
+    osc.stop(now + dur + 0.01);
+  }
+
+  return {
+    play() {
+      if (src) return;
+      src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+      src.loop = true;
+      src.connect(lp);
+      src.start();
+
+      // Schedule random chirps
+      birdInterval = setInterval(() => {
+        if (Math.random() < birdRate) chirp();
+      }, 500);
+    },
+    stop() {
+      if (birdInterval) {
+        clearInterval(birdInterval);
+        birdInterval = null;
+      }
+      if (!src) return;
+      const ref = src;
+      src = null;
+      try {
+        ref.stop();
+      } catch {
+        /* already stopped */
+      }
+      ref.disconnect();
+    },
+    dispose() {
+      if (birdInterval) {
+        clearInterval(birdInterval);
+        birdInterval = null;
+      }
+      if (src) {
+        try {
+          src.stop();
+        } catch {
+          /* already stopped */
+        }
+        src.disconnect();
+      }
+      lp.disconnect();
+      out.disconnect();
+    },
+  };
+}

package/src/audio/impacts.ts

@@ -0,0 +1,212 @@
+/**
+ * Impact sounds — procedural one-shot sounds for collisions and events.
+ *
+ * All functions take a Web Audio `AudioContext` and a destination `AudioNode`
+ * (typically a bus gain from setup-audio). Returns `{ play(), dispose() }`.
+ */
+
+function createNoiseBuffer(ctx: AudioContext, duration = 1): AudioBuffer {
+  const length = ctx.sampleRate * duration;
+  const buffer = ctx.createBuffer(1, length, ctx.sampleRate);
+  const data = buffer.getChannelData(0);
+  for (let i = 0; i < length; i++) data[i] = Math.random() * 2 - 1;
+  return buffer;
+}
+
+/** Short percussive thud — noise burst through a bandpass filter. */
+export function hit(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number; duration?: number; brightness?: number },
+) {
+  const pitch = options?.pitch ?? 400;
+  const volume = options?.volume ?? 0.5;
+  const duration = options?.duration ?? 0.1;
+  const brightness = options?.brightness ?? 1;
+  const noiseBuffer = createNoiseBuffer(ctx, 0.5);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+
+      const filter = ctx.createBiquadFilter();
+      filter.type = 'bandpass';
+      filter.frequency.value = pitch;
+      filter.Q.value = brightness;
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(1, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + duration);
+
+      src.connect(filter);
+      filter.connect(env);
+      env.connect(out);
+      src.start(now);
+      src.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Ball-bounce ping — sine tone with quick pitch drop. */
+export function bounce(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number; duration?: number },
+) {
+  const pitch = options?.pitch ?? 300;
+  const volume = options?.volume ?? 0.3;
+  const duration = options?.duration ?? 0.15;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const osc = ctx.createOscillator();
+      osc.type = 'sine';
+      osc.frequency.setValueAtTime(pitch, now);
+      osc.frequency.exponentialRampToValueAtTime(pitch * 0.5, now + duration);
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(1, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + duration);
+
+      osc.connect(env);
+      env.connect(out);
+      osc.start(now);
+      osc.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Heavy crash — layered noise burst with lowpass sweep + low sine thud. */
+export function crash(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { volume?: number; duration?: number; lowFreq?: number },
+) {
+  const volume = options?.volume ?? 0.7;
+  const duration = options?.duration ?? 0.5;
+  const lowFreq = options?.lowFreq ?? 80;
+  const noiseBuffer = createNoiseBuffer(ctx, 1);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+
+      // Noise layer: lowpass sweep from bright to dark
+      const noiseSrc = ctx.createBufferSource();
+      noiseSrc.buffer = noiseBuffer;
+      const lp = ctx.createBiquadFilter();
+      lp.type = 'lowpass';
+      lp.frequency.setValueAtTime(4000, now);
+      lp.frequency.exponentialRampToValueAtTime(200, now + duration);
+      const noiseEnv = ctx.createGain();
+      noiseEnv.gain.setValueAtTime(0.7, now);
+      noiseEnv.gain.exponentialRampToValueAtTime(0.001, now + duration);
+      noiseSrc.connect(lp);
+      lp.connect(noiseEnv);
+      noiseEnv.connect(out);
+      noiseSrc.start(now);
+      noiseSrc.stop(now + duration + 0.01);
+
+      // Low thud layer
+      const thud = ctx.createOscillator();
+      thud.type = 'sine';
+      thud.frequency.value = lowFreq;
+      const thudEnv = ctx.createGain();
+      thudEnv.gain.setValueAtTime(0.8, now);
+      thudEnv.gain.exponentialRampToValueAtTime(0.001, now + duration * 0.7);
+      thud.connect(thudEnv);
+      thudEnv.connect(out);
+      thud.start(now);
+      thud.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Large explosion — heavy noise burst with sub-bass tail. */
+export function explosion(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { volume?: number; duration?: number; subFreq?: number },
+) {
+  const volume = options?.volume ?? 0.8;
+  const duration = options?.duration ?? 1.0;
+  const subFreq = options?.subFreq ?? 40;
+  const noiseBuffer = createNoiseBuffer(ctx, 2);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+
+      // Noise layer: wide lowpass sweep
+      const noiseSrc = ctx.createBufferSource();
+      noiseSrc.buffer = noiseBuffer;
+      const lp = ctx.createBiquadFilter();
+      lp.type = 'lowpass';
+      lp.frequency.setValueAtTime(6000, now);
+      lp.frequency.exponentialRampToValueAtTime(100, now + duration);
+      const noiseEnv = ctx.createGain();
+      noiseEnv.gain.setValueAtTime(1, now);
+      noiseEnv.gain.exponentialRampToValueAtTime(0.001, now + duration);
+      noiseSrc.connect(lp);
+      lp.connect(noiseEnv);
+      noiseEnv.connect(out);
+      noiseSrc.start(now);
+      noiseSrc.stop(now + duration + 0.01);
+
+      // Sub-bass layer
+      const sub = ctx.createOscillator();
+      sub.type = 'sine';
+      sub.frequency.value = subFreq;
+      const subEnv = ctx.createGain();
+      subEnv.gain.setValueAtTime(1, now);
+      subEnv.gain.exponentialRampToValueAtTime(0.001, now + duration * 0.8);
+      sub.connect(subEnv);
+      subEnv.connect(out);
+      sub.start(now);
+      sub.stop(now + duration + 0.01);
+
+      // Crunch layer: short sawtooth burst
+      const crunch = ctx.createOscillator();
+      crunch.type = 'sawtooth';
+      crunch.frequency.value = 60;
+      const crunchEnv = ctx.createGain();
+      crunchEnv.gain.setValueAtTime(0.5, now);
+      crunchEnv.gain.exponentialRampToValueAtTime(0.001, now + 0.15);
+      crunch.connect(crunchEnv);
+      crunchEnv.connect(out);
+      crunch.start(now);
+      crunch.stop(now + 0.2);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}

package/src/audio/index.ts

@@ -0,0 +1,7 @@
+export { hum, nature, rain, wind } from './ambient';
+export { bounce, crash, explosion, hit } from './impacts';
+export { footstep, jump, whoosh } from './movement';
+export { arpeggio, bassPulse, stinger } from './musical';
+export { uiClick, uiError, uiHover, uiSuccess } from './ui-sounds';
+export { brakeSqueal, engineDrone, tireSkid } from './vehicle';
+export { chargeUp, gunshot, laser } from './weapons';

package/src/audio/movement.ts

@@ -0,0 +1,140 @@
+/**
+ * Movement sounds — footsteps, whooshes, jumps.
+ *
+ * All one-shot: call play() to trigger, dispose() to clean up.
+ */
+
+function createNoiseBuffer(ctx: AudioContext, duration = 1): AudioBuffer {
+  const length = ctx.sampleRate * duration;
+  const buffer = ctx.createBuffer(1, length, ctx.sampleRate);
+  const data = buffer.getChannelData(0);
+  for (let i = 0; i < length; i++) data[i] = Math.random() * 2 - 1;
+  return buffer;
+}
+
+/** Footstep — filtered noise burst with random pitch variation per play(). */
+export function footstep(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number; variation?: number },
+) {
+  const pitch = options?.pitch ?? 250;
+  const volume = options?.volume ?? 0.3;
+  const variation = options?.variation ?? 0.2;
+  const noiseBuffer = createNoiseBuffer(ctx, 0.2);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+
+      const filter = ctx.createBiquadFilter();
+      filter.type = 'bandpass';
+      filter.frequency.value = pitch * (1 + (Math.random() - 0.5) * 2 * variation);
+      filter.Q.value = 2;
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(0, now);
+      env.gain.linearRampToValueAtTime(1, now + 0.007);
+      env.gain.exponentialRampToValueAtTime(0.001, now + 0.05);
+
+      src.connect(filter);
+      filter.connect(env);
+      env.connect(out);
+      src.start(now);
+      src.stop(now + 0.06);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Whoosh — bandpass noise sweep for fast-moving objects. */
+export function whoosh(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number; duration?: number; speed?: number },
+) {
+  const pitch = options?.pitch ?? 600;
+  const volume = options?.volume ?? 0.3;
+  const duration = options?.duration ?? 0.2;
+  const speed = options?.speed ?? 1.0;
+  const noiseBuffer = createNoiseBuffer(ctx, 0.5);
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const src = ctx.createBufferSource();
+      src.buffer = noiseBuffer;
+
+      const filter = ctx.createBiquadFilter();
+      filter.type = 'bandpass';
+      filter.Q.value = 2;
+      filter.frequency.setValueAtTime(pitch * speed * 2, now);
+      filter.frequency.exponentialRampToValueAtTime(Math.max(pitch * 0.5, 20), now + duration);
+
+      // Triangle envelope: fade in 30%, fade out 70%
+      const peak = duration * 0.3;
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(0.001, now);
+      env.gain.linearRampToValueAtTime(1, now + peak);
+      env.gain.exponentialRampToValueAtTime(0.001, now + duration);
+
+      src.connect(filter);
+      filter.connect(env);
+      env.connect(out);
+      src.start(now);
+      src.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}
+
+/** Jump — quick ascending triangle tone. */
+export function jump(
+  ctx: AudioContext,
+  dest: AudioNode,
+  options?: { pitch?: number; volume?: number; duration?: number },
+) {
+  const pitch = options?.pitch ?? 150;
+  const volume = options?.volume ?? 0.3;
+  const duration = options?.duration ?? 0.15;
+
+  const out = ctx.createGain();
+  out.gain.value = volume;
+  out.connect(dest);
+
+  return {
+    play() {
+      const now = ctx.currentTime;
+      const osc = ctx.createOscillator();
+      osc.type = 'triangle';
+      osc.frequency.setValueAtTime(pitch, now);
+      osc.frequency.exponentialRampToValueAtTime(pitch * 2, now + duration);
+
+      const env = ctx.createGain();
+      env.gain.setValueAtTime(0.8, now);
+      env.gain.exponentialRampToValueAtTime(0.001, now + duration);
+
+      osc.connect(env);
+      env.connect(out);
+      osc.start(now);
+      osc.stop(now + duration + 0.01);
+    },
+    dispose() {
+      out.disconnect();
+    },
+  };
+}