Skip to content

Saves & Folders

Where animations are stored

Animations are saved to:

ReplicatedStorage
+-- XocoatlSaves              (tagged XocoatlPersistenceRoot)
    +-- SavedUIAnimations
        +-- Imports               (Folder — reserved; paste-import clips)
        +-- Built-in presets      (Folder — reserved; plugin-shipped bundles)
        +-- MyAnimation          (Folder)
        |   +-- Name             (StringValue)
        |   +-- Data             (StringValue -- JSON)
        +-- My Folder            (Folder, marked with _IsFolder)
            +-- AnotherAnimation (Folder)
                +-- Name
                +-- Data

The runtime finds the saves root by the XocoatlPersistenceRoot tag first. That means you can move or rename the saves folder as long as the tag stays on the folder.

The same root also holds UI Designer data (DesignerVariables, DesignerViewportSizes, DesignerPreferences) next to SavedUIAnimations. See UI Designer — Variables.

Older projects that still have ChocosToolsSaves are supported. On first open, Xocoatl tags the legacy folder and renames it to XocoatlSaves when there is no name collision.

If both ChocosToolsSaves and XocoatlSaves exist, or more than one folder has the XocoatlPersistenceRoot tag, Xocoatl warns instead of guessing. Use Tools → Xocoatl features → Locate Xocoatl Saves Folder to repair the tag on the correct folder.

{% hint style="warning" %} Rojo users

If Xocoatl renames an old ChocosToolsSaves folder to XocoatlSaves, update your Rojo project map so Studio and Rojo agree.

{% endhint %}

Saving an animation

File > Save -- saves the current animation in place (or to the root if it has not been saved before).

File > Save As... — opens the same explorer-style browser as Open Animation, but folders only:

  1. Pick Root (top level) or a folder, then click Save As.
  2. Use New Folder in the sidebar to create and name a folder before saving.
  3. After you confirm the destination, enter the animation name and save.

The folder step uses the same search, row styling, and sidebar layout as Open Animation (without the animation preview).

Saves Browser

Animation > Open Animation... opens a tall two-panel explorer: a sidebar card on the left (search, preview stage, and actions) and a full-height folder tree on the right (same card styling as the landing screen).

From here you can:

  • Open an animation -- double-click it, or single-click to select and confirm
  • Rename an animation or folder -- right-click > Rename
  • Delete an animation or folder -- right-click > Delete
  • Move into a folder -- drag and drop the animation or folder onto any other folder
  • Rearrange folders -- drag and drop folders up or down within the same level
  • Create Folder -- click the Add Folder button in the bottom bar to organise by character, screen, or feature

The sidebar header has a search bar — type to filter animations by name.

Folder rows show how many animations they contain on the right (e.g. 3 Animations, including nested subfolders). Animation rows show duration and last updated on the right (e.g. 2.50s — May 26 14:30), or - when no timestamp is saved yet.

The left panel is the only preview area — the list on the right does not change layout or icons for preview.

  • Hover an animation row → the sidebar plays that clip on loop inside a 16:9 stage, zoomed to fit the animated content with padding (not the full 1280×720 canvas). Uses the same interpolation + ParticleSim path as the Timeline preview.
  • Very large animations skip the hover preview and show a short message instead, so the saves browser stays responsive. Open the animation normally to edit or play it.
  • While a row is hovered, a compact play bar and time readout appear in the sidebar header next to the title.
  • Search ↔ preview swap — while previewing, the search box fades out and the play bar takes its place; search returns shortly after you move off the row. Search is disabled while hidden so you cannot type into it by accident.
  • Select a row only for opening, moving, or multi-select — it does not change the sidebar preview.
  • The preview area uses a transparent background so only the UI content is visible over the sidebar.
  • Move the mouse off the list → the preview clears.

Previews use the saved UI snapshot on the clip (or a matching target in StarterGui). Clips with no snapshot show a short message in the preview frame.

Hover the timestamp or name on a clip row for Made and Last updated details. Timestamps are stored inside the clip JSON: they are set the first time you Save or open an animation, and Save refreshes the last-updated time.

Multi-select

Use multi-select when you want to move several saved animations at once:

  • Ctrl-click animation rows to add or remove them from the current selection.
  • Shift-click another visible animation row to select a range.
  • Drag any selected animation to move the whole selected group into or out of folders.

Folders can still be dragged and reordered, but multi-select is intended for animation rows. Protected folders such as Imports and Built-in presets cannot be used as drop targets.

Drag and drop

Click and hold on any animation or folder, then drag it. A semi-transparent ghost card eases toward the cursor while you move, then stays at the pointer and fades out (background, stroke, and label ease from their current values to transparent). Drop it onto a folder to move it inside, or drop it between rows to reorder at the same level. While you drag, other rows shift aside and an accent gap opens at the drop position so you can see the final order before you release. Dropping onto the middle of a folder row moves the item into that folder (the row highlights). If you drag near the top or bottom edge of the tree, the list auto-scrolls so you can drop into folders that are off-screen.

Folders

Folders are purely organisational. The runtime scans the full tree recursively so animations inside folders are found automatically.

If you move the saves folder and Xocoatl cannot find it, open Tools → Xocoatl features, select the correct Folder in Explorer, then click Locate Xocoatl Saves Folder. Xocoatl will move the tag and create any missing child folders.

Linking an animation to a UI target

Every animation stores the _UIAID attribute of the root UI element it was created for (targetId). When you open an animation, the plugin searches your scene for an element with that GUID:

  1. If found -- opens with that element as the target automatically.
  2. If neither -- shows a prompt to set the target manually.

Export & Import

Use File → Export and File → Import from JSON… to share animations between Roblox places or team members.

Export to JSON

  1. Open the animation you want to share and set its target.
  2. Click File → Export → Export to JSON…
  3. A dialog opens with a JSON bundle in a text box — press Select All then Ctrl+C to copy it.
  4. Press Done.

The bundle contains the full animation clip data and a snapshot of the UI structure. Scripts and other non-UI children are excluded from the snapshot and listed in the dialog as a warning.

Export to Module (commission kit)

{% hint style="info" %} Not in the menu yet

Export to Module is in development and is not shown under File → Export in the current plugin build. Use Export to JSON for sharing clips today.

{% endhint %} When it ships, File → Export → Export to Module… will create a standalone module kit in your place — no runtime install required for the buyer. Choose Commission package to export a {Name}_Export folder with a UI clone plus scripts, or turn commission package off to add modules under your existing UI.

In the export dialog, pick a Playback mode:

Mode What ships Best for
Runtime slice (default) {Name}Config, {Name}Anim (keyframe data), {Name}Runtime, {Name}Player Matches Timeline preview — loop, easing, relative tracks
TweenService {Name}Config, {Name}Anim (generated TweenService:Create chains), {Name}Player Easy to read/edit plain Roblox tweens

Edit {Name}Config to change speed, loop, ping-pong, delay, or autoplay without touching generated animation code.

Particle and timeline-event tracks are warned in the export dialog and omitted from the module kit — they still work in preview, JSON export, and the installed runtime.

Snapshots preserve supported UI modifier properties, including UIShadow and beta UICorner per-corner radii when the current Studio build supports Roblox's New UI Capabilities API.

Newly written JSON (export, File → Save, and stored UI snapshots) rounds floats such as UDim2 scales and Color3 components to three decimal places so bundles are shorter and easier to copy; bundles you saved earlier are unchanged until you save or export again.

Importing

  1. Click File → Import from JSON…
  2. Paste the JSON bundle into the text box.
  3. Press Import.

The plugin will:

  • Recreate the exported UI inside StarterGui > Imports (the folder is created automatically if it does not exist yet).
  • Save the animation clip into your Imports folder in the saves browser.
  • Assign the clip a fresh unique ID so it is completely independent from the original -- importing the same bundle twice creates two separate animations with no ID conflicts.

After importing, open the animation manually via Animation > Open Animation... and select it from the Imports folder. Set the animation target to the recreated UI (or your own UI if you already have a compatible one).

Built-in presets

The plugin may ship timeline bundles (same JSON format as Export UI + Animation) into the reserved Built-in presets folder under SavedUIAnimations. They are applied the same way as a manual import: UI is recreated under StarterGui → Imports, and each clip gets a new id and name prefixed with [Built-in].

Shipped Built-in presets appear in Animation → Open Animation as rows under Built-in presets (or as a one-time virtual folder until you expand it). Only the preset you open is installed: it creates the save, optional StarterGui → Imports UI, and snapshots — other shipped presets stay unloaded until opened.

  • The saves browser treats Imports and Built-in presets like protected folders (lock icon, special ordering: Imports first, then Built-in presets). You cannot delete those folders or drop items onto them; clips inside can still be deleted or moved like any other save.
  • Plugin authors: add entries in BuiltinTimelinePresets.luau (see the plugin source under Modules/Core/). Each entry has a name label and a bundle string (use [=[ ... ]=] for the JSON). Bump VERSION when you add or change shipped bundles (for documentation consistency).

Renaming animations

File > Rename Animation... lets you give the current animation a new name.

{% hint style="warning" %} Renaming may break game code

If your game scripts reference an animation by name (e.g. Anim.play("MyAnimation")), renaming it here will break those calls. Update any references in your scripts after renaming.

You also cannot rename an animation to a name that is already taken by another animation.