Timeline Animator -- Overview¶

The Timeline Animator is a keyframe-based UI animation editor built into Roblox Studio. You add the elements you want to animate to your tracks, choose which properties to animate, set values at specific times, and the plugin smoothly interpolates between them.

Opening the editor¶

Click Timeline Animator in the plugin toolbar. If no animation is loaded you will see the landing screen — a center card flanked by the theme chooser (left) and a status card (right):

Area	Purpose
Center card	Idle setup steps; Open Saves; Set Target / Use Template when needed; compact list of animations linked to the selected UI
Theme chooser (left)	Browse and apply theme packs
Status card (right)	Install / Update Runtime, plugin version (short semver + status), and manual update check. Hover the plugin row for the full identity (`v0.2.0 - B35 - P10`).

From the center card you can also Open Saves, start a New Animation, or open an animation already linked to your Studio selection.

Layout¶

The editor is split into three panels side by side:

Panel	Location	Purpose
Hierarchy	Left	Shows the full UI tree of the animation target. Has a built-in search bar and click-to-select. Use it to add elements to your tracks.
Track List	Centre	One row per element header and one row per animated property. Scroll vertically together with the Timeline.
Timeline	Right	Keyframe diamonds, ruler, and playback controls. Scrolls vertically in sync with the Track List, and horizontally independently.

The Hierarchy panel can be hidden with the Show Hierarchy toggle in the Track List header to give the tracks more horizontal room.

Hierarchy search bar -- type in the search box (inside the Hierarchy header, to the right of the title) to filter the tree by name. Only matching elements and their ancestors stay visible. Clear the box to see the full tree again.

Add From Selected -- the cursor-plus icon button to the right of the search box lets you add multiple elements at once. Select any elements under the animation target in the Studio Explorer, then click the button. Every selected element that has animatable properties and is not yet in the Track List is added in one go.

Collapse/expand children -- click any element in the Hierarchy to select it, then press L to toggle its children open or closed.

Workflow¶

1. Set an Animation Target¶

Select a ScreenGui, Frame, CanvasGroup, or any GuiObject in the Studio Explorer, then click Animation > Set Target... in the menu bar.

A preview clone of your UI is created in StarterGui/_UIAnimPreview. All editing happens on this clone -- your real UI is never modified while you are working.

The preview clone

The clone is only for editing. When you press Play in Studio the runtime reads the saved animation data and applies it to the real UI, not the clone.

2. Open an Animation¶

Either create a new animation (Animation > New Animation) or open an existing save (Animation > Open Animation...). The animation must be open before you can add tracks or keyframes.

3. Add elements to your tracks¶

In the Hierarchy panel on the left, browse the full tree of the animation target. Click the + button to the right of any element to add it to the Track List. The element header row will appear in the centre panel.

2D particles (experimental) — for a supported GuiObject (Frame, labels, buttons, CanvasGroup), use the element header ⋮ menu → Make Particle Frame, then use the Particles row [+] (searchable picker, like Add property) and [⋮] to remove the whole particle system. They keyframe like other tracks and play in preview and in the shipped runtime. See Particles (experimental) for setup, sequence editing, and caveats.

You can also track the animation target itself (the root) by clicking its + button at the top of the Hierarchy tree.

Adding multiple elements at once — select the elements you want in the Studio Explorer, then click the Add From Selected button (cursor-plus icon, right of the search bar) to add all of them to the Track List in one click.

Multi-select editing — keyframes, compatible property tracks, and saved animations each support multi-select workflows. See Keyframes & Easing for keyframe and track selection, and Saves & Folders for selecting and moving multiple saved animations.

Only add what you need

Only elements you explicitly add will appear in the Track List. This keeps the view clean -- you work on what matters.

Extremely large animations load Track List rows progressively so the editor stays responsive while all tracked elements are still available.

4. Add property tracks¶

Each element in the Track List has a collapse arrow (>) on the far left and an [+] add property button on the right side of its header row. Click [+] to open the property picker for that element. Browse by category or search by name, then click a property to add it as a track.

Each property becomes its own row -- one row for Position, one for BackgroundTransparency, etc.

Property picker toggles — properties already on the track are highlighted. Click one again to remove that track (with confirmation).

ScreenGui Enabled — if your target is a ScreenGui, Xocoatl may prompt you to track the ScreenGui and keyframe Enabled = true at 0s so the UI shows in-game. See Animatable properties — ScreenGui Enabled.

Element order: drag on the class icon or name area of an element header (not the collapse arrow, +, ⋮, or particle indicators) to reorder tracked elements. A semi-transparent ghost follows the pointer (with a short ease), and an accent drop line shows where the row will land. On release, the ghost stays at the pointer and fades out (background, stroke, and label ease from their current values to fully transparent). Order is saved in the clip JSON as elementDisplayOrder (older clips without this field keep their previous discovery order). Keyframe data stays keyed by instance GUID — reordering is display-only and does not change animation behaviour.

Studio selection: moving the mouse off an element header (or finishing a normal click on the row) syncs the Studio Explorer selection to that element. After you drop a reorder, Explorer selection is left as-is (no jump to the row you dragged).

5. Set values and create keyframes¶

Move the scrubber (the vertical red line in the Timeline) to the time you want.
While dragging on the ruler scrub band, any keyframe diamond at the current scrub time scales up slightly (same motion as hovering a diamond) and does a small rotation wiggle (counter‑clockwise, then clockwise, then settle) the first moment you land on that time — so stacked keyframes are easier to spot. If you scrub away (or release) before the wiggle finishes, scale and rotation ease back smoothly to the normal diamond pose; scaling also returns when you release the scrubber.
Edit the value directly in the text field on the property track row (click the field, type a value, press Enter). A keyframe is created at the scrubber time automatically.
For compound properties like Position or Size, the text field uses comma-separated values in xScale, xOffset, yScale, yOffset order.
Shorthand: typing a single number into a compound field (e.g. 0) applies that value to all components at once.
Colour properties (BackgroundColor3, TextColor3, ImageColor3, etc.) show a clickable colour swatch instead of a text box. Click the swatch to open the Color Picker, choose a colour, and confirm — a keyframe is created at the current scrubber time. Expand the track (arrow on the left) to get individual R / G / B numeric fields for precise input.

You can also change a tracked property in Studio's Properties panel (with the preview clone selected) -- the plugin detects the change and creates a keyframe at the current scrubber time.

6. Set easing¶

Right-click a keyframe diamond to open the Keyframe Context Menu and choose an easing style (Linear, Quad, Sine, Back, Bounce, Elastic) and direction (In, Out, InOut). A small preview curve is shown next to the menu.

7. Preview¶

Press Play in the timeline header. Press Stop to return to the start. Use the arrow buttons to step frame-by-frame (hold for acceleration).

Enable the Loop toggle in the toolbar to repeat the animation during preview -- this only affects the editor preview, not in-game playback.

8. Save¶

Click File > Save (or Save As to name it and choose a folder). Animations are stored under ReplicatedStorage/XocoatlSaves/SavedUIAnimations by default; Xocoatl finds the saves root by the XocoatlPersistenceRoot tag if you move or rename it.

9. Close before testing or switching away¶

Before you test your game (Play) or do other work in Studio, use Animation > Close Animation. That removes the preview clone and restores your real UI.

Don't leave the animation open when pressing Play

If you leave an animation open and press Play, the preview clone can appear in the running game and your real UI may stay hidden.

Track List -- header controls¶

The Track List header row contains:

Control	What it does
Show Hierarchy toggle	Shows or hides the Hierarchy panel
Animation name field	Shows the current animation name; click to rename

Each element header row contains:

Control	What it does
> collapse arrow (left)	Collapses or expands all property tracks for that element
Class icon	Visual indicator of the element's class (Frame, TextLabel, etc.)
Element name (clickable)	Click to select that element in the Studio viewport for direct manipulation
[...] options button	Opens a dropdown: Copy Properties and Paste Properties first (values at the playhead), then a divider, then Show in Hierarchy and Delete From Track. Copy/Paste Properties writes keyframes at the playhead (only properties that exist on the target type). Effect headers use the same copy/paste pair, a divider, then Remove Effect. Separate from Edit ▸ Copy / Paste Keyframes (time-based diamond copy).
[+] add property button	Opens the property picker for this element

Each property track row contains:

Control	What it does
> collapse arrow (left, compound properties only)	Expands or collapses sub-rows showing individual components (e.g. X Scale, X Offset, Y Scale, Y Offset for a UDim2 property; R, G, B for a Color3 property). Collapsed by default.
Property name (clickable)	Click to select this track (for copy/paste). Selected track is highlighted.
Value field	Editable text box showing the current value at the scrubber. Press Enter to confirm and create a keyframe. Color3 properties show a colour swatch instead — click it to open the Color Picker.
delta toggle	Switches the track between absolute and relative (delta) mode. Lit up in bright blue when active.
[...] options button	Opens a dropdown: Delete From Track (removes this property track and all its keyframes).

The element collapse arrow (left of each element header row) only hides that element's own property rows. All other elements in the Track List remain visible regardless of any parent/child relationship.

Menu	Items
Animation	New Animation, Open Animation..., Close Animation, Set Target..., Template Animation, Preview in Container, Add Effects
File	Save, Save As..., Rename Animation..., Export UI + Animation..., Import UI + Animation...
Edit	Copy Keyframes, Paste Keyframes (clipboard) — then Undo, Redo (history), separated by a divider line
Options	Preferences... (opens a modal over the timeline — Keybinds, UI)
Options > Help	Opens the built-in help & docs panel
Options > Report	Opens the Developer Forum plugin thread (bugs and feature requests; Discord link is in the first post)
Options > Xocoatl vX.X.XX	Current plugin semver — compact label at the bottom of the Options dropdown. Hover the status card plugin row for the full identity (`v0.2.0 - B35 - P10`).

Plugin version labels¶

The plugin tracks three parts:

Part	Example	Meaning
Semver	`v0.2.0`	Human-readable release name (menus, changelog)
B	`B35`	Patch build — bumps on Creator Store patches within the same release
P	`P10`	Version code — bumps when a named Update available release ships

Compact UI shows semver + status (for example v0.2.0 · Up to date). Full identity (v0.2.0 - B35 - P10) is computed automatically from the three fields above — status-card hover, update/patch prompts, and the docs header all use the same format.

Button	Action
Zoom Out / Zoom In	Change the time scale of the timeline
Fit to View (P)	Zoom and scroll so the entire animation duration is visible
Left / Right arrows	Step backward / forward (hold for faster stepping)
Stop	Go to frame 0
Play / Pause	Start or pause playback
Loop	Toggle preview looping -- the animation repeats while previewing in the editor. Has no effect on in-game playback.
Undo / Redo	Step through the undo history
Add keyframe / Delete keyframe	Add or remove a keyframe at the playhead for the selected property track
Animation Name	Rename the current animation

Toolbar disabled with no animation open

All toolbar buttons are non-interactive when no animation is loaded. Open or create an animation to enable them.

Keyboard shortcuts¶

Shortcuts apply when the Timeline Animator window has focus. View and edit bindings in Options > Preferences > Keybinds (click a key badge to record a new chord). While Open Animation is already open, the shortcut does not open a second copy.

Default	Action
Space	Play / Pause
Q	Step backward (scrubber)
E	Step forward (scrubber)
P	Fit to view (zoom to fit the full animation)
Shift+O	Open Animation (saves browser)
Shift+S	Save animation (also Ctrl+S; change Save in Preferences → Keybinds)
L	Toggle collapse/expand children of the selected Hierarchy element
- (Minus)	Zoom out
= (Equals)	Zoom in
A	Add keyframe at playhead
X	Delete keyframe(s) at playhead or selected
Shift+Z / Shift+Y	Undo / Redo
Alt+C / Alt+V	Copy / Paste keyframes (same as toolbar / Edit menu; change in Preferences → Keybinds)

Preferences¶

Open Options > Preferences to open a modal on the timeline window: same backdrop and header style as Open Animation (shared PluginModalStyle). The panel is wider than the file browser: a main column for settings and a category column on the right (Keybinds, UI) so the scroll area stays roomy.

Undo / Redo¶

The editor has a full undo stack. Press Edit > Undo (or the Undo button in the header) to step back through any change: added keyframes, moved keyframes, changed values, added or removed property tracks, added or removed elements, changed easing, and more.