![readme splash](https://raw.githubusercontent.com/jeffreylanters/unity-tweens/master/.github/WIKI/repository-readme-splash.png) [![openupm](https://camo.githubusercontent.com/ba5a519c95956c78e96ccccdf748bc9183f7e8fee961cd67fdbc6c7287ccdc4c/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f6e6c2e6a6566667265796c616e746572732e747765656e733f6c6162656c3d55504d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d267374796c653d666f722d7468652d626164676526636f6c6f723d323332633337)](https://openupm.com/packages/nl.jeffreylanters.tweens/) [![downloads](https://camo.githubusercontent.com/37b2bf5438d093804bff38457a925f195390136f11bbd98ba8cd3906a07c2706/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f64796e616d69632f6a736f6e3f636f6c6f723d343041413732267374796c653d666f722d7468652d6261646765266c6162656c3d646f776e6c6f6164732671756572793d2532342e646f776e6c6f6164732675726c3d68747470732533412532462532467061636b6167652e6f70656e75706d2e636f6d253246646f776e6c6f616473253246706f696e74253246616c6c2d74696d652532466e6c2e6a6566667265796c616e746572732e747765656e73)](https://openupm.com/packages/nl.jeffreylanters.tweens/) [![size](https://camo.githubusercontent.com/d94d87a11c1962426f4e8f9c3b8bbb662f3014c5ce3324bcd05abcfd6088b26a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6a6566667265796c616e746572732f756e6974792d747765656e733f7374796c653d666f722d7468652d6261646765)](https://github.com/jeffreylanters/unity-tweens/raw/master/Runtime) [![sponsors](https://camo.githubusercontent.com/1295dea290f6534b8a77699e046886f70b95b90a8cb7dbcec7f3b4eebfdbe4cd/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73706f6e736f72732f6a6566667265796c616e746572733f636f6c6f723d453132433941267374796c653d666f722d7468652d6261646765)](https://github.com/sponsors/jeffreylanters) [![donate](https://camo.githubusercontent.com/d4333f9a25fa505b4cb3004377a81483eb30d1ea9592fb7b99a595653efe85fd/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f6e6174652d70617970616c2d4632333135303f7374796c653d666f722d7468652d6261646765)](https://paypal.me/jeffreylanters) An extremely light weight, extendable and customisable tweening engine made for strictly typed script-based animations for user-interfaces and world-space objects optimised for all platforms. [**Installation**](https://github.com/jeffreylanters/unity-tweens/raw/master/#installation) · [**Documentation**](https://github.com/jeffreylanters/unity-tweens/raw/master/#documentation) · [**License**](https://github.com/jeffreylanters/unity-tweens/blob/master/LICENSE.md) **Made with ♥ by Jeffrey Lanters**

# Installation ### Using the Unity Package Manager Install the latest stable release using the Unity Package Manager by adding the following line to your `manifest.json` file located within your project's Packages directory, or by adding the Git URL to the Package Manager Window inside of Unity. ```json "nl.jeffreylanters.tweens": "git+https://github.com/jeffreylanters/unity-tweens" ``` ### Using OpenUPM The module is availble on the OpenUPM package registry, you can install the latest stable release using the OpenUPM Package manager's Command Line Tool using the following command. ```sh openupm add nl.jeffreylanters.tweens ``` # Documentation Tweens focuses on providing a simple and easy to use API for creating and managing tween animations. The module is designed to be as lightweight as possible, while still providing a wide range of features. The module is also designed to be as extendable as possible, allowing you to create your own custom Tweens and Tweens while keeping typings strict. - [Getting Started](https://github.com/jeffreylanters/unity-tweens/raw/master/#getting-started) - Code examples on how to create your first Tween - [Tween Types](https://github.com/jeffreylanters/unity-tweens/raw/master/#tween-types) - A list of all available Tween types - [Tween Options](https://github.com/jeffreylanters/unity-tweens/raw/master/#tween-options) - A list of all available Tween options - [Tween Instances](https://github.com/jeffreylanters/unity-tweens/raw/master/#tween-instances) - Methods available on Tween instances - [Extensions](https://github.com/jeffreylanters/unity-tweens/raw/master/#extensions) - Extensions available by the Tween module - [Advanced Examples](https://github.com/jeffreylanters/unity-tweens/raw/master/#advanced-examples) - Advanced examples on how to use the Tween module Still using version 2 of Tweens? View the [documentation here](https://github.com/jeffreylanters/unity-tweens/tree/v2.1.0)! ## Getting Started To get started, create a new instance of one of the many available Tween types and add it to a GameObject. The following example shows how to create a new PositionTween and add it to a GameObject in order to move a GameObject from its current position to a new position. ```cs var tween = new PositionTween { to = new Vector3(10, 5, 20), duration = 5, }; gameObject.AddTween(tween); ``` The PositionTween in this example represents a configuration rather than a running tween, so you can reuse it as many times as you need while it can also be altered during uses. ```cs var tween = new PositionTween { to = new Vector3(10, 5, 20), duration = 5, }; gameObject.AddTween(tween); differentGameObject.AddTween(tween); tween.to.x = 20; otherGameObject.AddTween(tween); ``` When a Tween is added, an Instance will be returned. This is where the Tween will be running. The Instance can be used to control the Tween, for example to pause, resume or cancel the Tween. ```cs var tween = new PositionTween { }; var instance = gameObject.AddTween(tween); instance.Cancel(); ``` Use the built-in Tween Inspector to analyze and debug Tweens. The Tween Inspector can be found in the Window menu under the Analysis category. ![Tween Inspector Window](https://raw.githubusercontent.com/jeffreylanters/unity-tweens/master/.github/WIKI/tween-inspector.png) These are just some of the many options available to you, for more information on how to use this Tweens. Not only are there many different types of Tweens, but there are also many different options available to you. For more information on how to use this module, please refer to the rest of the documentation. Happy Tweening! ## Tween Types To start animating a value, you will need to create a new Tween. The following sections will list all available Tween types. When a Tween will animate a specific value within a Component, the Tween will get the required Component from the GameObject automatically. When the Component is not available, the Tween will be cancelled. ### Transform The following Tween Types can be used to alter values of a Transform Component; `PositionTween`, `PositionXTween`, `PositionYTween`, `PositionZTween`, `LocalPositionTween`, `LocalPositionXTween`, `LocalPositionYTween`, `LocalPositionZTween`, `RotationTween`, `LocalRotationTween`, `EulerAnglesTween`, `EulerAnglesXTween`, `EulerAnglesYTween`, `EulerAnglesZTween`, `LocalEulerAnglesTween`, `LocalEulerAnglesXTween`, `LocalEulerAnglesYTween`, `LocalEulerAnglesZTween`, `LocalScaleTween`, `LocalScaleXTween`, `LocalScaleTweenY`, `LocalScaleTweenZ`. ### Rect Transform The following Tween Types can be used to alter values of a Rect Transform Component; `AnchoredPositionTween`, `AnchoredPositionXTween`, `AnchoredPositionYTween`, `AnchorMinTween`, `AnchorMaxTween`. ### Sprite Renderer The following Tween Types can be used to alter values of a Sprite Renderer Component; `SpriteRendererAlphaTween`, `SpriteRendererColorTween`. ### Image The following Tween Types can only be used if the `requires com.unity.ugui` package is installed in your project, and can be used to alter values of an Image Component; `ImageFillAmountTween`. ### Graphic The following Tween Types can only be used if the `requires com.unity.ugui` package is installed in your project, and can be used to alter values of a Graphic Component; `GraphicAlphaTween`, `GraphicColorTween`. ### Audio Source The following Tween Types can be used to alter values of an Audio Source Component; `AudioSourceVolumeTween`, `AudioSourcePitchTween`, `AudioSourcePanTween`, `AudioSourcePriorityTween`, `AudioSourceReverbZoneMixTween`, `AudioSourceSpatialBlendTween`. ### Light The following Tween Types can be used to alter values of a Light Component; `LightColorTween`, `LightIntensityTween`, `LightRangeTween`, `LightSpotAngleTween`. ### Generic The following Tween Types can be used to alter values of any property; `FloatTween`, `Vector2Tween`, `Vector3Tween`, `Vector4Tween`, `ColorTween`, `QuaternionTween`, `RectTween`. ## Tween Options While the Tween Type defines what the Tween will do, the Tween Options define how the Tween will do it. In the following sections, you will find a list of all available Tween Options. ### From The from value defines the starting value of the Tween. When the from value is not set, the Tween will use the current value of the property. ```cs DataType from; ``` ```cs var tween = new ExampleTween { from = new Vector3(10, 5, 20), }; ``` ### To The to value defines the end value of the Tween. When the to value is not set, the Tween will use the current value of the property. ```cs DataType to; ``` ```cs var tween = new ExampleTween { to = new Vector3(10, 5, 20), }; ``` ### Duration The duration of the Tween in seconds defines how long the Tween will take to complete. When the duration is not set, the Tween will complete instantly. ```cs float duration; ``` ```cs var tween = new ExampleTween { duration = 5, }; ``` ### Delay The delay of the Tween in seconds defines how long the Tween will wait before starting. To change the behaviour of how to the delay will affect the Tween before it starts, you can change the [Fill Mode](https://github.com/jeffreylanters/unity-tweens/raw/master/#fill-mode). When the delay is not set, the Tween will start instantly. ```cs float delay; ``` ```cs var tween = new ExampleTween { delay = 5, }; ``` ### Loops The amount of times the Tween will loop defines how many times the Tween will repeat itself. When the Tween is using a [Ping Pong](https://github.com/jeffreylanters/unity-tweens/raw/master/#ping-pong) loop type, the Tween has to play both the forward and backward animation to count as one loop. When [Infinite](https://github.com/jeffreylanters/unity-tweens/raw/master/#infinite) is set, the Tween will loop forever and the loop count will be ignored. When the amount of loops is not set, the Tween will not loop. ```cs int loops; ``` ```cs var tween = new ExampleTween { loops = 5, }; ``` ### Infinite The infinite option defines whether the Tween will loop forever. When the Tween is set to loop forever, the [Loops](https://github.com/jeffreylanters/unity-tweens/raw/master/#loops) option will be ignored. When the infinite option is not set, the Tween will not loop forever. ```cs bool isInfinite; ``` ```cs var tween = new ExampleTween { isInfinite = true, }; ``` ### Ping Pong The ping pong option defines whether the Tween will play the animation backwards after the animation has finished. When the ping pong option is not set, the Tween will not play the animation backwards after the animation has finished. ```cs bool usePingPong; ``` ```cs var tween = new ExampleTween { usePingPong = true, }; ``` ### Ping Pong Interval The ping pong interval defines how long the Tween will wait before playing the animation backwards after the animation has finished. When the ping pong interval is not set, the Tween will play the animation backwards instantly after the animation has finished. ```cs float pingPongInterval; ``` ```cs var tween = new ExampleTween { pingPongInterval = 5, }; ``` ### Repeat Interval The repeat interval defines how long the Tween will wait before repeating itself. When the repeat interval is not set, the Tween will repeat itself instantly after the animation has finished. ```cs float repeatInterval; ``` ```cs var tween = new ExampleTween { repeatInterval = 5, }; ``` ### Offset The offset defines on which time the Tween will start. When the offset is not set, the Tween will start at the beginning. ```cs float offset; ``` ```cs var tween = new ExampleTween { offset = 5, }; ``` ### Ease Type The ease type defines how the Tween will animate. If an [Animation Curve](https://github.com/jeffreylanters/unity-tweens/raw/master/#animation-curve) is set, the Ease Type won't be used. When the ease type is not set, the Tween will animate linearly. The following Ease Types can be applied; `Linear`, `SineIn`, `SineOut`, `SineInOut`, `QuadIn`, `QuadOut`, `QuadInOut`, `CubicIn`, `CubicOut`, `CubicInOut`, `QuartIn`, `QuartOut`, `QuartInOut`, `QuintIn`, `QuintOut`, `QuintInOut`, `ExpoIn`, `ExpoOut`, `ExpoInOut`, `CircIn`, `CircOut`, `CircInOut`, `BackIn`, `BackOut`, `BackInOut`, `ElasticIn`, `ElasticOut`, `ElasticInOut`, `BounceIn`, `BounceOut`, `BounceInOut`. ```cs EaseType easeType; ``` ```cs var tween = new ExampleTween { easeType = EaseType.QuadInOut, }; ``` ### Animation Curve The animation curve defines how the Tween will animate. The animation curve can be used to create custom ease types. When the animation curve is not set, the Tween will animate according to the [Ease Type](https://github.com/jeffreylanters/unity-tweens/raw/master/#ease-type). ```cs AnimationCurve animationCurve; ``` ```cs var tween = new ExampleTween { animationCurve = AnimationCurve.EaseInOut(0, 0, 1, 1), }; ``` ### Use Unscaled Time The use unscaled time option defines whether the Tween will use the unscaled time. When the use unscaled time option is not set, the Tween will use the scaled time. ```cs bool useUnscaledTime; ``` ```cs var tween = new ExampleTween { useUnscaledTime = true, }; ``` ### Fill Mode The fill mode defines how the Tween will behave before the Tween has started and after the Tween has ended. When the fill mode is not set, the fill mode will be set to `Backward`. - `None` - The animation will not be applied before the Tween has started, and will return to its original state after the Tween has ended. - `Forward` - The animation will be applied before the Tween has started, but will return to its original state after the Tween has ended. - `Backward` - The animation will not be applied before the Tween has started, but will remain in its final state after the Tween has ended. - `Both` - The animation will be applied before the Tween has started, and will remain in its final state after the Tween has ended. ```cs FillMode fillMode; ``` ```cs var tween = new ExampleTween { fillMode = FillMode.Both, }; ``` ### On Add The on add delegate will be invoked when the Tween has been added to a GameObject. ```cs OnAddDelegate onAdd; ``` ```cs var tween = new ExampleTween { onAdd = (instance) => { Debug.Log("Tween has been added"); }, }; ``` ### On Start The on start delegate will be invoked when the Tween has started. ```cs OnStartDelegate onStart; ``` ```cs var tween = new ExampleTween { onStart = (instance) => { Debug.Log("Tween has started"); }, }; ``` ### On Update The on update delegate will be invoked when the Tween has updated. ```cs OnUpdateDelegate onUpdate; ``` ```cs var tween = new ExampleTween { onUpdate = (instance, value) => { Debug.Log("Tween has updated"); }, }; ``` ### on End The on end delegate will be invoked when the Tween has ended. ```cs OnEndDelegate onEnd; ``` ```cs var tween = new ExampleTween { onEnd = (instance) => { Debug.Log("Tween has ended"); }, }; ``` ### On Cancel The on cancel delegate will be invoked when the Tween has been cancelled. ```cs OnCancelDelegate onCancel; ``` ```cs var tween = new ExampleTween { onCancel = (instance) => { Debug.Log("Tween has been cancelled"); }, }; ``` ### On Finally The on finally delegate will be invoked when the Tween has ended or has been cancelled. ```cs OnFinallyDelegate onFinally; ``` ```cs var tween = new ExampleTween { onFinally = (instance) => { Debug.Log("Tween has ended or has been cancelled"); }, }; ``` ### Dont Invoke When Destroyed The don't invoke when destroyed option defines whether the Tween should invoke the delegates when the component is no longer present in the scene. When not set, all delegates will be invoked even when the component is destroyed. ```cs bool dontInvokeWhenDestroyed; ``` ```cs var tween = new ExampleTween { dontInvokeWhenDestroyed = true }; ``` ## Tween Instances When a Tween is added to a GameObject, an Instance will be returned. This is where the Tween will be running. The Instance can be used to control the Tween, for example to pause, resume or cancel the Tween. ### Cancel The cancel method will cancel the Tween. When the Tween is cancelled, the [On Cancel](https://github.com/jeffreylanters/unity-tweens/raw/master/#on-cancel) and [On Finally](https://github.com/jeffreylanters/unity-tweens/raw/master/#on-finally) delegates will be invoked. ```cs void Cancel(); ``` ```cs var tween = new ExampleTween { }; var instance = gameObject.AddTween(tween); instance.Cancel(); ``` ### Is Paused The is paused property will return whether the Tween is paused while also allowing you to pause the Tween. ```cs bool isPaused; ``` ```cs var tween = new ExampleTween { }; var instance = gameObject.AddTween(tween); instance.isPaused = true; ``` ### Target The target property defines the target GameObject on which the Tween is running. ```cs readonly GameObject target; ``` ```cs var tween = new ExampleTween { }; var instance = gameObject.AddTween(tween); Debug.Log(instance.target); ``` ### Await Decommission The await decommission method will return an enumerator that will await the decommission of the Tween. This can be used in coroutines to wait for the Tween to finish or be cancelled. ```cs IEnumerator AwaitDecommission(); ``` ```cs var tween = new ExampleTween { }; var instance = gameObject.AddTween(tween); yield return instance.AwaitDecommission(); ``` ### Await Decommission Async The await decommission async method will return an awaitable that will await the decommission of the Tween. This can be used in async methods to wait for the Tween to finish or be cancelled. ```cs Awaitable AwaitDecommissionAsync(); ``` ```cs var tween = new ExampleTween { }; var instance = gameObject.AddTween(tween); await instance.AwaitDecommissionAsync(); ``` ## Extensions Tweens also provides extension methods that can be used to control the Tween module. ### Add Tween The add tween method will add a new Tween to the target GameObject. When the Tween is added, an Instance will be returned. This is where the Tween will be running. The Instance can be used to control the Tween, for example to pause, resume or cancel the Tween. ```cs TweenInstance AddTween(this GameObject target, Tween tween) where ComponentType : Component; ``` ```cs var tween = new ExampleTween { }; var instance = gameObject.AddTween(tween); ``` ### Cancel Tweens The cancel tweens method will cancel all Tweens on the target GameObject. When a Tween is cancelled, the [On Cancel](https://github.com/jeffreylanters/unity-tweens/raw/master/#on-cancel) and [On Finally](https://github.com/jeffreylanters/unity-tweens/raw/master/#on-finally) delegates will be invoked. When the include children option is set, all Tweens on the children of the target GameObject will also be cancelled, otherwise only the Tweens on the target GameObject will be cancelled. ```cs void CancelTweens(this GameObject target, bool includeChildren = false); ``` ```cs gameObject.CancelTweens(); ``` ## Advanced Examples Besides the many different types of Tweens and Tween Options, Tweens also provides a wide range of features that can be used to create advanced animations. The following sections will show you how to implemented some of these features to create advanced animation logic. ### Tweening Custom Values The following example shows how to create a custom Tween that can be used to animate a value of an enemy Component. The Tween will animate the value of the Component from the current value to the new value. ```cs var enemy = GetComponent(); var tween = new FloatTween { from = enemy.health, to = 23, duration = 1, easeType = EaseType.SineOut, onUpdate = (_, value) => enemy.health = value, }; enemy.gameObject.AddTween(tween); ```