@quenty/settings 11.61.0 → 11.62.0

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.62.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/settings@11.61.0...@quenty/settings@11.62.0) (2026-07-23)
+
+### Features
+
+- Add baseline player-mock and support across Nevermore for mocked players. ([567d121](https://github.com/Quenty/NevermoreEngine/commit/567d121ffc014b42391554088189a1a6296dda83))
+
 # [11.61.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/settings@11.60.0...@quenty/settings@11.61.0) (2026-07-22)
 
 **Note:** Version bump only for package @quenty/settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/settings",
-  "version": "11.61.0",
+  "version": "11.62.0",
   "description": "Centralized player settings service",
   "keywords": [
     "Roblox",
@@ -28,42 +28,43 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/attributeutils": "14.32.0",
-    "@quenty/baseobject": "10.14.0",
-    "@quenty/binder": "14.40.0",
-    "@quenty/brio": "14.32.0",
-    "@quenty/canceltoken": "11.21.0",
-    "@quenty/cmdrservice": "13.50.0",
-    "@quenty/datastore": "13.45.0",
+    "@quenty/attributeutils": "14.33.0",
+    "@quenty/baseobject": "10.15.0",
+    "@quenty/binder": "14.41.0",
+    "@quenty/brio": "14.33.0",
+    "@quenty/canceltoken": "11.22.0",
+    "@quenty/cmdrservice": "13.51.0",
+    "@quenty/datastore": "13.46.0",
     "@quenty/ducktype": "5.11.0",
     "@quenty/enumutils": "3.4.6",
-    "@quenty/instanceutils": "13.32.0",
-    "@quenty/jsonutils": "10.20.0",
+    "@quenty/instanceutils": "13.33.0",
+    "@quenty/jsonutils": "10.21.0",
     "@quenty/loader": "10.11.0",
-    "@quenty/maid": "3.10.0",
-    "@quenty/nevermore-test-runner": "1.4.0",
-    "@quenty/observablecollection": "12.41.0",
-    "@quenty/playerbinder": "14.40.0",
-    "@quenty/playerutils": "8.35.0",
-    "@quenty/promise": "10.20.0",
-    "@quenty/remotefunctionutils": "10.20.0",
-    "@quenty/remoting": "12.35.0",
-    "@quenty/rx": "13.30.0",
-    "@quenty/rxbinderutils": "14.40.0",
-    "@quenty/rxsignal": "7.30.0",
-    "@quenty/servicebag": "11.19.0",
+    "@quenty/maid": "3.11.0",
+    "@quenty/nevermore-test-runner": "1.5.0",
+    "@quenty/observablecollection": "12.42.0",
+    "@quenty/playerbinder": "14.41.0",
+    "@quenty/playermock": "1.1.0",
+    "@quenty/playerutils": "8.36.0",
+    "@quenty/promise": "10.21.0",
+    "@quenty/remotefunctionutils": "10.21.0",
+    "@quenty/remoting": "12.36.0",
+    "@quenty/rx": "13.31.0",
+    "@quenty/rxbinderutils": "14.41.0",
+    "@quenty/rxsignal": "7.31.0",
+    "@quenty/servicebag": "11.20.0",
     "@quenty/signal": "7.13.1",
-    "@quenty/statestack": "14.34.0",
-    "@quenty/string": "3.3.7",
+    "@quenty/statestack": "14.35.0",
+    "@quenty/string": "3.4.0",
     "@quenty/symbol": "3.5.2",
     "@quenty/table": "3.9.2",
-    "@quenty/throttle": "10.13.0",
-    "@quenty/tie": "10.43.0",
-    "@quenty/valueobject": "13.33.0",
+    "@quenty/throttle": "10.14.0",
+    "@quenty/tie": "10.44.0",
+    "@quenty/valueobject": "13.34.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "93f15b200c0f465a0b5304fcf05f5cfe7fdcbd1d"
+  "gitHead": "1de37218a2bedb8e3f8614a2e09bba9eddc812da"
 }

package/src/Client/SettingsServiceClient.lua

@@ -15,6 +15,7 @@ local Brio = require("Brio")
 local CancelToken = require("CancelToken")
 local Maid = require("Maid")
 local Observable = require("Observable")
+local PlayerMock = require("PlayerMock")
 local PlayerSettingsClient = require("PlayerSettingsClient")
 local Promise = require("Promise")
 local ServiceBag = require("ServiceBag")
@@ -62,7 +63,7 @@ end
 function SettingsServiceClient.GetLocalPlayerSettings(
 	self: SettingsServiceClient
 ): PlayerSettingsClient.PlayerSettingsClient?
-	return self:GetPlayerSettings(Players.LocalPlayer)
+	return self:GetPlayerSettings(Players.LocalPlayer or PlayerMock.getMockedLocalPlayer())
 end
 
 --[=[
@@ -73,7 +74,7 @@ end
 function SettingsServiceClient.ObserveLocalPlayerSettingsBrio(self: SettingsServiceClient): Observable.Observable<
 	Brio.Brio<PlayerSettingsClient.PlayerSettingsClient>
 >
-	return self:ObservePlayerSettingsBrio(Players.LocalPlayer)
+	return self:ObservePlayerSettingsBrio(Players.LocalPlayer or PlayerMock.getMockedLocalPlayer())
 end
 
 --[=[
@@ -84,7 +85,7 @@ end
 function SettingsServiceClient.ObserveLocalPlayerSettings(self: SettingsServiceClient): Observable.Observable<
 	PlayerSettingsClient.PlayerSettingsClient
 >
-	return self:ObservePlayerSettings(Players.LocalPlayer)
+	return self:ObservePlayerSettings(Players.LocalPlayer or PlayerMock.getMockedLocalPlayer())
 end
 
 --[=[
@@ -97,7 +98,7 @@ function SettingsServiceClient.PromiseLocalPlayerSettings(
 	self: SettingsServiceClient,
 	cancelToken: CancelToken.CancelToken
 ): Promise.Promise<PlayerSettingsClient.PlayerSettingsClient>
-	return self:PromisePlayerSettings(Players.LocalPlayer, cancelToken)
+	return self:PromisePlayerSettings(Players.LocalPlayer or PlayerMock.getMockedLocalPlayer(), cancelToken)
 end
 
 --[=[
@@ -110,7 +111,7 @@ function SettingsServiceClient.ObservePlayerSettings(
 	self: SettingsServiceClient,
 	player: Player
 ): Observable.Observable<PlayerSettingsClient.PlayerSettingsClient>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return self._settingsDataService:ObservePlayerSettings(player)
 end
@@ -127,7 +128,7 @@ function SettingsServiceClient.ObservePlayerSettingsBrio(
 ): Observable.Observable<
 	Brio.Brio<PlayerSettingsClient.PlayerSettingsClient>
 >
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return self._settingsDataService:ObservePlayerSettingsBrio(player)
 end
@@ -142,7 +143,7 @@ function SettingsServiceClient.GetPlayerSettings(
 	self: SettingsServiceClient,
 	player: Player
 ): PlayerSettingsClient.PlayerSettingsClient?
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return self._settingsDataService:GetPlayerSettings(player)
 end
@@ -159,7 +160,7 @@ function SettingsServiceClient.PromisePlayerSettings(
 	player: Player,
 	cancelToken: CancelToken.CancelToken
 ): Promise.Promise<PlayerSettingsClient.PlayerSettingsClient>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return self._settingsDataService:PromisePlayerSettings(player, cancelToken)
 end

package/src/Shared/Player/PlayerSettingsBase.lua

@@ -10,6 +10,7 @@ local require = require(script.Parent.loader).load(script)
 local BaseObject = require("BaseObject")
 local DataStoreStringUtils = require("DataStoreStringUtils")
 local Observable = require("Observable")
+local PlayerMock = require("PlayerMock")
 local PlayerSettingsUtils = require("PlayerSettingsUtils")
 local Rx = require("Rx")
 local RxAttributeUtils = require("RxAttributeUtils")
@@ -51,7 +52,9 @@ end
 	@return Player
 ]=]
 function PlayerSettingsBase.GetPlayer(self: PlayerSettingsBase): Player?
-	return self._obj:FindFirstAncestorWhichIsA("Player")
+	-- The real Player ancestor, or the PlayerMock a test parented the settings folder under
+	-- (a mock's backing Folder is invisible to the IsA walk).
+	return self._obj:FindFirstAncestorWhichIsA("Player") or PlayerMock.findFirstAncestorMock(self._obj)
 end
 
 --[=[

package/src/Shared/Setting/SettingDefinition.lua

@@ -26,6 +26,7 @@ local Players = game:GetService("Players")
 local DuckTypeUtils = require("DuckTypeUtils")
 local Maid = require("Maid")
 local Observable = require("Observable")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 local ServiceBag = require("ServiceBag")
 local SettingProperty = require("SettingProperty")
@@ -175,9 +176,13 @@ function SettingDefinition.GetSettingProperty<T>(
 	player: Player
 ): SettingProperty.SettingProperty<T>
 	assert(ServiceBag.isServiceBag(serviceBag), "Bad serviceBag")
-	assert(typeof(player) == "Instance" and player:IsA("Player") or player == nil, "Bad player")
+	assert(
+		typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)) or player == nil,
+		"Bad player"
+	)
 
-	player = player or Players.LocalPlayer
+	-- 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)
 end
@@ -194,7 +199,7 @@ function SettingDefinition.GetLocalPlayerSettingProperty<T>(
 ): SettingProperty.SettingProperty<T>
 	assert(ServiceBag.isServiceBag(serviceBag), "Bad serviceBag")
 
-	return self:GetSettingProperty(serviceBag, Players.LocalPlayer)
+	return self:GetSettingProperty(serviceBag, Players.LocalPlayer or PlayerMock.getMockedLocalPlayer())
 end
 
 --[=[

package/src/Shared/Setting/SettingProperty.lua

@@ -5,7 +5,10 @@
 
 local require = require(script.Parent.loader).load(script)
 
+local Players = game:GetService("Players")
+
 local Observable = require("Observable")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 local Rx = require("Rx")
 local RxSignal = require("RxSignal")
@@ -24,7 +27,7 @@ export type SettingProperty<T> = typeof(setmetatable(
 
 		_serviceBag: ServiceBag.ServiceBag,
 		_bridge: SettingsDataService.SettingsDataService,
-		_player: Player,
+		_player: Player?,
 		_definition: any,
 	},
 	{} :: typeof({ __index = SettingProperty })
@@ -33,23 +36,33 @@ export type SettingProperty<T> = typeof(setmetatable(
 --[=[
 	Constructs a new SettingProperty.
 
+	A nil player means the local player: the real `Players.LocalPlayer`, or the mock a test has
+	already designated through [PlayerMock.setMockedLocalPlayer]. Designation may happen before
+	bags boot -- matching production, where `Players.LocalPlayer` exists before any service runs --
+	so construction requires a resolvable local player up front.
+
 	@param serviceBag ServiceBag
-	@param player Player
+	@param player Player?
 	@param definition SettingDefinition
 	@return SettingProperty<T>
 ]=]
-function SettingProperty.new<T>(serviceBag: ServiceBag.ServiceBag, player: Player, definition): SettingProperty<T>
+function SettingProperty.new<T>(serviceBag: ServiceBag.ServiceBag, player: Player?, definition): SettingProperty<T>
 	local self: SettingProperty<T> = setmetatable({} :: any, SettingProperty)
 
 	self._serviceBag = assert(serviceBag, "No serviceBag")
 	self._bridge = self._serviceBag:GetService(SettingsDataService) :: any
 
-	self._player = assert(player, "No player")
+	assert(player ~= nil or Players.LocalPlayer ~= nil or PlayerMock.getMockedLocalPlayer() ~= nil, "No player")
+	if player ~= nil then
+		self._player = player
+	end
 	self._definition = assert(definition, "No definition")
 
-	self:_promisePlayerSettings():Then(function(playerSettings)
-		playerSettings:EnsureInitialized(self._definition:GetSettingName(), self._definition:GetDefaultValue())
-	end)
+	if self:_findPlayer() ~= nil then
+		self:_promisePlayerSettings():Then(function(playerSettings)
+			playerSettings:EnsureInitialized(self._definition:GetSettingName(), self._definition:GetDefaultValue())
+		end)
+	end
 
 	return self
 end
@@ -191,16 +204,24 @@ function SettingProperty.PromiseRestoreDefault<T>(self: SettingProperty<T>): Pro
 	end)
 end
 
+function SettingProperty._findPlayer<T>(self: SettingProperty<T>): Player?
+	return rawget(self :: any, "_player") or Players.LocalPlayer or PlayerMock.getMockedLocalPlayer()
+end
+
+function SettingProperty._resolvePlayer<T>(self: SettingProperty<T>): Player
+	return assert(self:_findPlayer(), "No player") :: Player
+end
+
 function SettingProperty._observePlayerSettings<T>(self: SettingProperty<T>)
-	return self._bridge:ObservePlayerSettings(self._player)
+	return self._bridge:ObservePlayerSettings(self:_resolvePlayer())
 end
 
 function SettingProperty._getPlayerSettings<T>(self: SettingProperty<T>)
-	return self._bridge:GetPlayerSettings(self._player)
+	return self._bridge:GetPlayerSettings(self:_resolvePlayer())
 end
 
 function SettingProperty._promisePlayerSettings<T>(self: SettingProperty<T>)
-	return self._bridge:PromisePlayerSettings(self._player)
+	return self._bridge:PromisePlayerSettings(self:_resolvePlayer())
 end
 
 return SettingProperty

package/src/Shared/SettingsDataService.lua

@@ -14,6 +14,7 @@ local Maid = require("Maid")
 local Observable = require("Observable")
 local ObservableMap = require("ObservableMap")
 local ObservableSet = require("ObservableSet")
+local PlayerMock = require("PlayerMock")
 local PlayerSettingsInterface = require("PlayerSettingsInterface")
 local Promise = require("Promise")
 local Rx = require("Rx")
@@ -154,7 +155,7 @@ function SettingsDataService.ObservePlayerSettings(
 	self: SettingsDataService,
 	player: Player
 ): Observable.Observable<any>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return (self:_getPlayerSettingsMapForPlayer(player) :: any):ObserveAtKey(
 		player,
@@ -190,7 +191,7 @@ function SettingsDataService.PromisePlayerSettings(
 	player: Player,
 	cancelToken: any
 ): Promise.Promise<any>
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return Rx.toPromise(
 		(self:ObservePlayerSettings(player) :: any):Pipe({
@@ -209,7 +210,7 @@ end
 	@return Promise<PlayerSettingsBase>
 ]=]
 function SettingsDataService.GetPlayerSettings(self: SettingsDataService, player: Player): any
-	assert(typeof(player) == "Instance" and player:IsA("Player"), "Bad player")
+	assert(typeof(player) == "Instance" and (player:IsA("Player") or PlayerMock.isMock(player)), "Bad player")
 
 	return self:_getPlayerSettingsMapForPlayer(player):Get(player)
 end