@quenty/settings 11.66.2 → 11.66.3

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [11.66.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/settings@11.66.2...@quenty/settings@11.66.3) (2026-07-27)
+
+### Bug Fixes
+
+- **settings:** stop settings hydration recursing until the C stack dies ([#757](https://github.com/Quenty/NevermoreEngine/issues/757)) ([d6ff0e3](https://github.com/Quenty/NevermoreEngine/commit/d6ff0e313c05ff618ca794dd4bdc70fb3e645f0a))
+
 ## [11.66.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/settings@11.66.1...@quenty/settings@11.66.2) (2026-07-27)
 
 **Note:** Version bump only for package @quenty/settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/settings",
-  "version": "11.66.2",
+  "version": "11.66.3",
   "description": "Centralized player settings service",
   "keywords": [
     "Roblox",
@@ -66,5 +66,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "b2fa2984c2ea6e83136e5a7cbf57b14038d9a265"
+  "gitHead": "bc810790774857f24f8c69095c521be4fd4f397f"
 }

package/src/Client/Player/PlayerSettingsClient.lua

@@ -224,6 +224,13 @@ function PlayerSettingsClient.SetValue<T>(self: PlayerSettingsClient, settingNam
 		end
 	end
 
+	-- A reader already sees this value -- queued, in transit, or replicated. Observers dedupe on value
+	-- themselves; returning rather than just skipping the notification is what also skips the
+	-- redundant round-trip to the server.
+	if self:_getCurrentValue(settingName) == value then
+		return
+	end
+
 	local queueReplication = false
 	local toReplicate
 	if self._toReplicate then
@@ -256,6 +263,21 @@ function PlayerSettingsClient.SetValue<T>(self: PlayerSettingsClient, settingNam
 	end
 end
 
+-- No default to fall back on, so "unset" stays distinguishable from "set to the default".
+function PlayerSettingsClient._getCurrentValue(self: PlayerSettingsClient, settingName: string): any
+	if self._toReplicate and self._toReplicate[settingName] ~= nil then
+		return PlayerSettingsUtils.decodeForNetwork(self._toReplicate[settingName])
+	end
+
+	local pending = self._pendingReplicationDataInTransit.Value
+	if pending and pending[settingName] ~= nil then
+		return PlayerSettingsUtils.decodeForNetwork(pending[settingName])
+	end
+
+	local attributeName = PlayerSettingsUtils.getAttributeName(settingName)
+	return PlayerSettingsUtils.decodeForAttribute(self._obj:GetAttribute(attributeName))
+end
+
 function PlayerSettingsClient._sendSettings(self: PlayerSettingsClient)
 	if not self._toReplicate then
 		warn("Nothing to save, should not have called this method")

package/src/Shared/Setting/SettingDefinition.lua

@@ -31,6 +31,11 @@ local Promise = require("Promise")
 local ServiceBag = require("ServiceBag")
 local SettingProperty = require("SettingProperty")
 local SettingsDataService = require("SettingsDataService")
+local Symbol = require("Symbol")
+
+-- Cache key for the local player before the DataModel can name them, when there is no Player to
+-- key on (see [SettingDefinition.GetSettingProperty]).
+local UNRESOLVED_LOCAL_PLAYER = Symbol.named("unresolvedLocalPlayer")
 
 local SettingDefinition = {}
 SettingDefinition.ClassName = "SettingDefinition"
@@ -43,6 +48,7 @@ export type SettingDefinition<T> = typeof(setmetatable(
 		_defaultValue: T,
 		_maid: Maid.Maid,
 		_serviceBag: ServiceBag.ServiceBag,
+		_settingPropertyCache: { [any]: { [any]: any } },
 		ServiceName: string,
 	},
 	{} :: typeof({ __index = SettingDefinition })
@@ -63,6 +69,7 @@ function SettingDefinition.new<T>(settingName: string, defaultValue: T): Setting
 
 	self._settingName = settingName
 	self._defaultValue = defaultValue
+	self._settingPropertyCache = setmetatable({}, { __mode = "k" }) :: any
 
 	self.ServiceName = self._settingName .. "SettingDefinition"
 
@@ -164,7 +171,9 @@ function SettingDefinition.isSettingDefinition(value: any): boolean
 end
 
 --[=[
-	Gets a new setting property for the given definition
+	Gets the setting property for this definition, reused per (serviceBag, player) -- callers commonly
+	ask per use, and constructing one costs an EnsureInitialized round-trip and its own observable
+	chain.
 
 	@param serviceBag ServiceBag
 	@param player Player
@@ -184,7 +193,22 @@ function SettingDefinition.GetSettingProperty<T>(
 	-- May still be nil in a non-running DataModel; SettingProperty resolves the local player lazily.
 	player = player or Players.LocalPlayer or PlayerMock.getMockedLocalPlayer()
 
-	return SettingProperty.new(serviceBag, player, self)
+	-- Weak throughout: a cached property must not keep its bag or player alive. The lazily-resolved
+	-- local player has no key of its own, hence the sentinel.
+	local byPlayer = self._settingPropertyCache[serviceBag]
+	if not byPlayer then
+		byPlayer = setmetatable({}, { __mode = "kv" }) :: any
+		self._settingPropertyCache[serviceBag] = byPlayer
+	end
+
+	local playerKey: any = player or UNRESOLVED_LOCAL_PLAYER
+	local property = byPlayer[playerKey]
+	if not property then
+		property = SettingProperty.new(serviceBag, player, self)
+		byPlayer[playerKey] = property
+	end
+
+	return property
 end
 
 --[=[

package/src/Shared/Setting/SettingDefinition.spec.lua

@@ -0,0 +1,145 @@
+--!strict
+--[[
+	Coverage for the setting property a definition hands out: reused per (serviceBag, player), and its
+	observable neither rebuilds nor re-emits when the tie behind it churns. Callers routinely ask for a
+	property inline, and a tie mints a new interface per subscription -- so without these, reading a
+	setting from inside another setting's observer fans out work on every emission.
+
+	A stub implementer stands in for PlayerSettingsClient, returning the default for everything: the
+	plumbing between definition, property, and cache is what is under test, not stored values.
+
+	@class SettingDefinition.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PlayerMock = require("PlayerMock")
+local PlayerSettingsInterface = require("PlayerSettingsInterface")
+local PlayerSettingsUtils = require("PlayerSettingsUtils")
+local Rx = require("Rx")
+local ServiceBag = require("ServiceBag")
+local SettingDefinition = require("SettingDefinition")
+local SettingsDataService = require("SettingsDataService")
+local TieRealmUtils = require("TieRealmUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local SETTING_NAME = "TestSetting"
+local DEFAULT_VALUE = false
+
+local function setup()
+	local maid = Maid.new()
+
+	local serviceBag = maid:Add(ServiceBag.new())
+	-- Requested up front: SettingProperty only resolves it lazily, which a started bag rejects.
+	serviceBag:GetService(SettingsDataService)
+	serviceBag:Init()
+	serviceBag:Start()
+
+	-- Settings are not hydrated for a player outside the DataModel.
+	local player = maid:Add(PlayerMock.new())
+	player.Parent = Workspace
+
+	local folder = maid:Add(PlayerSettingsUtils.create())
+	folder.Parent = player
+
+	local implementer = {
+		GetPlayer = function()
+			return player
+		end,
+		GetValue = function(_self, _settingName, defaultValue)
+			return defaultValue
+		end,
+		ObserveValue = function(_self, _settingName, defaultValue)
+			return Rx.of(defaultValue)
+		end,
+		EnsureInitialized = function() end,
+		GetSettingProperty = function() end,
+		SetValue = function() end,
+		RestoreDefault = function() end,
+	}
+
+	local implementationMaid = maid:Add(Maid.new())
+	local function implement()
+		implementationMaid._current =
+			PlayerSettingsInterface:Implement(folder, implementer, TieRealmUtils.inferTieRealm())
+	end
+	implement()
+
+	return {
+		serviceBag = serviceBag,
+		player = player,
+		definition = SettingDefinition.new(SETTING_NAME, DEFAULT_VALUE),
+		-- Swaps in an equivalent implementation -- the container churn that mints the new interface
+		-- identity downstream sees.
+		reimplement = implement,
+		destroy = function(_self)
+			maid:DoCleaning()
+		end,
+	}
+end
+
+describe("SettingDefinition.GetSettingProperty", function()
+	it("reuses the property for the same serviceBag and player", function()
+		local controller = setup()
+
+		local first = controller.definition:GetSettingProperty(controller.serviceBag, controller.player)
+		local second = controller.definition:GetSettingProperty(controller.serviceBag, controller.player)
+
+		expect(second).toBe(first)
+
+		controller:destroy()
+	end)
+
+	it("keeps a separate property per player", function()
+		local controller = setup()
+		local otherPlayer = PlayerMock.new()
+		otherPlayer.Parent = Workspace
+
+		local property = controller.definition:GetSettingProperty(controller.serviceBag, controller.player)
+		local otherProperty = controller.definition:GetSettingProperty(controller.serviceBag, otherPlayer)
+
+		expect(otherProperty).never.toBe(property)
+
+		otherPlayer:Destroy()
+		controller:destroy()
+	end)
+end)
+
+describe("SettingProperty.Observe", function()
+	it("reuses the observable across calls", function()
+		local controller = setup()
+		local property = controller.definition:GetSettingProperty(controller.serviceBag, controller.player)
+
+		expect(property:Observe()).toBe(property:Observe())
+
+		controller:destroy()
+	end)
+
+	it("does not re-emit when the tie churns but the value does not", function()
+		local controller = setup()
+		local property = controller.definition:GetSettingProperty(controller.serviceBag, controller.player)
+
+		local emissions = 0
+		local maid = Maid.new()
+		maid:GiveTask(property:Observe():Subscribe(function()
+			emissions += 1
+		end))
+
+		expect(emissions).toBe(1)
+
+		controller.reimplement()
+		controller.reimplement()
+
+		expect(emissions).toBe(1)
+
+		maid:DoCleaning()
+		controller:destroy()
+	end)
+end)

package/src/Shared/Setting/SettingProperty.lua

@@ -72,7 +72,12 @@ end
 	@return Observable<T>
 ]=]
 function SettingProperty.Observe<T>(self: SettingProperty<T>): Observable.Observable<T>
-	return self:_observePlayerSettings():Pipe({
+	local found = rawget(self :: any, "_observeCache")
+	if found then
+		return found
+	end
+
+	local observe = self:_observePlayerSettings():Pipe({
 		Rx.where(function(settings)
 			return settings ~= nil
 		end),
@@ -92,7 +97,14 @@ function SettingProperty.Observe<T>(self: SettingProperty<T>): Observable.Observ
 				)
 			end
 		end) :: any,
+		-- The tie mints a new interface per subscription, so the switchMap above re-emits on churn that
+		-- never changed the value -- and observers that read other settings while handling one turn
+		-- each re-emit into a loop.
+		Rx.distinct() :: any,
+		Rx.cache() :: any,
 	}) :: any
+	rawset(self :: any, "_observeCache", observe)
+	return observe
 end
 
 (SettingProperty :: any).__index = function(self, index): any

package/src/Shared/SettingsDataService.lua

@@ -33,6 +33,7 @@ export type SettingsDataService = typeof(setmetatable(
 		_settingDefinitions: ObservableSet.ObservableSet<any>,
 		_playerSettingsCacheMap: ObservableMap.ObservableMap<Player, any>,
 		_hydratedPlayersMaid: Maid.Maid,
+		_hydratingPlayers: { [Player]: boolean },
 	},
 	{} :: typeof({ __index = SettingsDataService })
 ))
@@ -64,33 +65,71 @@ function SettingsDataService._getPlayerSettingsCacheMap(
 
 	self._playerSettingsCacheMap = self._maid:Add(ObservableMap.new() :: ObservableMap.ObservableMap<Player, any>)
 	self._hydratedPlayersMaid = self._maid:Add(Maid.new())
+	self._hydratingPlayers = {}
 
 	self._maid:GiveTask(Players.PlayerRemoving:Connect(function(player: Player)
-		self._hydratedPlayersMaid[player] = nil
+		self:_onPlayerRemoving(player)
 	end))
 
 	return (self._playerSettingsCacheMap :: any) :: ObservableMap.ObservableMap<Player, any>
 end
 
+-- Split out from the Players.PlayerRemoving connection above, which no test can make the engine fire.
+function SettingsDataService._onPlayerRemoving(self: SettingsDataService, player: Player): ()
+	-- Dropping the hydration emits into live observers, and a settings read from one of those handlers
+	-- lands back in [_getPlayerSettingsMapForPlayer], rebuilding the tie for a player on their way out.
+	-- So a tombstone claims the slot across the teardown instead of clearing it, and drops itself once
+	-- the player is really out of the DataModel and nothing can reach these settings again.
+	local tombstone = Maid.new()
+	tombstone:GiveTask(player.AncestryChanged:Connect(function()
+		if not player:IsDescendantOf(game) then
+			self._hydratedPlayersMaid[player] = nil
+		end
+	end))
+
+	self._hydratedPlayersMaid[player] = tombstone
+end
+
 function SettingsDataService._getPlayerSettingsMapForPlayer(
 	self: SettingsDataService,
 	player: Player
 ): ObservableMap.ObservableMap<Player, any>
 	local playerSettingsCacheMap = self:_getPlayerSettingsCacheMap()
 
+	-- Claimed already: either hydrated, or tombstoned by a departure (see [_onPlayerRemoving]).
 	if self._hydratedPlayersMaid[player] then
 		return playerSettingsCacheMap
 	end
 
+	-- Gone for good, and the tombstone has already dropped itself: their settings folder went with
+	-- them, so claiming a slot would only hold onto a departed player.
+	if not player:IsDescendantOf(game) then
+		return playerSettingsCacheMap
+	end
+
 	-- Note we only do this as requested to save memory. On the client, we're unlikely
 	-- to even query other player's settings.
-	self._hydratedPlayersMaid[player] = self:_hydrateCacheForPlayer(player)
+	--
+	-- Claim the slot before hydrating, not after: hydration emits synchronously, and a settings read
+	-- from that emission lands back here. Memoizing afterwards left the slot empty for the whole
+	-- emission, so each such read hydrated again -- minting a fresh tie interface the cache map cannot
+	-- dedupe by identity, so it re-emitted and recursed until the C stack died.
+	local playerMaid = Maid.new()
+	self._hydratedPlayersMaid[player] = playerMaid
+	self:_hydrateCacheForPlayer(player, playerMaid)
 
 	return playerSettingsCacheMap
 end
 
-function SettingsDataService._hydrateCacheForPlayer(self: SettingsDataService, player: Player): Maid.Maid
-	local playerMaid = Maid.new()
+function SettingsDataService._hydrateCacheForPlayer(
+	self: SettingsDataService,
+	player: Player,
+	playerMaid: Maid.Maid
+): ()
+	-- Tripwire for the crash: hydrating while a hydration is still on the stack is what used to
+	-- recurse. Unreachable now that the slot is claimed first, so firing means the claim was cleared.
+	assert(not self._hydratingPlayers[player], "[SettingsDataService] - Re-entrant hydration for player")
+	self._hydratingPlayers[player] = true
 
 	playerMaid:GiveTask((RxInstanceUtils.observeChildrenBrio(player, function(value): any
 		-- We really only care about this, and we can assume we have the tag immediately
@@ -107,10 +146,14 @@ function SettingsDataService._hydrateCacheForPlayer(self: SettingsDataService, p
 			end
 
 			local maid, playerSettings = brio:ToMaidAndValue()
-			maid:GiveTask(self._playerSettingsCacheMap:Set(playerSettings:GetPlayer(), playerSettings))
+
+			-- Keyed off the player we hydrated for, not `playerSettings:GetPlayer()`: we only observe
+			-- this player's children, so the tie call can only return `player` again -- at the cost of
+			-- a bindable round-trip per emission, and a nil key if the folder reparents.
+			maid:GiveTask(self._playerSettingsCacheMap:Set(player, playerSettings))
 		end))
 
-	return playerMaid
+	self._hydratingPlayers[player] = nil
 end
 
 --[=[

package/src/Shared/SettingsDataService.spec.lua

@@ -0,0 +1,181 @@
+--!strict
+--[[
+	Coverage for settings cache hydration, which used to recurse until the C stack died: the per-player
+	memo was only filled after hydration returned, so a read arriving during hydration's own
+	synchronous emission hydrated again -- and each subscription mints a fresh tie interface, so the
+	cache map re-emitted and fed the next read.
+
+	A stub implementer stands in for PlayerSettingsClient: the tie plumbing is what is under test, not
+	the settings themselves.
+
+	@class SettingsDataService.spec.lua
+]]
+
+local require = require(script.Parent.loader).load(script)
+
+local Workspace = game:GetService("Workspace")
+
+local Jest = require("Jest")
+local Maid = require("Maid")
+local PlayerMock = require("PlayerMock")
+local PlayerSettingsInterface = require("PlayerSettingsInterface")
+local PlayerSettingsUtils = require("PlayerSettingsUtils")
+local ServiceBag = require("ServiceBag")
+local SettingsDataService = require("SettingsDataService")
+local TieRealmUtils = require("TieRealmUtils")
+
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local function setup()
+	local maid = Maid.new()
+
+	local serviceBag = maid:Add(ServiceBag.new())
+	local settingsDataService: SettingsDataService.SettingsDataService =
+		serviceBag:GetService(SettingsDataService) :: any
+	serviceBag:Init()
+	serviceBag:Start()
+
+	-- Parented so a test can take it back out, the way a departing player leaves Players.
+	local player = maid:Add(PlayerMock.new())
+	player.Parent = Workspace
+
+	local getPlayerCalls = 0
+
+	local folder = maid:Add(PlayerSettingsUtils.create())
+	folder.Parent = player
+
+	maid:Add(PlayerSettingsInterface:Implement(folder, {
+		GetPlayer = function()
+			getPlayerCalls += 1
+			return player
+		end,
+		-- The rest only has to exist for the implementation to be valid.
+		GetSettingProperty = function() end,
+		GetValue = function() end,
+		SetValue = function() end,
+		ObserveValue = function() end,
+		RestoreDefault = function() end,
+		EnsureInitialized = function() end,
+	}, TieRealmUtils.inferTieRealm()))
+
+	return {
+		settingsDataService = settingsDataService,
+		player = player,
+		getPlayerCalls = function()
+			return getPlayerCalls
+		end,
+		maid = maid,
+		destroy = function(_self)
+			maid:DoCleaning()
+		end,
+	}
+end
+
+describe("SettingsDataService hydration", function()
+	it("resolves the same implementation across repeat reads", function()
+		local controller = setup()
+
+		local first = controller.settingsDataService:GetPlayerSettings(controller.player)
+		local second = controller.settingsDataService:GetPlayerSettings(controller.player)
+
+		expect(first).never.toBeNil()
+		expect(second).toBe(first)
+
+		controller:destroy()
+	end)
+
+	it("hydrates without invoking the implementation's GetPlayer", function()
+		local controller = setup()
+
+		controller.settingsDataService:GetPlayerSettings(controller.player)
+
+		expect(controller.getPlayerCalls()).toBe(0)
+
+		controller:destroy()
+	end)
+
+	it("does not re-hydrate when an observer reads settings during a re-hydration", function()
+		local controller = setup()
+		local settingsDataService = controller.settingsDataService
+		local player = controller.player
+
+		local sequence = ""
+		controller.maid:GiveTask(settingsDataService:ObservePlayerSettings(player):Subscribe(function(playerSettings)
+			sequence ..= if playerSettings ~= nil then "impl," else "nil,"
+
+			-- The re-entrant read: in production, any observer that reads a setting while handling one.
+			settingsDataService:GetPlayerSettings(player)
+		end))
+
+		expect(sequence).toBe("impl,")
+
+		-- Drops the memo without marking the player gone, so re-hydration is under test here rather than
+		-- the departure guard. The observer's own read used to find the memo still empty and hydrate
+		-- again, and so on until the C stack died.
+		local hydratedPlayersMaid = (settingsDataService :: any)._hydratedPlayersMaid
+		hydratedPlayersMaid[player] = nil
+
+		expect(settingsDataService:GetPlayerSettings(player)).never.toBeNil()
+
+		-- One re-hydration, not a cascade: nil is the old hydration tearing down, and the observer's own
+		-- read rebuilds from inside that emission.
+		expect(sequence).toBe("impl,nil,impl,")
+
+		controller:destroy()
+	end)
+
+	it("does not hydrate a player who has left", function()
+		local controller = setup()
+		local settingsDataService = controller.settingsDataService
+		local player = controller.player
+
+		local sequence = ""
+		controller.maid:GiveTask(settingsDataService:ObservePlayerSettings(player):Subscribe(function(playerSettings)
+			sequence ..= if playerSettings ~= nil then "impl," else "nil,"
+
+			settingsDataService:GetPlayerSettings(player)
+		end))
+
+		expect(sequence).toBe("impl,")
+
+		-- Stands in for Players.PlayerRemoving, which no test can make the engine fire.
+		local internal: any = settingsDataService
+		internal:_onPlayerRemoving(player)
+
+		-- The read from inside the teardown emission finds nothing to rebuild -- the settings folder is
+		-- leaving the DataModel too.
+		expect(sequence).toBe("impl,nil,")
+		expect(settingsDataService:GetPlayerSettings(player)).toBeNil()
+		expect(sequence).toBe("impl,nil,")
+
+		controller:destroy()
+	end)
+
+	it("stops holding a player once they are out of the DataModel", function()
+		local controller = setup()
+		local settingsDataService = controller.settingsDataService
+		local player = controller.player
+
+		settingsDataService:GetPlayerSettings(player)
+
+		local internal: any = settingsDataService
+		internal:_onPlayerRemoving(player)
+
+		-- The tombstone holds the slot for as long as the player could still be asked about.
+		expect(internal._hydratedPlayersMaid[player]).never.toBeNil()
+
+		-- What a removed player's instance actually does, and the point after which nothing can reach
+		-- these settings again.
+		player.Parent = nil
+
+		expect(internal._hydratedPlayersMaid[player]).toBeNil()
+
+		-- With the tombstone gone, the DataModel answers: a later read must not claim the slot back.
+		expect(settingsDataService:GetPlayerSettings(player)).toBeNil()
+		expect(internal._hydratedPlayersMaid[player]).toBeNil()
+
+		controller:destroy()
+	end)
+end)