@vgai/engine 0.2.0 → 0.3.0

package/src/audio/impacts.ts

@@ -1,212 +0,0 @@
-/**
- * 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/movement.ts

@@ -1,140 +0,0 @@
-/**
- * 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();
-    },
-  };
-}

package/src/audio/musical.ts

@@ -1,200 +0,0 @@
-/**
- * Musical sounds — rhythmic and melodic elements.
- *
- * bassPulse and arpeggio are continuous (play/stop).
- * stinger is one-shot.
- */
-
-/** Bass pulse — rhythmic low sine following a beat pattern. */
-export function bassPulse(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { frequency?: number; bpm?: number; volume?: number; pattern?: number[] },
-) {
-  const frequency = options?.frequency ?? 55;
-  const bpm = options?.bpm ?? 120;
-  const volume = options?.volume ?? 0.3;
-  const pattern = options?.pattern ?? [1, 0, 1, 0];
-  const beatInterval = 60 / bpm;
-
-  const out = ctx.createGain();
-  out.gain.value = volume;
-  out.connect(dest);
-
-  let osc: OscillatorNode | null = null;
-  let pulseGain: GainNode | null = null;
-  let timer: ReturnType<typeof setInterval> | null = null;
-  let step = 0;
-
-  return {
-    play() {
-      if (osc) return;
-      osc = ctx.createOscillator();
-      osc.type = 'sine';
-      osc.frequency.value = frequency;
-      pulseGain = ctx.createGain();
-      pulseGain.gain.value = 0;
-      osc.connect(pulseGain);
-      pulseGain.connect(out);
-      osc.start();
-      step = 0;
-
-      const tick = () => {
-        if (!pulseGain) return;
-        const beat = pattern[step % pattern.length]!;
-        const now = ctx.currentTime;
-        if (beat) {
-          pulseGain.gain.setValueAtTime(1, now);
-          pulseGain.gain.exponentialRampToValueAtTime(0.01, now + beatInterval * 0.8);
-        }
-        step++;
-      };
-
-      tick();
-      timer = setInterval(tick, beatInterval * 1000);
-    },
-    stop() {
-      if (timer) {
-        clearInterval(timer);
-        timer = null;
-      }
-      if (!osc) return;
-      const refs = { osc, pulseGain };
-      osc = null;
-      pulseGain = null;
-      setTimeout(() => {
-        try {
-          refs.osc.stop();
-        } catch {
-          /* already stopped */
-        }
-        refs.osc.disconnect();
-        refs.pulseGain?.disconnect();
-      }, 100);
-    },
-    dispose() {
-      if (timer) {
-        clearInterval(timer);
-        timer = null;
-      }
-      if (osc) {
-        try {
-          osc.stop();
-        } catch {
-          /* already stopped */
-        }
-        osc.disconnect();
-      }
-      pulseGain?.disconnect();
-      osc = null;
-      pulseGain = null;
-      out.disconnect();
-    },
-  };
-}
-
-/** Arpeggio — repeating note sequence. */
-export function arpeggio(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: {
-    notes?: number[];
-    bpm?: number;
-    waveform?: OscillatorType;
-    volume?: number;
-  },
-) {
-  const notes = options?.notes ?? [262, 330, 392, 523];
-  const bpm = options?.bpm ?? 140;
-  const waveform = options?.waveform ?? 'triangle';
-  const volume = options?.volume ?? 0.2;
-  const noteInterval = 60 / bpm;
-
-  const out = ctx.createGain();
-  out.gain.value = volume;
-  out.connect(dest);
-
-  let timer: ReturnType<typeof setInterval> | null = null;
-  let step = 0;
-
-  function playNote(freq: number) {
-    const now = ctx.currentTime;
-    const osc = ctx.createOscillator();
-    osc.type = waveform;
-    osc.frequency.value = freq;
-
-    const env = ctx.createGain();
-    env.gain.setValueAtTime(0.8, now);
-    env.gain.exponentialRampToValueAtTime(0.001, now + noteInterval * 0.9);
-
-    osc.connect(env);
-    env.connect(out);
-    osc.start(now);
-    osc.stop(now + noteInterval);
-  }
-
-  return {
-    play() {
-      if (timer) return;
-      step = 0;
-      const tick = () => {
-        playNote(notes[step % notes.length]!);
-        step++;
-      };
-      tick();
-      timer = setInterval(tick, noteInterval * 1000);
-    },
-    stop() {
-      if (timer) {
-        clearInterval(timer);
-        timer = null;
-      }
-    },
-    dispose() {
-      if (timer) {
-        clearInterval(timer);
-        timer = null;
-      }
-      out.disconnect();
-    },
-  };
-}
-
-/** Stinger — one-shot ascending note sequence for events. */
-export function stinger(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { notes?: number[]; volume?: number; tempo?: number },
-) {
-  const notes = options?.notes ?? [392, 494, 587, 784];
-  const volume = options?.volume ?? 0.3;
-  const tempo = options?.tempo ?? 0.12;
-
-  const out = ctx.createGain();
-  out.gain.value = volume;
-  out.connect(dest);
-
-  return {
-    play() {
-      const now = ctx.currentTime;
-      for (let i = 0; i < notes.length; i++) {
-        const t = now + i * tempo;
-        const osc = ctx.createOscillator();
-        osc.type = 'triangle';
-        osc.frequency.value = notes[i]!;
-
-        const env = ctx.createGain();
-        env.gain.setValueAtTime(0.8, t);
-        env.gain.exponentialRampToValueAtTime(0.001, t + tempo * 1.5);
-
-        osc.connect(env);
-        env.connect(out);
-        osc.start(t);
-        osc.stop(t + tempo * 1.5 + 0.01);
-      }
-    },
-    dispose() {
-      out.disconnect();
-    },
-  };
-}

package/src/audio/ui-sounds.ts

@@ -1,171 +0,0 @@
-/**
- * UI sounds — short tonal feedback for interface interactions.
- *
- * All one-shot: call play() to trigger, dispose() to clean up.
- */
-
-/** Click — short sine pip. */
-export function uiClick(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { pitch?: number; volume?: number },
-) {
-  const pitch = options?.pitch ?? 800;
-  const volume = options?.volume ?? 0.2;
-
-  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.value = pitch;
-
-      const env = ctx.createGain();
-      env.gain.setValueAtTime(1, now);
-      env.gain.exponentialRampToValueAtTime(0.001, now + 0.04);
-
-      osc.connect(env);
-      env.connect(out);
-      osc.start(now);
-      osc.stop(now + 0.05);
-    },
-    dispose() {
-      out.disconnect();
-    },
-  };
-}
-
-/** Hover — softer, higher sine pip. */
-export function uiHover(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { pitch?: number; volume?: number },
-) {
-  const pitch = options?.pitch ?? 1200;
-  const volume = options?.volume ?? 0.1;
-
-  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.value = pitch;
-
-      const env = ctx.createGain();
-      env.gain.setValueAtTime(1, now);
-      env.gain.exponentialRampToValueAtTime(0.001, now + 0.03);
-
-      osc.connect(env);
-      env.connect(out);
-      osc.start(now);
-      osc.stop(now + 0.04);
-    },
-    dispose() {
-      out.disconnect();
-    },
-  };
-}
-
-/** Success — two ascending tones (major third interval). */
-export function uiSuccess(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { pitch?: number; volume?: number },
-) {
-  const pitch = options?.pitch ?? 500;
-  const volume = options?.volume ?? 0.3;
-
-  const out = ctx.createGain();
-  out.gain.value = volume;
-  out.connect(dest);
-
-  return {
-    play() {
-      const now = ctx.currentTime;
-
-      // First note
-      const osc1 = ctx.createOscillator();
-      osc1.type = 'sine';
-      osc1.frequency.value = pitch;
-      const env1 = ctx.createGain();
-      env1.gain.setValueAtTime(1, now);
-      env1.gain.exponentialRampToValueAtTime(0.001, now + 0.15);
-      osc1.connect(env1);
-      env1.connect(out);
-      osc1.start(now);
-      osc1.stop(now + 0.16);
-
-      // Second note — major third above, delayed 0.1s
-      const osc2 = ctx.createOscillator();
-      osc2.type = 'sine';
-      osc2.frequency.value = pitch * (5 / 4);
-      const env2 = ctx.createGain();
-      env2.gain.setValueAtTime(0.001, now);
-      env2.gain.setValueAtTime(1, now + 0.1);
-      env2.gain.exponentialRampToValueAtTime(0.001, now + 0.25);
-      osc2.connect(env2);
-      env2.connect(out);
-      osc2.start(now);
-      osc2.stop(now + 0.26);
-    },
-    dispose() {
-      out.disconnect();
-    },
-  };
-}
-
-/** Error — two descending tones (minor second). */
-export function uiError(
-  ctx: AudioContext,
-  dest: AudioNode,
-  options?: { pitch?: number; volume?: number },
-) {
-  const pitch = options?.pitch ?? 400;
-  const volume = options?.volume ?? 0.3;
-
-  const out = ctx.createGain();
-  out.gain.value = volume;
-  out.connect(dest);
-
-  return {
-    play() {
-      const now = ctx.currentTime;
-
-      // First note
-      const osc1 = ctx.createOscillator();
-      osc1.type = 'sine';
-      osc1.frequency.value = pitch;
-      const env1 = ctx.createGain();
-      env1.gain.setValueAtTime(1, now);
-      env1.gain.exponentialRampToValueAtTime(0.001, now + 0.15);
-      osc1.connect(env1);
-      env1.connect(out);
-      osc1.start(now);
-      osc1.stop(now + 0.16);
-
-      // Second note — minor second below, delayed 0.1s
-      const osc2 = ctx.createOscillator();
-      osc2.type = 'sine';
-      osc2.frequency.value = pitch * 0.9;
-      const env2 = ctx.createGain();
-      env2.gain.setValueAtTime(0.001, now);
-      env2.gain.setValueAtTime(1, now + 0.1);
-      env2.gain.exponentialRampToValueAtTime(0.001, now + 0.25);
-      osc2.connect(env2);
-      env2.connect(out);
-      osc2.start(now);
-      osc2.stop(now + 0.26);
-    },
-    dispose() {
-      out.disconnect();
-    },
-  };
-}