Juce-Tween

Welcome to Tween Component, the open-source tweening library that's part of the Juce Unity tools framework.

• Easy to use: gracefully integrated with Unity.

• Flexible: nest as many tweens and sequences as you want to create complex animations.

• Extendible: Easily create neew Tweens for animating any variable imaginable.

• Coders friendly: we take a lot of effort making sure the underlying structure is clean and easy to extend. Code aims to be robust and well written.

Contents

• Why
• Installing
• Enabling Extensions
• Nomenclature
• Basic Usage
• Bindings
• Tween Components Documentation
• Want to contribute?
• Contributors

Why?

When we start developing games in Unity and we learn about Tweening engines, we quickly jump to the most popular ones like DoTween, and they seem magical.

But once you get more serious and advance on the journey of game development, you start to notice some small quirks and issues with those well known tweening engines that just make you wonder why they did that this way, or why this simple thing does not work.

This tweening engine aims to solve that. Things just work as you would expect, there is no conditions nor compromises.

Installing

Unity Package Manager dependences:

• TextMeshPro

- Via Github

Dependences

First of all, you will need to download the following dependences

• Juce-Utils

Download the full repositories, and then place them under the Assets folder of your Unity project.

Project installation

Download this repository, and place it under the Assets folder of your Unity project.

And that's all, with that you should be ready to go!

- Via UPM

Unity does not support resolving dependences from a git url. Because of that, you will need to add the following lines to your manifest.json.

"dependencies": {
   "com.juce.utils": "git+https://github.com/Juce-Assets/Juce-Utils",
   "com.juce.tween": "git+https://github.com/Juce-Assets/Juce-Tween",
},

Enabling Extensions

Since Unity is moving towards a very granular approach, we dont want to force our users to have all the dependences installed in your project to start using the tool.

To enanble or disable different extensions, first open on the Unity top bar: Tools/Juce/Configuration to open the Juce Configuration Window.

Once the window is opened, you just need to select which extension you want to use in your project. (You may need to wait for Unity to recompile).

For some Example scenes to work, you will probably need to add, at least, TextMeshPro to your project, and enable the toggle extension.

Nomenclature

• Tweening engine: system that allows you to animate stuff via code in an easy, concise and possibly powerful way.
• Tween: unit of work that takes control of a value and animates it.
• Sequence: special tween that, instead of taking control of a value, takes control of other tweens and animates them as a group.

Basic Usage

This is a very straightforward example of how the tweening engine works. Unity components have tweening extensions that you can call with the prefix Tween... like TweenPosition, TweenRotation, etc. This then returns an ITween that you can play whenever you want by callyng Play() on it;

using Juce.Tweening;
using UnityEngine;

public class Example : MonoBehaviour
{
    [SerializeField] private Transform transform = default;

    private void Start()
    {
        ITween tween = transform.TweenPosition(to: new Vector3(10, 0, 0), duration: 1f);

        tween.Play();
    }
}

Generic Tweens

This is the most flexible way of tweening and allows you to tween almost any value, either public or private, static or dynamic (shortcuts actually uses the generic tweens in the background).

static Tween.To(getter, setter, to, float duration, validation);

• Getter: function that gets called at the beggining to determine the starting value of the tween.
• Setter: function that gets called every update, while the tween is active, and returns the current value of the tween.
• Duration: time in seconds that the tween should take to complete.
• Validation (optional): funcion that gets called every update, checks if the tween should be killed. This is practical, for example, for checking if a component that is using has been destroyed while the tween was running.

Practical example:

using Juce.Tweening;
using UnityEngine;

public class Example : MonoBehaviour
{
    [SerializeField] private Transform transform = default;

    private void Start()
    {
        Vector3 finalValue = new Vector3(10, 0, 0);

        ITween tween = Tween.To(
            () => transform.position,
            toSet => transform.position = toSet,
            () => finalValue,
            duration: 1f,
            validation: () => transform != null
            );

        tween.Play();
    }
}

Shortcut Tweens

Juce-Tween includes shortcuts for some known Unity objects, like Transform, Rigidbody and Material, etc. You can start a tween directly from a reference to these objects, like:

transform.TweenPosition(new Vector3(10, 0, 0), 1);
image.TweenColor(Color.green, 1);
canvasGroup.TweenAlpha(0, 1);

If the target Unity object gets destroyed, the Tween will automatically be killed.

Sequences

Sequences are Tweens, but instead of animating a property or value they animate other Tweens or Sequences as a group. Sequences can be contained inside other Sequences without any limit to the depth of the hierarchy.

A Tween can be nested only inside a single other Sequence, meaning you can't reuse the same tween in multiple Sequences. To create a sequence, you do the following

ISequence sequence = JuceTween.Sequence();

sequence.Append(tween1);
sequence.Append(tween2);
sequence.Append(tween3);

sequence.Play();

Conclusions

We are always aiming to improve this tool. You can always leave suggestions on the Issues link.

Want to contribute?

Please follow these steps to get your work merged in.

0. Clone the repo and make a new branch: $ git checkout https://github.com/Juce-Assets/Juce-Tween/tree/develop -b [name_of_new_branch].

1. Add a feature, fix a bug, or refactor some code :)

2. Update README.md contributors, if necessary.

3. Open a Pull Request with a comprehensive description of changes.

Contributors

• Guillem SC - @Guillemsc