fix: Update the sound group package to include sound volume multipliers

Author: Quenty

src/soundgroups/package.json

@@ -26,16 +26,20 @@
   ],
   "dependencies": {
     "@quenty/baseobject": "file:../baseobject",
+    "@quenty/binder": "file:../binder",
     "@quenty/brio": "file:../brio",
     "@quenty/counter": "file:../counter",
     "@quenty/instanceutils": "file:../instanceutils",
     "@quenty/loader": "file:../loader",
     "@quenty/maid": "file:../maid",
     "@quenty/observablecollection": "file:../observablecollection",
+    "@quenty/promise": "file:../promise",
+    "@quenty/rogue-properties": "file:../rogue-properties",
     "@quenty/rx": "file:../rx",
     "@quenty/servicebag": "file:../servicebag",
     "@quenty/signal": "file:../signal",
     "@quenty/table": "file:../table",
+    "@quenty/tie": "file:../tie",
     "@quenty/valueobject": "file:../valueobject"
   },
   "publishConfig": {

src/soundgroups/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

src/soundgroups/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

src/soundgroups/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
 

src/soundgroups/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>

src/soundgroups/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,
+})

src/soundgroups/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,
+})