@quenty/ragdoll 5.1.0 → 5.1.2

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.1.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/ragdoll@5.1.1...@quenty/ragdoll@5.1.2) (2022-01-06)
+
+**Note:** Version bump only for package @quenty/ragdoll
+
+
+
+
+
+## [5.1.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/ragdoll@5.1.0...@quenty/ragdoll@5.1.1) (2022-01-06)
+
+**Note:** Version bump only for package @quenty/ragdoll
+
+
+
+
+
 # [5.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/ragdoll@5.0.2...@quenty/ragdoll@5.1.0) (2022-01-03)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/ragdoll",
-  "version": "5.1.0",
+  "version": "5.1.2",
   "description": "Quenty's Ragdoll system for Roblox - Floppy fun ragdolls",
   "keywords": [
     "Roblox",
@@ -27,7 +27,7 @@
   "dependencies": {
     "@quenty/baseobject": "^3.3.0",
     "@quenty/binder": "^4.6.0",
-    "@quenty/camera": "^5.1.0",
+    "@quenty/camera": "^5.1.1",
     "@quenty/characterutils": "^3.4.0",
     "@quenty/hapticfeedbackutils": "^2.1.1",
     "@quenty/humanoidanimatorutils": "^2.0.1",
@@ -43,5 +43,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d910da8f5c7e9a55a8bf76d8efbe5632713dd0fe"
+  "gitHead": "0efa1afd34157a4b4273f1621d7cc86bb48d6b41"
 }

package/src/Client/Classes/RagdollClient.lua

@@ -1,5 +1,8 @@
 --[=[
-	Client side ragdolling meant to be used with a binder
+	Client side ragdolling meant to be used with a binder. See [RagdollBindersClient].
+	While a humanoid is bound with this class, it is ragdolled.
+
+	@client
 	@class RagdollClient
 ]=]
 
@@ -19,6 +22,12 @@ local RagdollClient = setmetatable({}, BaseObject)
 RagdollClient.ClassName = "RagdollClient"
 RagdollClient.__index = RagdollClient
 
+--[=[
+	Constructs a new RagdollClient. Should be done via [Binder]. See [RagdollBindersClient].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return RagdollClient
+]=]
 function RagdollClient.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), RagdollClient)
 

package/src/Client/Classes/RagdollHumanoidOnDeathClient.lua

@@ -1,5 +1,7 @@
 --[=[
-	Ragdolls the humanoid on death
+	Ragdolls the humanoid on death. Should be bound via [RagdollBindersClient].
+
+	@client
 	@class RagdollHumanoidOnDeathClient
 ]=]
 
@@ -17,6 +19,12 @@ local RagdollHumanoidOnDeathClient = setmetatable({}, BaseObject)
 RagdollHumanoidOnDeathClient.ClassName = "RagdollHumanoidOnDeathClient"
 RagdollHumanoidOnDeathClient.__index = RagdollHumanoidOnDeathClient
 
+--[=[
+	Constructs a new RagdollHumanoidOnDeathClient. Should be done via [Binder]. See [RagdollBindersClient].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return RagdollHumanoidOnDeathClient
+]=]
 function RagdollHumanoidOnDeathClient.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), RagdollHumanoidOnDeathClient)
 

package/src/Client/Classes/RagdollHumanoidOnFallClient.lua

@@ -1,4 +1,7 @@
 --[=[
+	Ragdolls the humanoid on death. Should be bound via [RagdollBindersClient].
+
+	@client
 	@class RagdollHumanoidOnFallClient
 ]=]
 
@@ -18,6 +21,12 @@ RagdollHumanoidOnFallClient.__index = RagdollHumanoidOnFallClient
 
 require("PromiseRemoteEventMixin"):Add(RagdollHumanoidOnFallClient, RagdollHumanoidOnFallConstants.REMOTE_EVENT_NAME)
 
+--[=[
+	Constructs a new RagdollHumanoidOnFallClient. Should be done via [Binder]. See [RagdollBindersClient].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return RagdollHumanoidOnFallClient
+]=]
 function RagdollHumanoidOnFallClient.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), RagdollHumanoidOnFallClient)
 

package/src/Client/Classes/RagdollableClient.lua

@@ -1,4 +1,7 @@
 --[=[
+	Should be bound via [RagdollBindersClient].
+
+	@client
 	@class RagdollableClient
 ]=]
 
@@ -22,6 +25,12 @@ RagdollableClient.__index = RagdollableClient
 
 require("PromiseRemoteEventMixin"):Add(RagdollableClient, RagdollableConstants.REMOTE_EVENT_NAME)
 
+--[=[
+	Constructs a new RagdollableClient. Should be done via [Binder]. See [RagdollBindersClient].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return RagdollableClient
+]=]
 function RagdollableClient.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), RagdollableClient)
 

package/src/Client/RagdollBindersClient.lua

@@ -1,5 +1,18 @@
 --[=[
-	Holds binders
+	Holds binders for Ragdolls on the client. Be sure to initialize on the server. See [RagdollBindersClient] for details.
+	Be sure to use a [ServiceBag] to initialize this service.
+
+	```lua
+	-- Client.lua
+
+	local serviceBag = require("ServiceBag")
+	serviceBag:GetService(require("RagdollBindersClient"))
+
+	serviceBag:Init()
+	serviceBag:Start()
+	```
+
+	@client
 	@class RagdollBindersClient
 ]=]
 
@@ -9,10 +22,40 @@ local BinderProvider = require("BinderProvider")
 local Binder = require("Binder")
 
 return BinderProvider.new(function(self, serviceBag)
+--[=[
+	Apply this binder to a humanoid to ragdoll it. Humanoid must already have [Ragdollable] defined.
+
+	```lua
+	local ragdoll = serviceBag:GetService(RagdollBindersClient).Ragdoll:Get(humanoid)
+	if ragdoll then
+		print("Is ragdolled")
+	else
+		print("Not ragdolled")
+	end
+	```
+	@prop Ragdoll Binder<RagdollClient>
+	@within RagdollBindersClient
+]=]
 	self:Add(Binder.new("Ragdoll", require("RagdollClient"), serviceBag))
+
+--[=[
+	Enables ragdolling on a humanoid.
+	@prop Ragdollable Binder<RagdollableClient>
+	@within RagdollBindersClient
+]=]
 	self:Add(Binder.new("Ragdollable", require("RagdollableClient"), serviceBag))
 
-	-- Effects
+--[=[
+	Automatically applies ragdoll upon humanoid death.
+	@prop RagdollaRagdollHumanoidOnDeathble Binder<RagdollHumanoidOnDeathClient>
+	@within RagdollBindersClient
+]=]
 	self:Add(Binder.new("RagdollHumanoidOnDeath", require("RagdollHumanoidOnDeathClient"), serviceBag))
+
+--[=[
+	Automatically applies ragdoll upon humanoid fall.
+	@prop RagdollHumanoidOnFall Binder<RagdollHumanoidOnFallClient>
+	@within RagdollBindersClient
+]=]
 	self:Add(Binder.new("RagdollHumanoidOnFall", require("RagdollHumanoidOnFallClient"), serviceBag))
 end)

package/src/Server/Classes/Ragdoll.lua

@@ -1,5 +1,22 @@
 --[=[
-	Base class for ragdolls, meant to be used with binders
+	Base class for ragdolls, meant to be used with binders. See [RagdollBindersServer].
+	While a humanoid is bound with this class, it is ragdolled.
+
+	```lua
+	-- Be sure to do the service init on the client too
+	local serviceBag = require("ServiceBag")
+	local ragdollBindersServer = serviceBag:GetService(require("RagdollBindersServer"))
+
+	serviceBag:Init()
+	serviceBag:Start()
+
+	-- Enable ragdoll
+	ragdollBindersServer.Ragdoll:Bind(humanoid)
+
+	-- Disable ragdoll
+	ragdollBindersServer.Ragdoll:Unbind(humanoid)
+	```
+
 	@class Ragdoll
 ]=]
 
@@ -11,6 +28,12 @@ local Ragdoll = setmetatable({}, BaseObject)
 Ragdoll.ClassName = "Ragdoll"
 Ragdoll.__index = Ragdoll
 
+--[=[
+	Constructs a new Ragdoll. Should be done via [Binder]. See [RagdollBindersServer].
+	@param humanoid Humanoid
+	@param _serviceBag ServiceBag
+	@return Ragdoll
+]=]
 function Ragdoll.new(humanoid, _serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), Ragdoll)
 

package/src/Server/Classes/RagdollHumanoidOnDeath.lua

@@ -1,5 +1,6 @@
 --[=[
-	Ragdolls the humanoid on death
+	Ragdolls the humanoid on death.
+	@server
 	@class RagdollHumanoidOnDeath
 ]=]
 
@@ -12,8 +13,14 @@ local RagdollHumanoidOnDeath = setmetatable({}, BaseObject)
 RagdollHumanoidOnDeath.ClassName = "RagdollHumanoidOnDeath"
 RagdollHumanoidOnDeath.__index = RagdollHumanoidOnDeath
 
-function RagdollHumanoidOnDeath.new(humanid, serviceBag)
-	local self = setmetatable(BaseObject.new(humanid), RagdollHumanoidOnDeath)
+--[=[
+	Constructs a new RagdollHumanoidOnDeath. Should be done via [Binder]. See [RagdollBindersServer].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return RagdollHumanoidOnDeath
+]=]
+function RagdollHumanoidOnDeath.new(humanoid, serviceBag)
+	local self = setmetatable(BaseObject.new(humanoid), RagdollHumanoidOnDeath)
 
 	self._ragdollBinder = serviceBag:GetService(RagdollBindersServer).Ragdoll
 

package/src/Server/Classes/RagdollHumanoidOnFall.lua

@@ -1,4 +1,8 @@
 --[=[
+	When a humanoid is bound with this, it will ragdoll upon falling. Recommended that you use
+	[UnragdollAutomatically] in conjunction with this.
+
+	@server
 	@class RagdollHumanoidOnFall
 ]=]
 
@@ -14,6 +18,12 @@ local RagdollHumanoidOnFall = setmetatable({}, BaseObject)
 RagdollHumanoidOnFall.ClassName = "RagdollHumanoidOnFall"
 RagdollHumanoidOnFall.__index = RagdollHumanoidOnFall
 
+--[=[
+	Constructs a new RagdollHumanoidOnFall. Should be done via [Binder]. See [RagdollBindersServer].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return RagdollHumanoidOnFall
+]=]
 function RagdollHumanoidOnFall.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), RagdollHumanoidOnFall)
 

package/src/Server/Classes/Ragdollable.lua

@@ -1,4 +1,6 @@
 --[=[
+	Should be bound to any humanoid that is ragdollable. See [RagdollBindersServer].
+	@server
 	@class Ragdollable
 ]=]
 
@@ -18,6 +20,12 @@ local Ragdollable = setmetatable({}, BaseObject)
 Ragdollable.ClassName = "Ragdollable"
 Ragdollable.__index = Ragdollable
 
+--[=[
+	Constructs a new Ragdollable. Should be done via [Binder]. See [RagdollBindersServer].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return Ragdollable
+]=]
 function Ragdollable.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), Ragdollable)
 

package/src/Server/Classes/UnragdollAutomatically.lua

@@ -1,4 +1,6 @@
 --[=[
+	When a humanoid is tagged with this, it will unragdoll automatically.
+	@server
 	@class UnragdollAutomatically
 ]=]
 
@@ -15,6 +17,12 @@ local UnragdollAutomatically = setmetatable({}, BaseObject)
 UnragdollAutomatically.ClassName = "UnragdollAutomatically"
 UnragdollAutomatically.__index = UnragdollAutomatically
 
+--[=[
+	Constructs a new UnragdollAutomatically. Should be done via [Binder]. See [RagdollBindersServer].
+	@param humanoid Humanoid
+	@param serviceBag ServiceBag
+	@return UnragdollAutomatically
+]=]
 function UnragdollAutomatically.new(humanoid, serviceBag)
 	local self = setmetatable(BaseObject.new(humanoid), UnragdollAutomatically)
 

package/src/Server/RagdollBindersServer.lua

@@ -1,5 +1,20 @@
 --[=[
-	Holds binders
+	Holds binders for Ragdoll system. Be sure to initialize on the client too. See [RagdollBindersClient].
+	Be sure to use a [ServiceBag] to initialize this service.
+
+	```lua
+	-- Server.lua
+
+	local serviceBag = require("ServiceBag")
+	local ragdollBindersServer = serviceBag:GetService(require("RagdollBindersServer"))
+	serviceBag:Init()
+
+	ragdollBindersServer.RagdollHumanoidOnDeath:SetAutomaticTagging(false)
+
+	serviceBag:Start()
+	```
+
+	@server
 	@class RagdollBindersServer
 ]=]
 
@@ -10,14 +25,72 @@ local Binder = require("Binder")
 local PlayerHumanoidBinder = require("PlayerHumanoidBinder")
 
 return BinderProvider.new(function(self, serviceBag)
+--[=[
+	Apply this [Binder] to a humanoid to ragdoll it. Humanoid must already have [Ragdollable] defined.
+
+	```lua
+	local ragdollBinder = serviceBag:GetService(RagdollBindersClient).Ragdoll
+
+	local ragdoll = ragdollBinder:Get(humanoid)
+	if ragdoll then
+		print("Is ragdolled")
+		ragdollBinder:Unbind(humanoid)
+	else
+		print("Not ragdolled")
+		ragdollBinder:Bind(humanoid)
+	end
+	```
+
+	You can also use [RxBinderUtils.observeBoundClass] to observe whether a humanoid is ragdolled using an [Observable].
+
+	:::info
+	Like any usage of [Observable], be sure to give the [Subscription] to a [Maid] (or call
+	[Subscription.Destroy] on it) once done with the event connection.
+	:::
+
+	```lua
+	local maid = Maid.new()
+
+	local ragdollBinder = serviceBag:GetService(RagdollBindersClient).Ragdoll
+	maid:GiveTask(RxBinderUtils.observeBoundClass(ragdollBinder, humanoid):Subscribe(function(ragdoll)
+		if ragdoll then
+			print("Ragdolled!")
+		else
+			print("Not ragdolled")
+		end
+	end))
+	```
+
+	@prop Ragdoll Binder<Ragdoll>
+	@within RagdollBindersServer
+]=]
 	self:Add(Binder.new("Ragdoll", require("Ragdoll"), serviceBag))
+
+--[=[
+	Enables ragdolling on a humanoid.
+	@prop Ragdollable PlayerHumanoidBinder<Ragdollable>
+	@within RagdollBindersServer
+]=]
 	self:Add(PlayerHumanoidBinder.new("Ragdollable", require("Ragdollable"), serviceBag))
 
+--[=[
+	Automatically applies ragdoll upon humanoid death.
+	@prop RagdollHumanoidOnDeath PlayerHumanoidBinder<RagdollHumanoidOnDeath>
+	@within RagdollBindersServer
+]=]
 	self:Add(PlayerHumanoidBinder.new("RagdollHumanoidOnDeath", require("RagdollHumanoidOnDeath"), serviceBag))
+
+--[=[
+	Automatically applies ragdoll upon humanoid fall.
+	@prop RagdollHumanoidOnFall PlayerHumanoidBinder<RagdollHumanoidOnFall>
+	@within RagdollBindersServer
+]=]
 	self:Add(PlayerHumanoidBinder.new("RagdollHumanoidOnFall", require("RagdollHumanoidOnFall"), serviceBag))
-	self:Add(PlayerHumanoidBinder.new("UnragdollAutomatically", require("UnragdollAutomatically"), serviceBag))
 
-	self.RagdollHumanoidOnDeath:SetAutomaticTagging(true)
-	self.RagdollHumanoidOnFall:SetAutomaticTagging(true)
-	self.UnragdollAutomatically:SetAutomaticTagging(true)
+--[=[
+	Automatically unragdolls the humanoid.
+	@prop UnragdollAutomatically PlayerHumanoidBinder<UnragdollAutomatically>
+	@within RagdollBindersServer
+]=]
+	self:Add(PlayerHumanoidBinder.new("UnragdollAutomatically", require("UnragdollAutomatically"), serviceBag))
 end)

package/src/Shared/Classes/BindableRagdollHumanoidOnFall.lua

@@ -1,5 +1,5 @@
 --[=[
-	Ragdolls the humanoid on fall
+	Ragdolls the humanoid on fall. This is the base class.
 	@class BindableRagdollHumanoidOnFall
 ]=]
 
@@ -16,6 +16,12 @@ local BindableRagdollHumanoidOnFall = setmetatable({}, BaseObject)
 BindableRagdollHumanoidOnFall.ClassName = "BindableRagdollHumanoidOnFall"
 BindableRagdollHumanoidOnFall.__index = BindableRagdollHumanoidOnFall
 
+--[=[
+	Constructs a new BindableRagdollHumanoidOnFall.
+	@param humanoid Humanoid
+	@param ragdollBinder Binder<Ragdoll | RagdollClient>
+	@return BindableRagdollHumanoidOnFall
+]=]
 function BindableRagdollHumanoidOnFall.new(humanoid, ragdollBinder)
 	local self = setmetatable(BaseObject.new(humanoid), BindableRagdollHumanoidOnFall)
 

package/src/Shared/Classes/RagdollHumanoidOnFallConstants.lua

@@ -1,4 +1,5 @@
 --[=[
+	Constants for [RagdollHumanoidOnFall].
 	@class RagdollHumanoidOnFallConstants
 ]=]
 

package/src/Shared/RagdollConstants.lua

@@ -1,4 +1,5 @@
 --[=[
+	Constants for the [Ragdoll] class.
 	@class RagdollConstants
 ]=]
 

package/src/Shared/RagdollRigging.lua

@@ -1,4 +1,5 @@
 --[=[
+	Rigging data for humaoid ragdolls.
 	@class RagdollRigging
 ]=]
 
@@ -393,6 +394,11 @@ local function getMotorSet(model, motorSet)
 	return motors
 end
 
+--[=[
+	Creates joints on a model for a given rig type.
+	@param model Model
+	@param rigType HumanoidRigType
+]=]
 function RagdollRigging.createRagdollJoints(model, rigType)
 	local parts = indexParts(model)
 	if rigType == Enum.HumanoidRigType.R6 then
@@ -408,6 +414,10 @@ function RagdollRigging.createRagdollJoints(model, rigType)
 	end
 end
 
+--[=[
+	Removes ragdoll joints for a given model
+	@param model Model
+]=]
 function RagdollRigging.removeRagdollJoints(model)
 	for _, descendant in pairs(model:GetDescendants()) do
 		-- Remove BallSockets and NoCollides, leave the additional Attachments
@@ -419,6 +429,11 @@ function RagdollRigging.removeRagdollJoints(model)
 	end
 end
 
+--[=[
+	Retrieves all joint motors for a given rigType
+	@param model Model
+	@param rigType HumanoidRigType
+]=]
 function RagdollRigging.getMotors(model, rigType)
 	-- Note: We intentionally do not disable the root joint so that the mechanism root of the
 	-- character stays consistent when we break joints on the client. This avoid the need for the client to wait
@@ -436,6 +451,13 @@ function RagdollRigging.getMotors(model, rigType)
 	return motors
 end
 
+--[=[
+	Disables all particle emitters and fades them out. Yields for the duration.
+
+	@yields
+	@param character Model
+	@param duration number
+]=]
 function RagdollRigging.disableParticleEmittersAndFadeOutYielding(character, duration)
 	if RunService:IsServer() then
 		-- This causes a lot of unnecesarry replicated property changes
@@ -464,6 +486,13 @@ function RagdollRigging.disableParticleEmittersAndFadeOutYielding(character, dur
 	end
 end
 
+--[=[
+	Applies a sliding friction torque to the character making it stiffer and stiffer. Yields.
+
+	@yields
+	@param character Model
+	@param duration number
+]=]
 function RagdollRigging.easeJointFriction(character, duration)
 	local descendants = character:GetDescendants()
 	-- { { joint, initial friction, end friction }, ... }

package/src/Shared/RagdollUtils.lua

@@ -1,5 +1,7 @@
 --[=[
-	Utility mehtods for ragdolling. See Ragdoll.lua and RagdollClient.lua for implementation details
+	Utility methods for ragdolling. See [Ragdoll] and [RagdollClient] which call into this class.
+	If you want to make ragdolls without binders, this class may work for you.
+
 	@class RagdollUtils
 ]=]
 
@@ -19,6 +21,12 @@ local RagdollUtils = {}
 
 local EMPTY_FUNCTION = function() end
 
+--[=[
+	Sets up state monitoring for when the humanoid changes to ensure ragdoll is smooth.
+
+	@param humanoid Humanoid
+	@return Maid
+]=]
 function RagdollUtils.setupState(humanoid)
 	local maid = Maid.new()
 
@@ -68,7 +76,17 @@ function RagdollUtils.setupState(humanoid)
 	return maid
 end
 
--- We need this on all clients/servers to override animations!
+--[=[
+	Prevents animations from being applied on the humanoid torso on both
+	the server and client.
+
+	:::note
+	We need this on all clients/servers to override animations!
+	:::
+
+	@param humanoid Humanoid
+	@return Maid
+]=]
 function RagdollUtils.preventAnimationTransformLoop(humanoid)
 	local maid = Maid.new()
 
@@ -95,6 +113,13 @@ function RagdollUtils.preventAnimationTransformLoop(humanoid)
 	return maid
 end
 
+--[=[
+	Sets up the motors so that ragdoll can go, applying velocities to the ragdoll.
+	This needs to occur on the network owner of the character first.
+
+	@param humanoid Humanoid
+	@return Maid
+]=]
 function RagdollUtils.setupMotors(humanoid)
 	local character = humanoid.Parent
 	local rigType = humanoid.RigType
@@ -171,6 +196,13 @@ function RagdollUtils.setupMotors(humanoid)
 	end
 end
 
+--[=[
+	If the head is not a mesh part, this resizes the head into a mesh part with correct
+	physics, and ensures the head scaling is correct.
+
+	@param humanoid Humanoid
+	@return MaidTask
+]=]
 function RagdollUtils.setupHead(humanoid)
 	local model = humanoid.Parent
 	if not model then

package/src/Shared/RagdollableConstants.lua

@@ -1,4 +1,5 @@
 --[=[
+	Constants for the [Ragdollable] class.
 	@class RagdollableConstants
 ]=]