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 :)
- 70000 tweening entities
Translation
Rotation
Scale
- Burst
- Leak Detection: Off
- Safety Checks: Off
- Synchronous Compilation: On
- Jobs Debugger: Off
- GPU instancing
- Intel i7-8700 @ 3.2GHz
- NVIDIA GeForce GTX 1660 Ti
- 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)
- Translation
- Rotation
- Spline Translation (with optional Rotation)
- Scale (Uniform)
- NonUniformScale
- Base Color Tinting
- Base Color Alpha Fading
- Specular Color
- Emission Color
- Metallic
- Cutoff
- Bump Scale
- Occlusion Strength
- Smoothness
- 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": {
"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"
}
- "com.unity.splines" : "2.3.0"
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.
The main entry point of the library is the Tween
class. All functionality have overloads to support EntityManager
, EntityCommandBuffer
and EntityCommandBuffer.ParallelWriter
.
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);
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);
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 });
Tweens with infinite LoopCounts do not support OnComplete
component operations.
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>(),
),
}
});
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);
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!");
}
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.
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.
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.
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
.
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
;
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
.