@rbxts/sound-manager 2.0.0 → 2.1.0

package/README.md

@@ -25,5 +25,43 @@ Sounds.preloadAll();
 Sounds.play("SCP096");
 ```
 
+## Roadmap
+
+### Core API
+- [x] load
+- [x] play
+- [x] stop / stopAll
+- [x] preload / preloadAll
+- [x] fadeIn / fadeOut
+- [x] reset / resetAll
+- [x] setTimePosition
+- [x] setVolume / setGlobalVolume
+- [x] onEnd
+- [x] isPlaying
+
+### Development Utilities
+- [ ] Total Sound Count function
+- [ ] Currently Playing Sounds function
+- [ ] Sound Instance Getter function
+- [ ] Sound Properties Getter function
+
+### Category API
+- [x] playCategory
+- [x] stopCategory / stopAllCategories
+- [x] setCategoryVolume / setGlobalCategoryVolume
+- [x] fadeInCategory / fadeOutCategory
+- [x] preloadCategory / preloadAllCategories
+- [x] isCategoryPlaying
+- [x] onCategoryEnd
+- [x] resetCategory / resetAllCategories
+- [x] playSoundFromCategory
+
+### Features
+- [x] Sound Autocompletion
+- [ ] Sound Categories
+- [ ] Sound Creation functions
+- [ ] Sound Priority
+
+
 For more Details:
 https://dev-lukas0.github.io/Sound-Manager-Docs/

package/out/core/createSoundCategoryRegistry.d.ts

@@ -6,4 +6,17 @@ import { CategoryOptions } from "./options";
 export declare function createSoundCategoryRegistry<T extends Record<string, CategoryOptions>>(definitions: T): {
     loadCategory: (name: keyof T) => void;
     playCategory: <C extends keyof T>(name: C) => void;
+    stopCategory: <C extends keyof T>(name: C) => void;
+    stopAllCategories: () => void;
+    setCategoryVolume: <C extends keyof T>(category: C, volume: number) => void;
+    setGlobalCategoryVolume: (volume: number) => void;
+    isCategoryPlaying: <C extends keyof T>(category: C) => boolean;
+    playSoundFromCategory: <C extends keyof T, S extends keyof T[C]["sounds"]>(category: C, sound: S) => void;
+    resetCategory: <C extends keyof T>(category: C) => void;
+    resetAllCategories: <C extends keyof T>(category: C) => void;
+    preloadAllCategories: () => void;
+    preloadCategory: <C extends keyof T>(category: C) => void;
+    fadeInCategory: <C extends keyof T>(category: C, duration: number, volume: number) => void;
+    fadeOutCategory: <C extends keyof T>(category: C, duration: number, targetVolume?: number) => void;
+    onCategoryEnd: <C extends keyof T>(category: C, callback: () => void) => void;
 };

package/out/core/createSoundCategoryRegistry.luau

@@ -20,9 +20,6 @@ local function createSoundCategoryRegistry(definitions)
 		     
 	]]
 	local function loadCategory(name)
-		if folder:FindFirstChild(name) then
-			return nil
-		end
 		local config = definitions[name]
 		local category = folder:FindFirstChild(config.category)
 		if not category then
@@ -60,9 +57,16 @@ local function createSoundCategoryRegistry(definitions)
 		loadCategory(name)
 		local config = definitions[name]
 		local ReplicatedStorage = game:GetService("ReplicatedStorage")
-		local folder = ReplicatedStorage:FindFirstChild(config.category)
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
 		for sound in pairs(config.sounds) do
-			local _sound = folder:FindFirstChild(sound)
+			local _sound = categoryFolder:FindFirstChild(sound)
 			if not _sound then
 				continue
 			end
@@ -75,9 +79,392 @@ local function createSoundCategoryRegistry(definitions)
 			end
 		end
 	end
+	--[[
+		*
+		     * Stop every Sound from a Sound Category
+		     * @param name Sound Category
+		     
+	]]
+	local function stopCategory(name)
+		local config = definitions[name]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		for sound in pairs(config.sounds) do
+			local _sound = categoryFolder:FindFirstChild(sound)
+			if not _sound then
+				continue
+			end
+			local _result = _sound
+			if _result ~= nil then
+				_result = _result:IsA("Sound")
+			end
+			if _result then
+				_sound:Stop()
+			end
+		end
+	end
+	--[[
+		*
+		     * Stops every Sound from every Sound Category
+		     
+	]]
+	local function stopAllCategories()
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		for _, category in soundsFolder:GetChildren() do
+			if not category:IsA("Folder") then
+				continue
+			end
+			for _1, sound in category:GetChildren() do
+				if not sound:IsA("Sound") then
+					continue
+				end
+				sound:Stop()
+			end
+		end
+	end
+	--[[
+		*
+		     * Set the Volume of a Sound Category
+		     * @param category Sound Category
+		     * @param volume Volume
+		     
+	]]
+	local function setCategoryVolume(category, volume)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		for _, sound in categoryFolder:GetChildren() do
+			if not sound:IsA("Sound") then
+				continue
+			end
+			sound.Volume = volume
+		end
+	end
+	--[[
+		*
+		     * Set the Global Volume of every Sound Category
+		     * @param volume Volume
+		     
+	]]
+	local function setGlobalCategoryVolume(volume)
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		for _, category in soundsFolder:GetChildren() do
+			if not category:IsA("Folder") then
+				continue
+			end
+			for _1, sound in category:GetChildren() do
+				if not sound:IsA("Sound") then
+					continue
+				end
+				sound.Volume = volume
+			end
+		end
+	end
+	--[[
+		*
+		     * Whether a Category is playing or not
+		     * @param category Sound Category
+		     * @returns Whether a Category is playing or not
+		     
+	]]
+	local function isCategoryPlaying(category)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return false
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return false
+		end
+		local _exp = categoryFolder:GetChildren()
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(sound)
+			return sound:IsA("Sound")
+		end
+		local _length = 0
+		for _k, _v in _exp do
+			if _callback(_v, _k - 1, _exp) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		local sounds = _newValue
+		if #sounds == 0 then
+			return false
+		end
+		for _, sound in sounds do
+			if not sound.IsPlaying then
+				return false
+			end
+		end
+		return true
+	end
+	--[[
+		*
+		     * Play a Sound from a Category
+		     * @param category Sound Category
+		     * @param sound Sound Instance
+		     
+	]]
+	local function playSoundFromCategory(category, sound)
+		loadCategory(category)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		local soundInstance = categoryFolder:FindFirstChild(sound)
+		local _result = soundInstance
+		if _result ~= nil then
+			_result = _result:IsA("Sound")
+		end
+		if _result then
+			soundInstance:Play()
+		end
+	end
+	--[[
+		*
+		     * Reset a Sound Category Timeposition to 0
+		     * @param category Sound Category
+		     
+	]]
+	local function resetCategory(category)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		for _, sound in categoryFolder:GetChildren() do
+			if not sound:IsA("Sound") then
+				continue
+			end
+			sound.TimePosition = 0
+		end
+	end
+	--[[
+		*
+		     * Resets every Sound from every Sound Category
+		     * @param category Sound Category
+		     
+	]]
+	local function resetAllCategories(category)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		for _, folder in soundsFolder:GetChildren() do
+			if not folder:IsA("Folder") then
+				continue
+			end
+			for _1, sound in folder:GetChildren() do
+				if not sound:IsA("Sound") then
+					continue
+				end
+				sound.TimePosition = 0
+			end
+		end
+	end
+	--[[
+		*
+		     * Preloads a Sound Category
+		     * @param category Sound Category
+		     
+	]]
+	local function preloadCategory(category)
+		loadCategory(category)
+	end
+	--[[
+		*
+		     * Preloads every Sound Category
+		     
+	]]
+	local function preloadAllCategories()
+		for category in pairs(definitions) do
+			loadCategory(category)
+		end
+	end
+	--[[
+		*
+		     * Smoothly fade in a Sound Category
+		     * @param category Sound Category
+		     * @param duration Duration
+		     * @param volume Volume
+		     
+	]]
+	local function fadeInCategory(category, duration, volume)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		for _, sound in categoryFolder:GetChildren() do
+			if not sound:IsA("Sound") then
+				continue
+			end
+			sound.Volume = 0
+			sound:Play()
+			local step = 0.05
+			local interval = duration * step
+			task.spawn(function()
+				local vol = 0
+				while vol < volume do
+					vol += step
+					sound.Volume = math.clamp(vol, 0, volume)
+					task.wait(interval)
+				end
+			end)
+		end
+	end
+	--[[
+		*
+		     * Smoothly fade out a Sound Category
+		     * @param category Sound Category
+		     * @param duration Duration
+		     * @param targetVolume Target Volume
+		     
+	]]
+	local function fadeOutCategory(category, duration, targetVolume)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		for _, sound in categoryFolder:GetChildren() do
+			if not sound:IsA("Sound") then
+				continue
+			end
+			local startVolume = sound.Volume
+			local _condition = targetVolume
+			if _condition == nil then
+				_condition = 0
+			end
+			local endVolume = _condition
+			local step = 0.05
+			local interval = duration * step
+			task.spawn(function()
+				local vol = startVolume
+				while vol > endVolume do
+					vol = math.clamp(vol - step, endVolume, startVolume)
+					sound.Volume = vol
+					task.wait(interval)
+				end
+				sound.Volume = endVolume
+				if endVolume == 0 then
+					sound:Stop()
+				end
+			end)
+		end
+	end
+	--[[
+		*
+		     * Does something on Category end
+		     * @param category Sound Category
+		     * @param callback Callback
+		     
+	]]
+	local function onCategoryEnd(category, callback)
+		local config = definitions[category]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+		if not soundsFolder then
+			return nil
+		end
+		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		if not categoryFolder then
+			return nil
+		end
+		local _exp = categoryFolder:GetChildren()
+		-- ▼ ReadonlyArray.filter ▼
+		local _newValue = {}
+		local _callback = function(s)
+			return s:IsA("Sound")
+		end
+		local _length = 0
+		for _k, _v in _exp do
+			if _callback(_v, _k - 1, _exp) == true then
+				_length += 1
+				_newValue[_length] = _v
+			end
+		end
+		-- ▲ ReadonlyArray.filter ▲
+		local sounds = _newValue
+		if #sounds == 0 then
+			return nil
+		end
+		local remaining = #sounds
+		for _, sound in sounds do
+			sound.Ended:Connect(function()
+				remaining -= 1
+				if remaining <= 0 then
+					callback()
+				end
+			end)
+		end
+	end
 	return {
 		loadCategory = loadCategory,
 		playCategory = playCategory,
+		stopCategory = stopCategory,
+		stopAllCategories = stopAllCategories,
+		setCategoryVolume = setCategoryVolume,
+		setGlobalCategoryVolume = setGlobalCategoryVolume,
+		isCategoryPlaying = isCategoryPlaying,
+		playSoundFromCategory = playSoundFromCategory,
+		resetCategory = resetCategory,
+		resetAllCategories = resetAllCategories,
+		preloadAllCategories = preloadAllCategories,
+		preloadCategory = preloadCategory,
+		fadeInCategory = fadeInCategory,
+		fadeOutCategory = fadeOutCategory,
+		onCategoryEnd = onCategoryEnd,
 	}
 end
 return {

package/out/core/createSoundRegistry.d.ts

@@ -18,4 +18,5 @@ export declare function createSoundRegistry<T extends Record<string, SoundOption
     setVolume: (sound: keyof T, volume: number) => void;
     resetAll: (sound: keyof T) => void;
     onEnd: (sound: keyof T, callback: () => void) => void;
+    isPlaying: (sound: keyof T) => boolean;
 };

package/out/core/createSoundRegistry.luau

@@ -1,8 +1,8 @@
 -- Compiled with roblox-ts v3.0.0
 --[[
-	*
-	 * Create a sound Registry
-	 * @param definitions Define the Sounds
+	*
+	 * Create a sound Registry
+	 * @param definitions Define the Sounds
 	 
 ]]
 local function createSoundRegistry(definitions)
@@ -14,9 +14,9 @@ local function createSoundRegistry(definitions)
 		folder.Parent = ReplicatedStorage
 	end
 	--[[
-		*
-		     * Loads a Sound
-		     * @param name Define which Sound should be loaded
+		*
+		     * Loads a Sound
+		     * @param name Define which Sound should be loaded
 		     
 	]]
 	local function load(name)
@@ -40,9 +40,9 @@ local function createSoundRegistry(definitions)
 		sound.Parent = folder
 	end
 	--[[
-		*
-		     * Plays a Sound
-		     * @param name Define which Sound should be played
+		*
+		     * Plays a Sound
+		     * @param name Define which Sound should be played
 		     
 	]]
 	local function play(name)
@@ -54,9 +54,9 @@ local function createSoundRegistry(definitions)
 		end
 	end
 	--[[
-		*
-		     * Stops a Sound
-		     * @param name Define which Sound should be stopped
+		*
+		     * Stops a Sound
+		     * @param name Define which Sound should be stopped
 		     
 	]]
 	local function stop(name)
@@ -67,8 +67,8 @@ local function createSoundRegistry(definitions)
 		end
 	end
 	--[[
-		*
-		     * Loads every Sound
+		*
+		     * Loads every Sound
 		     
 	]]
 	local function preloadAll()
@@ -77,11 +77,11 @@ local function createSoundRegistry(definitions)
 		end
 	end
 	--[[
-		*
-		     * Smoothly fad in a sound
-		     * @param soundName Sound Instance
-		     * @param duration Time in Seconds
-		     * @param volume Volume
+		*
+		     * Smoothly fade in a sound
+		     * @param soundName Sound Instance
+		     * @param duration Time in Seconds
+		     * @param volume Volume
 		     
 	]]
 	local function fadeIn(soundName, duration, volume)
@@ -100,11 +100,11 @@ local function createSoundRegistry(definitions)
 		end)
 	end
 	--[[
-		*
-		     * Smoothly fade out a sound
-		     * @param soundName Sound name from Registry
-		     * @param duration Time in seconds
-		     * @param targetVolume Optional target volume (default 0)
+		*
+		     * Smoothly fade out a sound
+		     * @param soundName Sound name from Registry
+		     * @param duration Time in seconds
+		     * @param targetVolume Optional target volume (default 0)
 		     
 	]]
 	local function fadeOut(soundName, duration, targetVolume)
@@ -134,9 +134,9 @@ local function createSoundRegistry(definitions)
 		end)
 	end
 	--[[
-		*
-		     * Reset a Sound
-		     * @param sound Sound Instance
+		*
+		     * Reset a Sound
+		     * @param sound Sound Instance
 		     
 	]]
 	local function reset(sound)
@@ -147,9 +147,9 @@ local function createSoundRegistry(definitions)
 		_sound.TimePosition = 0
 	end
 	--[[
-		*
-		     * Reset every Sound
-		     * @param sound Sound Instance
+		*
+		     * Reset every Sound
+		     * @param sound Sound Instance
 		     
 	]]
 	local function resetAll(sound)
@@ -160,10 +160,10 @@ local function createSoundRegistry(definitions)
 		end
 	end
 	--[[
-		*
-		     * Set Time Position
-		     * @param sound Sound Instance
-		     * @param timePosition Time Position
+		*
+		     * Set Time Position
+		     * @param sound Sound Instance
+		     * @param timePosition Time Position
 		     
 	]]
 	local function setTimePosition(sound, timePosition)
@@ -174,9 +174,9 @@ local function createSoundRegistry(definitions)
 		_sound.TimePosition = timePosition
 	end
 	--[[
-		*
-		     * Stop every Sound
-		     * @param reset Define whether every Sound should also be reset?
+		*
+		     * Stop every Sound
+		     * @param reset Define whether every Sound should also be reset?
 		     
 	]]
 	local function stopAll(reset)
@@ -191,10 +191,10 @@ local function createSoundRegistry(definitions)
 		end
 	end
 	--[[
-		*
-		     * Set Sound Volume
-		     * @param sound Sound Instance
-		     * @param volume Sound Volume
+		*
+		     * Set Sound Volume
+		     * @param sound Sound Instance
+		     * @param volume Sound Volume
 		     
 	]]
 	local function setVolume(sound, volume)
@@ -205,9 +205,9 @@ local function createSoundRegistry(definitions)
 		_sound.Volume = volume
 	end
 	--[[
-		*
-		     * Set the global Sound Volume
-		     * @param volume Sound Volume
+		*
+		     * Set the global Sound Volume
+		     * @param volume Sound Volume
 		     
 	]]
 	local function setGlobalVolume(volume)
@@ -221,10 +221,10 @@ local function createSoundRegistry(definitions)
 		end
 	end
 	--[[
-		*
-		     * Plays Sound on Event Callback
-		     * @param name Sound Name
-		     * @param callback Callback
+		*
+		     * Does something on Sound end
+		     * @param name Sound Name
+		     * @param callback Callback
 		     
 	]]
 	local function onEnd(sound, callback)
@@ -235,14 +235,29 @@ local function createSoundRegistry(definitions)
 		_sound.Ended:Connect(callback)
 	end
 	--[[
-		*
-		     * Preloads a Sound
-		     * @param sound Sound Instance
+		*
+		     * Preloads a Sound
+		     * @param sound Sound Instance
 		     
 	]]
 	local function preload(sound)
 		load(sound)
 	end
+	--[[
+		*
+		     * Check whether a Sound is playing
+		     * @param sound Sound Instance
+		     * @returns Boolean
+		     
+	]]
+	local function isPlaying(sound)
+		local _sound = folder:WaitForChild(sound)
+		if _sound.IsPlaying == true then
+			return true
+		else
+			return false
+		end
+	end
 	return {
 		play = play,
 		stop = stop,
@@ -258,6 +273,7 @@ local function createSoundRegistry(definitions)
 		setVolume = setVolume,
 		resetAll = resetAll,
 		onEnd = onEnd,
+		isPlaying = isPlaying,
 	}
 end
 return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/sound-manager",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A sound manager for Roblox-Typescript projects.",
   "main": "out/init.lua",
   "scripts": {
@@ -34,7 +34,6 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@rbxts/sound-manager": "file:rbxts-sound-manager-1.2.0.tgz",
     "@rbxts/testez": "^0.4.2-ts.0"
   }
 }