@rbxts/sound-manager 2.2.0 → 2.3.1

package/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">
 	<a href="https://www.npmjs.com/package/@rbxts/sound-manager">
-		<img src="public/logo.png" alt="Sound-Manager" width="200" />
+		<img src="https://github.com/dev-lukas0/Sound-Manager/blob/master/public/logo.png?raw=true" alt="Sound-Manager" width="200" />
 	</a>
 	<br />
 	<b>Sound Manager</b>
@@ -40,7 +40,7 @@ npm install @rbxts/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/createSoundCategoryRegistry.d.ts

@@ -1,5 +1,4 @@
 import { CategoryOptions } from "./options";
-import { SoundHandle } from "./options";
 /**
  * Create a sound category Registry
  * @param definitions Define the Categorys
@@ -8,7 +7,7 @@ export declare function createSoundCategoryRegistry<T extends Record<string, Cat
     loadCategory: (name: keyof T) => void;
     playCategory: <C extends keyof T>(name: C, spatial?: {
         emitters: BasePart[];
-    }) => Map<string, SoundHandle> | undefined;
+    }) => void;
     stopCategory: <C extends keyof T>(name: C) => void;
     stopAllCategories: () => void;
     setCategoryVolume: <C extends keyof T>(category: C, volume: number) => void;

package/out/core/createSoundCategoryRegistry.luau

@@ -63,20 +63,38 @@ local function createSoundCategoryRegistry(definitions)
 		if not categoryFolder then
 			return nil
 		end
-		for _, sound in categoryFolder:GetChildren() do
-			if not sound:IsA("Sound") then
+		local categoryHandles
+		if spatial and #spatial.emitters > 0 then
+			local _name = name
+			categoryHandles = spatialHandles[_name]
+			if not categoryHandles then
+				categoryHandles = {}
+				local _name_1 = name
+				local _categoryHandles = categoryHandles
+				spatialHandles[_name_1] = _categoryHandles
+			end
+		end
+		for _, instance in categoryFolder:GetChildren() do
+			if not instance:IsA("Sound") then
 				continue
 			end
-			if spatial and #spatial.emitters > 0 then
-				local handle = createSpatialHandle(sound.SoundId, spatial.emitters, sound.Volume)
-				local _name = sound.Name
-				spatialHandles[_name] = handle
+			if spatial and #spatial.emitters > 0 and categoryHandles then
+				local _categoryHandles = categoryHandles
+				local _name = instance.Name
+				local old = _categoryHandles[_name]
+				if old then
+					old:stop()
+					old:destroy()
+				end
+				local handle = createSpatialHandle(instance.SoundId, spatial.emitters, instance.Volume)
+				local _categoryHandles_1 = categoryHandles
+				local _name_1 = instance.Name
+				_categoryHandles_1[_name_1] = handle
 				handle:play()
 			else
-				sound:Play()
+				instance:Play()
 			end
 		end
-		return spatialHandles
 	end
 	--[[
 		*
@@ -85,27 +103,25 @@ local function createSoundCategoryRegistry(definitions)
 		     
 	]]
 	local function stopCategory(name)
-		local config = definitions[name]
-		local ReplicatedStorage = game:GetService("ReplicatedStorage")
-		local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
-		if not soundsFolder then
-			return nil
+		local _name = name
+		local categoryHandles = spatialHandles[_name]
+		if categoryHandles then
+			for _, handle in categoryHandles do
+				handle:stop()
+				handle:destroy()
+			end
+			table.clear(categoryHandles)
+			local _name_1 = name
+			spatialHandles[_name_1] = nil
 		end
-		local categoryFolder = soundsFolder:FindFirstChild(config.category)
+		local config = definitions[name]
+		local categoryFolder = folder: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()
+		for _, instance in categoryFolder:GetChildren() do
+			if instance:IsA("Sound") then
+				instance:Stop()
 			end
 		end
 	end

package/out/core/createSoundRegistry.d.ts

@@ -27,6 +27,8 @@ export declare function createSoundRegistry<T extends Record<string, SoundOption
         emitters: BasePart[];
     }) => void;
     resetAll: (sound: keyof T) => void;
-    onEnd: (sound: keyof T, callback: () => void) => void;
+    onEnd: (sound: keyof T, callback: () => void, spatial?: {
+        emitters: BasePart[];
+    }) => void;
     isPlaying: (sound: keyof T) => boolean;
 };

package/out/core/createSoundRegistry.luau

@@ -83,6 +83,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()
@@ -122,6 +126,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 +176,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
@@ -218,7 +227,8 @@ local function createSoundRegistry(definitions)
 	]]
 	local function reset(sound)
 		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.TimePosition = 0
@@ -245,7 +255,8 @@ local function createSoundRegistry(definitions)
 	]]
 	local function setTimePosition(sound, timePosition)
 		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.TimePosition = timePosition
@@ -279,7 +290,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
@@ -311,12 +323,22 @@ local function createSoundRegistry(definitions)
 		     * @param callback Callback
 		     
 	]]
-	local function onEnd(sound, callback)
-		local _sound = folder:WaitForChild(sound)
-		if not _sound then
-			return nil
+	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)
+		else
+			local _sound = sound
+			local handle = spatialHandles[_sound]
+			if not handle then
+				return nil
+			end
+			handle:played(callback)
 		end
-		_sound.Ended:Connect(callback)
 	end
 	--[[
 		*
@@ -335,7 +357,10 @@ local function createSoundRegistry(definitions)
 		     
 	]]
 	local function isPlaying(sound)
-		local _sound = folder:WaitForChild(sound)
+		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

package/out/developer-tools/currentPlayingSounds.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns the current playing legacy sounds and spatial sounds
+ */
+export declare function currentPlayingSounds(): Array<string>;

package/out/developer-tools/currentPlayingSounds.luau

@@ -0,0 +1,34 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * @returns the current playing legacy sounds and spatial sounds
+	 
+]]
+local function currentPlayingSounds()
+	local ReplicatedStorage = game:GetService("ReplicatedStorage")
+	local playingSounds = {}
+	local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+	if soundsFolder and soundsFolder:IsA("Folder") then
+		for _, category in soundsFolder:GetChildren() do
+			if not category:IsA("Folder") then
+				continue
+			end
+			for _1, instance in category:GetChildren() do
+				if instance:IsA("Sound") then
+					local _arg0 = `{instance.Name}`
+					table.insert(playingSounds, _arg0)
+				end
+			end
+		end
+	end
+	for _, instance in ReplicatedStorage:GetChildren() do
+		if instance:IsA("AudioPlayer") then
+			local _arg0 = `{instance.Name}`
+			table.insert(playingSounds, _arg0)
+		end
+	end
+	return playingSounds
+end
+return {
+	currentPlayingSounds = currentPlayingSounds,
+}

package/out/developer-tools/soundProperties.d.ts

@@ -0,0 +1,13 @@
+import { SoundOptions } from "../core/options";
+/**
+ * @returns Properties of a sound
+ */
+export declare function soundProperties<T extends Record<string, SoundOptions>>(name: keyof T, definitions: T): {
+    id: string;
+    volume: number;
+    loop: boolean;
+    spatial: {
+        attenuation?: number;
+        directional?: boolean;
+    };
+};

package/out/developer-tools/soundProperties.luau

@@ -0,0 +1,32 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * @returns Properties of a sound
+	 
+]]
+local function soundProperties(name, definitions)
+	local sound = definitions[name]
+	if not sound then
+		error(`Sound {tostring(name)} not found`)
+	end
+	local _object = {
+		id = sound.id,
+	}
+	local _left = "volume"
+	local _condition = sound.volume
+	if _condition == nil then
+		_condition = 1
+	end
+	_object[_left] = _condition
+	local _left_1 = "loop"
+	local _condition_1 = sound.loop
+	if _condition_1 == nil then
+		_condition_1 = false
+	end
+	_object[_left_1] = _condition_1
+	_object.spatial = sound.spatial or {}
+	return _object
+end
+return {
+	soundProperties = soundProperties,
+}

package/out/developer-tools/totalSoundCount.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns Total count of legacy sounds and spatial sounds
+ */
+export declare function TotalSoundCount(): number;

package/out/developer-tools/totalSoundCount.luau

@@ -0,0 +1,32 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * @returns Total count of legacy sounds and spatial sounds
+	 
+]]
+local function TotalSoundCount()
+	local ReplicatedStorage = game:GetService("ReplicatedStorage")
+	local count = 0
+	local soundsFolder = ReplicatedStorage:FindFirstChild("Sounds")
+	if soundsFolder and soundsFolder:IsA("Folder") then
+		for _, category in soundsFolder:GetChildren() do
+			if not category:IsA("Folder") then
+				continue
+			end
+			for _1, instance in category:GetChildren() do
+				if instance:IsA("Sound") then
+					count += 1
+				end
+			end
+		end
+	end
+	for _, instance in ReplicatedStorage:GetChildren() do
+		if instance:IsA("AudioPlayer") then
+			count += 1
+		end
+	end
+	return count
+end
+return {
+	TotalSoundCount = TotalSoundCount,
+}

package/out/index.d.ts

@@ -1,2 +1,10 @@
+import { TotalSoundCount } from "./developer-tools/totalSoundCount";
+import { currentPlayingSounds } from "./developer-tools/currentPlayingSounds";
+import { soundProperties } from "./developer-tools/soundProperties";
 export * from "./core/createSoundRegistry";
 export * from "./core/createSoundCategoryRegistry";
+export declare namespace Developer_Tools {
+    const getTotalSoundCount: typeof TotalSoundCount;
+    const getCurrentPlayingSounds: typeof currentPlayingSounds;
+    const getSoundProperties: typeof soundProperties;
+}

package/out/init.luau

@@ -1,10 +1,24 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 local exports = {}
+local TotalSoundCount = TS.import(script, script, "developer-tools", "totalSoundCount").TotalSoundCount
+local currentPlayingSounds = TS.import(script, script, "developer-tools", "currentPlayingSounds").currentPlayingSounds
+local soundProperties = TS.import(script, script, "developer-tools", "soundProperties").soundProperties
 for _k, _v in TS.import(script, script, "core", "createSoundRegistry") or {} do
 	exports[_k] = _v
 end
 for _k, _v in TS.import(script, script, "core", "createSoundCategoryRegistry") or {} do
 	exports[_k] = _v
 end
+local Developer_Tools = {}
+do
+	local _container = Developer_Tools
+	local getTotalSoundCount = TotalSoundCount
+	_container.getTotalSoundCount = getTotalSoundCount
+	local getCurrentPlayingSounds = currentPlayingSounds
+	_container.getCurrentPlayingSounds = getCurrentPlayingSounds
+	local getSoundProperties = soundProperties
+	_container.getSoundProperties = getSoundProperties
+end
+exports.Developer_Tools = Developer_Tools
 return exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rbxts/sound-manager",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "A sound manager for Roblox-Typescript projects.",
   "main": "out/init.lua",
   "scripts": {
@@ -11,7 +11,7 @@
   },
   "keywords": [],
   "author": "Easy-Build-Studio",
-  "license": "ISC",
+  "license": "MIT",
   "type": "commonjs",
   "types": "out/index.d.ts",
   "files": [