@rbxts/sound-manager 2.1.0 → 2.2.0

package/README.md

@@ -1,15 +1,48 @@
-# Sound Manager
+<h1 align="center">
+	<a href="https://www.npmjs.com/package/@rbxts/sound-manager">
+		<img src="public/logo.png" alt="Sound-Manager" width="200" />
+	</a>
+	<br />
+	<b>Sound Manager</b>
+    
+</h1>
 
-A Roblox sound management library built with Roblox-TS
+<div align="center">
+
+![npm](https://img.shields.io/npm/dt/@rbxts/sound-manager?style=flat-square) ![npm](https://img.shields.io/npm/v/@rbxts/sound-manager?style=flat-square) ![GitHub](https://img.shields.io/github/license/dev-lukas0/Sound-Manager?style=flat-square)
+
+</div>
+
+---
+
+&nbsp;
+
+
+## 🔉 Sound Manager
+
+**Sound Manager** is a roblox sound-management library built with Roblox-TS, designed to simplify sound handling in your roblox projects.
+
+&nbsp;
+
+## 📦 Installation
 
-## Getting Started
 To use the Sound Manager library in your Roblox-TS project, install it via npm:
+
 ```bash
 npm install @rbxts/sound-manager
 ```
 
-Example usage:
-```typescript
+&nbsp;
+
+## 🚀 Quick Start
+
+[See the Documentation ->](https://dev-lukas0.github.io/Sound-Manager-Docs/)
+
+### ⚡ Starting with Sound Manager
+
+Sound-Manager uses [`createSoundRegistry`]() and [`createSoundCategoryRegistry`]() to create sounds and categories.
+
+```ts
 import { createSoundRegistry } from "@rbxts/sound-manager";
 
 const Sounds = createSoundRegistry({
@@ -17,51 +50,37 @@ const Sounds = createSoundRegistry({
         id: "rbxassetid://4714389545",
         volume: 1,
         loop: false,
-    } 
+    },
+
+    Test: {
+        id: "rbxassetid://17771398985",
+        volume: 1,
+        loop: true,
+    }
 });
+```
 
-Sounds.preloadAll();
+### 🎵 Playing Sounds
 
+To play a sound, you can use the [`play`](https://dev-lukas0.github.io/Sound-Manager-Docs/docs/API/play) method on the sound registry:
+
+```ts
 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
+&nbsp;
+
+## 🗺️ Roadmap
+-------
+See the [Roadmap](./Roadmap.md) for planned features and current progress.
+
+&nbsp;
+
+## 📝 License
+
+**Sound Manager** is licensed under the [MIT LICENSE](./LICENSE).
 
+&nbsp;
 
 For more Details:
 https://dev-lukas0.github.io/Sound-Manager-Docs/

package/out/core/createSoundCategoryRegistry.d.ts

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

@@ -1,4 +1,6 @@
 -- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local createSpatialHandle = TS.import(script, script.Parent, "createSpatialHandle").createSpatialHandle
 --[[
 	*
 	 * Create a sound category Registry
@@ -6,6 +8,7 @@
 	 
 ]]
 local function createSoundCategoryRegistry(definitions)
+	local spatialHandles = {}
 	local ReplicatedStorage = game:GetService("ReplicatedStorage")
 	local folder = ReplicatedStorage:FindFirstChild("Sounds")
 	if not folder then
@@ -53,31 +56,27 @@ local function createSoundCategoryRegistry(definitions)
 		     * @param name Sound Category
 		     
 	]]
-	local function playCategory(name)
+	local function playCategory(name, spatial)
 		loadCategory(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)
+		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
+		for _, sound in categoryFolder:GetChildren() do
+			if not sound:IsA("Sound") then
 				continue
 			end
-			local _result = _sound
-			if _result ~= nil then
-				_result = _result:IsA("Sound")
-			end
-			if _result then
-				_sound:Play()
+			if spatial and #spatial.emitters > 0 then
+				local handle = createSpatialHandle(sound.SoundId, spatial.emitters, sound.Volume)
+				local _name = sound.Name
+				spatialHandles[_name] = handle
+				handle:play()
+			else
+				sound:Play()
 			end
 		end
+		return spatialHandles
 	end
 	--[[
 		*

package/out/core/createSoundRegistry.d.ts

@@ -1,21 +1,31 @@
-import { SoundOptions } from "./options";
+import { SoundHandle, SoundOptions } from "./options";
 /**
  * Create a sound Registry
  * @param definitions Define the Sounds
  */
 export declare function createSoundRegistry<T extends Record<string, SoundOptions>>(definitions: T): {
-    play: (name: keyof T) => void;
-    stop: (name: keyof T) => void;
+    play: (name: keyof T, spatial?: {
+        emitters: BasePart[];
+    }) => SoundHandle | undefined;
+    stop: (name: keyof T, spatial?: {
+        emitters: BasePart[];
+    }) => void;
     preloadAll: () => void;
     load: (name: keyof T) => void;
-    fadeIn: (soundName: keyof T, duration: number, volume: number) => void;
-    fadeOut: (soundName: keyof T, duration: number, targetVolume?: number) => void;
+    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;
     preload: (sound: keyof T) => void;
     setGlobalVolume: (volume: number) => void;
-    setVolume: (sound: keyof T, volume: number) => void;
+    setVolume: (sound: keyof T, volume: number, spatial?: {
+        emitters: BasePart[];
+    }) => void;
     resetAll: (sound: keyof T) => void;
     onEnd: (sound: keyof T, callback: () => void) => void;
     isPlaying: (sound: keyof T) => boolean;

package/out/core/createSoundRegistry.luau

@@ -1,4 +1,6 @@
 -- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local createSpatialHandle = TS.import(script, script.Parent, "createSpatialHandle").createSpatialHandle
 --[[
 	*
 	 * Create a sound Registry
@@ -6,6 +8,7 @@
 	 
 ]]
 local function createSoundRegistry(definitions)
+	local spatialHandles = {}
 	local ReplicatedStorage = game:GetService("ReplicatedStorage")
 	local folder = ReplicatedStorage:FindFirstChild("Sounds")
 	if not folder then
@@ -43,28 +46,58 @@ local function createSoundRegistry(definitions)
 		*
 		     * Plays a Sound
 		     * @param name Define which Sound should be played
+		     * @param spatial Array of Baseparts
 		     
 	]]
-	local function play(name)
-		load(name)
-		local sound = folder:FindFirstChild(name)
-		local _result = sound
-		if _result ~= nil then
-			_result:Play()
+	local function play(name, spatial)
+		local config = definitions[name]
+		if not spatial or not spatial.emitters then
+			load(name)
+			local sound = folder:FindFirstChild(name)
+			local _result = sound
+			if _result ~= nil then
+				_result:Play()
+			end
+			return nil
+		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
+			handle:play()
+			return handle
 		end
 	end
 	--[[
 		*
 		     * Stops a Sound
 		     * @param name Define which Sound should be stopped
+		     * @param spatial Array of Baseparts
 		     
 	]]
-	local function stop(name)
-		local sound = folder:FindFirstChild(name)
-		local _result = sound
-		if _result ~= nil then
-			_result:Stop()
+	local function stop(name, spatial)
+		if not spatial then
+			local sound = folder:FindFirstChild(name)
+			local _result = sound
+			if _result ~= nil then
+				_result:Stop()
+			end
+			return nil
+		end
+		local _name = name
+		local handle = spatialHandles[_name]
+		if not handle then
+			return nil
 		end
+		handle:stop()
+		handle:destroy()
+		local _name_1 = name
+		spatialHandles[_name_1] = nil
 	end
 	--[[
 		*
@@ -82,22 +115,44 @@ local function createSoundRegistry(definitions)
 		     * @param soundName Sound Instance
 		     * @param duration Time in Seconds
 		     * @param volume Volume
+		     * @param spatial Array of Baseparts
 		     
 	]]
-	local function fadeIn(soundName, duration, volume)
-		local sound = folder:FindFirstChild(soundName)
-		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)
+	local function fadeIn(soundName, duration, volume, spatial)
+		local config = definitions[soundName]
+		if not spatial or not spatial.emitters then
+			local sound = folder:FindFirstChild(soundName)
+			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)
+		else
+			local emittersArray = spatial.emitters
+			local _exp = config.id
+			local _condition = config.volume
+			if _condition == nil then
+				_condition = 1
 			end
-		end)
+			local handle = createSpatialHandle(_exp, emittersArray, _condition)
+			local _self = handle
+			local _result = _self.fadeIn
+			if _result ~= nil then
+				_result(_self, duration, volume)
+			end
+			if not config.loop == true then
+				handle:played(function()
+					handle:destroy()
+				end)
+			end
+		end
 	end
 	--[[
 		*
@@ -105,33 +160,55 @@ local function createSoundRegistry(definitions)
 		     * @param soundName Sound name from Registry
 		     * @param duration Time in seconds
 		     * @param targetVolume Optional target volume (default 0)
+		     * @param spatial Array of Baseparts
 		     
 	]]
-	local function fadeOut(soundName, duration, targetVolume)
-		local sound = folder:FindFirstChild(soundName)
-		if not sound then
-			return nil
-		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)
+	local function fadeOut(soundName, duration, targetVolume, spatial)
+		local config = definitions[soundName]
+		if not spatial or not spatial.emitters then
+			local sound = folder:FindFirstChild(soundName)
+			if not sound then
+				return nil
+			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)
+		else
+			local emittersArray = spatial.emitters
+			local _exp = config.id
+			local _condition = config.volume
+			if _condition == nil then
+				_condition = 1
 			end
-			sound.Volume = endVolume
-			if endVolume == 0 then
-				sound:Stop()
+			local handle = createSpatialHandle(_exp, emittersArray, _condition)
+			local _self = handle
+			local _result = _self.fadeOut
+			if _result ~= nil then
+				_result(_self, duration)
 			end
-		end)
+			if not config.loop == true then
+				handle:played(function()
+					handle:destroy()
+				end)
+			end
+		end
 	end
 	--[[
 		*
@@ -195,14 +272,21 @@ local function createSoundRegistry(definitions)
 		     * Set Sound Volume
 		     * @param sound Sound Instance
 		     * @param volume Sound Volume
+		     * @param spatial Array of Baseparts
 		     
 	]]
-	local function setVolume(sound, volume)
-		local _sound = folder:FindFirstChild(sound)
-		if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
-			return nil
+	local function setVolume(sound, volume, spatial)
+		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
+				return nil
+			end
+			_sound.Volume = volume
+		else
+			local emittersArray = spatial.emitters
+			local handle = createSpatialHandle(config.id, emittersArray, volume)
 		end
-		_sound.Volume = volume
 	end
 	--[[
 		*

package/out/core/createSpatialHandle.d.ts

@@ -0,0 +1,7 @@
+import { SoundHandle } from "./options";
+/**
+ * Create a Spatial Handle
+ * @param assetId Asset ID
+ * @param emitters Emitter
+ */
+export declare function createSpatialHandle(assetId: string, emitters: BasePart[], volume: number): SoundHandle;

package/out/core/createSpatialHandle.luau

@@ -0,0 +1,59 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _functions = TS.import(script, script.Parent.Parent, "utils", "functions")
+local fadeIn = _functions.fadeIn
+local fadeOut = _functions.fadeOut
+--[[
+	*
+	 * Create a Spatial Handle
+	 * @param assetId Asset ID
+	 * @param emitters Emitter
+	 
+]]
+local function createSpatialHandle(assetId, emitters, volume)
+	local player = Instance.new("AudioPlayer")
+	player.Asset = assetId
+	player.Volume = volume
+	player.Parent = game:GetService("ReplicatedStorage")
+	local emitterInstances = {}
+	for _, part in emitters do
+		local emitter = Instance.new("AudioEmitter")
+		emitter.Parent = part
+		local wire = Instance.new("Wire")
+		wire.SourceInstance = player
+		wire.TargetInstance = emitter
+		wire.Parent = emitter
+		table.insert(emitterInstances, emitter)
+	end
+	return {
+		play = function(self)
+			player:Play()
+		end,
+		stop = function(self)
+			player:Stop()
+		end,
+		fadeIn = function(self, duration, volume)
+			fadeIn(player, volume, duration)
+		end,
+		fadeOut = function(self, duration)
+			fadeOut(player, duration)
+		end,
+		destroy = function(self)
+			player:Destroy()
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback = function(e)
+				return e:Destroy()
+			end
+			for _k, _v in emitterInstances do
+				_callback(_v, _k - 1, emitterInstances)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+		end,
+		played = function(self, callback)
+			player.Ended:Connect(callback)
+		end,
+	}
+end
+return {
+	createSpatialHandle = createSpatialHandle,
+}

package/out/core/options.d.ts

@@ -2,6 +2,18 @@ export interface SoundOptions {
     volume?: number;
     loop?: boolean;
     id: string;
+    spatial?: {
+        attenuation?: number;
+        directional?: boolean;
+    };
+}
+export interface SoundHandle {
+    play(): void;
+    stop(): void;
+    fadeIn?(duration: number, volume: number): void;
+    fadeOut?(duration: number): void;
+    destroy(): void;
+    played(callback: () => void): void;
 }
 interface SoundDefinition {
     id: string;

package/out/utils/functions.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fades in a Sound
+ * @param player AudioPlayer
+ * @param targetVolume Target volume
+ * @param duration Duration
+ */
+export declare function fadeIn(player: AudioPlayer, targetVolume: number, duration: number): void;
+/**
+ * Smoothly fades out a Sound
+ * @param player AudioPlayer
+ * @param duration Duration
+ */
+export declare function fadeOut(player: AudioPlayer, duration: number): void;

package/out/utils/functions.luau

@@ -0,0 +1,47 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Fades in a Sound
+	 * @param player AudioPlayer
+	 * @param targetVolume Target volume
+	 * @param duration Duration
+	 
+]]
+local function fadeIn(player, targetVolume, duration)
+	player.Volume = 0
+	player:Play()
+	local steps = 20
+	task.spawn(function()
+		for i = 0, steps do
+			player.Volume = (i / steps) * targetVolume
+			task.wait(duration / steps)
+		end
+	end)
+end
+--[[
+	*
+	 * Smoothly fades out a Sound
+	 * @param player AudioPlayer
+	 * @param duration Duration
+	 
+]]
+local function fadeOut(player, duration)
+	local _condition = player.Volume
+	if _condition == nil then
+		_condition = 1
+	end
+	local startVolume = _condition
+	local steps = 20
+	local interval = duration / steps
+	task.spawn(function()
+		for i = steps, 0, -1 do
+			player.Volume = (i / steps) * startVolume
+			task.wait(interval)
+		end
+		player:Stop()
+	end)
+end
+return {
+	fadeIn = fadeIn,
+	fadeOut = fadeOut,
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@rbxts/sound-manager",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "A sound manager for Roblox-Typescript projects.",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",
     "watch": "rbxtsc -w",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "start": "npm pack && npm run watch"
   },
   "keywords": [],
   "author": "Easy-Build-Studio",