You may be aware of TweenService, which can be used to animate just about any arbitrary property of any instance - allowing animation of UI components, camera position, size and color of parts, etc. TweenService is a powerful tool, but also requires lots of manual table creation and scripting knowledge.
The TweenSequence Editor is a plugin for the creation of TweenService animations using a visual editor, no scripting required! It is especially useful for animating UI components along with the UI editor, but its applications are as widespread as TweenService itself.
Why the TweenSequence Editor
This plugin decouples animating using TweenService from knowledge of scripting and the TweenService API. Using this plugin, UI designers or builders in collaborative environments with no knowledge of scripting could easily animate their own creations. Even for scripters, this plugin makes it easier than ever to animate complex sequences using TweenService. Those of you used to animation software and some game engines should have an easy time picking up this new tool.The plugin outputs an Animator object that uses a simple API to play or loop tweens created in the editor.
Examples
Using the TweenSequence Editor
Getting Started
Once you've installed the plugin, you may want to bind some shortcuts defined by the plugin. In Studio, navigate to File->Advanced->Customize Shortcuts, then bind the shortcuts Delete Keyframe, Copy Keyframe, and Paste Keyframe. Personally, I have these bound to X, C, and V, respectively.To start using the plugin, activate it using the button in the Plugins tab in Studio. The editor will now begin watching your current selection. Select which instance you would like to use as the root of the animation, then click Create.
- If animating the properties of only one instance (the Brightness of a PointLight, for example) select the instance itself as the root.
- If you’re animating multiple instances, select the lowest common parent above them all. (The Model or parent Frame, for example.)
You are also able to import TweenSequences from an Animator that is already exported. To do this, select any instance controlled by that Animator and select Import, rather than Create, when prompted.
After selecting a root and clicking Create (or Import), you can begin using the editor.
Navigating the Editor
The Topbar
The buttons across the top of the main Editor window are as follows, from left to right:- Save All - Saves and exports the changes to the associated Animator object. This button will highlight blue if there are any changes that need saving.
- Preview - Previews the TweenSequence that is currently being edited. Note that this will activate Play mode in Studio to play the animation, and stop when the animation stops.
- Delete Changes - Deletes all local changes and reloads all TweenSequences from the exported Animator object.
- Current TweenSequence - A dropdown menu used to switch between which TweenSequence is being edited. You can also create a new empty TweenSequence or a copy of the current TweenSequence using this dropdown.
- Rename - Renames the current TweenSequence. This name is how you will reference the animation in scripts.
- Delete - Deletes the current TweenSequence. If this is the only TweenSequence, it deletes the associated Animator as well.
- If a keyframe is selected, two more options will appear: EasingStyle and EasingDirection. These dropdowns will allow you to edit how the tween leading up to the selected keyframe behaves.
The Explorer
The left side of the TweenSequence Editor is the Explorer widget. This shows the root instance and all its children, as well as any properties of these instances that are being tracked.- Scroll up and down when the mouse is inside this widget to scroll through the displayed instances and properties, if you can’t see them all at once.
- Click the arrow next to an instance to hide its children and/or properties.
To add a new tracked property to an instance, click the + button to the right of the instance name. You will then be prompted to enter the name of the property to track. When the property is added, its initial value will be set to its current value in Studio.
While the TweenSequence Editor is active, it will listen for changes to tracked properties. Any changes will either add a new keyframe, or modify a keyframe if one already exists for the property at the playhead’s current position.
To delete a tracked property, click the trash icon next to the property name. This will also erase all its keyframes.
The Timeline
The right side of the TweenSequence Editor is the Timeline. This displays the keyframes for all tracked properties, and can be used to view them and move them around.- Left click or drag the mouse to move the playhead’s position.
- Scroll up and down when the mouse is inside the Timeline to zoom in and out.
- Drag with the middle mouse button to move left and right.
As you move the playhead, the animation will adjust to appear how it would look at that moment in time when the tween is playing.
Manipulating Keyframes
- Select a keyframe by clicking on it. This will move the playhead to the keyframe’s time.
- Move a keyframe by dragging it with the mouse. You can’t move a keyframe onto another keyframe, and you can’t move keyframes with a time of 0.
- Copy and paste a keyframe’s data, or delete a keyframe, using the actions you bound previously in Getting Started when a keyframe is selected.
Workflow
- Track the properties that you want to animate. Using the Properties widget in Studio or other editors, set the initial values of these properties.
- Move the playhead to the time at which you would like to insert a new keyframe.
- Using the Properties widget in Studio or other editors, modify the properties to what you want their new values to be at this time.
- Repeat steps 2-3 until you have finished your animation.
Using the Animator Object
The Animator object exported from the TweenSequence editor is a ModuleScript that lives in the root instance you selected. Don’t move this script, and only rename it if you are okay with it not working with the TweenSequence editor anymore until its name is changed back to “Animator”.
Being a ModuleScript, to use the Animator you must require it.
local animator = require(root.Animator)
--Play the tween named TrackName:
animator.TrackName:Play()
--Stop the tween named TrackName:
animator.TrackName:Stop()
--Loop the tween named TrackName twice:
animator.TrackName:Loop(2)
--Loop the tween named TrackName indefinitely until stopped:
animator.TrackName:Loop()
--Connect a function named doneFunc to the end of the tween named TrackName:
animator.TrackName.DonePlaying.Event:Connect(doneFunc)
--Stop all tweens for this instance:
animator.StopAll()
The Animator only cares about names and properties, so it can be used in multiple different copies of the same object, or even in entirely different objects. For example, you could animate a part’s CFrame by animating the main Camera CFrame in Studio and then moving the animator into the part when you’re done.
Caveats
This project is very new, so some things may be rough around the edges. Here's some important caveats to consider:- If you’re going to edit the immediate hierarchy (just underneath the root. Don’t worry about moving the root around) or name of instances with tracked properties, do so when the TweenSequence editor is open or that object’s tweens will not work anymore.
- Use Preview to preview the tween exactly as it will look ingame. Moving the playhead in the editor uses linear interpolation between keyframes, so it does not fully capture how EasingStyles like Bounce or Elastic will actually look.
- All Instances controlled by an Animator can’t have non-alphanumerical characters or non-unique names. Attempting to use an invalid name for an instance while the editor is open will immediately change the name to a valid one. Creating a new set of TweenSequences on a set of instances with invalid names will automatically change the names to valid ones. Be careful if you’re using non-uniquely named parts!
Future Plans
- Better keyframe manipulation (moving multiple keyframes, etc)
- Bugfixes (let me know what bugs pop up!)
