**UTween** is an interpolation animation component for **Unity**. You can quickly configure animations through built-in components or write animations through code. ![license](https://camo.githubusercontent.com/f57d9312d3f570e567c5c5f8910d2382d68d9db3e70a82fa2496a291c01e2cab/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6c73393531322f55547765656e) [![openupm](https://camo.githubusercontent.com/69dfd9e389079af1f9d568a24956899814183b2611a87137694dfe01017d38c6/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f636f6d2e6c73393531322e75747765656e3f6c6162656c3d6f70656e75706d2672656769737472795f7572693d68747470733a2f2f7061636b6167652e6f70656e75706d2e636f6d)](https://openupm.com/packages/com.ls9512.utween/) ![topLanguage](https://camo.githubusercontent.com/f7d1f329a7a98a5112be55e0d07b182f7df1e8fcbf4990057d868d7e1ff991ce/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f746f702f6c73393531322f55547765656e) ![size](https://camo.githubusercontent.com/f935159ef1fbd55cb3a684cee170e0f5ca3a96aa702754827ebe9c27a7b8ae8b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c616e6775616765732f636f64652d73697a652f6c73393531322f55547765656e) ![last](https://camo.githubusercontent.com/d3c2adbe7cad58f89cc9a0016e2a5cf58e260016632bcfc2c1995f4d11a064d2/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6173742d636f6d6d69742f6c73393531322f55547765656e) [![issue](https://camo.githubusercontent.com/47f9e7a8f32c1820fe09cd45e7a77fd4b39a675a7be6f76b50ff5ad08c2ce6ee/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6c73393531322f55547765656e)](https://github.com/ls9512/UTween/issues) [[中文文档]](https://github.com/ls9512/UTween/blob/master/README_CN.md) > Official QQ Group：[1070645638](https://jq.qq.com/?_wv=1027&k=ezkLnUln) * 1. [Quick Start](https://github.com/ls9512/UTween/raw/master/#QuickStart) * 1.1. [Features](https://github.com/ls9512/UTween/raw/master/#Features) * 1.2. [Environment](https://github.com/ls9512/UTween/raw/master/#Environment) * 1.3. [Preview](https://github.com/ls9512/UTween/raw/master/#Preview) * 1.4. [Installation](https://github.com/ls9512/UTween/raw/master/#Installation) * 2. [ Parameter](https://github.com/ls9512/UTween/raw/master/#Parameter) * 3. [Built-in Function](https://github.com/ls9512/UTween/raw/master/#Built-inFunction) * 3.1. [Core](https://github.com/ls9512/UTween/raw/master/#Core) * 3.1.1. [Tweener](https://github.com/ls9512/UTween/raw/master/#Tweener) * 3.1.2. [TweenManager](https://github.com/ls9512/UTween/raw/master/#TweenManager) * 3.1.3. [TweenPool](https://github.com/ls9512/UTween/raw/master/#TweenPool) * 3.1.4. [TweenAnimation](https://github.com/ls9512/UTween/raw/master/#TweenAnimation) * 3.1.5. [TweenAnimationAsset](https://github.com/ls9512/UTween/raw/master/#TweenAnimationAsset) * 3.2. [Data Type](https://github.com/ls9512/UTween/raw/master/#DataType) * 3.3. [Ease Function](https://github.com/ls9512/UTween/raw/master/#EaseFunction) * 3.3.1. [Standard](https://github.com/ls9512/UTween/raw/master/#Standard) * 3.3.2. [Additional](https://github.com/ls9512/UTween/raw/master/#Additional) * 3.4. [Tween Type](https://github.com/ls9512/UTween/raw/master/#TweenType) * 4. [Execute Flow](https://github.com/ls9512/UTween/raw/master/#ExecuteFlow) * 5. [Performance Testing](https://github.com/ls9512/UTween/raw/master/#PerformanceTesting) * 6. [Usage Example](https://github.com/ls9512/UTween/raw/master/#UsageExample) * 6.1. [Common Usage](https://github.com/ls9512/UTween/raw/master/#CommonUsage) * 6.2. [Chain Style](https://github.com/ls9512/UTween/raw/master/#ChainStyle) * 6.3. [Quick API](https://github.com/ls9512/UTween/raw/master/#QuickAPI) * 6.4. [Unity Component Extension](https://github.com/ls9512/UTween/raw/master/#UnityComponentExtension) * 6.5. [Sequential / Parallel](https://github.com/ls9512/UTween/raw/master/#SequentialParallel) * 6.6. [Dynamic Start / End](https://github.com/ls9512/UTween/raw/master/#DynamicStartEnd) * 6.7. [Animation Group](https://github.com/ls9512/UTween/raw/master/#AnimationGroup) * 6.8. [Configuration Assets](https://github.com/ls9512/UTween/raw/master/#ConfigurationAssets) * 7. [User Extension](https://github.com/ls9512/UTween/raw/master/#UserExtension) * 7.1. [Add Custom Ease Function](https://github.com/ls9512/UTween/raw/master/#AddCustomEaseFunction) * 7.2. [Add Custom Interpolation Animation](https://github.com/ls9512/UTween/raw/master/#AddCustomInterpolationAnimation) * 8. [The End](https://github.com/ls9512/UTween/raw/master/#TheEnd) ## 1. Quick Start ### 1.1. Features * Provide detailed parameters to achieve high freedom of custom animation. * Built-in animation realization of translation, rotation, scaling, value, color, etc. of a large number of commonly used components. * Built-in a large number of commonly used ease functions, and provide custom curves for independent setting of different axes. * Provide three usage modes of editor component, configuration file and code call. * All animations can be exported and saved as configuration files to realize animation resource management and reuse. * Support dynamic starting point, dynamic adjustment of parameters during animation (only available in script mode). * Provide high-performance material animation based on `MaterialPropertyBlock`. * Except for animations related to operating strings, it basically achieves 0 GC. * Good chain programming support. ### 1.2. Environment ![Unity: 2019.4.3f1](https://camo.githubusercontent.com/9a293e15a838dcc50431c95cc43b44243baed6b6f83dc68d4f15de08e4ebbbbe/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f556e6974792d323031392e342e3366312d626c7565) ![.NET 4.x](https://camo.githubusercontent.com/27d8a87432cf1bcbbf21e48af6eb9f42894f062e8bbd0583a7f83fc025c240e5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f2e4e45542d342e782d626c7565) ### 1.3. Preview Add components and use rich built-in animation and easing functions:

Build-in ease functions:

Support each axis independent curve:

The editor previews the animation in real time, what you see is what you get:

Built-in curve path editor:

### 1.4. Installation * 1. Download the latest [release](https://github.com/ls9512/UTween/releases) version of unitypackage. * 2. Install via [OpenUPM](https://github.com/openupm/openupm): ``` openupm add com.ls9512.utween ``` * 3. Install via [Unity Package Manager - Git URL](https://docs.unity3d.com/Manual/upm-ui-giturl.html): ``` "com.ls9512.utween": "git+https://github.com/ls9512/utween" ``` * 4. Download the repository source code and install it manually. * 5. May be released to AssetStore in the future. ## 2. Parameter * **From**: Starting value for interpolation * **To**: The end of the interpolation * **Curve**: Custom interpolation animation curve will be accumulated on the calculation result of the easing function * **Curve Target**: You can choose whether the calculation result of the curve is applied to the interpolation factor or the value of the interpolation result * **Curve Mode**: You can choose a single curve to act on the whole or use separate curve control for each axis * **Play Type**: Play type, optional **Once, Loop, LoopCount, PingPong, PingPongCount** * **Ease Type**: Built-in easing function type, the default is linear, there are many optional effects, please test by yourself. * **Loop Count**: Loop count * **Duration:**: Duration of interpolation process, unit s * **Interval**: Repeat interval time, only available in Loop and PingPong modes * **Speed Based**: Based on speed instead of time interpolation, the Duration parameter will be used as the speed value when selected * **Start Delay**: Delay time of interpolation start, unit s * **Auto Play**: Timing of auto play, default None, no auto play, optional **Awake, Start, Enable**, if you select Enable, it will be triggered multiple times * **Update Type**: Calculate the timing of the update, adjust it according to the actual needs of the animation, the default is **Update**, optional **LateUpdate** and **FixedUpdate** * **Time Scale**: Time scale, determine whether the animation is affected by the time scale speed change, you can control the separation of the interpolation animation from the game process * **Self Scale**: Self time scaling, used to adjust the animation playback speed, will change the actual running time of the animation * **Time Smooth**: Whether to use **Time.smoothDeltaTime** to prevent the animation from jittering due to frame rate fluctuations, only available when **Time Scale** is **true** * **Auto Kill**: Whether to automatically destroy after playing (only valid for non-infinite loop type playback) * **Callback**: Used to register callbacks at the beginning and end of interpolation *** ## 3. Built-in Function ### 3.1. Core #### 3.1.1. Tweener The smallest component that realizes a single animation effect corresponds to a complete set of animation parameters, and each Tweener component runs independently. #### 3.1.2. TweenManager It is used to manage and schedule all Tweener components, maintain all TweenPools, is controlled by the **Unity MonoBehaviour** life cycle, and provides **Update / LateUpdate / FixedUpdate** update modes. #### 3.1.3. TweenPool The internal object pool of the component is used for the recycling and reuse of Tweener components. #### 3.1.4. TweenAnimation Tweener's editor class, used to configure animation in **Inspector**, and provide different configuration interfaces for different Tweeners. But TweenAnimation itself does not provide any logical functions, the operation of animation still relies on TweenManager, and components only provide data and configuration interfaces. #### 3.1.5. TweenAnimationAsset Animation configuration resource files based on `ScriptableObject` can be imported and exported from `TweenAnimation`, and can be called by code to create animation. ### 3.2. Data Type * float * Vector2 * Vector3 * Vector4 * Quaternion * Color * Rect * Transform(Position Vector3/Rotation Vector3/Scale Vector3) ### 3.3. Ease Function #### 3.3.1. Standard * Linear * Circular * Quad * Cubic * Cubic * Quart * Sine * Expo * Circ * Back * Bounce * Elastic #### 3.3.2. Additional * Flash * Step * Parabola * Trigonometric ### 3.4. Tween Type * Position * Poition UGUI * Rotation EulerAngles * Rotation Quaternion * Scale * Transform * Size * Width * Height * Color * ColorBlock * Alpha * CanvasGroup Alpha * AudioSource Volume * Scrollbar * Slider * Text * Shkae * Value * Material Color * Material Float * Material Tilling * Material OFfset * Material Vector4 * Gradient * Path * Sequence * Parallel ## 4. Execute Flow * Prepare all necessary parameters. * Calculate the interpolation factor through RunTime / Duration. * Substitute the actual interpolation factor into the `EaseFunction` of the corresponding `EasyType` to calculate. * When CurveMode == Factor, multiply the difference factor by the curve calculation result. * Use the final interpolation factor to calculate the interpolation result value. * When CurveMode == Value, multiply the interpolation result by the curve calculation result. * Apply the interpolation result to the target component and refresh the component state. *** ## 5. Performance Testing * Test platform: i5-8500 / 16GB DDR4 2666 / GTX 950 / Unity 2019.4.3f1 * 1000 GameObjects rely on the TweenAnimation/TweenPosition component to execute in the scene. In the editor mode, the Profier counts that each frame consumes 3.21ms of CPU time. Under the same environment and animation effects, DOTween is 2.51ms. * Except that the object pool is empty at startup, all required Tweener objects need to be created, as well as string-related operations. In most cases, the GC is 0. *** ## 6. Usage Example ### 6.1. Common Usage ```csharp var tween = UTween.Create(); tween.SetFrom(0f); tween.SetTo(1f); tween.SetDuration(2f); tween.SetFloatCallback(value => { Debug.Log("Value : " + value); } }); tween.Play(); ``` ### 6.2. Chain Style You can quickly create interpolation animations through the `Tween.Create<>()` interface, and set some properties and callbacks in the way of `chain programming`. ```csharp UTween.Create() .SetFrom(0f) .SetTo(1f) .SetDuration(5f) .SetUpdateType(UpdateType.Update) .SetPlayType(PlayType.Once) .SetEaseType(EaseType.Linear) .SetTimeScale(false) .SetPlayCallback(() => { Debug.Log("Play"); }) .SetValueCallback(value => { Debug.Log("Value : " + value); }) .SetStopCallback(() => { Debug.Log("Stp["); }) .Play(); ``` ### 6.3. Quick API ```csharp UTween.Position(transform, Vector3.zero, Vector3.one, 1f); UTween.Scale(transform, Vector3.zero, Vector3.one, 1f); UTween.Rotation(transform, new Vector3(0, 0, 0), new Vector3(0, 360, 0), 1f); UTween.Color(image, Color.black, Color.white, 1f); UTween.Alpha(image, 0f, 1f, 1f); // Please try more APIs yourself ``` ### 6.4. Unity Component Extension ```csharp Transform transform; transform.Move(Vector3.zero, Vector3.one, 1f); ``` Currently only contains a small number of native component extension interfaces, which will be added later. ### 6.5. Sequential / Parallel Sequential interpolation animation/parallel interpolation animation can control the state of a group of Tweeners at one time, but at this time, the callback and state changes of the child Tweener will not be triggered, and the transfer is controlled by the upper-level component. * Sequence Example : ``` cs UTween.GetSequence() .Append(UTween.Position(SequneceMoveObj, Vector3.zero, Vector3.one, 2f)) .Append(UTween.Position(SequneceMoveObj, Vector3.one, Vector3.up, 2f)) .Append(UTween.Position(SequneceMoveObj, Vector3.up, Vector3.left, 2f)) .Append(UTween.Position(SequneceMoveObj, Vector3.left, Vector3.zero, 2f)) .Play(); ``` * Parallel Example : ``` cs UTween.GetParallel() .Append(UTween.Position(ParallelMoveObj1, new Vector3(2, 0, 0), new Vector3(4, 0, 0), 2f)) .Append(UTween.Position(ParallelMoveObj2, new Vector3(2, 2, 0), new Vector3(4, 2, 0), 2f)) .Play(); ``` ### 6.6. Dynamic Start / End Use the `SetFromGetter / SetToGetter` method to set the method of dynamically obtaining the start point and end point, and ensure that the animation update is performed after the start point value is updated, you can get an interpolated animation with the start point and end point dynamically changing: ```csharp public float FromValue = 0f; public float ToValue = 0f; UTween.Value(0f, 5f, 1f, value => FromValue = value); UTween.Value(10f, 5f, 1f, value => ToValue = value); UTween.Create() .SetFromGetter(()=> FromValue) .SetToGetter(()=> ToValue) .SetDuration(1f) .SetUpdateType(UpdateType.LateUpdate) .Play(); ``` ### 6.7. Animation Group Get the animation instance generated by one or more animation components configured on an object and play it through the `Identifier` parameter: ```csharp var tweeners = gameObject.GetTweeners("Open"); tweeners.Play(); ``` It is expensive to obtain animation components or animation instances in real time. It is recommended to cache the reference of the `TweenAnimation` component in advance and call it when needed. ### 6.8. Configuration Assets Create an animation through the loaded animation configuration file and play it after specifying the target: ```csharp TweenAnimationAsset Asset; UTween.Create(Asset) .SetTarget(TweenPosTarget) .Play(); ``` ## 7. User Extension ### 7.1. Add Custom Ease Function 1.Create a custom easing type constant: ```csharp [EnumClass("EaseType")] public static class EaseTypeExtension { #if UNITY_EDITOR [UnityEditor.InitializeOnLoadMethod] #else [UnityEngine.RuntimeInitializeOnLoadMethod] #endif public static void Init() { SerializeEnumAttribute.CacheSerializeEnum(typeof(EaseTypeExtension)); } [EnumProperty("Extension", "Ease Lerp")] public const int EaseLerp = 10001; } ``` 2.Create a custom interpolation class and integrate the implementation of the `EaseFunction` type: ```csharp public class EaseLerp : EaseFunction { public override int Type => EaseTypeExtension.EaseLerp; public override float Ease(float from, float to, float delta) { return Mathf.Lerp(from, to, delta); } } ``` ### 7.2. Add Custom Interpolation Animation 1.Create a custom animation type constant: ```csharp [EnumClass("TweenType")] public static class TweenTypeExtension { #if UNITY_EDITOR [UnityEditor.InitializeOnLoadMethod] #else [UnityEngine.RuntimeInitializeOnLoadMethod] #endif public static void Init() { SerializeEnumAttribute.CacheSerializeEnum(typeof(TweenTypeExtension)); } [EnumProperty("UI", "Text FontSize")] public const int TextFontSize = 10001; } ``` 2.Create a custom interpolation class and integrate the implementation of the `Tweener` type: ```csharp [Tweener(TweenTypeExtension.TextFontSize)] [RequireComponent(typeof(Text))] public class TweenTextFontSize : TweenFloatBase { public override int Type => TweenTypeExtension.TextFontSize; protected override void SetValue(float value) { Component.fontSize = (int)value; #if UNITY_EDITOR // Refresh for editor preview if (!Application.isPlaying) { UnityEditor.EditorUtility.SetDirty(Component); } #endif } } ``` 3.If you need to use it under the editor, you also need to write the corresponding editor code: ```csharp [TweenerEditor(TweenTypeExtension.TextFontSize)] public class TweenTextEditor : TweenFloatBaseEditor { public override int Type => TweenTypeExtension.TextFontSize; public override int RequireCurveCount => 1; public override bool AllowQuickOperation => true; public new TweenTextFontSize Tweener => Target as TweenTextFontSize; } ``` *** ## 8. The End This project is a self-developed plug-in for self-use. It has been verified by a certain period of time and accumulation of many small and medium-sized projects. It is now decided to open source for everyone to learn and use, but it does not mean that this is a highly completed commercial plug-in, which may exist Many functions are missing and hidden BUG. If nothing happens, the project will not update new functions in the future. The author will start to develop a brand new animation plug-in that will not be compatible with the current version. The new project will maintain existing features. Under the premise of large-scale reconstruction, and focus on improving ease of use, scalability and performance. However, if you encounter any problems or find BUGs in the process of using `UTween`, you can submit feedback in the `Issues` of this repository. People who want to improve and perfect the plug-in together are welcome to initiate `Pull Request` .