@quenty/characterutils 4.0.0-canary.236.5597d0a.0 → 4.0.0

package/CHANGELOG.md

@@ -3,7 +3,55 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# [4.0.0-canary.236.5597d0a.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.2.0...@quenty/characterutils@4.0.0-canary.236.5597d0a.0) (2021-12-18)
+# [4.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.6.0...@quenty/characterutils@4.0.0) (2022-03-06)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
+# [3.6.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.5.1...@quenty/characterutils@3.6.0) (2022-01-17)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
+## [3.5.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.5.0...@quenty/characterutils@3.5.1) (2022-01-16)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
+# [3.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.4.0...@quenty/characterutils@3.5.0) (2022-01-07)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
+# [3.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.3.1...@quenty/characterutils@3.4.0) (2022-01-03)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
+## [3.3.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.3.0...@quenty/characterutils@3.3.1) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
+# [3.3.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@3.2.0...@quenty/characterutils@3.3.0) (2021-12-18)
 
 **Note:** Version bump only for package @quenty/characterutils
 

package/README.md

@@ -1,14 +1,21 @@
 ## CharacterUtils
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />
   </a>
 </div>
 
-Provides utility functions for working with Roblox characters. These make some much-repeated actions much easier to access and operate.
+Provides utility functions for working with Roblox characters. These make some much-repeated actions much easier to access and operate.
+
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/CharacterUtils">View docs →</a></div>
+
+## Installation
+```
+npm install @quenty/characterutils --save
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/characterutils",
-  "version": "4.0.0-canary.236.5597d0a.0",
+  "version": "4.0.0",
   "description": "CharacterUtils",
   "keywords": [
     "Roblox",
@@ -25,13 +25,13 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/deferred": "2.0.1",
-    "@quenty/loader": "3.1.1",
-    "@quenty/maid": "2.0.1",
-    "@quenty/promise": "4.0.0-canary.236.5597d0a.0"
+    "@quenty/deferred": "^2.0.2",
+    "@quenty/loader": "^4.0.0",
+    "@quenty/maid": "^2.1.0",
+    "@quenty/promise": "^4.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5597d0abdadd88f369f1401a558a8d6d1a1c5aab"
+  "gitHead": "dd428cab58282c975a4c082957dc8f58e3186905"
 }

package/src/Shared/CharacterPromiseUtils.lua

@@ -1,42 +1,22 @@
---- Utility for Roblox character objects that involve promises.
--- @see Promise
--- @module CharacterPromiseUtil
+--[=[
+	Utility for Roblox character objects that involve promises.
+	@class CharacterPromiseUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
-local Promise = require("Promise")
 local Maid = require("Maid")
+local Promise = require("Promise")
 
-local CharacterPromiseUtil = {}
-
---- Given a humanoid creates a promise that will resolve once the `Humanoid.RootPart` property
--- resolves properly.
--- @param humanoid The humanoid to resolve for the root part
-function CharacterPromiseUtil.promiseRootPart(humanoid)
-	local promise = Promise.new()
-
-	if humanoid.RootPart then
-		promise:Resolve(humanoid.RootPart)
-		return promise
-	end
-
-	-- humanoid:GetPropertyChangedSignal("RootPart") does not fire
-	task.spawn(function()
-		local rootPart = humanoid.RootPart
-		while not rootPart and promise:IsPending() do
-			task.wait(0.05)
-			rootPart = humanoid.RootPart
-		end
-
-		if rootPart and promise:IsPending() then
-			promise:Resolve(rootPart)
-		end
-	end)
+local CharacterPromiseUtils = {}
 
-	return promise
-end
+--[=[
+	Returns a promise that will resolve once a character exists.
 
-function CharacterPromiseUtil.promiseCharacter(player)
+	@param player Player
+	@return Promise<Model>
+]=]
+function CharacterPromiseUtils.promiseCharacter(player)
 	assert(typeof(player) == "Instance", "Bad player")
 
 	local promise = Promise.new()
@@ -60,5 +40,5 @@ function CharacterPromiseUtil.promiseCharacter(player)
 
 end
 
-return CharacterPromiseUtil
+return CharacterPromiseUtils
 

package/src/Shared/CharacterUtils.lua

@@ -1,10 +1,17 @@
---- General character utility code.
--- @module CharacterUtils
+--[=[
+	General character utility code.
+	@class CharacterUtils
+]=]
 
 local Players = game:GetService("Players")
 
 local CharacterUtils = {}
 
+--[=[
+	Gets a player's humanoid, if it exists
+	@param player Player
+	@return Humanoid? -- Nil if not found
+]=]
 function CharacterUtils.getPlayerHumanoid(player)
 	local character = player.Character
 	if not character then
@@ -14,6 +21,11 @@ function CharacterUtils.getPlayerHumanoid(player)
 	return character:FindFirstChildOfClass("Humanoid")
 end
 
+--[=[
+	Gets a player's humanoid, and ensures it is alive, otherwise returns nil
+	@param player Player
+	@return Humanoid? -- Nil if not found
+]=]
 function CharacterUtils.getAlivePlayerHumanoid(player)
 	local humanoid = CharacterUtils.getPlayerHumanoid(player)
 	if not humanoid or humanoid.Health <= 0 then
@@ -23,6 +35,12 @@ function CharacterUtils.getAlivePlayerHumanoid(player)
 	return humanoid
 end
 
+--[=[
+	Gets a player's humanoid's rootPart, and ensures the humanoid is alive, otherwise
+	returns nil
+	@param player Player
+	@return BasePart? -- Nil if not found
+]=]
 function CharacterUtils.getAlivePlayerRootPart(player)
 	local humanoid = CharacterUtils.getPlayerHumanoid(player)
 	if not humanoid or humanoid.Health <= 0 then
@@ -32,6 +50,11 @@ function CharacterUtils.getAlivePlayerRootPart(player)
 	return humanoid.RootPart
 end
 
+--[=[
+	Gets a player's humanoid's rootPart otherwise returns nil
+	@param player Player
+	@return BasePart? -- Nil if not found
+]=]
 function CharacterUtils.getPlayerRootPart(player)
 	local humanoid = CharacterUtils.getPlayerHumanoid(player)
 	if not humanoid then
@@ -41,6 +64,20 @@ function CharacterUtils.getPlayerRootPart(player)
 	return humanoid.RootPart
 end
 
+--[=[
+	Unequips all tools for a give player's humanomid, if the humanoid
+	exists
+
+	```lua
+	local Players = game:GetService("Players")
+
+	for _, player in pairs(Players:GetPlayers()) do
+		CharacterUtils.unequipTools(player)
+	end
+	```
+
+	@param player Player
+]=]
 function CharacterUtils.unequipTools(player)
 	local humanoid = CharacterUtils.getPlayerHumanoid(player)
 	if humanoid then
@@ -48,10 +85,27 @@ function CharacterUtils.unequipTools(player)
 	end
 end
 
---- Returns the Player and Character that a descendent is part of, if it is part of one.
--- @param descendant A child of the potential character.
--- @treturn Player player
--- @treturn Character character
+--[=[
+	Returns the player that a descendent is part of, if it is part of one.
+
+	```lua
+	script.Parent.Touched:Connect(function(inst)
+		local player = CharacterUtils.getPlayerFromCharacter(inst)
+		if player then
+			-- activate button!
+		end
+	end)
+	```
+
+	:::tip
+	This method is useful in a ton of different situations. For example, you can
+	use it on classes bound to a humanoid, to determine the player. You can also
+	use it to determine, upon touched events, if a part is part of a character.
+	:::
+
+	@param descendant Instance -- A child of the potential character.
+	@return Player? -- Nil if not found
+]=]
 function CharacterUtils.getPlayerFromCharacter(descendant)
 	local character = descendant
 	local player = Players:GetPlayerFromCharacter(character)

package/src/Shared/RootPartUtils.lua

@@ -1,5 +1,7 @@
---- Utility functions involving the root part
--- @module RootPartUtils
+--[=[
+	Utility functions involving the root part
+	@class RootPartUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,6 +12,18 @@ local RootPartUtils = {}
 
 local MAX_YIELD_TIME = 60
 
+--[=[
+	Given a humanoid creates a promise that will resolve once the `Humanoid.RootPart` property
+	resolves properly.
+
+	:::info
+	This works around the fact that `humanoid:GetPropertyChangedSignal("RootPart")` does not fire
+	when the rootpart changes on a humanoid.
+	:::
+
+	@param humanoid Humanoid
+	@return Promise<BasePart>
+]=]
 function RootPartUtils.promiseRootPart(humanoid)
 	if humanoid.RootPart then
 		return Promise.resolved(humanoid.RootPart)
@@ -20,7 +34,7 @@ function RootPartUtils.promiseRootPart(humanoid)
 	local maid = Maid.new()
 	local promise = Promise.new()
 
-	spawn(function()
+	task.spawn(function()
 		while not humanoid.RootPart and promise:IsPending() do
 			task.wait(0.05)
 		end
@@ -31,7 +45,7 @@ function RootPartUtils.promiseRootPart(humanoid)
 		end
 	end)
 
-	delay(MAX_YIELD_TIME, function()
+	task.delay(MAX_YIELD_TIME, function()
 		if promise:IsPending() then
 			warn("[RootPartUtils.promiseRootPart] - TImed out on root part", debug.traceback())
 			promise:Reject("Timed out")