@rbxts/sound-manager 2.3.0 → 2.3.3

package/README.md

@@ -36,11 +36,11 @@ npm install @rbxts/sound-manager
 
 ## 🚀 Quick Start
 
-[See the Documentation ->](https://dev-lukas0.github.io/Sound-Manager-Docs/)
+[See the Documentation ->](https://dev-lukas0.github.io/Sound-Manager/)
 
 ### ⚡ Starting with Sound Manager
 
-Sound-Manager uses [`createSoundRegistry`]() and [`createSoundCategoryRegistry`]() to create sounds and categories.
+Sound-Manager uses [`createSoundRegistry`](https://dev-lukas0.github.io/Sound-Manager/docs/reference/create-sound-registry) and [`createSoundCategoryRegistry`](https://dev-lukas0.github.io/Sound-Manager/docs/reference/create-sound-category-registry) to create sounds and categories.
 
 ```ts
 import { createSoundRegistry } from "@rbxts/sound-manager";

package/out/core/createSoundRegistry.d.ts

@@ -11,24 +11,29 @@ export declare function createSoundRegistry<T extends Record<string, SoundOption
         emitters: BasePart[];
     }) => void;
     preloadAll: () => void;
-    load: (name: keyof T) => void;
+    load: (name: keyof T, spatial?: {
+        emitters: BasePart[];
+    }) => SoundHandle | undefined;
     fadeIn: (soundName: keyof T, duration: number, volume: number, spatial?: {
         emitters: BasePart[];
     }) => void;
     fadeOut: (soundName: keyof T, duration: number, targetVolume?: number, spatial?: {
         emitters: BasePart[];
     }) => void;
-    reset: (sound: keyof T) => void;
-    setTimePosition: (sound: keyof T, timePosition: number) => void;
-    stopAll: (reset?: true) => void;
+    reset: (sound: keyof T, spatial?: boolean) => void;
+    setTimePosition: (sound: keyof T, timePosition: number, spatial?: boolean) => void;
+    stopAll: (reset?: true, spatial?: boolean) => void;
     preload: (sound: keyof T) => void;
-    setGlobalVolume: (volume: number) => void;
+    setGlobalVolume: (volume: number, spatial?: boolean) => void;
     setVolume: (sound: keyof T, volume: number, spatial?: {
         emitters: BasePart[];
     }) => void;
-    resetAll: (sound: keyof T) => void;
+    resetAll: (sound: keyof T, spatial?: boolean) => void;
     onEnd: (sound: keyof T, callback: () => void, spatial?: {
         emitters: BasePart[];
     }) => void;
-    isPlaying: (sound: keyof T) => boolean;
+    isPlaying: (sound: keyof T, spatial?: boolean) => boolean;
+    preloadAllSpatial: (emittersMap: Partial<Record<keyof T, BasePart[]>>) => void;
+    preloadSpatial: (name: keyof T, emitters: BasePart[]) => void;
+    destroy: (sound: keyof T, spatial?: boolean) => void;
 };

package/out/core/createSoundRegistry.luau

@@ -20,27 +20,42 @@ local function createSoundRegistry(definitions)
 		*
 		     * Loads a Sound
 		     * @param name Define which Sound should be loaded
+		     * @param spatial Array of BaseParts
 		     
 	]]
-	local function load(name)
-		if folder:FindFirstChild(name) then
-			return nil
-		end
+	local function load(name, spatial)
 		local config = definitions[name]
-		local sound = Instance.new("Sound")
-		sound.Name = name
-		sound.SoundId = config.id
-		local _condition = config.volume
-		if _condition == nil then
-			_condition = 1
-		end
-		sound.Volume = _condition
-		local _condition_1 = config.loop
-		if _condition_1 == nil then
-			_condition_1 = false
+		if not spatial or not spatial.emitters then
+			if folder:FindFirstChild(name) then
+				return nil
+			end
+			local config = definitions[name]
+			local sound = Instance.new("Sound")
+			sound.Name = name
+			sound.SoundId = config.id
+			local _condition = config.volume
+			if _condition == nil then
+				_condition = 1
+			end
+			sound.Volume = _condition
+			local _condition_1 = config.loop
+			if _condition_1 == nil then
+				_condition_1 = false
+			end
+			sound.Looped = _condition_1
+			sound.Parent = folder
+		else
+			local emittersArray = spatial.emitters
+			local _exp = config.id
+			local _condition = config.volume
+			if _condition == nil then
+				_condition = 1
+			end
+			local handle = createSpatialHandle(_exp, emittersArray, _condition)
+			local _name = name
+			spatialHandles[_name] = handle
+			return handle
 		end
-		sound.Looped = _condition_1
-		sound.Parent = folder
 	end
 	--[[
 		*
@@ -83,6 +98,10 @@ local function createSoundRegistry(definitions)
 	local function stop(name, spatial)
 		if not spatial then
 			local sound = folder:FindFirstChild(name)
+			if not sound then
+				warn(`{name} not found! Tip: Preload the sound first before using it.`)
+				return nil
+			end
 			local _result = sound
 			if _result ~= nil then
 				_result:Stop()
@@ -109,6 +128,59 @@ local function createSoundRegistry(definitions)
 			load(name)
 		end
 	end
+	--[[
+		*
+		     * Preloads all spatial Sounds
+		     * @param emittersMap
+		     
+	]]
+	local function preloadAllSpatial(emittersMap)
+		for name, emitters in pairs(emittersMap) do
+			local emitterArray = emitters
+			if not emitterArray then
+				continue
+			end
+			local soundName = name
+			if spatialHandles[soundName] ~= nil then
+				continue
+			end
+			local config = definitions[soundName]
+			local _exp = config.id
+			local _condition = config.volume
+			if _condition == nil then
+				_condition = 1
+			end
+			local handle = createSpatialHandle(_exp, emitterArray, _condition)
+			spatialHandles[soundName] = handle
+		end
+	end
+	--[[
+		*
+		     * Preloads a spatial sound
+		     * @param name Sound Name
+		     * @param emitters Emitters
+		     
+	]]
+	local function preloadSpatial(name, emitters)
+		local _name = name
+		if spatialHandles[_name] ~= nil then
+			return nil
+		end
+		local config = definitions[name]
+		if not config then
+			warn(`{name} is not defined in the registry.`)
+			return nil
+		end
+		local _exp = config.id
+		local _exp_1 = emitters
+		local _condition = config.volume
+		if _condition == nil then
+			_condition = 1
+		end
+		local handle = createSpatialHandle(_exp, _exp_1, _condition)
+		local _name_1 = name
+		spatialHandles[_name_1] = handle
+	end
 	--[[
 		*
 		     * Smoothly fade in a sound
@@ -122,6 +194,10 @@ local function createSoundRegistry(definitions)
 		local config = definitions[soundName]
 		if not spatial or not spatial.emitters then
 			local sound = folder:FindFirstChild(soundName)
+			if not sound then
+				warn(`{soundName} not found! Tip: Preload the sound first before using it.`)
+				return nil
+			end
 			sound.Volume = 0
 			sound:Play()
 			local step = 0.05
@@ -168,6 +244,7 @@ local function createSoundRegistry(definitions)
 		if not spatial or not spatial.emitters then
 			local sound = folder:FindFirstChild(soundName)
 			if not sound then
+				warn(`{soundName} not found! Tip: Preload the sound first before using it.`)
 				return nil
 			end
 			local startVolume = sound.Volume
@@ -214,25 +291,43 @@ local function createSoundRegistry(definitions)
 		*
 		     * Reset a Sound
 		     * @param sound Sound Instance
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
-	local function reset(sound)
-		local _sound = folder:FindFirstChild(sound)
-		if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
-			return nil
+	local function reset(sound, spatial)
+		if not spatial then
+			local _sound = folder:FindFirstChild(sound)
+			if not _sound then
+				warn(`{sound} not found! Tip: Preload the sound first before using it.`)
+				return nil
+			end
+			_sound.TimePosition = 0
+		end
+		local _sound_1 = sound
+		local _sound = spatialHandles[_sound_1]
+		local _result = _sound
+		if _result ~= nil then
+			_result:setTimePosition(0)
 		end
-		_sound.TimePosition = 0
 	end
 	--[[
 		*
 		     * Reset every Sound
 		     * @param sound Sound Instance
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
-	local function resetAll(sound)
-		for _, sound in folder:GetChildren() do
-			if sound:IsA("Sound") then
-				sound.TimePosition = 0
+	local function resetAll(sound, spatial)
+		if not spatial then
+			for _, sound in folder:GetChildren() do
+				if sound:IsA("Sound") then
+					sound.TimePosition = 0
+				end
+			end
+		end
+		for _, instance in folder:GetChildren() do
+			if instance:IsA("AudioPlayer") then
+				instance.TimePosition = 0
 			end
 		end
 	end
@@ -241,24 +336,46 @@ local function createSoundRegistry(definitions)
 		     * Set Time Position
 		     * @param sound Sound Instance
 		     * @param timePosition Time Position
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
-	local function setTimePosition(sound, timePosition)
-		local _sound = folder:FindFirstChild(sound)
-		if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
-			return nil
+	local function setTimePosition(sound, timePosition, spatial)
+		if not spatial then
+			local _sound = folder:FindFirstChild(sound)
+			if not _sound then
+				warn(`{sound} not found! Tip: Preload the sound first before using it.`)
+				return nil
+			end
+			_sound.TimePosition = timePosition
+		end
+		local _sound_1 = sound
+		local _sound = spatialHandles[_sound_1]
+		local _result = _sound
+		if _result ~= nil then
+			_result:setTimePosition(timePosition)
 		end
-		_sound.TimePosition = timePosition
 	end
 	--[[
 		*
 		     * Stop every Sound
 		     * @param reset Define whether every Sound should also be reset?
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
-	local function stopAll(reset)
+	local function stopAll(reset, spatial)
+		if not spatial then
+			for _, instance in folder:GetChildren() do
+				if not instance:IsA("Sound") then
+					continue
+				end
+				instance:Stop()
+				if reset then
+					instance.TimePosition = 0
+				end
+			end
+		end
 		for _, instance in folder:GetChildren() do
-			if not instance:IsA("Sound") then
+			if not instance:IsA("AudioPlayer") then
 				continue
 			end
 			instance:Stop()
@@ -279,7 +396,8 @@ local function createSoundRegistry(definitions)
 		local config = definitions[sound]
 		if not spatial or spatial.emitters then
 			local _sound = folder:FindFirstChild(sound)
-			if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
+			if not _sound then
+				warn(`{sound} not found! Tip: Preload the sound first before using it.`)
 				return nil
 			end
 			_sound.Volume = volume
@@ -292,14 +410,25 @@ local function createSoundRegistry(definitions)
 		*
 		     * Set the global Sound Volume
 		     * @param volume Sound Volume
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
-	local function setGlobalVolume(volume)
+	local function setGlobalVolume(volume, spatial)
+		if not spatial then
+			for _, instance in folder:GetChildren() do
+				if not instance:IsA("Sound") then
+					continue
+				end
+				if instance:IsA("Sound") then
+					instance.Volume = volume
+				end
+			end
+		end
 		for _, instance in folder:GetChildren() do
-			if not instance:IsA("Sound") then
+			if not instance:IsA("AudioPlayer") then
 				continue
 			end
-			if instance:IsA("Sound") then
+			if instance:IsA("AudioPlayer") then
 				instance.Volume = volume
 			end
 		end
@@ -309,12 +438,14 @@ local function createSoundRegistry(definitions)
 		     * Does something on Sound end
 		     * @param name Sound Name
 		     * @param callback Callback
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
 	local function onEnd(sound, callback, spatial)
 		if not spatial then
 			local _sound = folder:WaitForChild(sound)
 			if not _sound then
+				warn(`{sound} not found! Tip: Preload the sound first before using it.`)
 				return nil
 			end
 			_sound.Ended:Connect(callback)
@@ -341,15 +472,59 @@ local function createSoundRegistry(definitions)
 		     * Check whether a Sound is playing
 		     * @param sound Sound Instance
 		     * @returns Boolean
+		     * @param spatial Define whether this sound is a spatial sound or not
 		     
 	]]
-	local function isPlaying(sound)
-		local _sound = folder:FindFirstChild(sound)
-		if _sound.IsPlaying == true then
+	local function isPlaying(sound, spatial)
+		if not spatial then
+			local _sound = folder:FindFirstChild(sound)
+			if not _sound then
+				warn(`{sound} not found! Tip: Preload the sound first before using it.`)
+			end
+			if _sound.IsPlaying == true then
+				return true
+			else
+				return false
+			end
+		end
+		local _sound_1 = sound
+		local _sound = spatialHandles[_sound_1]
+		if not _sound then
+			warn(`{sound} not found! Tip: Preload the sound first before using it.`)
+		end
+		local _result = _sound
+		if _result ~= nil then
+			_result = _result:playing()
+		end
+		if _result == true then
 			return true
-		else
-			return false
 		end
+		return false
+	end
+	--[[
+		*
+		     * Delete a sound instance
+		     * @param sound Sound Instance
+		     * @param spatial Define whether this sound is a spatial sound or not
+		     
+	]]
+	local function destroy(sound, spatial)
+		if not spatial then
+			local instance = folder:FindFirstChild(sound)
+			if not instance then
+				warn(`{sound} not found! Tip: Preload the sound first before using it.`)
+				return nil
+			end
+			instance:Destroy()
+			return nil
+		end
+		local _sound = sound
+		local handle = spatialHandles[_sound]
+		if not handle then
+			warn(`{sound} not found! Tip: Preload the sound first before using it.`)
+			return nil
+		end
+		handle:destroy()
 	end
 	return {
 		play = play,
@@ -367,6 +542,9 @@ local function createSoundRegistry(definitions)
 		resetAll = resetAll,
 		onEnd = onEnd,
 		isPlaying = isPlaying,
+		preloadAllSpatial = preloadAllSpatial,
+		preloadSpatial = preloadSpatial,
+		destroy = destroy,
 	}
 end
 return {

package/out/core/createSpatialHandle.luau

@@ -52,6 +52,12 @@ local function createSpatialHandle(assetId, emitters, volume)
 		played = function(self, callback)
 			player.Ended:Connect(callback)
 		end,
+		playing = function(self)
+			return player.IsPlaying
+		end,
+		setTimePosition = function(self, timeposition)
+			player.TimePosition = timeposition
+		end,
 	}
 end
 return {

package/out/core/options.d.ts

@@ -14,6 +14,8 @@ export interface SoundHandle {
     fadeOut?(duration: number): void;
     destroy(): void;
     played(callback: () => void): void;
+    playing(): boolean;
+    setTimePosition(timeposition: number): void;
 }
 interface SoundDefinition {
     id: string;
@@ -24,4 +26,10 @@ export interface CategoryOptions {
     category: string;
     sounds: Record<string, SoundDefinition>;
 }
+export interface AudioListenerHandle {
+    listener: AudioListener;
+    output: AudioDeviceOutput;
+    wire: Wire;
+    destroy(): void;
+}
 export {};

package/out/createAudioListener.d.ts

@@ -0,0 +1,8 @@
+import { AudioListenerHandle } from "./core/options";
+type ListenerParent = BasePart | Camera | Model;
+/**
+ * Creates an Audio Listener
+ * @param parent BasePart | Camera | Model
+ */
+export declare function createAudioListener(parent: ListenerParent, name?: string): AudioListenerHandle | undefined;
+export {};

package/out/createAudioListener.luau

@@ -0,0 +1,39 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Creates an Audio Listener
+	 * @param parent BasePart | Camera | Model
+	 
+]]
+local function createAudioListener(parent, name)
+	if parent:FindFirstChild("Sound-Manager-AudioListener") then
+		warn("AudioListener already exists on this parent")
+		return nil
+	end
+	local listener = Instance.new("AudioListener")
+	local _condition = name
+	if _condition == nil then
+		_condition = "Sound-Manager-AudioListener"
+	end
+	listener.Name = _condition
+	listener.Parent = parent
+	local output = Instance.new("AudioDeviceOutput")
+	output.Name = "Sound-Manager-AudioOutput"
+	local wire = Instance.new("Wire")
+	wire.Name = "ListenerToOutput"
+	wire.SourceInstance = listener
+	wire.TargetInstance = output
+	output.Parent = wire
+	wire.Parent = listener
+	return {
+		listener = listener,
+		output = output,
+		wire = wire,
+		destroy = function(self)
+			listener:Destroy()
+		end,
+	}
+end
+return {
+	createAudioListener = createAudioListener,
+}

package/out/index.d.ts

@@ -3,6 +3,7 @@ import { currentPlayingSounds } from "./developer-tools/currentPlayingSounds";
 import { soundProperties } from "./developer-tools/soundProperties";
 export * from "./core/createSoundRegistry";
 export * from "./core/createSoundCategoryRegistry";
+export * from "./createAudioListener";
 export declare namespace Developer_Tools {
     const getTotalSoundCount: typeof TotalSoundCount;
     const getCurrentPlayingSounds: typeof currentPlayingSounds;

package/out/init.luau

@@ -10,6 +10,9 @@ end
 for _k, _v in TS.import(script, script, "core", "createSoundCategoryRegistry") or {} do
 	exports[_k] = _v
 end
+for _k, _v in TS.import(script, script, "createAudioListener") or {} do
+	exports[_k] = _v
+end
 local Developer_Tools = {}
 do
 	local _container = Developer_Tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/sound-manager",
-  "version": "2.3.0",
+  "version": "2.3.3",
   "description": "A sound manager for Roblox-Typescript projects.",
   "main": "out/init.lua",
   "scripts": {