@quenty/soundgroup 1.26.0 → 1.26.1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.26.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/soundgroup@1.26.0...@quenty/soundgroup@1.26.1) (2026-01-05)
+
+
+### Bug Fixes
+
+* Update the sound group package to include sound volume multipliers ([bf9591f](https://github.com/Quenty/NevermoreEngine/commit/bf9591fe2d08dbefae47f8c449b7bbf20c01fdfe))
+
+
+
+
+
 # [1.26.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/soundgroup@1.25.8...@quenty/soundgroup@1.26.0) (2026-01-04)
 
 **Note:** Version bump only for package @quenty/soundgroup

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2025 James Onnen (Quenty)
+Copyright (c) 2014-2026 James Onnen (Quenty)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/soundgroup",
-  "version": "1.26.0",
+  "version": "1.26.1",
   "description": "Service and utility methods to working with sound groups and sounds in Roblox",
   "keywords": [
     "Roblox",
@@ -26,20 +26,24 @@
   ],
   "dependencies": {
     "@quenty/baseobject": "^10.9.1",
+    "@quenty/binder": "^14.26.1",
     "@quenty/brio": "^14.21.0",
-    "@quenty/counter": "^7.22.0",
+    "@quenty/counter": "^7.22.1",
     "@quenty/instanceutils": "^13.21.0",
     "@quenty/loader": "^10.9.1",
     "@quenty/maid": "^3.5.1",
-    "@quenty/observablecollection": "^12.25.0",
+    "@quenty/observablecollection": "^12.25.1",
+    "@quenty/promise": "^10.12.4",
+    "@quenty/rogue-properties": "^11.31.1",
     "@quenty/rx": "^13.21.0",
     "@quenty/servicebag": "^11.13.4",
     "@quenty/signal": "^7.11.3",
     "@quenty/table": "^3.9.0",
-    "@quenty/valueobject": "^13.22.0"
+    "@quenty/tie": "^10.27.1",
+    "@quenty/valueobject": "^13.22.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "22144a14aa443a177ff307edd3813a838f8c1d5f"
+  "gitHead": "5232cd2c58ca0dcdf591dd8ae78995211da2f3e2"
 }

package/src/Client/SoundGroupServiceClient.lua

@@ -16,6 +16,10 @@ function SoundGroupServiceClient:Init(serviceBag: ServiceBag.ServiceBag)
 	self._serviceBag = assert(serviceBag, "No serviceBag")
 	self._maid = Maid.new()
 
+	-- External
+	self._serviceBag:GetService(require("TieRealmService"))
+	self._serviceBag:GetService(require("RoguePropertyService"))
+
 	-- Internal
 	self._serviceBag:GetService(require("SoundEffectService"))
 end

package/src/Server/SoundGroupService.lua

@@ -17,6 +17,10 @@ function SoundGroupService:Init(serviceBag: ServiceBag.ServiceBag)
 	self._serviceBag = assert(serviceBag, "No serviceBag")
 	self._maid = Maid.new()
 
+	-- External
+	self._serviceBag:GetService(require("TieRealmService"))
+	self._serviceBag:GetService(require("RoguePropertyService"))
+
 	-- Internal
 	self._soundEffectService = self._serviceBag:GetService(require("SoundEffectService"))
 end

package/src/Shared/SoundEffectService.lua

@@ -1,4 +1,4 @@
---!nonstrict
+--!strict
 --[=[
 	Handles applying global volume and effects to specific sounds in a group based upon a path.
 
@@ -11,25 +11,46 @@ local RunService = game:GetService("RunService")
 local SoundService = game:GetService("SoundService")
 
 local Maid = require("Maid")
+local Promise = require("Promise")
 local ServiceBag = require("ServiceBag")
+local SoundEffectsList = require("SoundEffectsList")
 local SoundEffectsRegistry = require("SoundEffectsRegistry")
 local SoundGroupPathUtils = require("SoundGroupPathUtils")
 local SoundGroupTracker = require("SoundGroupTracker")
+local SoundGroupVolume = require("SoundGroupVolume")
 local WellKnownSoundGroups = require("WellKnownSoundGroups")
 
 local SoundEffectService = {}
 SoundEffectService.ServiceName = "SoundEffectService"
 
-function SoundEffectService:Init(serviceBag: ServiceBag.ServiceBag)
-	assert(not self._serviceBag, "Already initialized")
+export type SoundEffectService = typeof(setmetatable(
+	{} :: {
+		_serviceBag: ServiceBag.ServiceBag,
+		_maid: Maid.Maid,
+		_soundEffectsRegister: any, -- SoundEffectsRegistry.SoundEffectsRegistry,
+		_tracker: any, -- SoundGroupTracker.SoundGroupTracker,
+	},
+	{} :: typeof({ __index = SoundEffectService })
+))
+
+function SoundEffectService.Init(self: SoundEffectService, serviceBag: ServiceBag.ServiceBag)
+	assert(not (self :: any)._serviceBag, "Already initialized")
 	self._serviceBag = assert(serviceBag, "No serviceBag")
 	self._maid = Maid.new()
 
+	-- External
+	self._serviceBag:GetService(require("TieRealmService"))
+	self._serviceBag:GetService(require("RoguePropertyService"))
+
+	-- State
 	self._soundEffectsRegister = self._maid:Add(SoundEffectsRegistry.new())
 	self._tracker = self._maid:Add(SoundGroupTracker.new(SoundService))
+
+	-- Binders
+	self._serviceBag:GetService(require("SoundGroupVolume"))
 end
 
-function SoundEffectService:Start()
+function SoundEffectService.Start(self: SoundEffectService): ()
 	self:_setupEffectApplication()
 end
 
@@ -38,14 +59,42 @@ end
 	@param sound Sound
 	@param soundGroupPath string? -- Optional
 ]=]
-function SoundEffectService:RegisterSFX(sound: Sound, soundGroupPath: string?)
+function SoundEffectService.RegisterSFX(self: SoundEffectService, sound: Sound, soundGroupPath: string): ()
 	assert(typeof(sound) == "Instance" and sound:IsA("Sound"), "Bad sound")
 	assert(SoundGroupPathUtils.isSoundGroupPath(soundGroupPath) or soundGroupPath == nil, "Bad soundGroupPath")
 
 	sound.SoundGroup = self:GetOrCreateSoundGroup(soundGroupPath or WellKnownSoundGroups.SFX)
 end
 
-function SoundEffectService:GetOrCreateSoundGroup(soundGroupPath: string): SoundGroup
+--[=[
+	Creates a NumberValue multiplier for the given sound group path.
+
+	Destroy (or unparent) the returned NumberValue to remove the multiplier.
+
+	@param soundGroupPath string
+	@return Promise<NumberValue>
+]=]
+function SoundEffectService:PromiseCreateVolumeMultiplier(soundGroupPath: string): Promise.Promise<NumberValue>
+	local soundGroup = self:GetOrCreateSoundGroup(soundGroupPath)
+	if soundGroup == nil then
+		return Promise.rejected("Failed to get or create sound group for path: " .. soundGroupPath)
+	end
+
+	local soundGroupVolumeBinder = self._serviceBag:GetService(require("SoundGroupVolume"))
+	soundGroupVolumeBinder:Tag(soundGroup)
+
+	return soundGroupVolumeBinder:Promise(soundGroup):Then(function(soundGroupVolume)
+		return soundGroupVolume:CreateMultiplier()
+	end)
+end
+
+--[=[
+	Returns the SoundGroup for the given path, creating it if it does not exist.
+
+	@param soundGroupPath string
+	@return SoundGroup
+]=]
+function SoundEffectService.GetOrCreateSoundGroup(self: SoundEffectService, soundGroupPath: string): SoundGroup
 	assert(SoundGroupPathUtils.isSoundGroupPath(soundGroupPath), "Bad soundGroupPath")
 
 	local found = self:GetSoundGroup(soundGroupPath)
@@ -54,10 +103,21 @@ function SoundEffectService:GetOrCreateSoundGroup(soundGroupPath: string): Sound
 	end
 
 	-- Handle deferred mode
-	return SoundGroupPathUtils.findOrCreateSoundGroup(soundGroupPath)
+	found = SoundGroupPathUtils.findOrCreateSoundGroup(soundGroupPath)
+	assert(found, "Failed to create sound group for path")
+
+	SoundGroupVolume:Tag(found)
+
+	return found
 end
 
-function SoundEffectService:GetSoundGroup(soundGroupPath: string): SoundGroup
+--[=[
+	Returns the SoundGroup for the given path, or nil if it does not exist.
+
+	@param soundGroupPath string
+	@return SoundGroup
+]=]
+function SoundEffectService.GetSoundGroup(self: SoundEffectService, soundGroupPath: string): SoundGroup?
 	assert(SoundGroupPathUtils.isSoundGroupPath(soundGroupPath), "Bad soundGroupPath")
 
 	if not self._tracker then
@@ -71,27 +131,41 @@ function SoundEffectService:GetSoundGroup(soundGroupPath: string): SoundGroup
 
 	local found = self._tracker:GetFirstSoundGroup(soundGroupPath)
 	if found then
+		SoundGroupVolume:Tag(found)
 		return found
 	end
 
-	return SoundGroupPathUtils.findOrCreateSoundGroup(soundGroupPath)
+	found = SoundGroupPathUtils.findSoundGroup(soundGroupPath)
+	if found then
+		SoundGroupVolume:Tag(found)
+	end
+
+	return found
 end
 
-function SoundEffectService:PushEffect(soundGroupPath: string, effect)
+function SoundEffectService.PushEffect(
+	self: SoundEffectService,
+	soundGroupPath: string,
+	effect: SoundEffectsList.SoundEffectApplier
+): ()
 	assert(SoundGroupPathUtils.isSoundGroupPath(soundGroupPath), "Bad soundGroupPath")
 	assert(type(effect) == "function", "Bad effect")
 
 	return self._soundEffectsRegister:PushEffect(soundGroupPath, effect)
 end
 
-function SoundEffectService:ApplyEffects(soundGroupPath, instance)
+function SoundEffectService.ApplyEffects(
+	self: SoundEffectService,
+	soundGroupPath: string,
+	instance: SoundGroup | Sound
+): () -> ()
 	assert(SoundGroupPathUtils.isSoundGroupPath(soundGroupPath), "Bad soundGroupPath")
 	assert(typeof(instance) == "Instance" and (instance:IsA("SoundGroup") or instance:IsA("Sound")), "Bad instance")
 
 	return self._soundEffectsRegister:ApplyEffects(soundGroupPath, instance)
 end
 
-function SoundEffectService:_setupEffectApplication()
+function SoundEffectService._setupEffectApplication(self: SoundEffectService): ()
 	self._maid:GiveTask(self._tracker:ObserveSoundGroupsBrio():Subscribe(function(brio)
 		if brio:IsDead() then
 			return
@@ -102,7 +176,7 @@ function SoundEffectService:_setupEffectApplication()
 			if soundGroupPath then
 				maid._currentEffects = self._soundEffectsRegister:ApplyEffects(soundGroupPath, soundGroup)
 			else
-				maid._currentEffects = nil
+				maid._currentEffects = nil :: any
 			end
 		end))
 	end))
@@ -122,7 +196,7 @@ function SoundEffectService:_setupEffectApplication()
 	end))
 end
 
-function SoundEffectService:Destroy()
+function SoundEffectService.Destroy(self: SoundEffectService): ()
 	self._maid:DoCleaning()
 end
 

package/src/Shared/Volume/SoundGroupVolume.lua

@@ -0,0 +1,65 @@
+--!strict
+local SoundGroupVolumeInterface = require(script.Parent.SoundGroupVolumeInterface)
+--[=[
+	@class SoundGroupVolume
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local BaseObject = require("BaseObject")
+local Binder = require("Binder")
+local ServiceBag = require("ServiceBag")
+local SoundGroupVolumeProperties = require("SoundGroupVolumeProperties")
+local TieRealms = require("TieRealms")
+
+local SoundGroupVolume = setmetatable({}, BaseObject)
+SoundGroupVolume.ClassName = "SoundGroupVolume"
+SoundGroupVolume.__index = SoundGroupVolume
+
+export type SoundGroupVolume =
+	typeof(setmetatable(
+		{} :: {
+			_obj: SoundGroup,
+			_serviceBag: ServiceBag.ServiceBag,
+			_tieRealmService: any,
+			_properties: any,
+			RenderedVolume: any,
+		},
+		{} :: typeof({ __index = SoundGroupVolume })
+	))
+	& BaseObject.BaseObject
+
+function SoundGroupVolume.new(instance: SoundGroup, serviceBag: ServiceBag.ServiceBag): SoundGroupVolume
+	local self: SoundGroupVolume = setmetatable(BaseObject.new(instance) :: any, SoundGroupVolume)
+
+	self._serviceBag = assert(serviceBag, "No serviceBag")
+	self._tieRealmService = self._serviceBag:GetService(require("TieRealmService"))
+
+	self._properties = SoundGroupVolumeProperties:Get(self._serviceBag, self._obj)
+	self.RenderedVolume = self._properties.Volume
+
+	self._maid:GiveTask(SoundGroupVolumeInterface:Implement(self._obj, self, self._tieRealmService:GetTieRealm()))
+
+	-- Assign our volume to the current volume if we're on the server
+	if self._tieRealmService:GetTieRealm() == TieRealms.SERVER then
+		self._properties.Volume:SetBaseValue(self._obj.Volume)
+	end
+
+	self._maid:GiveTask(self._properties.Volume:Observe():Subscribe(function(volume)
+		self._obj.Volume = volume
+	end))
+
+	return self
+end
+
+--[=[
+	Creates a volume multiplier for this sound group volume.
+
+	@param amount number?
+	@return NumberValue
+]=]
+function SoundGroupVolume.CreateMultiplier(self: SoundGroupVolume, amount: number?): NumberValue
+	return self._properties.Volume:CreateMultiplier(amount or 1)
+end
+
+return Binder.new("SoundGroupVolume", SoundGroupVolume :: any) :: Binder.Binder<SoundGroupVolume>

package/src/Shared/Volume/SoundGroupVolumeInterface.lua

@@ -0,0 +1,12 @@
+--!strict
+--[=[
+    @class SoundGroupVolumeInterface
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local TieDefinition = require("TieDefinition")
+
+return TieDefinition.new("SoundGroupVolume", {
+	CreateMultiplier = TieDefinition.Types.METHOD,
+})

package/src/Shared/Volume/SoundGroupVolumeProperties.lua

@@ -0,0 +1,12 @@
+--!strict
+--[=[
+	@class SoundGroupVolumeProperties
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local RoguePropertyTableDefinition = require("RoguePropertyTableDefinition")
+
+return RoguePropertyTableDefinition.new("SoundGroupVolume", {
+	Volume = 1,
+})