AnimationService

The top-level module. Manages the global render loop, active tracks, preprocessing, and provides both fire-and-forget and track-based APIs.

local AnimationService = require(path.to.AnimationService)

Methods

local signal = AnimationService.Play(button, HoverAnim, {
    Reset = true,     -- restore properties when done
    Loop = true,      -- loop forever
    Reverse = false,  -- play forward
})

signal:Connect(function(event, ...)
    if event == "Completed" then
        print("Done!")
    elseif event == "MarkerReached" then
        local name, data = ...
        print("Hit marker:", name)
    end
end)

local buttons = { btn1, btn2, btn3, btn4 }
local signal = AnimationService.PlayBatch(buttons, FadeIn, {
    Stagger = 0.05,  -- 50ms delay between each item
    Reset = true,
})

signal:Connect(function(event, ...)
    if event == "MarkerReached" then
        local name, data, instance = ...
        print(instance.Name, "hit marker:", name)
    end
end)

local track = AnimationService.CreateTrack(panel, SlideIn)
track.Completed:Connect(function()
    print("Slide finished")
end)
track:Play()

local track = AnimationService.CreateBatchedTrack(listItems, RevealAnim, {
    Stagger = 0.03,
})
track:Play()

-- Show exactly what frame 10 looks like
AnimationService.SetFrame(button, ClickAnim, 10)

-- Player closed a menu, clean everything up
AnimationService.ClearInstance(menuFrame)

local processed = AnimationService.Preprocess(ListItemAnim)

-- Now use the processed result for many instances
for _, item in ipairs(items) do
    AnimationService.Play(item, processed, { Stagger = 0.02 })
end

TrackOptions

The optional options table accepted by Play, PlayBatch, CreateTrack, and CreateBatchedTrack.

-- Common patterns:

-- Hover: forward on enter, reverse on leave
AnimationService.Play(btn, HoverAnim)
AnimationService.Play(btn, HoverAnim, { Reverse = true })

-- One-shot notification that cleans itself up
AnimationService.Play(popup, FadeIn, { DeleteOnComplete = true })

-- Looping idle animation with restore on cleanup
AnimationService.Play(icon, PulseAnim, { Loop = true, Reset = true })

-- Staggered list reveal
AnimationService.PlayBatch(items, SlideIn, {
    Stagger = 0.04,
    Delay = 0.2,
})

AnimTrack

Returned by AnimationService.CreateTrack(). Represents a single animation bound to a single instance. Gives you frame-level control over playback.

Properties

Methods

-- Scrub to the halfway point
track:Scrub(track.Duration / 2)

-- Scrub to a specific frame (at 30 FPS)
track:Scrub(15 / 30)

track:SetSpeed(-1)  -- play in reverse
track:SetSpeed(0.5) -- slow motion

Events

track.MarkerReached:Connect(function(name, data)
    if name == "PlaySound" then
        SoundService:PlayLocalSound(data.Data)
    end
end)

Full Example

local AnimationService = require(game.ReplicatedStorage.CascadeAnimations.AnimationService)
local SlideAnim = require(game.ReplicatedStorage.CascadeAnimations.SlideIn)

local track = AnimationService.CreateTrack(menuFrame, SlideAnim, {
    Delay = 0.2,
    DeleteOnComplete = true,
})

track.Completed:Connect(function()
    print("Menu is now visible")
end)

track:Play()

BatchedAnimTrack

Returned by AnimationService.CreateBatchedTrack(). Animates the same animation across multiple instances with a single track, supporting staggered timing.

Properties

Methods

BatchedAnimTrack shares the same method interface as AnimTrack:

Events

Same as AnimTrack: .Completed, .Looped, .Cancelled, .MarkerReached.

For MarkerReached, the callback receives a third argument: the specific Instance that triggered the event.

track.MarkerReached:Connect(function(name, data, instance)
    -- 'instance' tells you which item in the batch hit the marker
    print(instance.Name, "reached marker:", name)
end)

Stagger Example

-- Stagger a list of items for a cascading reveal
local items = scrollFrame:GetChildren()

local track = AnimationService.CreateBatchedTrack(items, FadeIn, {
    Stagger = 0.04,  -- 40ms between each
    Loop = false,
    Reset = true,
})

track.Completed:Connect(function()
    print("All items revealed")
end)

track:Play()

Signal

A lightweight custom event class used throughout Cascade. Follows standard Roblox signal conventions. Shipped as part of the AnimationService module.

Creating a Signal

local Signal = require(path.to.AnimationService.Signal)

local onHealthChanged = Signal.new()

Methods

local connection = onHealthChanged:Connect(function(newHealth)
    print("Health:", newHealth)
end)

-- Later:
connection.Disconnect() -- stop listening

onHealthChanged:Fire(75)

local status = track.Completed:Wait()
print("Track completed")

Types & Config

Reference for the data structures used by the animation engine.

AnimationConfig

The primary data format. This is what the editor exports when you save an animation.

Keyframe

A single point in a track's timeline.

TrackOptions

Optional flags passed to Play, CreateTrack, etc.

AnimationEvent

A marker placed on the timeline that fires MarkerReached during playback.

Track Paths

Track keys in the Tracks table use slash-delimited paths. The last segment is the property name. Sub-properties use dot notation.

-- Direct property on root
"Transparency"

-- Child object's property
"ContentFrame/Transparency"

-- Deeply nested
"LeftPanel/Content/TitleArea/Tagline/TextTransparency"

-- Sub-property (axis isolation)
"ContentFrame/Size.X.Scale"
"ContentFrame/Position.Y.Offset"

The engine resolves instance paths via FindFirstChild from the root. Every sibling must have a unique name.

Core Concepts

Before using the editor, understand these fundamental concepts.

What is a Keyframe?

A keyframe is a snapshot of a property's value at a specific point in time. The animation engine interpolates between keyframes to produce smooth motion.

For example, to fade a frame from fully visible to invisible:

• Keyframe at Frame 0: Transparency = 0 (fully visible)
• Keyframe at Frame 30: Transparency = 1 (invisible)

The engine fills in every frame between 0 and 30 automatically based on the easing curve.

FPS (Frames Per Second)

FPS defines the time resolution of your animation. It determines how many frames fit into one second.

• 60 FPS — each frame = 1/60th of a second (~16.7ms). Smooth and precise.
• 30 FPS — each frame = 1/30th of a second (~33.3ms). Standard for UI.
• 20 FPS — each frame = 1/20th of a second (50ms). Good for simple transitions.

FPS is a timeline grid setting, not a runtime cap. The engine evaluates at Roblox's native framerate and interpolates between your keyframes regardless of FPS.

Total Frames

TotalFrames defines how many frames long your animation is. Combined with FPS, it determines the duration:

When you change FPS in Animation Settings, TotalFrames stays the same and the duration adjusts. When you change TotalFrames, the duration adjusts too.

Easing

Each keyframe has an easing style and direction that controls how the value transitions to the next keyframe.

Cascade supports all Roblox EasingStyle values: Linear, Quad, Cubic, Quart, Quint, Sine, Exponential, Circular, Elastic, Back, Bounce.

Directions: In (slow start), Out (slow end), InOut (slow both ends).

Relative Mode

Normally, keyframes store absolute values (e.g. Size = {0.5, 0, 0.3, 0}). In Relative Mode, keyframes store deltas (offsets from the instance's current value).

This is powerful for reusable effects. A "hover grow" animation that adds +10px to Size works on any button regardless of its base size.

Sub-Property Animation

Most editors lock entire properties like Size or Position. Cascade lets you animate individual axes independently:

• Size.X.Scale — only the X scale
• Position.Y.Offset — only the Y offset
• BackgroundColor3.R — only the red channel

This enables effects that would be impossible otherwise, like growing width while shrinking height independently with different easing curves.

Animation Events

Events are markers placed on the timeline that fire callbacks during playback. Use them to sync sounds, trigger particle effects, or run game logic at precise moments in your animation.

Events fire via the MarkerReached signal on AnimTrack/BatchedAnimTrack. Each event has a Name and optional Data payload. Events work correctly in all playback modes: forward, reverse, looping, and staggered batches.

Service Mode (Play / PlayBatch)

The signal returned by .Play() and .PlayBatch() wraps all events into a single callback. The first argument is the event type string.

local signal = AnimationService.Play(button, MyAnim)
signal:Connect(function(event, ...)
    if event == "MarkerReached" then
        local name, data = ...
        if name == "PlaySound" then
            SoundService:PlayLocalSound(data.Data)
        end
    elseif event == "Completed" then
        print("Done!")
    end
end)

Track Mode (CreateTrack / CreateBatchedTrack)

Track objects expose .MarkerReached as a dedicated signal. The callback receives the event name and data directly.

local track = AnimationService.CreateTrack(button, MyAnim)
track.MarkerReached:Connect(function(name, data)
    if name == "PlaySound" then
        SoundService:PlayLocalSound(data.Data)
    end
end)
track:Play()

Batched Track Events

For BatchedAnimTrack, the callback receives a third argument: the specific instance that triggered the event. With stagger, each instance fires its events independently after its stagger delay elapses.

local track = AnimationService.CreateBatchedTrack(items, RevealAnim, {
    Stagger = 0.04,
})
track.MarkerReached:Connect(function(name, data, instance)
    print(instance.Name, "reached:", name)
end)
track:Play()

Editor Features

The Cascade editor is a dockable Roblox Studio plugin. Here's what it can do.

Hierarchy Browser

The left panel shows a tree view of the selected instance and all its descendants. Click any object in the hierarchy to select it in the Studio Explorer. The hierarchy panel is toggleable from the tracklist header.

Property Tracklist

The right side of the tracklist shows all animated properties, grouped by object. Each row represents one track (one animatable property). Properties are added via the Property Popup.

Timeline Grid

The main workspace. Keyframes appear as diamonds on track rows aligned to the frame grid. You can:

• Click a keyframe to select it
• Right-click a keyframe to open the keyframe editor
• Drag keyframes to retime them
• Box-select to select multiple keyframes across tracks
• Scroll to move through time, Ctrl+Scroll to zoom
• Middle-mouse drag to pan
• Use the Add Keyframe keybind (0 or +) to insert a keyframe at the current frame

Auto-Record

When recording mode is active (the record button is toggled on), any property change you make in the Studio viewport or Properties panel is automatically captured as a keyframe at the current frame position. This lets you "act out" animations naturally.

Keyframe Editor

Right-click a keyframe (or press the keybind) to open the keyframe editor popup. Here you can:

• Edit the exact value with type-aware inputs
• Change the easing style and direction

Relative Mode Toggle

Each track row has a Δ button. Click it to toggle relative mode for that specific track. When active, the badge turns accent-colored and all keyframes on that track are treated as deltas from the base state.

Smart Inspector

The value input fields accept loose syntax. For example, you can type {0.5, 10} for a UDim value and the parser will format it correctly. Color values accept 0-255 RGB.

Clipboard & Undo

Full non-destructive editing with undo/redo history. Copy, cut, and paste keyframes across tracks. Multi-select keyframes with box selection and move them as a group.

Animation Settings

Open via the toolbar or keybind. Configure:

• FPS — frame rate (affects grid density and time conversion)
• Total Frames — animation length in frames
• Loop — whether the animation loops during preview
• Events — enable/disable the event track row

The computed length in seconds is displayed as a read-only label.

Save & Load

Animations are serialized to ModuleScripts inside ReplicatedStorage.CascadeAnimations. The save/open dialogs let you name, browse, and overwrite animations. The exported format is a plain Luau table that you require() at runtime.

Themes

The editor ships with multiple themes: Dark, Light, Blue, and Orange. Themes are managed by the ThemeManager and affect all UI components.

Customizable Keybinds

Every action can be rebound in the keybind settings. Bindings persist across Studio sessions via plugin:SetSetting(). You can assign multiple keys to the same action, add modifier keys (Shift, Ctrl, Alt), and reset to defaults.

Keybinds

Default keyboard shortcuts. All keybinds are customizable in the editor's settings panel.

Playback

Editing

Clipboard

Popups

Navigation

Best Practices

Practical tips for getting the most out of Cascade.

Naming & Hierarchy

Service vs. Track Mode

Performance

Relative Mode

button.MouseEnter:Connect(function()
    AnimationService.Play(button, HoverAnim)
end)

button.MouseLeave:Connect(function()
    AnimationService.Play(button, HoverAnim, { Reverse = true })
end)

Editor Workflow