General purpose modules for Roblox development. [Read-only Codeberg mirror]
FadeUi, TweenSequence
+395
+47
Docs/FadeUi.md
+47
Docs/FadeUi.md
···
1
+
# FadeUi
2
+
3
+
Fade UI elements in and out using `TweenService`. Automatically traverses all descendant `GuiBase` elements and tweens their transparency properties.
4
+
5
+
## Methods
6
+
7
+
### `FadeOut`
8
+
9
+
`FadeOut(ui: GuiBase, transparencyInfo: TweenInfo, waitForEnd: boolean)` → `void`
10
+
11
+
Fades out all descendant `GuiBase` elements of the given UI container by tweening their transparency properties to `1`.
12
+
13
+
Handles the following instance types:
14
+
15
+
- `TextLabel`, `TextButton`, `TextBox`: tweens `BackgroundTransparency` and `TextTransparency`
16
+
- `ImageLabel`, `ImageButton`: tweens `BackgroundTransparency` and `ImageTransparency`
17
+
- `Frame`: tweens `BackgroundTransparency`
18
+
19
+
#### Parameters
20
+
21
+
| Name | Type | Required |
22
+
| ---------------- | ----------- | -------- |
23
+
| ui | `GuiBase` | Yes |
24
+
| transparencyInfo | `TweenInfo` | Yes |
25
+
| waitForEnd | `boolean` | Yes |
26
+
27
+
---
28
+
29
+
### `FadeIn`
30
+
31
+
`FadeIn(ui: GuiBase, transparencyInfo: TweenInfo, waitForEnd: boolean)` → `void`
32
+
33
+
Fades in all descendant `GuiBase` elements of the given UI container by tweening their transparency properties to `0`.
34
+
35
+
Handles the following instance types:
36
+
37
+
- `TextLabel`, `TextButton`, `TextBox`: tweens `BackgroundTransparency` and `TextTransparency`
38
+
- `ImageLabel`, `ImageButton`: tweens `BackgroundTransparency` and `ImageTransparency`
39
+
- `Frame`: tweens `BackgroundTransparency`
40
+
41
+
#### Parameters
42
+
43
+
| Name | Type | Required |
44
+
| ---------------- | ----------- | -------- |
45
+
| ui | `GuiBase` | Yes |
46
+
| transparencyInfo | `TweenInfo` | Yes |
47
+
| waitForEnd | `boolean` | Yes |
+92
Docs/TweenSequence.md
+92
Docs/TweenSequence.md
···
1
+
# TweenSequence
2
+
3
+
Play a sequence of tweens, waits, parallel tween groups, and callbacks with support for pausing and resuming mid-sequence.
4
+
5
+
## Types
6
+
7
+
### `TweenSequenceType`
8
+
9
+
```
10
+
{ number | Tween | {Tween} | () -> () }
11
+
```
12
+
13
+
A sequence is an ordered array of items. Each item is processed one at a time (except parallel groups), in the order it appears. Supported item types:
14
+
15
+
| Type | Behaviour |
16
+
| ------------- | ----------------------------------------------------------------------------------------------- |
17
+
| `number` | Waits for that many seconds before advancing. |
18
+
| `Tween` | Plays the tween and waits for it to complete before advancing. |
19
+
| `{Tween}` | Plays all tweens in parallel. Waits for the longest one to complete before advancing. |
20
+
| `() -> ()` | Calls the function immediately and advances. No waiting. |
21
+
22
+
---
23
+
24
+
## Constructor
25
+
26
+
### `Create`
27
+
28
+
`Create(sequence: TweenSequenceType)` → `TweenSequence`
29
+
30
+
Creates a new `TweenSequence` from the provided sequence. Does not begin playback automatically.
31
+
32
+
#### Parameters
33
+
34
+
| Name | Type | Required |
35
+
| -------- | -------------------- | -------- |
36
+
| sequence | `TweenSequenceType` | Yes |
37
+
38
+
#### Returns
39
+
40
+
| Type |
41
+
| --------------- |
42
+
| `TweenSequence` |
43
+
44
+
#### Example
45
+
46
+
```lua
47
+
local seq = TweenSequence.Create({
48
+
tweenA, -- plays tweenA, waits for completion
49
+
1.5, -- waits 1.5 seconds
50
+
{ tweenB, tweenC }, -- plays tweenB and tweenC in parallel, waits for longest
51
+
function() print("done!") end,
52
+
})
53
+
seq:Play()
54
+
```
55
+
56
+
---
57
+
58
+
## Properties
59
+
60
+
### `Playing`
61
+
62
+
`Playing: boolean`
63
+
64
+
`true` while the sequence is actively running. Set to `false` when the sequence completes or is paused.
65
+
66
+
---
67
+
68
+
## Methods
69
+
70
+
### `Play`
71
+
72
+
`Play()` → `void`
73
+
74
+
Plays the sequence from the beginning. Each item in the sequence is processed in order.
75
+
76
+
---
77
+
78
+
### `Pause`
79
+
80
+
`Pause()` → `void`
81
+
82
+
Pauses the sequence at the current step. Any actively playing `Tween` instances at that step are also paused. The elapsed time within the current step is retained for use by [`Resume`](#resume).
83
+
84
+
---
85
+
86
+
### `Resume`
87
+
88
+
`Resume()` → `void`
89
+
90
+
Resumes the sequence from where it was paused. Completes the remaining duration of the current step (accounting for elapsed time) before advancing to subsequent steps.
91
+
92
+
Does nothing if the sequence is already playing or has not been started.
+55
Modules/FadeUi.luau
+55
Modules/FadeUi.luau
···
1
+
--!optimize 2
2
+
--!strict
3
+
local module = {}
4
+
5
+
local TweenService = game:GetService("TweenService")
6
+
7
+
-- Fades out all descendant <code>GuiBase</code> elements of the given UI container.
8
+
-- Tweens <code>BackgroundTransparency</code>, <code>TextTransparency</code>, and <code>ImageTransparency</code> to 1.
9
+
-- Optionally waits for the tween to finish before returning.
10
+
function module.FadeOut(ui: GuiBase, transparencyInfo: TweenInfo, waitForEnd: boolean)
11
+
local uisToFade = {}
12
+
for _, v in ipairs(ui:GetDescendants()) do
13
+
if v:IsA("GuiBase") then
14
+
table.insert(uisToFade, v)
15
+
end
16
+
end
17
+
for _, v in ipairs(uisToFade) do
18
+
if v:IsA("TextLabel") or v:IsA("TextButton") or v:IsA("TextBox") then
19
+
TweenService:Create(v, transparencyInfo, { BackgroundTransparency = 1, TextTransparency = 1 }):Play()
20
+
elseif v:IsA("ImageLabel") or v:IsA("ImageButton") then
21
+
TweenService:Create(v, transparencyInfo, { BackgroundTransparency = 1, ImageTransparency = 1 }):Play()
22
+
elseif v:IsA("Frame") then
23
+
TweenService:Create(v, transparencyInfo, { BackgroundTransparency = 1 }):Play()
24
+
end
25
+
end
26
+
if waitForEnd == true then
27
+
task.wait(transparencyInfo.Time)
28
+
end
29
+
end
30
+
31
+
-- Fades in all descendant <code>GuiBase</code> elements of the given UI container.
32
+
-- Tweens <code>BackgroundTransparency</code>, <code>TextTransparency</code>, and <code>ImageTransparency</code> to 0.
33
+
-- Optionally waits for the tween to finish before returning.
34
+
function module.FadeIn(ui: GuiBase, transparencyInfo: TweenInfo, waitForEnd: boolean)
35
+
local uisToFade = {}
36
+
for _, v in ipairs(ui:GetDescendants()) do
37
+
if v:IsA("GuiBase") then
38
+
table.insert(uisToFade, v)
39
+
end
40
+
end
41
+
for _, v in ipairs(uisToFade) do
42
+
if v:IsA("TextLabel") or v:IsA("TextButton") or v:IsA("TextBox") then
43
+
TweenService:Create(v, transparencyInfo, { BackgroundTransparency = 0, TextTransparency = 0 }):Play()
44
+
elseif v:IsA("ImageLabel") or v:IsA("ImageButton") then
45
+
TweenService:Create(v, transparencyInfo, { BackgroundTransparency = 0, ImageTransparency = 0 }):Play()
46
+
elseif v:IsA("Frame") then
47
+
TweenService:Create(v, transparencyInfo, { BackgroundTransparency = 0 }):Play()
48
+
end
49
+
end
50
+
if waitForEnd == true then
51
+
task.wait(transparencyInfo.Time)
52
+
end
53
+
end
54
+
55
+
return module
+201
Modules/TweenSequence.luau
+201
Modules/TweenSequence.luau
···
1
+
--!optimize 2
2
+
--!strict
3
+
local RunService = game:GetService("RunService")
4
+
5
+
type TweenSequenceItem = number | Tween | { Tween } | () -> ()
6
+
export type TweenSequenceType = { TweenSequenceItem }
7
+
8
+
type CurrentState = {
9
+
thread: thread?,
10
+
index: number,
11
+
elapsed: number,
12
+
heartbeat: RBXScriptConnection?,
13
+
activeTweenIndices: { number },
14
+
}
15
+
16
+
type TweenSequenceImpl = {
17
+
__index: TweenSequenceImpl,
18
+
__tostring: (self: TweenSequence) -> string,
19
+
new: (sequence: TweenSequenceType) -> TweenSequence,
20
+
_connectHeartbeat: (self: TweenSequence) -> (),
21
+
_disconnectHeartbeat: (self: TweenSequence) -> (),
22
+
_runItem: (self: TweenSequence, item: TweenSequenceItem) -> (),
23
+
_resumeItem: (self: TweenSequence, item: TweenSequenceItem) -> (),
24
+
Play: (self: TweenSequence) -> (),
25
+
Pause: (self: TweenSequence) -> (),
26
+
Resume: (self: TweenSequence) -> (),
27
+
}
28
+
29
+
export type TweenSequence = typeof(setmetatable(
30
+
{} :: {
31
+
_sequence: TweenSequenceType,
32
+
_current: CurrentState,
33
+
Playing: boolean,
34
+
},
35
+
{} :: TweenSequenceImpl
36
+
))
37
+
38
+
local TweenSequence = {} :: TweenSequenceImpl
39
+
TweenSequence.__index = TweenSequence
40
+
41
+
-- Creates a new <code>TweenSequence</code> from a sequence of items.
42
+
-- Items can be <code>number</code> (wait), <code>Tween</code>, <code>{Tween}</code> (parallel), or <code>() -> ()</code> (callback).
43
+
function TweenSequence.new(sequence: TweenSequenceType): TweenSequence
44
+
local self = setmetatable({}, TweenSequence)
45
+
self._sequence = sequence
46
+
self.Playing = false
47
+
self._current = {
48
+
thread = nil,
49
+
index = 0,
50
+
elapsed = 0,
51
+
heartbeat = nil,
52
+
activeTweenIndices = {},
53
+
}
54
+
return self
55
+
end
56
+
57
+
function TweenSequence:_connectHeartbeat()
58
+
self._current.heartbeat = RunService.Heartbeat:Connect(function(dt: number)
59
+
self._current.elapsed += dt
60
+
end)
61
+
end
62
+
63
+
function TweenSequence:_disconnectHeartbeat()
64
+
if self._current.heartbeat then
65
+
self._current.heartbeat:Disconnect()
66
+
self._current.heartbeat = nil
67
+
end
68
+
end
69
+
70
+
function TweenSequence:_runItem(item: TweenSequenceItem)
71
+
if typeof(item) == "number" then
72
+
task.wait(item)
73
+
elseif typeof(item) == "table" then
74
+
self._current.activeTweenIndices = {}
75
+
for tweenIndex, tween in item do
76
+
tween:Play()
77
+
table.insert(self._current.activeTweenIndices, tweenIndex)
78
+
tween.Completed:Connect(function()
79
+
local idx = table.find(self._current.activeTweenIndices, tweenIndex)
80
+
if idx then
81
+
table.remove(self._current.activeTweenIndices, idx)
82
+
end
83
+
end)
84
+
end
85
+
local longest: Tween = item[1]
86
+
for _, tween in item do
87
+
if tween.TweenInfo.Time > longest.TweenInfo.Time then
88
+
longest = tween
89
+
end
90
+
end
91
+
longest.Completed:Wait()
92
+
elseif typeof(item) == "function" then
93
+
item()
94
+
else
95
+
item:Play()
96
+
item.Completed:Wait()
97
+
end
98
+
end
99
+
100
+
function TweenSequence:_resumeItem(item: TweenSequenceItem)
101
+
if typeof(item) == "number" then
102
+
local remaining = item - self._current.elapsed
103
+
if remaining > 0 then
104
+
task.wait(remaining)
105
+
end
106
+
elseif typeof(item) == "table" then
107
+
for _, tweenIndex in self._current.activeTweenIndices do
108
+
item[tweenIndex]:Play()
109
+
end
110
+
if #self._current.activeTweenIndices > 0 then
111
+
local longest: Tween = item[self._current.activeTweenIndices[1]]
112
+
for _, tweenIndex in self._current.activeTweenIndices do
113
+
local tween: Tween = item[tweenIndex]
114
+
if tween.TweenInfo.Time > longest.TweenInfo.Time then
115
+
longest = tween
116
+
end
117
+
end
118
+
longest.Completed:Wait()
119
+
end
120
+
else
121
+
local tween = item :: Tween
122
+
tween:Play()
123
+
tween.Completed:Wait()
124
+
end
125
+
end
126
+
127
+
-- Plays the sequence from the beginning.
128
+
-- Sets <code>Playing</code> to <code>true</code> for the duration of playback.
129
+
function TweenSequence:Play()
130
+
self._current.thread = task.spawn(function()
131
+
self.Playing = true
132
+
for index, item in self._sequence do
133
+
self._current.index = index
134
+
self._current.elapsed = 0
135
+
self._current.activeTweenIndices = {}
136
+
self:_connectHeartbeat()
137
+
self:_runItem(item)
138
+
self:_disconnectHeartbeat()
139
+
end
140
+
self.Playing = false
141
+
end)
142
+
end
143
+
144
+
-- Pauses the sequence at the current step.
145
+
-- Pauses any actively playing <code>Tween</code> instances at that step.
146
+
function TweenSequence:Pause()
147
+
self:_disconnectHeartbeat()
148
+
if self._current.thread then
149
+
task.cancel(self._current.thread)
150
+
self._current.thread = nil
151
+
end
152
+
local item = self._sequence[self._current.index]
153
+
if item then
154
+
if typeof(item) == "table" then
155
+
for _, tween in item do
156
+
if tween.PlaybackState == Enum.PlaybackState.Playing then
157
+
tween:Pause()
158
+
end
159
+
end
160
+
elseif typeof(item) ~= "number" and typeof(item) ~= "function" then
161
+
item:Pause()
162
+
end
163
+
end
164
+
self.Playing = false
165
+
end
166
+
167
+
-- Resumes the sequence from where it was paused.
168
+
-- Completes the remaining duration of the current step before advancing.
169
+
function TweenSequence:Resume()
170
+
if self._current.index == 0 or self.Playing then
171
+
return
172
+
end
173
+
self._current.thread = task.spawn(function()
174
+
self.Playing = true
175
+
local startIndex = self._current.index
176
+
self:_connectHeartbeat()
177
+
self:_resumeItem(self._sequence[startIndex])
178
+
self:_disconnectHeartbeat()
179
+
for index = startIndex + 1, #self._sequence do
180
+
self._current.index = index
181
+
self._current.elapsed = 0
182
+
self._current.activeTweenIndices = {}
183
+
self:_connectHeartbeat()
184
+
self:_runItem(self._sequence[index])
185
+
self:_disconnectHeartbeat()
186
+
end
187
+
self.Playing = false
188
+
end)
189
+
end
190
+
191
+
function TweenSequence:__tostring(): string
192
+
return ("TweenSequence(Playing=%s, step=%d/%d)"):format(
193
+
tostring(self.Playing),
194
+
self._current.index,
195
+
#self._sequence
196
+
)
197
+
end
198
+
199
+
return {
200
+
Create = TweenSequence.new,
201
+
}