@quenty/flipbook 9.17.0 → 9.17.1

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [9.17.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/flipbook@9.17.0...@quenty/flipbook@9.17.1) (2025-04-05)
+
+
+### Bug Fixes
+
+* Add types to packages ([2374fb2](https://github.com/Quenty/NevermoreEngine/commit/2374fb2b043cfbe0e9b507b3316eec46a4e353a0))
+
+
+
+
+
 # [9.17.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/flipbook@9.16.2...@quenty/flipbook@9.17.0) (2025-04-02)
 
 **Note:** Version bump only for package @quenty/flipbook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/flipbook",
-  "version": "9.17.0",
+  "version": "9.17.1",
   "description": "Handles playing back animated spritesheets",
   "keywords": [
     "Roblox",
@@ -25,19 +25,19 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/baseobject": "^10.8.0",
-    "@quenty/ducktype": "^5.8.1",
-    "@quenty/instanceutils": "^13.17.0",
-    "@quenty/loader": "^10.8.0",
-    "@quenty/maid": "^3.4.0",
-    "@quenty/promise": "^10.10.1",
-    "@quenty/rx": "^13.17.0",
-    "@quenty/sprites": "^13.16.0",
-    "@quenty/uiobjectutils": "^6.16.0",
-    "@quenty/valueobject": "^13.17.0"
+    "@quenty/baseobject": "^10.8.1",
+    "@quenty/ducktype": "^5.8.2",
+    "@quenty/instanceutils": "^13.17.1",
+    "@quenty/loader": "^10.8.1",
+    "@quenty/maid": "^3.4.1",
+    "@quenty/promise": "^10.10.2",
+    "@quenty/rx": "^13.17.1",
+    "@quenty/sprites": "^13.16.1",
+    "@quenty/uiobjectutils": "^6.16.1",
+    "@quenty/valueobject": "^13.17.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "e8ea56930e65322fcffc05a1556d5df988068f0b"
+  "gitHead": "78c3ac0ab08dd18085b6e6e6e4f745e76ed99f68"
 }

package/src/Client/Flipbook.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	A spritesheet that is animated. See [FlipbookPlayer] for playback.
 	@class Flipbook
@@ -16,21 +17,42 @@ local DuckTypeUtils = require("DuckTypeUtils")
 	.columns number
 	.imageRectSize Vector2
 	.frameRate number
-	.restFrame number | nil -- Optional reset frame
+	.restFrame number? -- Optional reset frame
 	@within Flipbook
 ]=]
+export type FlipbookData = {
+	image: string,
+	frameCount: number,
+	rows: number,
+	columns: number,
+	imageRectSize: Vector2,
+	frameRate: number?,
+	restFrame: number?,
+}
 
 local Flipbook = {}
 Flipbook.ClassName = "Flipbook"
 Flipbook.__index = Flipbook
 
+export type Flipbook = typeof(setmetatable(
+	{} :: {
+		_frameSprites: { [number]: Sprite.Sprite? },
+		_frameCount: number,
+		_frameRate: number,
+		_imageRectSize: Vector2,
+		_restFrame: number?,
+		_imageId: string,
+	},
+	Flipbook
+))
+
 --[=[
 	Constructs a new Flipbook
 	@param data FlipbookData
 	@return Flipbook
 ]=]
-function Flipbook.new(data)
-	local self = setmetatable({}, Flipbook)
+function Flipbook.new(data: FlipbookData): Flipbook
+	local self: Flipbook = setmetatable({} :: any, Flipbook)
 
 	self._frameSprites = {}
 	self._frameRate = 60
@@ -44,7 +66,7 @@ function Flipbook.new(data)
 		assert(data.columns, "Bad columns")
 		assert(data.rows, "Bad rows")
 
-		self:SetFrameCount(data.rows*data.columns)
+		self:SetFrameCount(data.rows * data.columns)
 	end
 
 	if data.frameRate then
@@ -62,73 +84,76 @@ function Flipbook.new(data)
 	return self
 end
 
-function Flipbook.isFlipbook(value)
+function Flipbook.isFlipbook(value: any): boolean
 	return DuckTypeUtils.isImplementation(Flipbook, value)
 end
 
-function Flipbook:_loadFrames(image, columns, imageRectSize)
+function Flipbook._loadFrames(self: Flipbook, image: string, columns: number, imageRectSize: Vector2)
 	assert(type(columns) == "number", "Bad columns")
 	assert(typeof(imageRectSize) == "Vector2", "Bad imageRectSize")
 
 	self:SetImageRectSize(imageRectSize)
 
-	for i=0, self._frameCount do
+	for i = 0, self._frameCount do
 		local x = i % columns
 		local y = math.floor(i / columns)
-		local position = imageRectSize*Vector2.new(x, y)
+		local position = imageRectSize * Vector2.new(x, y)
 
 		local index = i + 1
 		local name = string.format("Frame_%d", index)
 
-		self:SetSpriteAtIndex(index, Sprite.new({
-			Texture = image;
-			Size = imageRectSize;
-			Position = position;
-			Name = name;
-		}))
+		self:SetSpriteAtIndex(
+			index,
+			Sprite.new({
+				Texture = image,
+				Size = imageRectSize,
+				Position = position,
+				Name = name,
+			})
+		)
 	end
 end
 
-function Flipbook:GetRestFrame()
+function Flipbook.GetRestFrame(self: Flipbook): number?
 	return self._restFrame
 end
 
-function Flipbook:SetSpriteAtIndex(index, sprite)
+function Flipbook.SetSpriteAtIndex(self: Flipbook, index: number, sprite: Sprite.Sprite)
 	assert(type(index) == "number", "Bad index")
 	assert(type(sprite) == "table", "Bad sprite")
 
 	self._frameSprites[index] = sprite
 end
 
-function Flipbook:SetImageRectSize(imageRectSize)
+function Flipbook.SetImageRectSize(self: Flipbook, imageRectSize: Vector2)
 	assert(typeof(imageRectSize) == "Vector2", "No imageRectSize")
 
 	self._imageRectSize = imageRectSize
 end
 
-function Flipbook:SetFrameCount(frameCount)
+function Flipbook.SetFrameCount(self: Flipbook, frameCount: number)
 	assert(type(frameCount) == "number", "Bad frameCount")
 
 	self._frameCount = frameCount
 end
 
-function Flipbook:SetFrameRate(frameRate)
+function Flipbook.SetFrameRate(self: Flipbook, frameRate: number)
 	assert(type(frameRate) == "number", "Bad frameRate")
 
 	self._frameRate = frameRate
 end
 
-function Flipbook:GetPreloadAssetId()
+function Flipbook.GetPreloadAssetId(self: Flipbook): { string }
 	return { self._imageId }
 end
 
-function Flipbook:GetSprite(index)
+function Flipbook.GetSprite(self: Flipbook, index: number): Sprite.Sprite?
 	assert(type(index) == "number", "Bad index")
 
 	return self._frameSprites[index]
 end
 
-function Flipbook:HasSprite(index)
+function Flipbook.HasSprite(self: Flipbook, index: number): boolean
 	assert(type(index) == "number", "Bad index")
 
 	return self._frameSprites[index] ~= nil
@@ -138,7 +163,7 @@ end
 	Gets the sprite size
 	@return Vector2
 ]=]
-function Flipbook:GetImageRectSize()
+function Flipbook.GetImageRectSize(self: Flipbook): Vector2
 	return self._imageRectSize
 end
 
@@ -146,7 +171,7 @@ end
 	Gets the frames per a second
 	@return number
 ]=]
-function Flipbook:GetFrameRate()
+function Flipbook.GetFrameRate(self: Flipbook): number
 	return self._frameRate
 end
 
@@ -154,15 +179,15 @@ end
 	Gets the play time for the animated sheet
 	@return number
 ]=]
-function Flipbook:GetPlayTime()
-	return self._frameCount/self._frameRate
+function Flipbook.GetPlayTime(self: Flipbook): number
+	return self._frameCount / self._frameRate
 end
 
 --[=[
 	Retrieves the frames for the sprite sheet.
-	@return frames
+	@return number
 ]=]
-function Flipbook:GetFrameCount()
+function Flipbook.GetFrameCount(self: Flipbook): number
 	return self._frameCount
 end
 

package/src/Client/Library/FlipbookLibrary.lua

@@ -6,6 +6,7 @@
 local require = require(script.Parent.loader).load(script)
 
 local Flipbook = require("Flipbook")
+local _ServiceBag = require("ServiceBag")
 
 local FlipbookLibrary = {}
 FlipbookLibrary.__index = FlipbookLibrary
@@ -23,7 +24,7 @@ function FlipbookLibrary.new(serviceName, register)
 	return self
 end
 
-function FlipbookLibrary:Init(serviceBag)
+function FlipbookLibrary:Init(serviceBag: _ServiceBag.ServiceBag)
 	assert(self ~= FlipbookLibrary, "Should construct new FlipbookLibrary")
 	assert(not self._spritesheets, "Already initialized")
 	self._serviceBag = assert(serviceBag, "No serviceBag")
@@ -37,7 +38,7 @@ function FlipbookLibrary:GetPreloadAssetIds()
 	assert(self._spritesheets, "Not initialized")
 
 	local assets = {}
-	for _, sheet in pairs(self._spritesheets) do
+	for _, sheet in self._spritesheets do
 		table.insert(assets, sheet:GetPreloadAssetId())
 	end
 	return assets

package/src/Client/Player/FlipbookPlayer.lua

@@ -1,3 +1,4 @@
+--!strict
 --[=[
 	Plays an [Flipbook] on a given imagelabel.
 	@class FlipbookPlayer
@@ -13,42 +14,70 @@ local Maid = require("Maid")
 local Promise = require("Promise")
 local Rx = require("Rx")
 local ValueObject = require("ValueObject")
+local _Observable = require("Observable")
 
 local FlipbookPlayer = setmetatable({}, BaseObject)
 FlipbookPlayer.ClassName = "FlipbookPlayer"
 FlipbookPlayer.__index = FlipbookPlayer
 
+type PlayData = {
+	startTime: number,
+	times: number,
+}
+
+export type FlipbookPlayer = typeof(setmetatable(
+	{} :: {
+		_obj: ImageLabel | ImageButton,
+		_maid: Maid.Maid,
+		_isPlaying: ValueObject.ValueObject<boolean>,
+		_isBoomarang: ValueObject.ValueObject<boolean>,
+		_playData: ValueObject.ValueObject<PlayData>,
+		_flipbook: ValueObject.ValueObject<Flipbook.Flipbook>,
+
+		_originalImage: string,
+		_originalRectOffset: UDim2,
+		_originalRectSize: UDim2,
+	},
+	{ __index = FlipbookPlayer}
+))
+
+type State = {
+	flipbook: Flipbook.Flipbook?,
+	playData: PlayData?,
+}
+
 --[=[
 	Constructs a new FlipbookPlayer
 
-	@param imageLabel ImageLabel
+	@param imageLabel ImageLabel | ImageButton
 	@return FlipbookPlayer
 ]=]
-function FlipbookPlayer.new(imageLabel)
-	local self = setmetatable(BaseObject.new(imageLabel), FlipbookPlayer)
+function FlipbookPlayer.new(imageLabel: ImageLabel | ImageButton): FlipbookPlayer
+	local self: FlipbookPlayer = setmetatable(BaseObject.new(imageLabel) :: any, FlipbookPlayer)
 
-	assert(typeof(self._obj) == "Instance" and (self._obj:IsA("ImageLabel") or self._obj:IsA("ImageButton")), "Bad imageLabel")
+	assert(
+		typeof(self._obj) == "Instance" and (self._obj:IsA("ImageLabel") or self._obj:IsA("ImageButton")),
+		"Bad imageLabel"
+	)
 
 	self._isPlaying = self._maid:Add(ValueObject.new(false, "boolean"))
-
 	self._isBoomarang = self._maid:Add(ValueObject.new(false, "boolean"))
-
 	self._playData = self._maid:Add(ValueObject.new(nil))
-
 	self._flipbook = self._maid:Add(ValueObject.new(nil))
 
-	self._originalImage = self._obj.Image
-	self._originalRectOffset = self._obj.ImageRectOffset
-	self._originalRectSize = self._obj.ImageRectSize
+	local obj: any = self._obj
+	self._originalImage = obj.Image
+	self._originalRectOffset = obj.ImageRectOffset
+	self._originalRectSize = obj.ImageRectSize
 
 	self._maid:GiveTask(Rx.combineLatest({
-		playData = self._playData:Observe();
-		flipbook = self._flipbook:Observe();
+		playData = self._playData:Observe(),
+		flipbook = self._flipbook:Observe(),
 	}):Subscribe(function(state)
 		if state.flipbook then
 			if state.playData then
 				self._isPlaying.Value = true
-				self._maid._playing = self:_execPlay(state.flipbook, state.playData)
+				self._maid._playing = self:_execPlay(state.flipbook, state.playData :: any)
 			else
 				self._isPlaying.Value = false
 				self._maid._playing = nil
@@ -57,16 +86,16 @@ function FlipbookPlayer.new(imageLabel)
 				if restFrame then
 					self:_updateToFrame(state.flipbook, restFrame)
 				else
-					self._obj.Image = self._originalImage
-					self._obj.ImageRectOffset = self._originalRectOffset
-					self._obj.ImageRectSize = self._originalRectSize
+					obj.Image = self._originalImage
+					obj.ImageRectOffset = self._originalRectOffset
+					obj.ImageRectSize = self._originalRectSize
 				end
 			end
 		else
 			self._isPlaying.Value = false
-			self._obj.Image = self._originalImage
-			self._obj.ImageRectOffset = self._originalRectOffset
-			self._obj.ImageRectSize = self._originalRectSize
+			obj.Image = self._originalImage
+			obj.ImageRectOffset = self._originalRectOffset
+			obj.ImageRectSize = self._originalRectSize
 		end
 	end))
 
@@ -77,7 +106,7 @@ end
 	Sets the current sheet and starts play if needed
 	@param flipbook Flipbook
 ]=]
-function FlipbookPlayer:SetFlipbook(flipbook)
+function FlipbookPlayer:SetFlipbook(flipbook: Flipbook.Flipbook)
 	assert(Flipbook.isFlipbook(flipbook), "Bad flipbook")
 
 	self._flipbook.Value = flipbook
@@ -87,7 +116,7 @@ end
 	Gets the current flipbook
 	@return Flipbook?
 ]=]
-function FlipbookPlayer:GetFlipbook()
+function FlipbookPlayer:GetFlipbook(): Flipbook.Flipbook?
 	return self._flipbook.Value
 end
 
@@ -96,7 +125,7 @@ end
 
 	@return Promise
 ]=]
-function FlipbookPlayer:PromisePlayOnce()
+function FlipbookPlayer:PromisePlayOnce(): Promise.Promise<()>
 	return self:PromisePlayRepeat(1)
 end
 
@@ -106,12 +135,12 @@ end
 	@param times number
 	@return Promise
 ]=]
-function FlipbookPlayer:PromisePlayRepeat(times)
+function FlipbookPlayer:PromisePlayRepeat(times: number): Promise.Promise<()>
 	assert(type(times) == "number", "Bad times")
 
-	local data = {
-		startTime = os.clock();
-		times = times;
+	local data: PlayData = {
+		startTime = os.clock(),
+		times = times,
 	}
 
 	self._playData.Value = data
@@ -124,7 +153,7 @@ end
 
 	@param isBoomarang boolean
 ]=]
-function FlipbookPlayer:SetIsBoomarang(isBoomarang)
+function FlipbookPlayer:SetIsBoomarang(isBoomarang: boolean)
 	assert(type(isBoomarang) == "boolean", "Bad isBoomarang")
 
 	self._isBoomarang.Value = isBoomarang
@@ -133,17 +162,17 @@ end
 --[=[
 	Plays the flipbook indefinitely
 ]=]
-function FlipbookPlayer:Play()
+function FlipbookPlayer:Play(): ()
 	self._playData.Value = {
-		startTime = 0; -- Synchronize with other variants
-		times = math.huge;
+		startTime = 0, -- Synchronize with other variants
+		times = math.huge,
 	}
 end
 
 --[=[
 	Stops the flipbook
 ]=]
-function FlipbookPlayer:Stop()
+function FlipbookPlayer:Stop(): ()
 	self._playData.Value = nil
 end
 
@@ -151,7 +180,7 @@ end
 	Returns true if the flipbook is playing
 	@return boolean
 ]=]
-function FlipbookPlayer:IsPlaying()
+function FlipbookPlayer:IsPlaying(): boolean
 	return self._isPlaying.Value
 end
 
@@ -159,11 +188,11 @@ end
 	Observes if the flipbook is playing
 	@return Observable<boolean>
 ]=]
-function FlipbookPlayer:ObserveIsPlaying()
+function FlipbookPlayer:ObserveIsPlaying(): _Observable.Observable<boolean>
 	return self._isPlaying:Observe()
 end
 
-function FlipbookPlayer:_promiseDonePlaying(data)
+function FlipbookPlayer:_promiseDonePlaying(data: { any }): Promise.Promise<()>
 	assert(type(data) == "table", "Bad data")
 
 	local maid = Maid.new()
@@ -191,7 +220,7 @@ function FlipbookPlayer:_promiseDonePlaying(data)
 	return promise
 end
 
-function FlipbookPlayer:_execPlay(flipbook, playData)
+function FlipbookPlayer:_execPlay(flipbook: Flipbook.Flipbook, playData: PlayData): Maid.Maid
 	assert(type(playData) == "table", "Bad playData")
 	assert(type(playData.startTime) == "number", "Bad playData.startTime")
 
@@ -205,21 +234,21 @@ function FlipbookPlayer:_execPlay(flipbook, playData)
 	return maid
 end
 
-function FlipbookPlayer:_computeFrameCount(originalFrameCount, isBoomarang)
+function FlipbookPlayer:_computeFrameCount(originalFrameCount: number, isBoomarang: boolean): number
 	if isBoomarang then
-		return 2*originalFrameCount - 2
+		return 2 * originalFrameCount - 2
 	else
 		return originalFrameCount
 	end
 end
 
-function FlipbookPlayer:_update(flipbook, currentTime, playData)
+function FlipbookPlayer:_update(flipbook: Flipbook.Flipbook, currentTime: number, playData: PlayData)
 	local isBoomarang = self._isBoomarang.Value
-	local fps = flipbook:GetFrameRate()
-	local originalFrameCount = flipbook:GetFrameCount()
+	local fps: number = flipbook:GetFrameRate()
+	local originalFrameCount: number = flipbook:GetFrameCount()
 
-	local frameCount = self:_computeFrameCount(originalFrameCount, isBoomarang)
-	local frame = (math.floor((currentTime - playData.startTime)*fps)%frameCount) + 1
+	local frameCount: number = self:_computeFrameCount(originalFrameCount, isBoomarang)
+	local frame: number = (math.floor((currentTime - playData.startTime) * fps) % frameCount) + 1
 
 	if isBoomarang then
 		if frame > originalFrameCount then
@@ -231,11 +260,11 @@ function FlipbookPlayer:_update(flipbook, currentTime, playData)
 	if playData.times ~= math.huge then
 		local executeFrameCount = originalFrameCount
 		if isBoomarang then
-			executeFrameCount = 2*originalFrameCount - 1
+			executeFrameCount = 2 * originalFrameCount - 1
 		end
 
 		local elapsed = os.clock() - playData.startTime
-		local totalPlayTimeAllowed = playData.times*executeFrameCount/fps
+		local totalPlayTimeAllowed = playData.times * executeFrameCount / fps
 
 		if elapsed > totalPlayTimeAllowed then
 			isOver = true
@@ -250,7 +279,7 @@ function FlipbookPlayer:_update(flipbook, currentTime, playData)
 	end
 end
 
-function FlipbookPlayer:_updateToFrame(flipbook, frame)
+function FlipbookPlayer:_updateToFrame(flipbook: Flipbook.Flipbook, frame: number)
 	local sprite = flipbook:GetSprite(frame)
 	if sprite then
 		sprite:Style(self._obj)

package/src/Client/Player/FlipbookPlayer.story.lua

@@ -9,7 +9,7 @@ local FlipbookPlayer = require("FlipbookPlayer")
 local Maid = require("Maid")
 local UICornerUtils = require("UICornerUtils")
 
-local function makeLabel(maid, flipbook, target, isBoomarang)
+local function makeLabel(maid: Maid.Maid, flipbook: Flipbook.Flipbook, target: Instance, isBoomarang: boolean)
 	local size = flipbook:GetImageRectSize()
 
 	local imageLabel = Instance.new("ImageLabel")
@@ -65,7 +65,7 @@ local function makeButton(maid, flipbook, target, isBoomarang)
 	return imageButton
 end
 
-return function(target)
+return function(target: Instance)
 	local maid = Maid.new()
 
 	local container = Instance.new("Frame")