@rbxts/sound-manager 1.0.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lukas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,17 +1,29 @@
-# Sound Manager
-
-A Roblox sound management library built with Roblox-TS
-
-## 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
-import { Sounds } from "@rbxts/sound-manager";
-
-Sounds.load("TestSound", "rbxassetid://4714389545", { volume: 1, loop: false });     
-Sounds.play("TestSound")
-```
+# Sound Manager
+
+A Roblox sound management library built with Roblox-TS
+
+## 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
+import { createSoundRegistry } from "@rbxts/sound-manager";
+
+const Sounds = createSoundRegistry({
+    SCP096: {
+        id: "rbxassetid://4714389545",
+        volume: 1,
+        loop: false,
+    } 
+});
+
+Sounds.preloadAll();
+
+Sounds.play("SCP096");
+```
+
+For more Details:
+https://dev-lukas0.github.io/Sound-Manager-Docs/

package/out/core/createSoundCategoryRegistry.d.ts

@@ -0,0 +1,9 @@
+import { CategoryOptions } 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;
+};

package/out/core/createSoundCategoryRegistry.luau

@@ -0,0 +1,85 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Create a sound category Registry
+	 * @param definitions Define the Categorys
+	 
+]]
+local function createSoundCategoryRegistry(definitions)
+	local ReplicatedStorage = game:GetService("ReplicatedStorage")
+	local folder = ReplicatedStorage:FindFirstChild("Sounds")
+	if not folder then
+		folder = Instance.new("Folder")
+		folder.Name = "Sounds"
+		folder.Parent = ReplicatedStorage
+	end
+	--[[
+		*
+		     * Loads a Category
+		     * @param name Define which Sound Category should be loaded
+		     
+	]]
+	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
+			category = Instance.new("Folder")
+			category.Name = config.category
+			category.Parent = folder
+		end
+		for sound, soundConfig in pairs(config.sounds) do
+			if category:FindFirstChild(sound) then
+				continue
+			end
+			local newSound = Instance.new("Sound")
+			newSound.Name = sound
+			newSound.SoundId = soundConfig.id
+			local _condition = soundConfig.volume
+			if _condition == nil then
+				_condition = 1
+			end
+			newSound.Volume = _condition
+			local _condition_1 = soundConfig.loop
+			if _condition_1 == nil then
+				_condition_1 = false
+			end
+			newSound.Looped = _condition_1
+			newSound.Parent = category
+		end
+	end
+	--[[
+		*
+		     * Play every Sound from a Sound Category
+		     * @param name Sound Category
+		     
+	]]
+	local function playCategory(name)
+		loadCategory(name)
+		local config = definitions[name]
+		local ReplicatedStorage = game:GetService("ReplicatedStorage")
+		local folder = ReplicatedStorage:FindFirstChild(config.category)
+		for sound in pairs(config.sounds) do
+			local _sound = folder:FindFirstChild(sound)
+			if not _sound then
+				continue
+			end
+			local _result = _sound
+			if _result ~= nil then
+				_result = _result:IsA("Sound")
+			end
+			if _result then
+				_sound:Play()
+			end
+		end
+	end
+	return {
+		loadCategory = loadCategory,
+		playCategory = playCategory,
+	}
+end
+return {
+	createSoundCategoryRegistry = createSoundCategoryRegistry,
+}

package/out/core/createSoundRegistry.d.ts

@@ -0,0 +1,21 @@
+import { 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;
+    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;
+    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;
+    resetAll: (sound: keyof T) => void;
+    onEnd: (sound: keyof T, callback: () => void) => void;
+};

package/out/core/createSoundRegistry.luau

@@ -0,0 +1,265 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Create a sound Registry
+	 * @param definitions Define the Sounds
+	 
+]]
+local function createSoundRegistry(definitions)
+	local ReplicatedStorage = game:GetService("ReplicatedStorage")
+	local folder = ReplicatedStorage:FindFirstChild("Sounds")
+	if not folder then
+		folder = Instance.new("Folder")
+		folder.Name = "Sounds"
+		folder.Parent = ReplicatedStorage
+	end
+	--[[
+		*
+		     * Loads a Sound
+		     * @param name Define which Sound should be loaded
+		     
+	]]
+	local function load(name)
+		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
+	end
+	--[[
+		*
+		     * Plays a Sound
+		     * @param name Define which Sound should be played
+		     
+	]]
+	local function play(name)
+		load(name)
+		local sound = folder:FindFirstChild(name)
+		local _result = sound
+		if _result ~= nil then
+			_result:Play()
+		end
+	end
+	--[[
+		*
+		     * Stops a Sound
+		     * @param name Define which Sound should be stopped
+		     
+	]]
+	local function stop(name)
+		local sound = folder:FindFirstChild(name)
+		local _result = sound
+		if _result ~= nil then
+			_result:Stop()
+		end
+	end
+	--[[
+		*
+		     * Loads every Sound
+		     
+	]]
+	local function preloadAll()
+		for name in pairs(definitions) do
+			load(name)
+		end
+	end
+	--[[
+		*
+		     * Smoothly fad in a sound
+		     * @param soundName Sound Instance
+		     * @param duration Time in Seconds
+		     * @param volume Volume
+		     
+	]]
+	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)
+			end
+		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)
+		     
+	]]
+	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)
+			end
+			sound.Volume = endVolume
+			if endVolume == 0 then
+				sound:Stop()
+			end
+		end)
+	end
+	--[[
+		*
+		     * Reset a Sound
+		     * @param sound Sound Instance
+		     
+	]]
+	local function reset(sound)
+		local _sound = folder:FindFirstChild(sound)
+		if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
+			return nil
+		end
+		_sound.TimePosition = 0
+	end
+	--[[
+		*
+		     * Reset every Sound
+		     * @param sound Sound Instance
+		     
+	]]
+	local function resetAll(sound)
+		for _, sound in folder:GetChildren() do
+			if sound:IsA("Sound") then
+				sound.TimePosition = 0
+			end
+		end
+	end
+	--[[
+		*
+		     * Set Time Position
+		     * @param sound Sound Instance
+		     * @param timePosition Time Position
+		     
+	]]
+	local function setTimePosition(sound, timePosition)
+		local _sound = folder:FindFirstChild(sound)
+		if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
+			return nil
+		end
+		_sound.TimePosition = timePosition
+	end
+	--[[
+		*
+		     * Stop every Sound
+		     * @param reset Define whether every Sound should also be reset?
+		     
+	]]
+	local function stopAll(reset)
+		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
+	--[[
+		*
+		     * Set Sound Volume
+		     * @param sound Sound Instance
+		     * @param volume Sound Volume
+		     
+	]]
+	local function setVolume(sound, volume)
+		local _sound = folder:FindFirstChild(sound)
+		if not (sound ~= 0 and sound == sound and sound ~= "" and sound) then
+			return nil
+		end
+		_sound.Volume = volume
+	end
+	--[[
+		*
+		     * Set the global Sound Volume
+		     * @param volume Sound Volume
+		     
+	]]
+	local function setGlobalVolume(volume)
+		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
+	--[[
+		*
+		     * Plays Sound on Event Callback
+		     * @param name Sound Name
+		     * @param callback Callback
+		     
+	]]
+	local function onEnd(sound, callback)
+		local _sound = folder:WaitForChild(sound)
+		if not _sound then
+			return nil
+		end
+		_sound.Ended:Connect(callback)
+	end
+	--[[
+		*
+		     * Preloads a Sound
+		     * @param sound Sound Instance
+		     
+	]]
+	local function preload(sound)
+		load(sound)
+	end
+	return {
+		play = play,
+		stop = stop,
+		preloadAll = preloadAll,
+		load = load,
+		fadeIn = fadeIn,
+		fadeOut = fadeOut,
+		reset = reset,
+		setTimePosition = setTimePosition,
+		stopAll = stopAll,
+		preload = preload,
+		setGlobalVolume = setGlobalVolume,
+		setVolume = setVolume,
+		resetAll = resetAll,
+		onEnd = onEnd,
+	}
+end
+return {
+	createSoundRegistry = createSoundRegistry,
+}

package/out/core/options.d.ts

@@ -1,4 +1,15 @@
 export interface SoundOptions {
     volume?: number;
     loop?: boolean;
+    id: string;
 }
+interface SoundDefinition {
+    id: string;
+    volume?: number;
+    loop?: boolean;
+}
+export interface CategoryOptions {
+    category: string;
+    sounds: Record<string, SoundDefinition>;
+}
+export {};

package/out/index.d.ts

@@ -1,7 +1,2 @@
-import { SoundOptions } from "./core/options";
-export declare namespace Sounds {
-    /** * * @param sound Define the Sound to play */
-    function play(soundName: string): void;
-    /** * * @param soundname Define the name of the Sound * @param soundid Define the SoundID of the Sound * @param options Define the options for the Sound (e.g. volume) */
-    function load(soundName: string, soundId: string, options?: SoundOptions): void;
-}
+export * from "./core/createSoundRegistry";
+export * from "./core/createSoundCategoryRegistry";

package/out/init.luau

@@ -1,55 +1,10 @@
 -- Compiled with roblox-ts v3.0.0
-local Sounds = {}
-do
-	local _container = Sounds
-	--* * * @param sound Define the Sound to play 
-	local function play(soundName)
-		local soundFolder = game:GetService("ReplicatedStorage"):FindFirstChild("Sounds")
-		if not soundFolder then
-			warn("Sound folder not found in ReplicatedStorage.")
-			return nil
-		end
-		local _sound = soundFolder:FindFirstChild(soundName)
-		if _sound then
-			_sound:Play()
-		else
-			warn(`Sound: {soundName} not found! Make sure to load it first.`)
-		end
-	end
-	_container.play = play
-	--* * * @param soundname Define the name of the Sound * @param soundid Define the SoundID of the Sound * @param options Define the options for the Sound (e.g. volume) 
-	local function load(soundName, soundId, options)
-		local soundFolder = game:GetService("ReplicatedStorage"):FindFirstChild("Sounds")
-		if not soundFolder then
-			soundFolder = Instance.new("Folder")
-			soundFolder.Name = "Sounds"
-			soundFolder.Parent = game:GetService("ReplicatedStorage")
-		end
-		if soundFolder:FindFirstChild(soundName) then
-			warn(`Sound: {soundName} already exists.`)
-			return nil
-		end
-		local newSound = Instance.new("Sound")
-		newSound.Name = soundName
-		newSound.SoundId = soundId
-		newSound.Parent = soundFolder
-		local _result = options
-		if _result ~= nil then
-			_result = _result.volume
-		end
-		if _result ~= nil then
-			newSound.Volume = options.volume
-		end
-		local _result_1 = options
-		if _result_1 ~= nil then
-			_result_1 = _result_1.loop
-		end
-		if _result_1 ~= nil then
-			newSound.Looped = options.loop
-		end
-	end
-	_container.load = load
+local TS = _G[script]
+local exports = {}
+for _k, _v in TS.import(script, script, "core", "createSoundRegistry") or {} do
+	exports[_k] = _v
 end
-return {
-	Sounds = Sounds,
-}
+for _k, _v in TS.import(script, script, "core", "createSoundCategoryRegistry") or {} do
+	exports[_k] = _v
+end
+return exports

package/package.json

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