cubeforge 0.4.8 → 0.4.9

package/dist/index.d.ts

@@ -13,7 +13,7 @@ import { AnimationClip } from '@cubeforge/gameplay';
 export { AISteering, AnimationClip, AnimationControllerResult, BindingControls, CharacterControls, CutsceneControls, CutsceneStep, DialogueControls, DialogueLine, DialogueScript, ForceControls, GameState as GameStateDefinition, GameStateMachineResult, HealthControls, HealthOptions, KinematicBodyControls, LevelTransitionControls, ObjectPool, PathfindingControls, PlatformerControllerOptions, RestartControls, SaveControls, SaveOptions, TopDownMovementOptions, TransitionOptions, TransitionType, TweenControls, useAISteering, useAnimationController, useCharacterController, useCutscene, useDamageZone, useDialogue, useDropThrough, useForces, useGameStateMachine, useGameStore, useHealth, useKinematicBody, useLevelTransition, useObjectPool, usePathfinding, usePersistedBindings, usePlatformerController, useRestart, useSave, useTopDownMovement, useTween } from '@cubeforge/gameplay';
 import { EngineState } from '@cubeforge/context';
 export { EngineState, useCircleEnter, useCircleExit, useCircleStay, useCollidingWith, useCollisionEnter, useCollisionExit, useCollisionStay, useTriggerEnter, useTriggerExit, useTriggerStay } from '@cubeforge/context';
-export { AudioGroup, SoundControls, SpatialSoundControls, SpatialSoundOptions, duck, getGroupVolume, getListenerPosition, setGroupMute, setGroupVolume, setListenerPosition, setMasterVolume, stopGroup, useSound, useSpatialSound } from '@cubeforge/audio';
+export { AudioGroup, MusicControls, MusicOptions, SoundControls, SoundOptions, SpatialSoundControls, SpatialSoundOptions, duck, getGroupVolume, getListenerPosition, getMasterVolume, setGroupMute, setGroupVolume, setGroupVolumeFaded, setListenerPosition, setMasterVolume, stopGroup, useMusic, useSound, useSpatialSound } from '@cubeforge/audio';
 export { DevToolsHandle } from '@cubeforge/devtools';
 
 interface GameControls {

package/dist/index.js

@@ -16723,12 +16723,24 @@ function getAudioCtx() {
   return _audioCtx;
 }
 var groupGainNodes = /* @__PURE__ */ new Map();
+var groupVolumes = /* @__PURE__ */ new Map();
+var groupMuted = /* @__PURE__ */ new Map();
+var groupSources = /* @__PURE__ */ new Map();
+function registerGroupSource(group, stopFn) {
+  let set = groupSources.get(group);
+  if (!set) {
+    set = /* @__PURE__ */ new Set();
+    groupSources.set(group, set);
+  }
+  set.add(stopFn);
+  return () => set.delete(stopFn);
+}
 function getGroupGainNode(group) {
   const existing = groupGainNodes.get(group);
   if (existing) return existing;
   const ctx = getAudioCtx();
   const gain = ctx.createGain();
-  gain.gain.value = 1;
+  gain.gain.value = groupVolumes.get(group) ?? 1;
   if (group === "master") {
     gain.connect(ctx.destination);
   } else {
@@ -16738,38 +16750,56 @@ function getGroupGainNode(group) {
   return gain;
 }
 function setGroupVolume(group, volume) {
+  const clamped = Math.max(0, Math.min(1, volume));
+  groupVolumes.set(group, clamped);
+  if (groupMuted.get(group)) return;
   const node = groupGainNodes.get(group);
-  if (node) node.gain.value = Math.max(0, Math.min(1, volume));
-  else {
-    getGroupGainNode(group).gain.value = Math.max(0, Math.min(1, volume));
-  }
+  if (node) node.gain.value = clamped;
+  else getGroupGainNode(group).gain.value = clamped;
 }
 function setMasterVolume(volume) {
-  getGroupGainNode("master").gain.value = Math.max(0, Math.min(1, volume));
+  const clamped = Math.max(0, Math.min(1, volume));
+  groupVolumes.set("master", clamped);
+  if (groupMuted.get("master")) return;
+  getGroupGainNode("master").gain.value = clamped;
 }
 function getGroupVolume(group) {
-  return groupGainNodes.get(group)?.gain.value ?? 1;
+  return groupVolumes.get(group) ?? 1;
+}
+function getMasterVolume() {
+  return getGroupVolume("master");
 }
 function setGroupMute(group, muted) {
+  groupMuted.set(group, muted);
   const node = getGroupGainNode(group);
-  node.gain.value = muted ? 0 : 1;
+  node.gain.value = muted ? 0 : groupVolumes.get(group) ?? 1;
 }
 function stopGroup(group) {
-  setGroupMute(group, true);
-  setTimeout(() => {
-    const node = groupGainNodes.get(group);
-    if (node) node.gain.value = 1;
-  }, 16);
+  const sources = groupSources.get(group);
+  if (sources) {
+    for (const stop of [...sources]) stop();
+    sources.clear();
+  }
+}
+function setGroupVolumeFaded(group, volume, duration) {
+  const clamped = Math.max(0, Math.min(1, volume));
+  groupVolumes.set(group, clamped);
+  const node = getGroupGainNode(group);
+  const ctx = getAudioCtx();
+  const now = ctx.currentTime;
+  node.gain.cancelScheduledValues(now);
+  node.gain.setValueAtTime(node.gain.value, now);
+  node.gain.linearRampToValueAtTime(clamped, now + Math.max(0, duration));
 }
 function duck(group, amount, duration) {
   const node = getGroupGainNode(group);
   const ctx = getAudioCtx();
   const now = ctx.currentTime;
-  const prev = node.gain.value;
+  const prev = groupVolumes.get(group) ?? 1;
   node.gain.cancelScheduledValues(now);
-  node.gain.setValueAtTime(prev, now);
-  node.gain.linearRampToValueAtTime(amount, now + 0.05);
-  node.gain.setValueAtTime(amount, now + duration);
+  node.gain.setValueAtTime(node.gain.value, now);
+  node.gain.linearRampToValueAtTime(Math.max(0, Math.min(1, amount)), now + 0.05);
+  node.gain.setValueAtTime(Math.max(0, Math.min(1, amount)), now + duration);
   node.gain.linearRampToValueAtTime(prev, now + duration + 0.2);
 }
 
@@ -16817,7 +16847,10 @@ function useSound(src, opts = {}) {
   const volRef = useRef26(opts.volume ?? 1);
   const loopRef = useRef26(opts.loop ?? false);
   const groupRef = useRef26(opts.group);
+  const rateRef = useRef26(opts.playbackRate ?? 1);
+  const onEndedRef = useRef26(opts.onEnded);
   const maxInstances = opts.maxInstances ?? 4;
+  onEndedRef.current = opts.onEnded;
   useEffect58(() => {
     let cancelled = false;
     loadBuffer(src).then((buf) => {
@@ -16831,6 +16864,7 @@ function useSound(src, opts = {}) {
         } catch {
         }
         entry.gain.disconnect();
+        entry.unregister?.();
       }
       activeInstances.current = [];
       bufferRef.current = null;
@@ -16839,6 +16873,7 @@ function useSound(src, opts = {}) {
   }, [src]);
   const getDestination = () => groupRef.current ? getGroupGainNode(groupRef.current) : getGroupGainNode("master");
   const removeInstance = (entry) => {
+    entry.unregister?.();
     const idx = activeInstances.current.indexOf(entry);
     if (idx !== -1) activeInstances.current.splice(idx, 1);
   };
@@ -16846,39 +16881,56 @@ function useSound(src, opts = {}) {
     while (activeInstances.current.length >= maxInstances) {
       const oldest = activeInstances.current.shift();
       if (oldest) {
+        oldest.source.onended = null;
         try {
           oldest.source.stop();
         } catch {
         }
         oldest.gain.disconnect();
+        oldest.unregister?.();
       }
     }
   };
-  const play = (playOpts) => {
-    if (!bufferRef.current) return;
+  const spawnEntry = (buf, startGain) => {
     const ctx = getAudioCtx();
-    if (ctx.state === "suspended") void ctx.resume();
-    stopOldestIfNeeded();
-    const entry = createPoolEntry(ctx, bufferRef.current, loopRef.current, volRef.current, getDestination());
+    const dest = getDestination();
+    const entry = createPoolEntry(ctx, buf, loopRef.current, startGain, dest);
+    entry.source.playbackRate.value = rateRef.current;
+    const group = groupRef.current ?? "master";
+    entry.unregister = registerGroupSource(group, () => {
+      try {
+        entry.source.stop();
+      } catch {
+      }
+      removeInstance(entry);
+      entry.gain.disconnect();
+    });
     entry.source.onended = () => {
       removeInstance(entry);
       entry.gain.disconnect();
+      onEndedRef.current?.();
     };
+    return entry;
+  };
+  const play = (playOpts) => {
+    if (!bufferRef.current) return;
+    const ctx = getAudioCtx();
+    if (ctx.state === "suspended") void ctx.resume();
+    stopOldestIfNeeded();
+    const entry = spawnEntry(bufferRef.current, volRef.current);
     const delay = playOpts?.delay;
-    if (delay && delay > 0) {
-      entry.source.start(ctx.currentTime + delay);
-    } else {
-      entry.source.start();
-    }
+    entry.source.start(delay && delay > 0 ? ctx.currentTime + delay : void 0);
     activeInstances.current.push(entry);
   };
   const stop = () => {
-    for (const entry of activeInstances.current) {
+    for (const entry of [...activeInstances.current]) {
+      entry.source.onended = null;
       try {
         entry.source.stop();
       } catch {
       }
       entry.gain.disconnect();
+      entry.unregister?.();
     }
     activeInstances.current = [];
   };
@@ -16888,18 +16940,20 @@ function useSound(src, opts = {}) {
       entry.gain.gain.value = v;
     }
   };
+  const setPlaybackRate = (rate) => {
+    rateRef.current = rate;
+    for (const entry of activeInstances.current) {
+      entry.source.playbackRate.value = rate;
+    }
+  };
   const fadeIn = (duration) => {
     if (!bufferRef.current) return;
     const ctx = getAudioCtx();
     if (ctx.state === "suspended") void ctx.resume();
     stop();
-    const entry = createPoolEntry(ctx, bufferRef.current, loopRef.current, 0, getDestination());
+    const entry = spawnEntry(bufferRef.current, 0);
     entry.gain.gain.setValueAtTime(0, ctx.currentTime);
     entry.gain.gain.linearRampToValueAtTime(volRef.current, ctx.currentTime + duration);
-    entry.source.onended = () => {
-      removeInstance(entry);
-      entry.gain.disconnect();
-    };
     entry.source.start();
     activeInstances.current.push(entry);
   };
@@ -16930,19 +16984,26 @@ function useSound(src, opts = {}) {
       if (!buf) return;
       const ctx = getAudioCtx();
       if (ctx.state === "suspended") void ctx.resume();
-      const entry = createPoolEntry(ctx, buf, loopRef.current, 0, getDestination());
+      const entry = spawnEntry(buf, 0);
       entry.gain.gain.setValueAtTime(0, ctx.currentTime);
       entry.gain.gain.linearRampToValueAtTime(volRef.current, ctx.currentTime + duration);
-      entry.source.onended = () => {
-        removeInstance(entry);
-        entry.gain.disconnect();
-      };
       entry.source.start();
       activeInstances.current.push(entry);
       bufferRef.current = buf;
     }).catch(console.error);
   };
-  return { play, stop, setVolume, fadeIn, fadeOut, crossfadeTo };
+  return {
+    play,
+    stop,
+    setVolume,
+    setPlaybackRate,
+    fadeIn,
+    fadeOut,
+    crossfadeTo,
+    get isPlaying() {
+      return activeInstances.current.length > 0;
+    }
+  };
 }
 
 // ../../packages/audio/src/useSpatialSound.ts
@@ -17076,6 +17137,136 @@ function useSpatialSound(src, opts = {}) {
   return { play, stop, setPosition, setVolume };
 }
 
+// ../../packages/audio/src/useMusic.ts
+import { useEffect as useEffect60, useRef as useRef28 } from "react";
+var currentTrack = null;
+function stopTrack(track, fadeDuration) {
+  const ctx = getAudioCtx();
+  const now = ctx.currentTime;
+  track.gain.gain.cancelScheduledValues(now);
+  track.gain.gain.setValueAtTime(track.gain.gain.value, now);
+  if (fadeDuration > 0) {
+    track.gain.gain.linearRampToValueAtTime(0, now + fadeDuration);
+    setTimeout(
+      () => {
+        try {
+          track.source.stop();
+        } catch {
+        }
+        track.gain.disconnect();
+        track.unregister();
+      },
+      fadeDuration * 1e3 + 50
+    );
+  } else {
+    try {
+      track.source.stop();
+    } catch {
+    }
+    track.gain.disconnect();
+    track.unregister();
+  }
+}
+var musicBufferCache = /* @__PURE__ */ new Map();
+async function loadMusicBuffer(src) {
+  const cached = musicBufferCache.get(src);
+  if (cached) return cached;
+  const res = await fetch(src);
+  const data = await res.arrayBuffer();
+  const buf = await getAudioCtx().decodeAudioData(data);
+  musicBufferCache.set(src, buf);
+  return buf;
+}
+function useMusic(src, opts = {}) {
+  const volRef = useRef28(opts.volume ?? 1);
+  const loopRef = useRef28(opts.loop ?? true);
+  const isPlayingRef = useRef28(false);
+  const srcRef = useRef28(src);
+  useEffect60(() => {
+    srcRef.current = src;
+  }, [src]);
+  useEffect60(() => {
+    return () => {
+      if (currentTrack) {
+        stopTrack(currentTrack, 1);
+        currentTrack = null;
+        isPlayingRef.current = false;
+      }
+    };
+  }, []);
+  const startTrack = (buf, fadeDuration) => {
+    const ctx = getAudioCtx();
+    if (ctx.state === "suspended") void ctx.resume();
+    if (currentTrack) {
+      stopTrack(currentTrack, fadeDuration);
+      currentTrack = null;
+    }
+    const dest = getGroupGainNode("music");
+    const gain = ctx.createGain();
+    gain.gain.value = 0;
+    gain.connect(dest);
+    const source = ctx.createBufferSource();
+    source.buffer = buf;
+    source.loop = loopRef.current;
+    source.connect(gain);
+    const unregister = registerGroupSource("music", () => {
+      try {
+        source.stop();
+      } catch {
+      }
+      gain.disconnect();
+      if (currentTrack?.source === source) {
+        currentTrack = null;
+        isPlayingRef.current = false;
+      }
+    });
+    source.onended = () => {
+      gain.disconnect();
+      unregister();
+      if (currentTrack?.source === source) {
+        currentTrack = null;
+        isPlayingRef.current = false;
+      }
+    };
+    if (fadeDuration > 0) {
+      gain.gain.setValueAtTime(0, ctx.currentTime);
+      gain.gain.linearRampToValueAtTime(volRef.current, ctx.currentTime + fadeDuration);
+    } else {
+      gain.gain.value = volRef.current;
+    }
+    source.start();
+    currentTrack = { src: srcRef.current, source, gain, unregister };
+    isPlayingRef.current = true;
+  };
+  const play = (fadeDuration = 1) => {
+    loadMusicBuffer(srcRef.current).then((buf) => startTrack(buf, fadeDuration)).catch(console.error);
+  };
+  const stop = (fadeDuration = 1) => {
+    if (currentTrack) {
+      stopTrack(currentTrack, fadeDuration);
+      currentTrack = null;
+      isPlayingRef.current = false;
+    }
+  };
+  const crossfadeTo = (newSrc, fadeDuration = 1) => {
+    srcRef.current = newSrc;
+    loadMusicBuffer(newSrc).then((buf) => startTrack(buf, fadeDuration)).catch(console.error);
+  };
+  const setVolume = (v) => {
+    volRef.current = v;
+    if (currentTrack) currentTrack.gain.gain.value = v;
+  };
+  return {
+    play,
+    stop,
+    crossfadeTo,
+    setVolume,
+    get isPlaying() {
+      return isPlayingRef.current;
+    }
+  };
+}
+
 // ../../packages/audio/src/listener.ts
 function setListenerPosition(x, y) {
   const ctx = getAudioCtx();
@@ -17264,6 +17455,7 @@ export {
   getDescendants,
   getGroupVolume,
   getListenerPosition,
+  getMasterVolume,
   gjk,
   gjkEpaQuery,
   globalInputContext,
@@ -17311,6 +17503,7 @@ export {
   setDeterministicMode,
   setGroupMute,
   setGroupVolume,
+  setGroupVolumeFaded,
   setListenerPosition,
   setMassProperties,
   setMasterVolume,
@@ -17369,6 +17562,7 @@ export {
   useKinematicBody,
   useLevelTransition,
   useLocalMultiplayer,
+  useMusic,
   useObjectPool,
   useParent,
   usePathfinding,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cubeforge",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "React-first 2D browser game engine",
   "type": "module",
   "main": "./dist/index.js",