@quenty/characterutils 4.2.0 → 5.0.1-canary.269.5b9ce8a.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.0.1-canary.269.5b9ce8a.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@5.0.0...@quenty/characterutils@5.0.1-canary.269.5b9ce8a.0) (2022-06-24)
+
+
+### Features
+
+* Add RxCharacterUtils ([#262](https://github.com/Quenty/NevermoreEngine/issues/262)) ([760a912](https://github.com/Quenty/NevermoreEngine/commit/760a9121368f17eedc5bfca2decec66444811dfe))
+
+
+
+
+
+# [5.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@4.2.0...@quenty/characterutils@5.0.0) (2022-05-21)
+
+**Note:** Version bump only for package @quenty/characterutils
+
+
+
+
+
 # [4.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/characterutils@4.1.0...@quenty/characterutils@4.2.0) (2022-03-27)
 
 **Note:** Version bump only for package @quenty/characterutils

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2021 Quenty
+Copyright (c) 2014-2022 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/characterutils",
-  "version": "4.2.0",
+  "version": "5.0.1-canary.269.5b9ce8a.0",
   "description": "CharacterUtils",
   "keywords": [
     "Roblox",
@@ -25,13 +25,13 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/deferred": "^2.1.0",
-    "@quenty/loader": "^4.1.0",
-    "@quenty/maid": "^2.3.0",
-    "@quenty/promise": "^4.2.0"
+    "@quenty/deferred": "2.1.0",
+    "@quenty/loader": "5.0.0",
+    "@quenty/maid": "2.3.0",
+    "@quenty/promise": "5.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "501844bd6c3d3f765fd3032b997d8030bc963a1f"
+  "gitHead": "5b9ce8a8da36bff12861cddfe093808c6f0a8b66"
 }

package/src/Shared/RxCharacterUtils.lua

@@ -0,0 +1,103 @@
+--[=[
+	Utilities for observing characters and their humanoids.
+	@class RxCharacterUtils
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local Brio = require("Brio")
+local Maid = require("Maid")
+local Observable = require("Observable")
+local RxBrioUtils = require("RxBrioUtils")
+local RxInstanceUtils = require("RxInstanceUtils")
+
+local RxCharacterUtils = {}
+
+--[=[
+	Observe a player's last character.
+	@param player Player
+	@return Observable<Brio<Model>>
+]=]
+function RxCharacterUtils.observeLastCharacterBrio(player: Player)
+	-- This assumes a player's 'Character' field is set to nil when
+	-- their character is destroyed, or when they leave the game.
+	return RxInstanceUtils.observePropertyBrio(player, "Character", function(character)
+		return character ~= nil
+	end)
+end
+
+--[=[
+	Observe a player's last humanoid. Note that it may not be alive!
+	@param player Player
+	@return Observable<Brio<Humanoid>>
+]=]
+function RxCharacterUtils.observeLastHumanoidBrio(player: Player)
+	return RxCharacterUtils.observeLastCharacterBrio(player):Pipe({
+		RxBrioUtils.switchMapBrio(function(character)
+			return RxInstanceUtils.observeLastNamedChildBrio(character, "Humanoid", "Humanoid")
+		end);
+	})
+end
+
+--[[
+	Returns an observable that emits a single brio with the value of the given humanoid.
+	When the humanoid dies, the brio is killed and the subscription completes.
+	If the humanoid is dead on subscription, the observable immediately completes with nothing emitted.
+	@param humanoid Humanoid
+	@return Observable<Brio<Humanoid>>
+]]
+local function observeHumanoidLifetimeAsBrio(humanoid: Humanoid)
+	return Observable.new(function(sub)
+		local function onDeath()
+			sub:Complete()
+		end
+
+		if humanoid.Health > 0 then
+			local maid = Maid.new()
+
+			maid._brio = Brio.new(humanoid)
+			sub:Fire(maid._brio)
+
+			-- Died can fire multiple times, but it's ok as we disconnect immediately.
+			maid:GiveTask(humanoid.Died:Connect(onDeath))
+
+			return maid
+		else
+			onDeath()
+		end
+	end)
+end
+
+--[=[
+	Observes a player's last living humanoid.
+
+	```lua
+	local Players = game:GetService("Players")
+
+	maid:GiveTask(
+		RxCharacterUtils.observeLastAliveHumanoidBrio(Players.LocalPlayer)
+			:Subscribe(function(humanoidBrio)
+				local humanoid: Humanoid = humanoidBrio:GetValue()
+				local humanoidMaid = humanoidBrio:ToMaid()
+
+				print("Humanoid:", humanoid)
+
+				humanoidMaid:GiveTask(function()
+					-- The maid cleans up on humanoid death, or when given player leaves the game.
+					print("Humanoid has been killed or destroyed!")
+				end)
+			end)
+	)
+	```
+	@param player Player
+	@return Observable<Brio<Humanoid>>
+]=]
+function RxCharacterUtils.observeLastAliveHumanoidBrio(player: Player)
+	return RxCharacterUtils.observeLastHumanoidBrio(player):Pipe({
+		RxBrioUtils.switchMapBrio(function(humanoid)
+			return observeHumanoidLifetimeAsBrio(humanoid)
+		end);
+	})
+end
+
+return RxCharacterUtils