Local character

Author: Sleitnick

.github/workflows/ci.yaml

@@ -32,5 +32,5 @@ jobs:
     - uses: JohnnyMorganz/stylua-action@v4
       with:
         token: ${{ secrets.GITHUB_TOKEN }}
-        version: v2.3.0
+        version: v2.3.1
         args: --check ./lib

docs/Observers/characters.md

@@ -28,3 +28,12 @@ Observers.observeCharacter(function(player, character)
 	end
 end)
 ```
+
+There are scenarios where you only want to observe characters from a select list of players.
+This can be done by providing a list of players as the final argument to `observeCharater`:
+
+```lua
+Observers.observeCharacter(function(player, character)
+	...
+end, { somePlayer, anotherPlayer }) -- Only observe characters from 'somePlayer' and 'anotherPlayer'
+```

docs/Observers/localcharacter.md

@@ -0,0 +1,13 @@
+# Local Character
+
+Use the `observeLocalCharacter` observer to observe the lifespan of the local character.
+This can only be run on the client.
+
+```lua
+Observers.observeLocalCharacter(function(character)
+	print("Local character has spawned")
+	return function()
+		print("Local character has been removed")
+	end
+end)
+```

lib/init.luau

@@ -12,4 +12,5 @@ return {
 	observeProperty = require(script.observeProperty),
 	observePlayer = require(script.observePlayer),
 	observeCharacter = require(script.observeCharacter),
+	observeLocalCharacter = require(script.observeLocalCharacter),
 }

lib/observeCharacter.luau

@@ -19,9 +19,22 @@ type Callback = (player: Player, character: Model) -> (() -> ())?
 		end
 	end)
 	```
+
+	An optional `allowedPlayers` array can be provided. Only characters
+	belonging to players in the array are observed.
+
+	```lua
+	observeCharacter(function(player, character)
+		-- ...
+	end, { somePlayer, anotherPlayer })
+	```
 ]=]
-local function observeCharacter(callback: Callback): () -> ()
+local function observeCharacter(callback: Callback, allowedPlayers: { Player }?): () -> ()
 	return observePlayer(function(player)
+		if allowedPlayers ~= nil and not table.find(allowedPlayers, player) then
+			return nil
+		end
+
 		local cleanupFn: (() -> ())? = nil
 
 		local characterAddedConn: RBXScriptConnection

lib/observeLocalCharacter.luau

@@ -0,0 +1,76 @@
+--!strict
+
+local Players = game:GetService("Players")
+local RunService = game:GetService("RunService")
+
+local IS_CLIENT = RunService:IsClient()
+
+type Callback = (character: Model) -> (() -> ())?
+
+--[=[
+	@within Observers
+	@client
+
+	Creates an observer that captures the local character in the game. This
+	can only be called from client-side code.
+
+	```lua
+	-- In a LocalScript or Client-context script
+	observeLocalCharacter(function(character)
+		print("Local character spawned")
+
+		return function()
+			-- Cleanup
+			print("Local character removed")
+		end
+	end)
+	```
+]=]
+local function observeLocalCharacter(callback: Callback): () -> ()
+	assert(IS_CLIENT, "observeLocalCharacter can only be called from the client")
+
+	local cleanup: (() -> ())? = nil
+	local subscribed = true
+
+	local function onCharacterAdded(character: Model)
+		local cleanupFn: (() -> ())? = nil
+
+		local ancestryChangedConn: RBXScriptConnection
+		ancestryChangedConn = character.AncestryChanged:Connect(function(_, parent)
+			if parent == nil and ancestryChangedConn.Connected then
+				ancestryChangedConn:Disconnect()
+				if typeof(cleanupFn) == "function" and subscribed then
+					task.spawn(cleanupFn)
+					if cleanup == cleanupFn then
+						cleanup = nil
+					end
+				end
+			end
+		end)
+
+		cleanupFn = callback(character)
+		if typeof(cleanupFn) == "function" then
+			if ancestryChangedConn.Connected then
+				cleanup = cleanupFn
+			else
+				task.spawn(cleanupFn)
+			end
+		end
+	end
+
+	local characterAddedConn = Players.LocalPlayer.CharacterAdded:Connect(onCharacterAdded)
+	if Players.LocalPlayer.Character ~= nil then
+		task.spawn(onCharacterAdded, Players.LocalPlayer.Character)
+	end
+
+	return function()
+		subscribed = false
+		characterAddedConn:Disconnect()
+		if typeof(cleanup) == "function" then
+			task.spawn(cleanup)
+			cleanup = nil
+		end
+	end
+end
+
+return observeLocalCharacter

rokit.toml

@@ -4,7 +4,7 @@
 # New tools can be added by running `rokit add <tool>` in a terminal.
 
 [tools]
-StyLua = "JohnnyMorganz/StyLua@2.3.0"
+StyLua = "JohnnyMorganz/StyLua@2.3.1"
 selene = "Kampfkarren/selene@0.29.0"
 wally = "UpliftGames/wally@0.3.2"
 rojo = "rojo-rbx/rojo@7.6.0"