// ReSharper disable CompareOfFloatsByEqualityOperator
#if PRIME_TWEEN_INSPECTOR_DEBUGGING && UNITY_EDITOR
#define ENABLE_SERIALIZATION
#endif
using System;
using JetBrains.Annotations;
using UnityEngine;
namespace PrimeTween {
/// The main API of the PrimeTween library.
/// Use static Tween methods to start animations (tweens).
/// Use the returned Tween struct to control the running tween and access its properties.
/// Tweens are non-reusable. That is, when a tween completes (or is stopped manually), it becomes 'dead' ( == false) and can no longer be used to control the tween or access its properties.
/// To restart the animation from the beginning (or play in the opposite direction), simply start a new Tween. Starting tweens is very fast and doesn't allocate garbage,
/// so you can start hundreds of tweens per seconds with no performance overhead.
///
/// var tween = Tween.LocalPositionX(transform, endValue: 1.5f, duration: 1f);
/// // Let the tween run for some time...
/// if (tween.isAlive) {
/// Debug.Log($"Animation is still running, elapsed time: {tween.elapsedTime}.");
/// } else {
/// Debug.Log("Animation is already completed.");
/// }
///
#if ENABLE_SERIALIZATION
[Serializable]
#endif
public
#if !ENABLE_SERIALIZATION
readonly
#endif
partial struct Tween : IEquatable
{
public long Id => id;
/// Uniquely identifies the tween.
/// Can be observed from the Debug Inspector if PRIME_TWEEN_INSPECTOR_DEBUGGING is defined. Use only for debugging purposes.
internal
#if !ENABLE_SERIALIZATION
readonly
#endif
long id;
internal readonly ReusableTween tween;
internal bool IsCreated => id != 0;
internal Tween([NotNull] ReusableTween tween) {
Assert.IsNotNull(tween);
Assert.AreNotEqual(-1, tween.id);
id = tween.id;
this.tween = tween;
}
/// A tween is 'alive' when it has been created and is not stopped or completed yet. Paused tween is also considered 'alive'.
public bool isAlive => id != 0 && tween.id == id && tween._isAlive;
/// Elapsed time of the current cycle.
public float elapsedTime {
get {
if (!validateIsAlive()) {
return 0;
}
if (cyclesDone == cyclesTotal) {
return duration;
}
var result = elapsedTimeTotal - duration * cyclesDone;
if (result < 0f) {
return 0f;
}
Assert.IsTrue(result >= 0f);
return result;
}
set => setElapsedTime(value);
}
void setElapsedTime(float value) {
if (!tryManipulate()) {
return;
}
if (value < 0f || float.IsNaN(value)) {
Debug.LogError($"Invalid elapsedTime value: {value}, tween: {ToString()}");
return;
}
var cycleDuration = duration;
if (value > cycleDuration) {
value = cycleDuration;
}
var _cyclesDone = cyclesDone;
if (_cyclesDone == cyclesTotal) {
_cyclesDone -= 1;
}
setElapsedTimeTotal(value + cycleDuration * _cyclesDone);
}
/// The total number of cycles. Returns -1 to indicate infinite number cycles.
public int cyclesTotal => validateIsAlive() ? tween.settings.cycles : 0;
public int cyclesDone => validateIsAlive() ? tween.getCyclesDone() : 0;
/// The duration of one cycle.
public float duration {
get {
if (!validateIsAlive()) {
return 0;
}
var result = tween.cycleDuration;
TweenSettings.validateFiniteDuration(result);
return result;
}
}
[NotNull]
public override string ToString() => isAlive ? tween.GetDescription() : $"DEAD / id {id}";
/// Elapsed time of all cycles.
public float elapsedTimeTotal {
get => validateIsAlive() ? tween.getElapsedTimeTotal() : 0;
set => setElapsedTimeTotal(value);
}
void setElapsedTimeTotal(float value) {
if (!tryManipulate()) {
return;
}
if (value < 0f || float.IsNaN(value) || (cyclesTotal == -1 && value >= float.MaxValue)) { // >= tests for positive infinity, see SetInfiniteTweenElapsedTime() test
Debug.LogError($"Invalid elapsedTimeTotal value: {value}, tween: {ToString()}");
return;
}
tween.SetElapsedTimeTotal(value, false);
// SetElapsedTimeTotal may complete the tween, so isAlive check is needed
if (isAlive && value > durationTotal) {
tween.elapsedTimeTotal = durationTotal;
}
}
/// The duration of all cycles. If cycles == -1, returns .
public float durationTotal => validateIsAlive() ? tween.getDurationTotal() : 0;
/// Normalized progress of the current cycle expressed in 0..1 range.
public float progress {
get {
if (!validateIsAlive()) {
return 0;
}
if (duration == 0) {
return 0;
}
return Mathf.Min(elapsedTime / duration, 1f);
}
set {
value = Mathf.Clamp01(value);
if (value == 1f) {
bool isLastCycle = cyclesDone == cyclesTotal - 1;
if (isLastCycle) {
setElapsedTimeTotal(float.MaxValue);
return;
}
}
setElapsedTime(value * duration);
}
}
/// Normalized progress of all cycles expressed in 0..1 range.
public float progressTotal {
get {
if (!validateIsAlive()) {
return 0;
}
if (cyclesTotal == -1) {
return 0;
}
var _totalDuration = durationTotal;
Assert.IsFalse(float.IsInfinity(_totalDuration));
if (_totalDuration == 0) {
return 0;
}
return Mathf.Min(elapsedTimeTotal / _totalDuration, 1f);
}
set {
if (cyclesTotal == -1) {
Debug.LogError($"It's not allowed to set progressTotal on infinite tween (cyclesTotal == -1), tween: {ToString()}.");
return;
}
value = Mathf.Clamp01(value);
if (value == 1f) {
setElapsedTimeTotal(float.MaxValue);
return;
}
setElapsedTimeTotal(value * durationTotal);
}
}
/// The current percentage of change between 'startValue' and 'endValue' values in 0..1 range.
public float interpolationFactor => validateIsAlive() ? Mathf.Max(0f, tween.easedInterpolationFactor) : 0f;
public bool isPaused {
get => tryManipulate() && tween._isPaused;
set {
if (tryManipulate() && tween.trySetPause(value)) {
if (value) {
return;
}
if ((timeScale > 0 && progressTotal >= 1f) ||
(timeScale < 0 && progressTotal == 0f)) {
if (tween.isMainSequenceRoot()) {
tween.sequence.releaseTweens();
} else {
tween.kill();
}
}
}
}
}
/// Interrupts the tween, ignoring onComplete callback.
public void Stop() {
if (isAlive && tryManipulate()) {
tween.kill();
}
}
/// Immediately completes the tween.
/// If the tween has infinite cycles (cycles == -1), completes only the current cycle. To choose between 'startValue' and 'endValue' in the case of infinite cycles, use before calling Complete().
public void Complete() {
// don't warn that tween is dead because dead tween means that it's already 'completed'
if (isAlive && tryManipulate()) {
tween.ForceComplete();
}
}
internal bool tryManipulate() {
if (!validateIsAlive()) {
return false;
}
if (!tween.canManipulate()) {
Assert.LogError(Constants.cantManipulateNested, id);
return false;
}
return true;
}
/// Stops the tween when it reaches 'startValue' or 'endValue' for the next time.
/// For example, if you have an infinite tween (cycles == -1) with CycleMode.Yoyo/Rewind, and you wish to stop it when it reaches the 'endValue', then set to true.
/// To stop the animation at the 'startValue', set to false.
public void SetRemainingCycles(bool stopAtEndValue) {
if (!tryManipulate()) {
return;
}
if (tween.settings.cycleMode == CycleMode.Restart || tween.settings.cycleMode == CycleMode.Incremental) {
Debug.LogWarning(nameof(SetRemainingCycles) + "(bool " + nameof(stopAtEndValue) + ") is meant to be used with CycleMode.Yoyo or Rewind. Please consider using the overload that accepts int instead.");
}
SetRemainingCycles(tween.getCyclesDone() % 2 == 0 == stopAtEndValue ? 1 : 2);
}
/// Sets the number of remaining cycles.
/// This method modifies the so that the tween will complete after the number of .
/// To set the initial number of cycles, pass the 'cycles' parameter to 'Tween.' methods instead.
/// Setting cycles to -1 will repeat the tween indefinitely.
public void SetRemainingCycles(int cycles) {
Assert.IsTrue(cycles >= -1);
if (!tryManipulate()) {
return;
}
if (tween.timeScale < 0f) {
Debug.LogError(nameof(SetRemainingCycles) + "() doesn't work with negative " + nameof(tween.timeScale));
}
if (tween.tweenType == TweenType.Delay && tween.HasOnComplete) {
Debug.LogError("Applying cycles to Delay will not repeat the OnComplete() callback, but instead will increase the Delay duration.\n" +
"OnComplete() is called only once when ALL tween cycles complete. To repeat the OnComplete() callback, please use the Sequence.Create(cycles: numCycles) and put the tween inside a Sequence.\n" +
"More info: https://discussions.unity.com/t/926420/101\n");
}
if (cycles == -1) {
tween.settings.cycles = -1;
} else {
TweenSettings.setCyclesTo1If0(ref cycles);
tween.settings.cycles = tween.getCyclesDone() + cycles;
}
}
/// Adds completion callback. Please consider using to prevent a possible capture of variable into a closure.
/// Set to 'false' to disable the error about target's destruction. Please note that the the callback will be silently ignored in the case of target's destruction. More info: https://github.com/KyryloKuzyk/PrimeTween/discussions/4
public Tween OnComplete(Action onComplete, bool warnIfTargetDestroyed = true) {
if (validateIsAlive()) {
tween.OnComplete(onComplete, warnIfTargetDestroyed);
}
return this;
}
/// Adds completion callback.
/// Set to 'false' to disable the error about target's destruction. Please note that the the callback will be silently ignored in the case of target's destruction. More info: https://github.com/KyryloKuzyk/PrimeTween/discussions/4
/// The example shows how to destroy the object after the completion of a tween.
/// Please note: we're using the '_transform' variable from the onComplete callback to prevent garbage allocation. Using the 'transform' variable directly will capture it into a closure and generate garbage.
///
/// Tween.PositionX(transform, endValue: 1.5f, duration: 1f)
/// .OnComplete(transform, _transform => Destroy(_transform.gameObject));
///
public Tween OnComplete([NotNull] T target, Action onComplete, bool warnIfTargetDestroyed = true) where T : class {
if (validateIsAlive()) {
tween.OnComplete(target, onComplete, warnIfTargetDestroyed);
}
return this;
}
public Sequence Group(Tween _tween) => tryManipulate() ? Sequence.Create(this).Group(_tween) : default;
public Sequence Chain(Tween _tween) => tryManipulate() ? Sequence.Create(this).Chain(_tween) : default;
public Sequence Group(Sequence sequence) => tryManipulate() ? Sequence.Create(this).Group(sequence) : default;
public Sequence Chain(Sequence sequence) => tryManipulate() ? Sequence.Create(this).Chain(sequence) : default;
bool validateIsAlive() {
if (!IsCreated) {
Debug.LogError(Constants.defaultCtorError);
} else if (!isAlive) {
Assert.LogError(Constants.isDeadMessage, id);
}
return isAlive;
}
/// Custom timeScale. To smoothly animate timeScale over time, use method.
public float timeScale {
get => tryManipulate() ? tween.timeScale : 1;
set {
if (tryManipulate()) {
Assert.IsFalse(float.IsNaN(value));
Assert.IsFalse(float.IsInfinity(value));
tween.timeScale = value;
}
}
}
public Tween OnUpdate(T target, Action onUpdate) where T : class {
if (validateIsAlive()) {
tween.SetOnUpdate(target, onUpdate);
}
return this;
}
internal float durationWithWaitDelay => tween.calcDurationWithWaitDependencies();
public override int GetHashCode() => id.GetHashCode();
/// https://www.jacksondunstan.com/articles/5148
public bool Equals(Tween other) => isAlive && other.isAlive && id == other.id;
}
}