@rbxts/sound-manager 2.0.1 → 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

@@ -79,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

@@ -222,7 +222,7 @@ local function createSoundRegistry(definitions)
 	end
 	--[[
 		*
-		     * Plays Sound on Event Callback
+		     * Does something on Sound end
 		     * @param name Sound Name
 		     * @param callback Callback
 		     
@@ -243,6 +243,21 @@ local function createSoundRegistry(definitions)
 	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.1",
+  "version": "2.1.0",
   "description": "A sound manager for Roblox-Typescript projects.",
   "main": "out/init.lua",
   "scripts": {