SpriteSheetManager — GUI Sprite Sheet Animator
A fully modular image-based sprite sheet animator designed for UI animations with maximum flexibility and minimal effort.
Get the module on Creator Marketplace
Inspired by this post by @HungryHungryFox02.
Special thanks to ChatGPT for writing every single line of code.
Features
Regular loop
Bounce (ping-pong) loop
Frame skipping
Manual direction
Reversible play
Runtime FPS control
Pause, resume, stop
Event-driven architecture
Lock row/column playback
No external dependencies. Plug & play.
Quick Start
local SpriteSheetManager = require(path.to.SpriteSheetManager)
local manager = SpriteSheetManager.new({
ImageLabel = script.Parent.ImageLabel,
Frames = 16,
Rows = 4,
Columns = 4
})
manager:Play()
🏗️ Full Constructor Options
local manager = SpriteSheetManager.new({
ImageLabel = yourImageLabel,
Frames = 12,
Rows = 3,
Columns = 4,
FPS = 24,
isLooped = true,
isBounceLooped = false, -- isBounceLooped will override isLooped
InitialFrame = 1, -- initial frame will overrite (initial) row and column
InitialRow = 1,
InitialColumn = 1,
IgnoreFrames = {2, 4},
IgnoreRows = {3},
IgnoreColumns = {1},
isOneDimensional = false,
isTopToBottom = false -- this will only work if isOneDimensional is true
})
Controls
manager:Play()
manager:Pause()
manager:Resume()
manager:Stop()
manager:ReversePlay() -- changes direction before calling Play()
manager:SetFPS(15)
print(manager:GetFPS())
manager:SetFrame(6)
print(manager:GetFrame())
manager:SetDirection(-1)
print(manager:GetDirection())
🔒 Locking Playback (Row/Column)
manager:LockRow(3) -- Locks given row, plays across columns
manager:LockColumn(3) -- Locks given column, plays across rows
manager:ClearLock() -- Unlocks both
BindOns
Use :BindOnX() to bind functions on Events.
manager:BindOnFrameChanged(function(frame)
print("Frame:", frame)
end)
manager:BindOnBounceReversed(function()
print("Direction:", manager:GetDirection())
end)
manager:OnStopped(function()
print("Stopped at:", manager:GetFrame())
end)
| Event Name | When it Fires |
|---|---|
FrameChanged |
On every visible frame update |
Paused |
When Pause() is called |
Resumed |
When Resume() is called |
Stopped |
When animation is stopped |
Looped |
On a normal loop wraparound |
BounceReversed |
Direction flips in bounce mode |
State Check
print(manager:GetState()) --> "Playing" | "Paused" | "Stopped"
print(manager:isPlaying()) --> true/false
print(manager:isPaused()) --> true/false
print(manager:isStopped()) --> true/false
Requirements
- Sprite sheet must be evenly spaced (grid).
- Target must be
ImageLabel. - Recommended
ScaleType = Cropon ImageLabel. - For previewing in studio, change ImageLabel size property to match
Size = UDim2.fromScale(columns, rows).
Limitations
FPS was previously capped at 60 — now unlimited!- Do not enable both
isLoopedandisBounceLoopedat the same time. - Do not enable both
RowandColumnLockat the same time. - Works only with ImageLabel (no ImageButton, etc.)
- Ensure consistent layout for accurate animations.
Frames,Rows,Columnscount must entered by hand.
Sample Setup
Example: UI Button with Sprite Animation
local SpriteSheetManager = require(path.to.SpriteSheetManager)
local button = script.Parent.ImageLabel
local animator = SpriteSheetManager.new({
ImageLabel = button,
Frames = 20,
Rows = 5,
Columns = 4,
FPS = 16,
isBounceLooped = true
})
button.MouseEnter:Connect(function()
animator:Play()
end)
button.MouseLeave:Connect(function()
animator:Stop()
end)
Got feedback or suggestions? Drop them below!
Enjoy animating! 
