PrimeTween

PrimeTween is a high-performance, allocation-free animation library for Unity. Animate anything with just one line of code, tweak all animation properties directly from the Inspector, and create complex animation sequences. No runtime memory allocations, ever.

Performance comparison with other tween libraries.

Asset Store | Forum | FAQ | YouTube

Table of Contents

• Getting started
  • Installation
  • Animations
  • Shakes
  • Callbacks
  • Delays
  • Cycles
• Sequencing tweens
  • Sequence
  • Coroutines
  • Async/await
• Controlling tweens
• Inspector integration
• Custom tweens
• Advanced
  • Timescale
  • OnUpdate
  • Speed-based animations
  • Custom easing
  • LateUpdate/FixedUpdate
  • Install via Unity Package Manager (UPM)
• Zero allocations with delegates
• Debugging tweens
• Migrating from DOTween to PrimeTween
  • Performance comparison
  • DOTween adapter
  • Tween.PlayForward/PlayBackwards
  • Migration cheatsheet
• Support

Getting started

Installation

Import PrimeTween from Asset Store. This is a preferable option because it comes with a Demo scene.
Optional: install via Unity Package Manager (UPM).

Animations

Without further ado, let's jump straight to the code!

using PrimeTween;

// Animate 'transform.position.y' from the current value to 10 in 1 second using the Ease.InOutSine
Tween.PositionY(transform, endValue: 10, duration: 1, ease: Ease.InOutSine);

// Rotate 'transform' from the current rotation to (0, 90, 0) in 1 second
Tween.Rotation(transform, endValue: Quaternion.Euler(0, 90, 0), duration: 1);

// Rotate 'transform' around the y-axis by 360 degrees in 1 second 
Tween.EulerAngles(transform, startValue: Vector3.zero, endValue: new Vector3(0, 360), duration: 1);

That's it!

Simply type Tween. and let your IDE suggest all supported animations. Out of the box, PrimeTween can animate almost everything: UI, UI Toolkit, Materials, Camera properties, Transforms, AudioSource, and whatnot.

Didn't find what you're looking for? No problem, use Tween.Custom() to animate anything.

To view PrimeTween's XML documentation in your IDE, enable this setting: 'Unity Preferences/External Tools/Generate .csproj files for/Local tarball' and press the 'Regenerate project files' button.

Shakes

// Shake the camera with medium strength (0.5f) 
Tween.ShakeCamera(camera, strengthFactor: 0.5f);

// Shake the camera with heavy strength (1.0f) for a duration of 0.5f seconds and a frequency of 10 shakes per second 
Tween.ShakeCamera(camera, strengthFactor: 1.0f, duration: 0.5f, frequency: 10);

// Shake the y-axis position with an amplitude of 1 unit 
Tween.ShakeLocalPosition(transform, strength: new Vector3(0, 1), duration: 1, frequency: 10);

// Shake the z-axis rotation with an amplitude of 15 degrees
Tween.ShakeLocalRotation(transform, strength: new Vector3(0, 0, 15), duration: 1, frequency: 10);

// Punch localPosition in the direction of 'punchDir'
var punchDir = transform.up;
Tween.PunchLocalPosition(transform, strength: punchDir, duration: 0.5f, frequency: 10);

Callbacks

Use .OnComplete() to execute custom code on tween's completion.

// Call SomeMethod() when the animation completes
Tween.Position(transform, endValue: new Vector3(10, 0), duration: 1)
    .OnComplete(() => SomeMethod());
    
// After the animation completes, wait for 0.5 seconds, then destroy the GameObject
Tween.Scale(transform, endValue: 0, duration: 1, endDelay: 0.5f)
    .OnComplete(() => Destroy(gameObject));

"But wait! There is a memory allocation in the example above" you would say. And you would be right: calling SomeMethod() or Destroy() captures this reference in a closure and allocates heap memory. See how to address this in the zero allocations section.

Delays

Creating delays is by far the most useful feature in game development. Delays in PrimeTween behave like normal tweens and can be used with sequences, coroutines, and async/await methods. All while being completely allocation-free.

Tween.Delay(duration: 1f, () => Debug.Log("Delay completed"));

Cycles

Animations can be repeated with the help of cycles. To apply cycles to an animation, pass the int cycles and CycleMode cycleMode parameters to a Tween. method. Setting cycles to -1 will repeat the tween indefinitely.

Tween.PositionY(transform, endValue: 10, duration: 0.5f, cycles: 2, cycleMode: CycleMode.Yoyo);

To apply cycles to a Sequence, use the Sequence.Create(cycles: numCycles, cycleMode: CycleMode.Yoyo) method.

Sequence.Create(cycles: 2, CycleMode.Yoyo)
    .Chain(Tween.PositionX(transform, 10, duration))
    .Chain(Tween.PositionY(transform, 20, duration));

enum CycleMode

• Restart (default): restarts the tween from the beginning.
• Yoyo: animates forth and back, like a yoyo. Easing is the same on the backward cycle.
• Incremental: at the end of a cycle increments the endValue by the difference between startValue and endValue. For example, if a tween moves position.x from 0 to 1, then after the first cycle, the tween will move the position.x from 1 to 2, and so on.
• Rewind: rewinds the tween as if time was reversed. Easing is reversed on the backward cycle.

SetRemainingCycles(int cycles)

Sets the number of remaining cycles to an animation. This method modifies the cyclesTotal so that the animation will complete after the number of cycles.

SetRemainingCycles(bool stopAtEndValue)

Stops an animation when it reaches 'startValue' or 'endValue' for the next time.
For example, if you have an infinite animation (cycles == -1) with CycleMode.Yoyo/Rewind, and you wish to stop it when it reaches the 'endValue', then set stopAtEndValue to true. To stop the animation at the 'startValue' set stopAtEndValue to false.

Sequencing tweens

Sequence

There are several sequencing methods in PrimeTween. Let's start with the most common one: grouping tweens in Sequences.

Sequence is a group of tweens, callbacks, and other sequences. Animations in a sequence can overlap, run sequentially or in parallel, or any combination of those. You can control a Sequence the same way as individual tweens, see controlling tweens section.

Sequence.Create(cycles: 10, CycleMode.Yoyo)
    // PositionX and Scale tweens are 'grouped', so they will run in parallel
    .Group(Tween.PositionX(transform, endValue: 10f, duration: 1.5f))
    .Group(Tween.Scale(transform, endValue: 2f, duration: 0.5f, startDelay: 1))
    // Rotation tween is 'chained' so it will start when both previous tweens are finished (after 1.5 seconds)
    .Chain(Tween.Rotation(transform, endValue: new Vector3(0f, 0f, 45f), duration: 1f)) 
    .ChainDelay(1)
    .ChainCallback(() => Debug.Log("Sequence cycle completed"))
    // Insert color animation at time of '0.5' seconds
    // Inserted animations overlap with other animations in the sequence
    .Insert(atTime: 0.5f, Tween.Color(image, Color.red, duration: 0.5f));

Insert(float atTime, Tween/Sequence animation)

Places animation inside this sequence at the specified time, overlapping with other animations. The total sequence duration is increased if the inserted animation doesn't fit inside the current sequence duration.

Chain(Tween/Sequence animation)

Places animation after all previously added animations in this sequence. Chained animations run sequentially after one another.

Group(Tween/Sequence animation)

Groups animation with the 'previous' animation in this Sequence. The 'previous' animation is the animation used in the preceding Group/Chain/Insert() method call. Grouped animations start at the same time and run in parallel.

Coroutines

Another sequencing method is waiting for animations in coroutines by calling .ToYieldInstruction().

IEnumerator Coroutine() {
    Tween.PositionX(transform, endValue: 10f, duration: 1.5f);
    yield return Tween.Scale(transform, 2f, 0.5f, startDelay: 1).ToYieldInstruction();
    yield return Tween.Rotation(transform, new Vector3(0f, 0f, 45f), 1f).ToYieldInstruction();
    // Non-allocating alternative to 'yield return new WaitForSeconds(1f)'
    yield return Tween.Delay(1).ToYieldInstruction(); 
    Debug.Log("Sequence completed");
}

Async/await

And the last method is awaiting animations using the async/await pattern. Async/await is a great tool to prevent the callback hell in your code. PrimeTween doesn't use threads, so tweens can be awaited on all platforms, even on WebGL.

async void AsyncMethod() {
    Tween.PositionX(transform, endValue: 10f, duration: 1.5f);
    await Tween.Scale(transform, endValue: 2f, duration: 0.5f, startDela