Concepts & terms¶

A short reference for the main terms used in the Timeline Animator and the runtime API. Sorted by subject.

Editor & timeline¶

Term	What it is	What it does
Node / Element	A single instance in the animated UI tree (e.g. a Frame, TextLabel, or CanvasGroup).	In the Hierarchy panel, each node is one instance you can add to the Track List. Nodes must be explicitly added before their properties can be animated.
Hierarchy panel	The left panel in the Timeline Animator.	Shows the full tree of the animation target (the preview clone). Click the + button next to any element to add it to the Track List. Elements already on tracks are highlighted with a blue accent. Collapse or hide this panel using the Show Hierarchy toggle in the Track List header.
Track List	The centre panel in the Timeline Animator.	Shows one element header row per added element, and one property track row per animated property under that element. Scrolls vertically in sync with the Timeline.
Element header row	A row in the Track List representing one added element.	Has a collapse arrow (▶), class icon, element name, [⋮] options button, and [+] add property button. Collapse it to hide its property rows; [⋮] includes Copy / Paste Properties (playhead), Show in Hierarchy, and Delete From Track.
Property track row	A row in the Track List representing one animated property of one element.	Has a property name (clickable for selection), a value text field, a delta (△) toggle, and a hover-reveal trash icon. Keyframe diamonds appear on the matching Timeline row.
Property	A single animatable attribute of a UI instance (e.g. `Position`, `BackgroundColor3`, `GroupTransparency`).	Once added as a track to an element, you set values at specific times to create keyframes. The plugin interpolates between keyframes. See Animatable properties for the full list.
Track	One property track row and its matching timeline row, tied to one property on one element.	Displays that property's keyframes as diamonds. Click the property name to select the track (for copy/paste).
Keyframe	A value stored at a specific time for one property on one element.	The plugin tweens between consecutive keyframes. Move the scrubber to a time, change the value, and a keyframe is created. Drag diamonds to reposition; right-click for easing.
Scrubber / Playhead	The vertical red line in the Timeline.	Marks the current time. Moving it updates the preview. Use Q / E or the arrow buttons to step; drag the scrubber head to jump. New keyframes are placed at the scrubber time.
Timeline	The right-hand panel: ruler, keyframe tracks, and playback controls.	Shows time left-to-right. Each row matches one property track. Keyframes appear as diamonds. Play (▶) runs the animation; Stop (■) resets to the start. Scrolls vertically with the Track List and horizontally independently.
Ruler	The dark bar at the top of the Timeline showing time (0s, 0.5s, 1s…).	Lets you see and set the scrubber position. Right-click the ruler to Place Event (add an event marker).
Duration	The total length of the animation in seconds.	From 0 to the last keyframe (or the duration you set). The runtime uses it to clamp `scrub(t)` and to know when a clip has finished.
Easing	The curve used between two keyframes (style + direction).	Style: Linear, Quad, Sine, Back, Bounce, Elastic. Direction: In, Out, InOut. Set per keyframe via the Keyframe Context Menu. Default is Quad Out.
Keyframe Context Menu	The menu that opens when you right-click a keyframe diamond or empty timeline space.	Easing (compact style + direction + curve preview), Copy, Paste, and Delete keyframes. When multiple keyframes are selected, easing can apply to all.
Delta (relative) mode	A per-track toggle (△ button on the property row).	When on (lit blue), keyframe values are stored as offsets from the element's original value rather than absolute values. Useful for animations that need to work regardless of where the element starts.
Preview clone	A copy of your UI created when you set an animation target.	Lives in `StarterGui/_UIAnimPreview`. All editing and preview playback happen on this clone; your real UI is never changed. Use Animation → Close Animation before testing so the clone is removed and the real UI is restored.
Animation target	The root UI element (ScreenGui, Frame, CanvasGroup, etc.) that an animation is tied to.	Set via Animation → Set Target…. The plugin clones it into the preview. At runtime, the same root (or an override via `target`) receives the animated values.
Clip	A saved animation: name, duration, target link, and all keyframe data (tracks, values, easing).	What you edit in the editor and what you play at runtime with `Anim.play("ClipName")`. One clip can animate many elements and properties.
Event marker	A named point in time on the ruler.	Placed by right-clicking the ruler → Place Event. At runtime, when the playhead passes that time, `onEvent` or `handle.MarkerReached` fires with the name. Use for sounds, showing text, or other logic.

Saving & storage¶

Term	What it is	What it does
Save / Save As	File menu actions to persist the current clip.	Save updates the existing save. Save As lets you name the clip and choose a folder. Data is stored under `ReplicatedStorage/XocoatlSaves/SavedUIAnimations` by default, with the saves root found by the `XocoatlPersistenceRoot` tag.
Saves Browser	The panel opened by Animation → Open Animation….	Two-panel explorer: sidebar (search, hover preview, actions) and a full-height save tree. Open, rename, move, preview on hover, or delete clips and create folders. The runtime scans this tree to find clips by name.
targetId / GUID (_UIAID)	A unique id stored on the animation target (the `_UIAID` attribute).	Saved with each clip so the plugin can find the correct UI when you open the animation. If the UI was moved or renamed, you may need to set the target again or use `{ target = myGuiObject }` at runtime.
Folder	A container in the Saves Browser (marked with `_IsFolder`).	Purely for organisation. The runtime still finds all clips inside folders. Use for grouping by screen, character, or feature.

Runtime¶

Term	What it is	What it does
Runtime	The scripts injected into your game when you click Install Runtime in the plugin.	Lives in `StarterPlayerScripts/Xocoatl`. Loads saved clips from ReplicatedStorage and applies keyframe data to your UI each frame. Required for animations to play in-game.
UIAnimController	The main module you `require` in a LocalScript to play animations.	Exposes `play`, `stop`, `pause`, `reset`, `scrub`, `playBatch`, `sequence`, `clearInstance`, etc. See UIAnimController.
Handle	The object returned by `Anim.play("ClipName")`.	Lets you control that run: `stop()`, `pause()`, `resume()`, `scrub(t)`, `setSpeed(n)`, `setLoop(…)`. Also exposes signals: `Completed`, `Looped`, `Cancelled`, `MarkerReached`.
BatchHandle	The object returned by `Anim.playBatch(instances, "ClipName", opts)`.	Lets you `stop()`, `pause()`, or `resume()` all instances at once. There is no name-based control for batches — keep the handle to stop early.
SequenceHandle	The object returned by `Anim.sequence(steps)`.	Lets you `stop()`, `pause()`, or `resume()` the whole sequence. Useful to chain several clips one after another without nested `onComplete` callbacks.
playBatch	`Anim.playBatch(instances, name, opts)`.	Plays the same clip on multiple UI roots with an optional stagger delay between each. Typical use: list or grid reveals (e.g. cards fading in one after another).
sequence	`Anim.sequence(steps, opts)`.	Plays a list of clips in order; each starts when the previous finishes. Steps are `{ name = "ClipName", opts = { … } }`.
clearInstance	`Anim.clearInstance(inst)`.	Stops every animation whose target root is `inst`. Call before hiding or destroying that UI so no handles keep running and the next time you show it there's no conflict.