Skip to content

Tween library for Unity ECS/DOTS.

License

MIT, Unknown licenses found

Licenses found

MIT
LICENSE
Unknown
LICENSE.meta
Notifications You must be signed in to change notification settings

dyonng/dots-tween

 
 

Repository files navigation

Entity Tween

GitHub release (latest SemVer) GitHub package.json version (branch)
GitHub GitHub repo size

Updated to Unity 2022.3 LTS

Tweening library for Unity ECS/DOTS
Updated for Entities 1.0.16
Uses Entities Graphics library from Unity.
Developed on 2022.3.9f1, in case you were wondering :)

Table of Contents

Demonstration

Link to the larger gif

Configuration

  • 70000 tweening entities
    • Translation
    • Rotation
    • Scale
  • Burst
    • Leak Detection: Off
    • Safety Checks: Off
    • Synchronous Compilation: On
    • Jobs Debugger: Off
  • GPU instancing

Hardware

  • Intel i7-8700 @ 3.2GHz
  • NVIDIA GeForce GTX 1660 Ti

Features

  • Pause, resume and stop all or individual tweens on an entity
  • Multiple types of active tweens on the same entity at the same time
  • Ping-pong (on tweens)
  • Loop
  • Start delay
  • Timelines
  • Ease library (from easings.net)

Tweening Support

Transform

  • Translation
  • Rotation
  • Spline Translation (with optional Rotation)
  • Scale (Uniform)
  • NonUniformScale

URP

  • Base Color Tinting
  • Base Color Alpha Fading
  • Specular Color
  • Emission Color
  • Metallic
  • Cutoff
  • Bump Scale
  • Occlusion Strength
  • Smoothness

HDRP

  • Base Color Tinting
  • Base Color Alpha Fading
  • Unlit Color Tinting
  • Unlit Color Alpha Fading
  • AlphaCutoff
  • AmbientOcclusionRemapMax
  • AmbientOcclusionRemapMin
  • DetailAlbedoScale
  • DetailNormalScale
  • DetailSmoothnessScale
  • DiffusionProfileHash
  • EmissiveColor
  • Metallic
  • Smoothness
  • SmoothnessRemapMax
  • SmoothnessRemapMin
  • SpecularColor
  • Thickness
  • ThicknessRemap

Dependencies

"dependencies": {
    "com.unity.collections": "2.1.4",
    "com.unity.entities": "1.0.16",
    "com.unity.burst": "1.8.8",
    "com.unity.mathematics": "1.2.6",
    "com.unity.entities.graphics": "1.0.16"
}

For Spline Support

  • "com.unity.splines" : "2.3.0"

Installation

Entity Tween is a Unity package. You can install it from the git URL in Unity package manager.

Or, you can edit Packages/manifest.json manually, adding git URL as a dependency:

{
    "dependencies": {
        "com.dyonng.dotstween": "https://github.com/dyonng/dots-tween.git"
    }
}

For more information, please visit Unity documentation.

Examples

The main entry point of the library is the Tween class. All functionality have overloads to support EntityManager, EntityCommandBuffer and EntityCommandBuffer.ParallelWriter.

Move the entity

float3 start = new float3(0.0f, 0.0f, 0.0f);
float3 end = new float3(1.0f, 1.0f, 1.0f);
float duration = 5.0f;

Tween.Move.FromTo(ref entityManager, entity, start, end, duration);
Tween.Move.FromTo(ref commandBuffer, entity, start, end, duration);
Tween.Move.FromTo(ref parallelWriter, entity, sortKey, start, end, duration);

Stop the entity

This will stop all tweens on the entity.

Tween.Controls.StopAll(entityManager, entity);

To stop a specific tween on an entity, use its returned tweenId.

var translationTweenId = Tween.Move.FromTo(ref entityManager, entity, start, end, duration);

Tween.Controls.Stop(ref ecb, entity, translationTweenId);

Loop infinitely

When LoopCount is -1, it means loop the tween infinitely. It's recommended to use Tween.Infinite in case it changes in the future.

Tween.Move.FromTo(ref entityManager, entity, start, end, duration, new TweenParams { LoopCount = Tween.Infinite });

Perform Component Operations On Start/Complete

Tweens with infinite LoopCounts do not support OnComplete component operations.

Has been updated to use ComponentTypeSet to support multiple component tags

Tween.Scale.FromTo(ref entityManager, entity, start, end, duration, new TweenParams
{
    LoopCount = 2,
    OnStart = new ComponentOperations
    {
        Add = new ComponentTypeSet(
            ComponentType.ReadOnly<CoolTag1>(),
            ComponentType.ReadOnly<CoolTag2>(),
            ComponentType.ReadOnly<CoolTag3>(),
        ),
    },
    OnComplete = new ComponentOperations
    {
        Add = new ComponentTypeSet(ComponentType.ReadOnly<ExampleTweenDoneTag>()),
        Remove = new ComponentTypeSet(
            ComponentType.ReadOnly<AnotherTag1>(),
            ComponentType.ReadOnly<AnotherTag2>(),
        ),
    }
});

Creating and Playing Timelines

Tweens with infinite LoopCounts are not supported within a timeline.

var duration = 1.5f;

Tween.Timeline.Create(out var timeline);
timeline.Append(obj, new TweenScaleCommand(1f, 2.2f, duration))
timeline.Insert(2f, obj, new TweenTranslationCommand(float3.zero, new float3(1f, 2f, 3f), duration))
timeline.SetStartDelay(0.5f)
timeline.AddOnComplete(new ComponentOperations { Add = ComponentType.ReadOnly<ExampleTag>() })
timeline.Play(ref entityCommandBuffer);

Check if the entity is tweening

Any entity with component TweenState is tweening; that is, to know if the entity is tweening, check if the entity has any TweenState component in any way.

if (EntityManager.HasComponent<TweenState>(entity))
{
    Debug.Log("It's tweening!");
}

Workflow

Command

When starting a tween by calling Tween's functions (e.g. Tween.Move.FromTo()), it creates a tween command component of its kind (e.g. TweenTranslationCommand) containing the tweening data on the target entity.

If starting multiple tweens with the same type consequently, the command component will be overridden by the last one, which means only the last tween will be successfully triggered.

Generation

TweenGenerateSystem is an abstract generic system, which will take the commands of its kind, then append a TweenState with an unique tween ID to the DynamicBuffer of the target entity. Also, it creates another component with the same tween ID, storing the start and end information of the tween.

Making TweenState an IBufferElementData allows multiple active tweens on the same entity at the same time, while the other part of the tween data, e.g. TweenTranslation, is an IComponentData, which ensures that there must be only one tween of the certain type.

For example, TweenTranslationGenerateSystem, which inherits TweenGenerateSystem, will take TweenTranslationCommand then create TweenState and TweenTranslation on the target entity.

Easing

TweenEaseSystem iterates all TweenState components and update the elapsed time of the tween, then calculate the progress by EasingFunctions.Ease(tween.EaseType, tween.GetNormalizedTime()) for later use.

Applying

For every type of tweens, there is a system responsible for applying the value to the target component.

For example, TweenTranslationSystem takes TweenState and TweenTranslation and interpolate the value depending on the eased percentage, then apply it to Translation.

Checking State

TweenStateSystem iterates all TweenState components checking if they're about to be looped, ping-ponged or destroyed. The tween will loop infinitely when its TweenState.LoopCount < 0; however, if it just ticked to -1 from 0, the system will mark it as pending destroy with TweenDestroyCommand;

Destroying

TweenDestroySystem is also an abstract generic system for each type of tween to implement, which destroys TweenState marked by TweenStateSystem earlier and its corresponding tween data component.

For example, TweenTranslationDestroySystem will be responsible for destroying TweenState and TweenTranslation.

Donation

NagaChiang's Donation Link (Original Author):

ko-fi