a Unity Tween EnginePowered by DEMIGIANT

Get HOTween

Here it is (.zip)

For release notes, changelog, and HOTween's Visual Editor, head to Download.

DOTween (HOTween v2) IS OUT!
More than 4x faster, more efficient, and with tons of new features.
Check it out

All of HOTween methods and properties are fully documented, but code comments will work only with C# (UnityScript isn't able to decode them).
Luckily, automatic code completion will work with any programming language.

Here, we'll have a look at HOTween's installation, plus some basics. To get to know HOTween's full power and options, head to Documentation.

Installation

C#

Simply unzip HOTween.zip anywhere inside your Unity project's Assets folder (but keep the DLL and the XML together, or you'll lose the code tooltips).

UnityScript and Boo

Create an Assets/Plugins folder in your Unity project (if you don't have it already), and unzip HOTween.zip there.

HOTween Editor

After installing HOTween's DLL, you can import HOTween's Editor package and it's done. You can watch a tutorial of its usage on the homepage.

Get ready to code

Before using HOTween, you will have to import its namespaces in your script (yes! namespaces! that's a thing I can't live without! the fact that open source Unity code doesn't support neither them nor internal members is the only reason I made a DLL :P):

C# using Holoville.HOTween; using Holoville.HOTween.Plugins; // You need this only if you plan to use some of the non-default tween plugins public class MyClass { ... }

UnityScript import Holoville.HOTween; import Holoville.HOTween.Plugins; // You need this only if you plan to use some of the non-default tween plugins function Start () { ... }

HOTween basics

The tween creation logic is quite simple, and will be somehow familiar to you if you're used to other tween engines. You always use HOTween.To() (or HOTween.From()), and give it a target (which is the object that contains the property or field you wish to tween), a duration, and a series of parameters (like the properties to tween, the type of easing, the type and number of loops, eventual callbacks, and so on).

In these examples I will use Transforms, but keep in mind that HOTween can animate ANY non-static public property or field of ANY object.

Fast HOTween

Let's start with the most basic example. If you are in a real hurry, and just want to tween a single property using HOTween's default parameters, you can simply do this:

Fast: animate a Transform from its current position to x:10, y:20, z:30 HOTween.To(myGameObject.transform, 1, "position", new Vector3(10,20,30));

Where the parameters are: the object whose properties you want to tween, the duration of the tween, the name of the property to tween, and the value you want to tween to.

TipYou can change HOTween's default parameters at any time, by changing HOTween.defUpdateType, .defEaseType, .defLoopType or defTimeScale.

Full HOTween

If you want to control more parameters (like loop type and amount, ease type, etc.), or tween more than one property/field of the same target, you will need to use a TweenParms object and pass it to HOTween.To parameters (HOTween Sequence uses SequenceParms instead).

Code assist will automatically tell you what type of parameters you have at your disposal, just keep in mind that Prop(propName,endValue) is where you place the name of the property to tween and its end value, and that you can chain as many Prop as you wish.

To use TweenParms, you can either create it inline, adding all the Props and options you want via method chaining...

Inline method chaining to tween position + rotation + scale + set easing and delay HOTween.To(myGameObject.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).Prop("rotation", new Vector3(0,720,0)).Prop("localScale", new Vector3(4,4,4)).Ease(EaseType.EaseOutBounce).Delay(1));

...or create it separately and then pass it to HOTween...

Create parameters to tween position + rotation + scale + set easing and delay, and then apply them. // C# TweenParms parms = new TweenParms(); // UnityScript var parms:TweenParms = new TweenParms(); // Both C# than UnityScript parms.Prop("position", new Vector3(10,20,30)); // Position tween parms.Prop("rotation", new Vector3(0,720,0)); // Rotation tween parms.Prop("localScale", new Vector3(4,4,4)); // Scale tween parms.Ease(EaseType.EaseOutBounce); // Easing type parms.Delay(1); // Initial delay // You can fill the parameters with more options than these ones, // check the full list in the documentation HOTween.To(myGameObject.transform, 1, parms );

...or, obviously, create it separately but inline.

Create inline parameters to tween position + rotation + scale + set easing and delay // C# TweenParms parms = new TweenParms().Prop("position", new Vector3(10,20,30)).Prop("rotation", new Vector3(0,720,0)).Prop("localScale", new Vector3(4,4,4)).Ease(EaseType.EaseOutBounce).Delay(1); // UnityScript var parms:TweenParms = new TweenParms().Prop("position", new Vector3(10,20,30)).Prop("rotation", new Vector3(0,720,0)).Prop("localScale", new Vector3(4,4,4)).Ease(EaseType.EaseOutBounce).Delay(1); // Both C# than UnityScript HOTween.To(myGameObject.transform, 1, parms );

TipIf you want to store a TweenParms object for other HOTweens, changing only the Props, use NewProp(propName,endValue): it will clear any previous Props before applying the new one.

Why method chaining? I studied and implemented many ways (like Hashtables or object initializers), but I ended up deciding that this was the best one, because it's reliable and fast to write: 1) it's type-safe, 2) code assist will show you the available parameters while you type, and 3) code completion will quickly fill them.

TipThere is a special parameter called Pause(), which will force the newly created tween to start in a paused state.

TipHOTween gameObject's full name is HOTween : [total first-level* tweens and sequences]. Thus, if you're in the Editor, you can have an immediate feedback on how many tweens are running, just by looking at your hierarchy.
* First-level means only Tweeners and Sequences not nested inside other Sequences.

HOTween Sequence basics

Each time you call HOTween.To, a new Tweener is created and returned. You can let that object go by itself, or you can place it inside a Sequence, to create complex sequences of tweens and control them dinamically as they were one. Also, you can place Sequences inside other Sequences, to make things more fun.

Think of a Sequence as a timeline, where you place Tweeners or other Sequences at the position you decide. Also, it can be controlled as any video timeline would: play and pause it, but also rewind, restart, reverse, complete, or directly set its position (either with GoTo(position) or with mySequence.position=[time]).

Creating a Sequence

If you want to use a Sequence, first of all you'll have to create one (obviously, you are not limited to just one). You do it by simply calling new Sequence(parms), where parms work exactly the same way as TweenParms, but are of type SequenceParms.

Creating a new Sequence and set loops to 3 and loopType to Yoyo mySequence = new Sequence(new SequenceParms().Loops(3,LoopType.Yoyo));

Adding tweens to a Sequence

Once you've created the sequence, you can add tweens to it by using mySequence.Append(tween), mySequence.Prepend(tween), or mySequence.Insert(atTime,tween).

Adding 3 Tweeners to a sequence // Append adds the given Tweener or Sequence to the right of the sequence (time-wise) mySequence.Append(HOTween.To(myGameObject1.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).Prop("rotation", new Vector3(0,720,0)).Prop("localScale", new Vector3(4,4,4)).Ease(EaseType.EaseOutBounce))); // Prepend adds the given Tweener or Sequence to the left of the sequence (time-wise), // moving all previous Tweeners/Sequences to the right. mySequence.Prepend(HOTween.To(myGameObject2.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).Prop("rotation", new Vector3(0,720,0)).Prop("localScale", new Vector3(4,4,4)).Ease(EaseType.EaseInElastic))); // Insert just places the given Tweener or Sequence at the desired point in time. mySequence.Insert(1, HOTween.To(myGameObject3.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).Prop("rotation", new Vector3(0,720,0)).Prop("localScale", new Vector3(4,4,4)).Ease(EaseType.EaseOutQuad)));

TipYou can also append and prepend empty intervals to a Sequence, using AppendInterval(duration) and PrependInterval(duration).

TipTweeners and Sequences share the same IHOTweenComponent interface, with all the same controls like Play, Reverse, GoTo, Kill, etc.

Callbacks

Callbacks are added to a Tweener via TweenParms, and to a Sequence via SequenceParms, and they can be chained like the rest of the parameters:

Using HOTween.To with an onComplete callback HOTween.To(myGameObject.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).OnComplete(MyFunction));

Creating a Sequence with an onComplete callback mySequence = new Sequence(new SequenceParms().OnComplete(MyFunction));

You can check all the available callbacks in the Documentation.

TipCallbacks added to a Tweener/Sequence will work even if the Tweener/Sequence is added to another Sequence.

You can use 2 types of functions for HOTween callbacks. Which one will be used will depend on if you passed additional parameters when setting a tween's On[Something] parameter.

Callback type A: Parameterless function

A function that returns nothing and has no parameters:

C# Sample parameter-less callback function HOTween.To(myGameObject.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).OnComplete(MyFunction)); private void MyFunction() { // Your code here }

UnityScript Sample parameter-less callback function private function MyFunction() { // Your code here }

Callback type B: Function who accepts a TweenEvent parameter

A function that returns nothing (void) and has a single parameter of type TweenEvent, which will be sent by HOTween when a callback is invoked.

The TweenEvent object will contain 2 properties:

tweenEvent.tween

a reference to the Tweener or Sequence to which the callback was added.

tweenEvent.parms

an array of the eventual additional parameters you wrote when setting the callback.

C# Sample TweenEvent callback function HOTween.To(myGameObject.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).OnComplete(MyFunction,1,2,3)); private void MyFunction( TweenEvent e ) { Debug.Log( e.tween ); // outputs the tweener or sequence that invoked this function if ( e.parms != null ) { Debug.Log( e.parms[0] ); // outputs 1 } }

UnityScript Sample TweenEvent callback function HOTween.To(myGameObject.transform, 1, new TweenParms().Prop("position", new Vector3(10,20,30)).OnComplete(MyFunction,1,2,3)); private function MyFunction( e:TweenEvent ) { Debug.Log( e.tween ); // outputs the tweener or sequence that invoked this function if ( e.parms != null ) { Debug.Log( e.parms[0] ); // outputs 1 } }

TipCallback functions can be public, private, static, internal, protected, or whatever.

TipOther than callbacks, you can use Coroutines, like WaitForCompletion. Check it in the Tweener and Sequence documentation.

Plugins

All HOTween's animations work with plugins, but they are usually managed automatically. When adding a Prop parameter to HOTween.To, you normally just write the name of the property to tween and the end value, then HOTween finds by himself the correct plugin to apply, based on the property's type. This system works if you want to animate values in the default way, but sometimes you wish to use special kinds of animations. That's when you can directly assign special plugins to a Prop parameter.

For example, if you animate a Vector3 property, HOTween automatically uses the PlugVector3 plugin, which animates the x/y/z values linearly from the starting vector to the ending one. If you want to animate only the Y value of the vector, you might instead tell him to use the PlugVector3Y plugin. Or, if you wish to move along a path, you might use the PlugVector3Path plugin.

Let's see a simple example.

Animating only the Y axis of a Vector3 property, with PlugVector3Y HOTween.To(myGameObject.transform, 1, new TweenParms().Prop("position", new PlugVector3Y(20)));

All plugins have additional optional parameters that you can set, like the easing for that property, or if the value should be considered relative or absolute (think of relative as moving a value BY instead than TO). Also, some plugins have even more additional parameters that are set with method chaining (like PlugVector3Path, which lets you choose if the path should be smoothly closed automatically, and the type of orientation).

That's it for the basics. For a full list of available plugins, see the Documentation.