@quenty/animations 8.17.2 → 8.17.3

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [8.17.3](https://github.com/Quenty/NevermoreEngine/compare/@quenty/animations@8.17.2...@quenty/animations@8.17.3) (2025-04-10)
+
+**Note:** Version bump only for package @quenty/animations
+
+
+
+
+
 ## [8.17.2](https://github.com/Quenty/NevermoreEngine/compare/@quenty/animations@8.17.0...@quenty/animations@8.17.2) (2025-04-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/animations",
-  "version": "8.17.2",
+  "version": "8.17.3",
   "description": "Utility methods for playing back animations on Roblox",
   "keywords": [
     "Roblox",
@@ -25,20 +25,20 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "^10.8.2",
+    "@quenty/baseobject": "^10.8.3",
     "@quenty/enumutils": "^3.4.2",
     "@quenty/humanoidanimatorutils": "^3.1.2",
-    "@quenty/loader": "^10.8.2",
-    "@quenty/maid": "^3.4.2",
-    "@quenty/promise": "^10.10.3",
-    "@quenty/promisemaid": "^5.10.3",
-    "@quenty/rbxasset": "^5.8.2",
-    "@quenty/rx": "^13.17.2",
-    "@quenty/signal": "^7.10.2",
-    "@quenty/valueobject": "^13.17.2"
+    "@quenty/loader": "^10.8.3",
+    "@quenty/maid": "^3.4.3",
+    "@quenty/promise": "^10.10.4",
+    "@quenty/promisemaid": "^5.10.4",
+    "@quenty/rbxasset": "^5.8.3",
+    "@quenty/rx": "^13.17.3",
+    "@quenty/signal": "^7.10.3",
+    "@quenty/valueobject": "^13.17.3"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "64def70499ec067077ee39f279936b620b217847"
+  "gitHead": "b06c070ae91d5dab7bd8de6e290ad2caabb15d8f"
 }

package/src/Shared/AnimationSlotPlayer.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	Acts as a priority slot which can be overridden and play any animation in.
 	See Roblox's animation system for more information.
@@ -18,14 +19,26 @@ local AnimationSlotPlayer = setmetatable({}, BaseObject)
 AnimationSlotPlayer.ClassName = "AnimationSlotPlayer"
 AnimationSlotPlayer.__index = AnimationSlotPlayer
 
+export type AnimationSlotPlayer = typeof(setmetatable(
+	{} :: {
+		_maid: Maid.Maid,
+		_animationTarget: ValueObject.ValueObject<Instance>,
+		_defaultFadeTime: ValueObject.ValueObject<number>,
+		_defaultAnimationPriority: ValueObject.ValueObject<Enum.AnimationPriority>,
+		_currentAnimationTrackData: ValueObject.ValueObject<any>,
+		_currentAnimationId: ValueObject.ValueObject<string>,
+	},
+	{} :: typeof({ __index = AnimationSlotPlayer })
+)) & BaseObject.BaseObject
+
 --[=[
 	Creates a new AnimationSlotPlayer with a target to play the animation on.
 
 	@param animationTarget Instance? | Observable<Instance>
 	@return AnimationSlotPlayer
 ]=]
-function AnimationSlotPlayer.new(animationTarget)
-	local self = setmetatable(BaseObject.new(), AnimationSlotPlayer)
+function AnimationSlotPlayer.new(animationTarget): AnimationSlotPlayer
+	local self: AnimationSlotPlayer = setmetatable(BaseObject.new() :: any, AnimationSlotPlayer)
 
 	self._animationTarget = self._maid:Add(ValueObject.new(nil))
 	self._defaultFadeTime = self._maid:Add(ValueObject.new(0.1, "number"))
@@ -45,7 +58,7 @@ end
 
 	@param defaultFadeTime number
 ]=]
-function AnimationSlotPlayer:SetDefaultFadeTime(defaultFadeTime: number)
+function AnimationSlotPlayer.SetDefaultFadeTime(self: AnimationSlotPlayer, defaultFadeTime: number)
 	self._defaultFadeTime.Value = defaultFadeTime
 end
 
@@ -54,8 +67,11 @@ end
 
 	@param defaultAnimationPriority number
 ]=]
-function AnimationSlotPlayer:SetDefaultAnimationPriority(defaultAnimationPriority)
-	assert(EnumUtils.isOfType(Enum.AnimationPriority, defaultAnimationPriority) or defaultAnimationPriority == nil, "Bad defaultAnimationPriority")
+function AnimationSlotPlayer.SetDefaultAnimationPriority(self: AnimationSlotPlayer, defaultAnimationPriority)
+	assert(
+		EnumUtils.isOfType(Enum.AnimationPriority, defaultAnimationPriority) or defaultAnimationPriority == nil,
+		"Bad defaultAnimationPriority"
+	)
 
 	self._defaultAnimationPriority.Value = defaultAnimationPriority
 end
@@ -65,10 +81,18 @@ end
 
 	@param animationTarget Instance | Observable<Instance>
 ]=]
-function AnimationSlotPlayer:SetAnimationTarget(animationTarget)
+function AnimationSlotPlayer.SetAnimationTarget(self: AnimationSlotPlayer, animationTarget)
 	self._animationTarget:Mount(animationTarget)
 end
 
+type AnimationData = {
+	animationId: string,
+	track: AnimationTrack,
+	originalSpeed: number?,
+	originalWeight: number?,
+	originalPriority: Enum.AnimationPriority?,
+}
+
 --[=[
 	Adjusts the speed of the animation playing in the slot
 
@@ -76,7 +100,7 @@ end
 	@param speed number
 	@return () -> () -- Callback to clean things up
 ]=]
-function AnimationSlotPlayer:AdjustSpeed(id: string | number, speed: number)
+function AnimationSlotPlayer.AdjustSpeed(self: AnimationSlotPlayer, id: string | number, speed: number)
 	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
 	assert(type(speed) == "number", "Bad speed")
 
@@ -84,8 +108,9 @@ function AnimationSlotPlayer:AdjustSpeed(id: string | number, speed: number)
 
 	local topMaid = Maid.new()
 
+	-- stylua: ignore
 	topMaid:GiveTask(self._currentAnimationTrackData
-		:ObserveBrio(function(data)
+		:ObserveBrio(function(data: AnimationData)
 			return data and data.animationId == animationId
 		end)
 		:Subscribe(function(brio)
@@ -93,7 +118,7 @@ function AnimationSlotPlayer:AdjustSpeed(id: string | number, speed: number)
 				return
 			end
 
-			local data = brio:GetValue()
+			local data: AnimationData = brio:GetValue()
 			local maid = brio:ToMaid()
 
 			data.track:AdjustSpeed(speed)
@@ -111,7 +136,7 @@ function AnimationSlotPlayer:AdjustSpeed(id: string | number, speed: number)
 	self._maid._currentSpeedAdjustment = topMaid
 
 	return function()
-		if self._maid._currentSpeedAdjustment == topMaid then
+		if self._maid._currentSpeedAdjustment :: any == topMaid then
 			self._maid._currentSpeedAdjustment = nil
 		end
 	end
@@ -125,7 +150,7 @@ end
 	@param fadeTime number?
 	@return () -> () -- Callback to clean things up
 ]=]
-function AnimationSlotPlayer:AdjustWeight(id: string, weight: number, fadeTime: number?)
+function AnimationSlotPlayer.AdjustWeight(self: AnimationSlotPlayer, id: string, weight: number, fadeTime: number?)
 	assert(RbxAssetUtils.isConvertableToRbxAsset(id), "Bad id")
 	assert(type(weight) == "number", "Bad weight")
 	assert(type(fadeTime) == "number" or fadeTime == nil, "Bad fadeTime")
@@ -134,6 +159,7 @@ function AnimationSlotPlayer:AdjustWeight(id: string, weight: number, fadeTime:
 
 	local topMaid = Maid.new()
 
+	-- stylua: ignore
 	topMaid:GiveTask(self._currentAnimationTrackData
 		:ObserveBrio(function(data)
 			return data and data.animationId == animationId
@@ -143,7 +169,7 @@ function AnimationSlotPlayer:AdjustWeight(id: string, weight: number, fadeTime:
 				return
 			end
 
-			local data = brio:GetValue()
+			local data: AnimationData = brio:GetValue()
 			local maid = brio:ToMaid()
 
 			data.track:AdjustWeight(weight, fadeTime)
@@ -161,7 +187,7 @@ function AnimationSlotPlayer:AdjustWeight(id: string, weight: number, fadeTime:
 	self._maid._currentWeightAdjustment = topMaid
 
 	return function()
-		if self._maid._currentWeightAdjustment == topMaid then
+		if self._maid._currentWeightAdjustment :: any == topMaid then
 			self._maid._currentWeightAdjustment = nil
 		end
 	end
@@ -177,7 +203,14 @@ end
 	@param priority Enum.AnimationPriority?
 	@return () -> () -- Callback to clean things up
 ]=]
-function AnimationSlotPlayer:Play(id: string | number, fadeTime: number?, weight: number?, speed: number?, priority: Enum.AnimationPriority?): () -> ()
+function AnimationSlotPlayer.Play(
+	self: AnimationSlotPlayer,
+	id: string | number,
+	fadeTime: number?,
+	weight: number?,
+	speed: number?,
+	priority: Enum.AnimationPriority?
+): () -> ()
 	fadeTime = fadeTime or self._defaultFadeTime.Value
 	priority = priority or self._defaultAnimationPriority.Value
 	weight = weight or 1 -- We need to explicitly adjust the weight here
@@ -186,45 +219,47 @@ function AnimationSlotPlayer:Play(id: string | number, fadeTime: number?, weight
 
 	local animationId = RbxAssetUtils.toRbxAssetId(id)
 
-	topMaid:GiveTask(self._animationTarget:ObserveBrio(function(target)
-		return target ~= nil
-	end):Subscribe(function(brio)
-		if brio:IsDead() then
-			return
-		end
-
-		local animationTarget = brio:GetValue()
-		local maid = brio:ToMaid()
-
-		local track = AnimationUtils.playAnimation(animationTarget, animationId, fadeTime, weight, speed, priority)
-		if track then
-			local data = {
-				animationId = animationId;
-				track = track;
-				originalSpeed = speed;
-				originalWeight = weight;
-				originalPriority = priority;
-			}
+	topMaid:GiveTask(self._animationTarget
+		:ObserveBrio(function(target)
+			return target ~= nil
+		end)
+		:Subscribe(function(brio)
+			if brio:IsDead() then
+				return
+			end
 
-			self._currentAnimationTrackData.Value = data
-			maid:GiveTask(function()
-				if self._currentAnimationTrackData.Value == data then
-					self._currentAnimationTrackData.Value = nil
-				end
-			end)
+			local animationTarget: any = brio:GetValue()
+			local maid = brio:ToMaid()
 
-			maid:GiveTask(function()
-				track:AdjustWeight(0, fadeTime or self._defaultFadeTime.Value)
-			end)
-		else
-			warn("[AnimationSlotPlayer] - Failed to get animation to play")
-		end
-	end))
+			local track = AnimationUtils.playAnimation(animationTarget, animationId, fadeTime, weight, speed, priority)
+			if track then
+				local data = {
+					animationId = animationId,
+					track = track,
+					originalSpeed = speed,
+					originalWeight = weight,
+					originalPriority = priority,
+				}
+
+				self._currentAnimationTrackData.Value = data
+				maid:GiveTask(function()
+					if self._currentAnimationTrackData.Value == data then
+						self._currentAnimationTrackData.Value = nil
+					end
+				end)
+
+				maid:GiveTask(function()
+					track:AdjustWeight(0, fadeTime or self._defaultFadeTime.Value)
+				end)
+			else
+				warn("[AnimationSlotPlayer] - Failed to get animation to play")
+			end
+		end))
 
 	self._maid._current = topMaid
 
 	return function()
-		if self._maid._current == topMaid then
+		if self._maid._current :: any == topMaid then
 			self._maid._current = nil
 		end
 	end
@@ -233,7 +268,7 @@ end
 --[=[
 	Stops the current animation playing
 ]=]
-function AnimationSlotPlayer:Stop()
+function AnimationSlotPlayer.Stop(self: AnimationSlotPlayer)
 	self._maid._current = nil
 end
 

package/src/Shared/AnimationTrackPlayer.lua

@@ -17,6 +17,20 @@ local AnimationTrackPlayer = setmetatable({}, BaseObject)
 AnimationTrackPlayer.ClassName = "AnimationTrackPlayer"
 AnimationTrackPlayer.__index = AnimationTrackPlayer
 
+export type AnimationTrackPlayer = typeof(setmetatable(
+	{} :: {
+		-- Public
+		KeyframeReached: Signal.Signal<()>,
+
+		-- Private
+		_animationTarget: ValueObject.ValueObject<Instance>,
+		_trackId: ValueObject.ValueObject<string | number>,
+		_currentTrack: ValueObject.ValueObject<AnimationTrack?>,
+		_animationPriority: ValueObject.ValueObject<number>,
+	},
+	{} :: typeof({ __index = AnimationTrackPlayer })
+)) & BaseObject.BaseObject
+
 --[=[
 	Plays an animation track in the target. Async loads the track when
 	all data is found.
@@ -25,8 +39,8 @@ AnimationTrackPlayer.__index = AnimationTrackPlayer
 	@param animationId string | number?
 	@return AnimationTrackPlayer
 ]=]
-function AnimationTrackPlayer.new(animationTarget, animationId)
-	local self = setmetatable(BaseObject.new() :: any, AnimationTrackPlayer)
+function AnimationTrackPlayer.new(animationTarget, animationId: string | number): AnimationTrackPlayer
+	local self: AnimationTrackPlayer = setmetatable(BaseObject.new() :: any, AnimationTrackPlayer)
 
 	self._animationTarget = self._maid:Add(ValueObject.new(nil))
 	self._trackId = self._maid:Add(ValueObject.new(nil))
@@ -50,33 +64,41 @@ end
 
 function AnimationTrackPlayer:_setupState()
 	self._maid:GiveTask(Rx.combineLatest({
-		animationTarget = self._animationTarget:Observe();
-		trackId = self._trackId:Observe();
-		animationPriority = self._animationPriority:Observe();
-	}):Pipe({
-		Rx.throttleDefer();
-	}):Subscribe(function(state)
-		if state.animationTarget and state.trackId then
-			self._currentTrack.Value = AnimationUtils.getOrCreateAnimationTrack(state.animationTarget, state.trackId, state.animationPriority)
-		else
-			self._currentTrack.Value = nil
-		end
-	end))
-
-	self._maid:GiveTask(self._currentTrack:ObserveBrio(function(track)
-		return track ~= nil
-	end):Subscribe(function(brio)
-		if brio:IsDead() then
-			return
-		end
-
-		local maid = brio:ToMaid()
-		local track = brio:GetValue()
+		animationTarget = self._animationTarget:Observe(),
+		trackId = self._trackId:Observe(),
+		animationPriority = self._animationPriority:Observe(),
+	})
+		:Pipe({
+			Rx.throttleDefer() :: any,
+		})
+		:Subscribe(function(state)
+			if state.animationTarget and state.trackId then
+				self._currentTrack.Value = AnimationUtils.getOrCreateAnimationTrack(
+					state.animationTarget,
+					state.trackId,
+					state.animationPriority
+				)
+			else
+				self._currentTrack.Value = nil
+			end
+		end))
 
-		maid:GiveTask(track.KeyframeReached:Connect(function(...)
-			self.KeyframeReached:Fire(...)
+	self._maid:GiveTask(self._currentTrack
+		:ObserveBrio(function(track)
+			return track ~= nil
+		end)
+		:Subscribe(function(brio)
+			if brio:IsDead() then
+				return
+			end
+
+			local maid = brio:ToMaid()
+			local track = brio:GetValue()
+
+			maid:GiveTask(track.KeyframeReached:Connect(function(...)
+				self.KeyframeReached:Fire(...)
+			end))
 		end))
-	end))
 end
 
 --[=[
@@ -84,7 +106,7 @@ end
 
 	@param animationId string | number
 ]=]
-function AnimationTrackPlayer:SetAnimationId(animationId)
+function AnimationTrackPlayer:SetAnimationId(animationId: string | number)
 	return self._trackId:Mount(animationId)
 end
 
@@ -93,7 +115,7 @@ end
 
 	@return string | number
 ]=]
-function AnimationTrackPlayer:GetAnimationId()
+function AnimationTrackPlayer:GetAnimationId(): string | number
 	return self._trackId.Value
 end
 

package/src/Shared/AnimationUtils.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	@class AnimationUtils
 ]=]