@quenty/characterutils 12.39.0 → 12.40.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.
 
+## [12.40.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@12.40.0...@quenty/characterutils@12.40.1) (2026-07-25)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+# [12.40.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@12.39.0...@quenty/characterutils@12.40.0) (2026-07-25)
+
+### Features
+
+- Add RootPartUtils.getPlayerRootPart(player) ([dc1c687](https://github.com/Quenty/NevermoreEngine/commit/dc1c68760c3e4b699b0a4e59eec464b73a61867b))
+- Add RootPartUtils.promisePlayerHumanoidRootPart(player) ([50a789b](https://github.com/Quenty/NevermoreEngine/commit/50a789b4ae0f126d893fd86405b1f5b2ccdfc5b7))
+
 # [12.39.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@12.38.0...@quenty/characterutils@12.39.0) (2026-07-24)
 
 **Note:** Version bump only for package @quenty/characterutils

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/characterutils",
-  "version": "12.39.0",
+  "version": "12.40.1",
   "description": "CharacterUtils",
   "keywords": [
     "Roblox",
@@ -28,19 +28,19 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/brio": "14.34.0",
+    "@quenty/brio": "14.35.1",
     "@quenty/deferred": "2.3.2",
-    "@quenty/instanceutils": "13.34.0",
+    "@quenty/instanceutils": "13.35.1",
     "@quenty/loader": "10.11.0",
     "@quenty/maid": "3.11.0",
     "@quenty/nevermore-test-runner": "1.5.0",
-    "@quenty/playermock": "1.4.0",
-    "@quenty/promise": "10.22.0",
-    "@quenty/rx": "13.32.0",
+    "@quenty/playermock": "1.5.1",
+    "@quenty/promise": "10.23.0",
+    "@quenty/rx": "13.33.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "04f569a7981517ae20394ec3ca3923c421a93d43"
+  "gitHead": "f276b791b8eb4e88b952b5babaf0f4189c1a11d0"
 }

package/src/Shared/RootPartUtils.lua

@@ -6,7 +6,9 @@
 
 local require = require(script.Parent.loader).load(script)
 
+local CharacterUtils = require("CharacterUtils")
 local Maid = require("Maid")
+local PlayerMock = require("PlayerMock")
 local Promise = require("Promise")
 
 local RootPartUtils = {}
@@ -70,6 +72,98 @@ function RootPartUtils.promiseRootPart(humanoid: Humanoid): Promise.Promise<Base
 	return promise
 end
 
+--[=[
+	Given a player creates a promise that will resolve once the player has a character whose
+	humanoid has a resolved `Humanoid.RootPart`.
+
+	Resolves with the root part of whatever character the player has at that moment, so a respawn
+	while waiting is followed instead of leaving the promise stuck on a destroyed character. Health
+	is not considered -- a dead humanoid still has a root part, matching
+	[CharacterUtils.getPlayerRootPart].
+
+	```lua
+	RootPartUtils.promisePlayerHumanoidRootPart(player):Then(function(rootPart)
+		print(rootPart:GetPivot())
+	end)
+	```
+
+	Accepts a [PlayerMock] as well as a real `Player`.
+
+	@param player Player
+	@return Promise<BasePart>
+]=]
+function RootPartUtils.promisePlayerHumanoidRootPart(player: Player): Promise.Promise<BasePart>
+	assert(player:IsA("Player") or PlayerMock.isMock(player), "Bad player")
+
+	local rootPart = CharacterUtils.getPlayerRootPart(player)
+	if rootPart then
+		return Promise.resolved(rootPart)
+	end
+
+	local maid = Maid.new()
+	local promise = Promise.new()
+
+	-- Same unobservable-property problem promiseRootPart works around, so the same poll: it reads
+	-- through CharacterUtils.getPlayerRootPart, which covers the character spawning, its humanoid
+	-- appearing and the root part resolving in one check -- and reads a mock's character through
+	-- the mock seam.
+	task.spawn(function()
+		while promise:IsPending() do
+			local currentRootPart = CharacterUtils.getPlayerRootPart(player)
+			if currentRootPart then
+				promise:Resolve(currentRootPart)
+				return
+			end
+			task.wait(0.05)
+		end
+	end)
+
+	task.delay(MAX_YIELD_TIME, function()
+		if promise:IsPending() then
+			warn(debug.traceback("[RootPartUtils.promisePlayerHumanoidRootPart] - Timed out on root part"))
+			promise:Reject("Timed out")
+		end
+	end)
+
+	-- A player who left is never getting a character; a mock leaves the same way (PlayerMock.kick
+	-- unparents rather than destroys), so this native signal serves both.
+	maid:GiveTask(player.AncestryChanged:Connect(function()
+		if not player:IsDescendantOf(game) then
+			promise:Reject("Player removed from game")
+		end
+	end))
+
+	promise:Finally(function()
+		maid:DoCleaning()
+	end)
+
+	return promise
+end
+
+--[=[
+	Gets the root part of the player's current character, if it exists.
+
+	Synchronous counterpart to [RootPartUtils.promisePlayerHumanoidRootPart]. Health is not
+	considered -- a dead humanoid still has a root part.
+
+	```lua
+	local rootPart = RootPartUtils.getPlayerRootPart(player)
+	if rootPart then
+		print(rootPart:GetPivot())
+	end
+	```
+
+	Accepts a [PlayerMock] as well as a real `Player`.
+
+	@param player Player
+	@return BasePart? -- Nil if not found
+]=]
+function RootPartUtils.getPlayerRootPart(player: Player): BasePart?
+	assert(player:IsA("Player") or PlayerMock.isMock(player), "Bad player")
+
+	return CharacterUtils.getPlayerRootPart(player)
+end
+
 --[=[
 	Gets the root part of a character, if it exists
 	@param character Model

package/src/Shared/RootPartUtils.spec.lua

@@ -0,0 +1,179 @@
+--!strict
+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 RootPartUtils = require("RootPartUtils")
+
+local afterEach = Jest.Globals.afterEach
+local beforeEach = Jest.Globals.beforeEach
+local describe = Jest.Globals.describe
+local expect = Jest.Globals.expect
+local it = Jest.Globals.it
+
+local maid: Maid.Maid = nil :: any
+local player: Player = nil :: any
+
+beforeEach(function()
+	maid = Maid.new()
+	player = PlayerMock.new()
+	player.Parent = Workspace -- the leave path needs an ancestry to change
+end)
+
+afterEach(function()
+	maid:DoCleaning() -- settles any promise left pending, so no poll outlives the test
+	player:Destroy()
+end)
+
+local function getRootPart(character: Model): BasePart
+	return character:FindFirstChild("HumanoidRootPart") :: BasePart
+end
+
+describe("RootPartUtils.promisePlayerHumanoidRootPart", function()
+	it("resolves already with the root part of a spawned character", function()
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+
+		local promise = maid:Add(RootPartUtils.promisePlayerHumanoidRootPart(player))
+		expect(promise:IsFulfilled()).toBe(true)
+
+		local ok, rootPart = promise:Yield()
+		expect(ok).toBe(true)
+		expect(rootPart).toBe(getRootPart(character))
+	end)
+
+	it("stays pending until a character spawns", function()
+		local promise = maid:Add(RootPartUtils.promisePlayerHumanoidRootPart(player))
+		expect(promise:IsPending()).toBe(true)
+
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+
+		local ok, rootPart = promise:Yield()
+		expect(ok).toBe(true)
+		expect(rootPart).toBe(getRootPart(character))
+	end)
+
+	it("resolves with the root part of the character present when it spawns, not a despawned one", function()
+		local firstCharacter = PlayerMock.loadMinimalCharacterAsync(player)
+		local firstRootPart = getRootPart(firstCharacter)
+		PlayerMock.removeCharacter(player)
+
+		local promise = maid:Add(RootPartUtils.promisePlayerHumanoidRootPart(player))
+		expect(promise:IsPending()).toBe(true)
+
+		local secondCharacter = PlayerMock.loadMinimalCharacterAsync(player)
+
+		local ok, rootPart = promise:Yield()
+		expect(ok).toBe(true)
+		expect(rootPart).toBe(getRootPart(secondCharacter))
+		expect(rootPart).never.toBe(firstRootPart)
+	end)
+
+	it("resolves for a dead humanoid, which still has a root part", function()
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+		local humanoid = character:FindFirstChildOfClass("Humanoid") :: Humanoid
+		humanoid.Health = 0
+
+		local promise = maid:Add(RootPartUtils.promisePlayerHumanoidRootPart(player))
+
+		local ok, rootPart = promise:Yield()
+		expect(ok).toBe(true)
+		expect(rootPart).toBe(getRootPart(character))
+	end)
+
+	it("resolves once a humanoid is added to a character that spawned without one", function()
+		local character = Instance.new("Model")
+
+		local rootPart = Instance.new("Part")
+		rootPart.Name = "HumanoidRootPart"
+		rootPart.Anchored = true
+		rootPart.Parent = character
+		character.PrimaryPart = rootPart
+
+		PlayerMock.loadCharacterAsync(player, character)
+
+		local promise = maid:Add(RootPartUtils.promisePlayerHumanoidRootPart(player))
+		expect(promise:IsPending()).toBe(true)
+
+		local humanoid = Instance.new("Humanoid")
+		humanoid.Parent = character
+
+		local ok, resolved = promise:Yield()
+		expect(ok).toBe(true)
+		expect(resolved).toBe(rootPart)
+	end)
+
+	it("rejects when the player leaves the game", function()
+		local promise = maid:Add(RootPartUtils.promisePlayerHumanoidRootPart(player))
+		expect(promise:IsPending()).toBe(true)
+
+		PlayerMock.kick(player)
+
+		local ok, err = promise:Yield()
+		expect(ok).toBe(false)
+		expect(err).toBe("Player removed from game")
+	end)
+
+	it("rejects a value that is neither a Player nor a PlayerMock", function()
+		local folder = Instance.new("Folder")
+
+		expect(function()
+			RootPartUtils.promisePlayerHumanoidRootPart(folder :: any)
+		end).toThrow()
+
+		folder:Destroy()
+	end)
+end)
+
+describe("RootPartUtils.getPlayerRootPart", function()
+	it("returns the root part of a spawned character", function()
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+
+		expect(RootPartUtils.getPlayerRootPart(player)).toBe(getRootPart(character))
+	end)
+
+	it("returns nil when the player has no character", function()
+		expect(RootPartUtils.getPlayerRootPart(player)).toBe(nil)
+	end)
+
+	it("returns nil once the character is removed", function()
+		PlayerMock.loadMinimalCharacterAsync(player)
+		PlayerMock.removeCharacter(player)
+
+		expect(RootPartUtils.getPlayerRootPart(player)).toBe(nil)
+	end)
+
+	it("returns nil for a character without a humanoid", function()
+		local character = Instance.new("Model")
+
+		local rootPart = Instance.new("Part")
+		rootPart.Name = "HumanoidRootPart"
+		rootPart.Anchored = true
+		rootPart.Parent = character
+		character.PrimaryPart = rootPart
+
+		PlayerMock.loadCharacterAsync(player, character)
+
+		expect(RootPartUtils.getPlayerRootPart(player)).toBe(nil)
+	end)
+
+	it("returns the root part for a dead humanoid", function()
+		local character = PlayerMock.loadMinimalCharacterAsync(player)
+		local humanoid = character:FindFirstChildOfClass("Humanoid") :: Humanoid
+		humanoid.Health = 0
+
+		expect(RootPartUtils.getPlayerRootPart(player)).toBe(getRootPart(character))
+	end)
+
+	it("rejects a value that is neither a Player nor a PlayerMock", function()
+		local folder = Instance.new("Folder")
+
+		expect(function()
+			RootPartUtils.getPlayerRootPart(folder :: any)
+		end).toThrow()
+
+		folder:Destroy()
+	end)
+end)