Class TweenBase

Abstract base class for all tween implementations in the Scylla tween system. Encapsulates the complete lifecycle engine: state machine, timing, delay handling, easing, loop logic (Restart, Yoyo, Incremental), per-tween time scaling, callback dispatch, pool-reset contract, and optional TweenManager registration.

Inheritance
object
TweenBase
TweenColor
TweenFloat
TweenQuaternion
TweenVector2
TweenVector3
TweenVector4
Tween<T>
Implements
Inherited Members
Namespace: Scylla.Core.Util.Tween
Assembly: ScyllaCore.dll
Syntax
public abstract class TweenBase : ITween
Remarks

Lifecycle state machine: A tween begins in Created. Calling Play() transitions it to Delayed (if a delay was set) or Playing directly. Once the delay elapses, the state automatically advances to Playing during the first Update(float) call that consumes the remaining delay time.

Start-value capture: When Play() is called, the base class invokes CaptureStartValue() so that derived classes can snapshot the current property value before any interpolation begins. This means "To" tweens always start from the live value at play time, not at creation time.

Managed vs. manual: When IsManaged is true the tween is registered with TweenManager and receives Update(float) calls automatically every frame (driven by Update(float)). The global time scale from GlobalTimeScale is also applied on top of the per-tween TimeScale. Manual tweens require the caller to invoke Update(float) explicitly and are not affected by the global time scale.

Looping: Pass a non-zero loop count to SetLoops(int, LoopType) to enable looping. Use -1 for infinite loops. Supported loop types are: Restart (jump back to start), Yoyo (reverse direction on alternating iterations), and Incremental (accumulate each iteration's change into the next).

Pooling: Concrete tween instances are managed by TweenPool. The Reset() method clears all state so the instance can be safely reused. Derived classes must call base.Reset() and clear their own fields.

Callback safety: All callbacks (OnStart(Action), OnUpdate(Action), OnComplete(Action), OnKill(Action), OnLoopComplete(Action), OnPause(Action), OnResume(Action)) are invoked through an internal try/catch wrapper. Exceptions thrown by callbacks are logged via Debug.LogException and do not propagate to the update loop.

Typical usage goes through the ScyllaTween factory rather than constructing concrete tween types directly.

Constructors

TweenBase()

Initializes a new instance of TweenBase with default settings as defined by TweenSettings.

Declaration
protected TweenBase()
Remarks

This constructor is called by derived-class constructors and by the pool when allocating a new instance. The tween starts in Created and is not yet managed, delayed, or playing. Default easing is DefaultEaseType (typically OutQuad), and auto-kill follows DefaultAutoKill (typically true).

Properties

AutoKill

Gets whether this tween is automatically killed when it completes.

Declaration
public bool AutoKill { get; }
Property Value
Type Description
bool

When true, the tween calls Kill(bool) immediately after raising the OnComplete(Action) callback, transitioning to Killed and unregistering itself from the TweenManager. Set via SetAutoKill(bool). Defaults to DefaultAutoKill (initially true).

CompletedLoops

Gets the number of loop iterations that have fully completed so far.

Declaration
public int CompletedLoops { get; }
Property Value
Type Description
int

Incremented each time a full forward (or reverse, for Yoyo) pass of the tween finishes. Resets to 0 when the tween is restarted via Restart() or Rewind().

Delay

Gets the initial delay in seconds before the tween begins playing after Play() is called.

Declaration
public float Delay { get; }
Property Value
Type Description
float

While the delay is counting down the tween is in Delayed state and IsPlaying returns true. Set via SetDelay(float). Defaults to 0 (no delay).

Duration

Gets the total playback duration of the tween in seconds, excluding any delay.

Declaration
public float Duration { get; }
Property Value
Type Description
float

The number of seconds from when playback begins (after the delay elapses) until the tween reaches its end value. A duration of 0 causes the tween to complete immediately on the first update after the delay.

EaseType

Gets the EaseType that controls the interpolation curve of this tween.

Declaration
public EaseType EaseType { get; }
Property Value
Type Description
EaseType

Determines how the animated value accelerates and decelerates over the tween's duration. When set to Custom, a user-supplied delegate is used instead. Change via SetEase(EaseType) or SetEase(Func<float, float>). Defaults to DefaultEaseType (initially OutQuad).

EasedProgress

Gets the eased, direction-corrected progress value that derived classes should use when interpolating between start and end values.

Declaration
protected float EasedProgress { get; }
Property Value
Type Description
float

The raw Progress value is first adjusted for Yoyo-reverse mode (inverted to 1 - t when the tween is playing backward), then passed through the active easing function.

For Custom, the user-supplied delegate is invoked. For all other ease types, Evaluate(EaseType, float) is called. The returned value is intentionally unclamped: elastic and back easing functions can produce values below 0 or above 1, and the interpolation math in derived classes must accommodate this to reproduce the intended overshoot effect.

ElapsedTime

Gets the amount of time that has elapsed during active playback, in seconds.

Declaration
public float ElapsedTime { get; }
Property Value
Type Description
float

The running total of scaled delta time accumulated while the tween is in the Playing state. Delay time is tracked separately and is not included in this value. Ranges from 0 to Duration under normal playback.

ID

Gets the unique identifier assigned to this tween instance.

Declaration
public TweenID ID { get; }
Property Value
Type Description
TweenID

A TweenID that is globally unique for the lifetime of the application. The ID is generated at construction time (or at pool-reset time) and does not change while the tween is alive. Use it to look up a tween via GetTween(TweenID) or GetTween(TweenID).

IsComplete

Gets whether the tween has run to completion and reached its end value.

Declaration
public bool IsComplete { get; }
Property Value
Type Description
bool

Returns true only when the tween is in Complete. Note that if AutoKill is true the tween transitions immediately from Complete to Killed, so callers that check IsComplete in an OnComplete(Action) callback may observe true for only a single frame.

IsKilled

Gets whether the tween has been killed and is no longer usable.

Declaration
public bool IsKilled { get; }
Property Value
Type Description
bool

Returns true when the tween is in Killed state. A killed tween will not respond to lifecycle calls and should be discarded or returned to the pool. Managed tweens are automatically unregistered from TweenManager when killed.

IsManaged

Gets whether this tween is registered with and automatically updated by the TweenManager.

Declaration
public bool IsManaged { get; }
Property Value
Type Description
bool

true when the tween is being ticked by Update(float); false when the caller is responsible for driving updates manually via Update(float). Toggle via SetManaged(bool).

IsPaused

Gets whether the tween is currently paused.

Declaration
public bool IsPaused { get; }
Property Value
Type Description
bool

Returns true when the tween is in Paused state. A paused tween retains its ElapsedTime and can be resumed by calling Play().

IsPlaying

Gets whether the tween is currently in an active playback state.

Declaration
public bool IsPlaying { get; }
Property Value
Type Description
bool

Returns true when the tween is in either Playing or Delayed state - that is, it has been started but has not been paused, completed, or killed. Returns false in all other states.
Remarks

Returns true when the tween is in either Playing or Delayed, since a delayed tween is actively waiting and will proceed to play without further action from the caller.

IsYoyoReversed

Gets whether the tween is currently playing in reverse during a Yoyo loop iteration.

Declaration
protected bool IsYoyoReversed { get; }
Property Value
Type Description
bool

true during every even-numbered Yoyo iteration (0-based), where the tween animates from end back to start; false during forward iterations. Always false for non-Yoyo loop types.

LoopType

Gets the LoopType that controls how the tween behaves at the end of each loop iteration.

Declaration
public LoopType LoopType { get; }
Property Value
Type Description
LoopType

Only meaningful when Loops is non-zero. Set via SetLoops(int, LoopType). Defaults to Restart.
See Also

Loops

Gets the total number of loop iterations the tween will execute.

Declaration
public int Loops { get; }
Property Value
Type Description
int
  • 0 - no looping; the tween plays once and completes.
  • A positive integer - the tween repeats that many times.
  • -1 - the tween loops indefinitely until explicitly killed.

Set via SetLoops(int, LoopType).

Progress

Gets the normalized playback progress as a value clamped between 0.0 and 1.0.

Declaration
public float Progress { get; }
Property Value
Type Description
float

Computed as ElapsedTime / Duration. Returns 1.0 when Duration is zero or when the tween has completed. This is the raw linear progress; easing is applied separately before the interpolated value is written to the target property.
Remarks

Returns 1f when Duration is zero or negative, to avoid a division-by-zero condition and treat a zero-duration tween as instantly complete. The value is clamped to the [0, 1] range.

State

Gets the current lifecycle state of the tween.

Declaration
public TweenState State { get; }
Property Value
Type Description
TweenState

One of the TweenState values that describes where the tween currently sits in its lifecycle. The convenience bool properties (IsPlaying, IsPaused, IsComplete, IsKilled) each test this value.
See Also

Target

Gets the object that this tween is animating, or null if no target was set.

Declaration
public object Target { get; }
Property Value
Type Description
object

Used by the TweenManager for target-based batch operations such as KillTweensByTarget(object, bool) and PauseTweensByTarget(object). It is also used to detect destroyed Unity objects during the update loop; if the target is a UnityEngine.Object that has been destroyed, the tween is automatically removed from the manager. Set via SetTarget on TweenBase.

TimeScale

Gets the per-tween time scale multiplier applied to delta time during updates.

Declaration
public float TimeScale { get; }
Property Value
Type Description
float

Multiplied against the incoming delta time before advancing ElapsedTime. For managed tweens the result is further multiplied by GlobalTimeScale. A value of 2.0 makes the tween play twice as fast; 0.5 makes it play at half speed. Set via SetTimeScale(float). Defaults to 1.0.

Methods

ApplyValue(float)

Writes the interpolated value to the target property at the given eased progress. Must be implemented by derived classes to perform type-specific interpolation.

Declaration
protected abstract void ApplyValue(float easedProgress)
Parameters
Type Name Description
float easedProgress

The eased (and Yoyo-corrected) progress value computed by EasedProgress. This value is intentionally unclamped; elastic and back easing can produce values below 0 or above 1, which derived classes must propagate to their lerp functions to achieve the intended overshoot or anticipation.

CaptureStartValue()

Called once during Play() (for new or restarted tweens) to snapshot the current value of the target property as the tween's start value, without applying any change.

Declaration
protected virtual void CaptureStartValue()
Remarks

The base implementation is empty. Derived classes override this to read their getter delegate and store the result in their start-value field, but only when a start value has not already been pinned via a SetFrom call. This approach ensures that the start value reflects the live property value at the moment play begins, not at the moment the tween was created.

Complete()

Immediately advances the tween to its final value and transitions to Complete.

Declaration
public ITween Complete()
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Sets ElapsedTime to Duration, applies the end value, and fires the OnComplete(Action) callback. If AutoKill is true, Kill(bool) is subsequently called automatically. Has no effect on a tween that is already killed or complete.

Kill(bool)

Permanently stops the tween and transitions it to Killed.

Declaration
public ITween Kill(bool complete = false)
Parameters
Type Name Description
bool complete

When true, the tween immediately jumps to its end value and fires the OnComplete(Action) callback before being killed. When false, the tween is killed in its current state without any final value update.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Calling Kill on an already-killed tween is a no-op. After killing, the OnKill(Action) callback is fired. Managed tweens are automatically unregistered from the TweenManager.

A killed tween should not be used further. If the tween was obtained from the pool it will be returned automatically when AutoKill is true; otherwise, the pool handles reclamation after the kill callback.

OnComplete(Action)

Registers a callback that is invoked when all loop iterations have finished and the tween reaches Complete.

Declaration
public ITween OnComplete(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke. Exceptions thrown by the callback are caught and logged but do not stop the tween.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Fires once when the very last iteration ends. For per-iteration completion notification see OnLoopComplete(Action). If AutoKill is true, Kill(bool) is called immediately after this callback returns.

OnKill(Action)

Registers a callback that is invoked when the tween is killed via Kill(bool).

Declaration
public ITween OnKill(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke on kill. Exceptions thrown by the callback are caught and logged. Fires regardless of whether the tween was killed with complete: true or false, and always fires after the OnComplete(Action) callback when applicable.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Fires whenever the tween is killed, regardless of whether it was killed manually, via AutoKill, or via KillAll(bool). If the tween was killed with complete: true, OnComplete(Action) fires first.

OnLoopComplete(Action)

Registers a callback that is invoked at the end of each individual loop iteration, including all but the very last iteration.

Declaration
public ITween OnLoopComplete(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke each time a loop iteration completes. Exceptions thrown by the callback are caught and logged.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

This callback fires once per completed iteration when Loops is non-zero. It does not fire on the final completion - use OnComplete(Action) for that.

OnPause(Action)

Registers a callback that is invoked when the tween is paused via Pause().

Declaration
public ITween OnPause(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke when the tween transitions into Paused state. Exceptions thrown by the callback are caught and logged.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.

OnResume(Action)

Registers a callback that is invoked when a paused tween is resumed via Play().

Declaration
public ITween OnResume(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke when the tween transitions out of Paused back into Playing or Delayed. Exceptions thrown by the callback are caught and logged.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.

OnStart(Action)

Registers a callback that is invoked once when the tween transitions from the delay phase (or directly from Created) into Playing for the first time.

Declaration
public ITween OnStart(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke. Exceptions thrown by the callback are caught and logged but do not stop the tween.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

This callback fires exactly once per Play() call, after any configured Delay has elapsed. Calling Restart() resets the internal flag, so the callback fires again on the next start.

OnUpdate(Action)

Registers a callback that is invoked after each frame in which the tween advances its animated value.

Declaration
public ITween OnUpdate(Action callback)
Parameters
Type Name Description
Action callback

The action to invoke on every update tick while the tween is playing. Exceptions thrown by the callback are caught and logged but do not stop the tween.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

The callback fires after the animated property has been updated with the new eased value, so the property's current value reflects the just-applied interpolation when the callback runs.

Pause()

Pauses the tween, suspending updates while preserving elapsed time.

Declaration
public ITween Pause()
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Only effective when the tween is in Playing or Delayed state. Fires the OnPause(Action) callback. The tween can be resumed by calling Play() again.

Play()

Starts or resumes the tween, transitioning it into an active playback state.

Declaration
public ITween Play()
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

The behaviour of Play depends on the tween's current state:

PrepareIncrementalLoop()

Called at the end of each Incremental loop iteration to allow derived classes to update internal state before the next iteration begins.

Declaration
protected virtual void PrepareIncrementalLoop()
Remarks

The base implementation is empty. Derived classes that support incremental looping (e.g., TweenFloat, TweenVector3) override this to capture the current property value as the new start point, so each loop iteration adds the change amount on top of the previous iteration's result.

Reset()

Resets all tween state back to initial defaults, preparing the instance for reuse from a pool.

Declaration
public virtual void Reset()
Remarks

Clears all callbacks, resets timing values, generates a new TweenID, and sets State back to Created. This is called automatically by the tween pool (TweenPool) before returning an instance to a caller. Derived classes that override this method must call the base implementation.

Restart()

Restarts the tween from the very beginning, resetting all timing and loop state.

Declaration
public ITween Restart()
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Resets ElapsedTime, CompletedLoops, and any Yoyo-reverse flag back to their initial values, then immediately begins playback (respecting the configured Delay). If the tween is managed it re-registers with the TweenManager if not already active.

Rewind()

Resets the tween's elapsed time and applies the start value without changing the tween's active/paused state.

Declaration
public ITween Rewind()
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Unlike Restart(), Rewind does not begin playback. The tween stays in whatever state it is currently in (playing, paused, etc.) but ElapsedTime is reset to 0, CompletedLoops is cleared, and the interpolated value is set back to the starting value.

SetAutoKill(bool)

Controls whether this tween is automatically killed and returned to the pool when it completes.

Declaration
public ITween SetAutoKill(bool autoKill)
Parameters
Type Name Description
bool autoKill

true to automatically call Kill(bool) after the OnComplete(Action) callback fires, freeing the tween for pool reuse. false to keep the tween alive in Complete state, allowing it to be restarted or inspected. Defaults to DefaultAutoKill (initially true).
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.

SetDelay(float)

Sets the delay in seconds that elapses before playback begins after Play() is called.

Declaration
public ITween SetDelay(float delay)
Parameters
Type Name Description
float delay

Duration of the delay in seconds. Negative values are clamped to 0. During the delay the tween is in Delayed state and IsPlaying returns true.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Negative values are clamped to zero. The delay does not affect currently playing tweens - it is only evaluated when the tween is next started via Play() or Restart().

SetDuration(float)

Sets the total playback duration of the tween in seconds.

Declaration
public ITween SetDuration(float duration)
Parameters
Type Name Description
float duration

The duration in seconds. Negative values are clamped to zero, which causes the tween to complete instantaneously on the first Update(float) call.
Returns
Type Description
ITween

This tween instance for method chaining.
Remarks

This method is called internally by Initialize methods on derived classes. It can also be called directly to adjust the duration of a tween that has not yet started. Changing the duration of an already-playing tween will affect the remaining time based on the current ElapsedTime.

SetEase(EaseType)

Sets the easing curve used to interpolate the animated value over the tween's duration.

Declaration
public ITween SetEase(EaseType easeType)
Parameters
Type Name Description
EaseType easeType

The predefined easing curve to apply. All standard Robert Penner easing functions are supported, plus Linear and Flash. Passing Custom without also calling SetEase(Func<float, float>) will result in a no-op custom function.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Clears any previously set custom ease function. To use a delegate-based ease curve, call the overload SetEase(Func<float, float>) instead.

SetEase(Func<float, float>)

Sets a fully custom easing function for fine-grained control over interpolation.

Declaration
public ITween SetEase(Func<float, float> easeFunction)
Parameters
Type Name Description
Func<float, float> easeFunction

A delegate that accepts a normalized time value t in the range [0, 1] and returns the eased output value. The output may exceed [0, 1] to produce overshoot effects (as with elastic or back easing). Setting this automatically switches EaseType to Custom.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Internally sets EaseType to Custom and stores the delegate. The function receives the raw (or Yoyo-adjusted) progress value in the range [0, 1] and must return the eased progress. It may return values outside [0, 1] to produce overshoot or anticipation effects.

SetLoops(int, LoopType)

Configures how many times the tween repeats and how it behaves between iterations.

Declaration
public ITween SetLoops(int loops, LoopType loopType = LoopType.Restart)
Parameters
Type Name Description
int loops

The number of loop iterations to execute:

  • 0 - no looping (plays once).
  • Positive integer - repeats that many additional times.
  • -1 - loops indefinitely until Kill(bool) is called.
LoopType loopType

Controls how the tween transitions between iterations. Defaults to Restart.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

Pass 0 for loops to disable looping (single playthrough). Pass -1 for infinite loops. Any positive value sets an exact iteration count. The first playthrough counts as loop iteration zero; CompletedLoops only increments when looping is enabled.

loopType determines what happens when each iteration ends: Restart jumps back to the start value, Yoyo reverses direction, and Incremental accumulates the change each iteration.

See Also

SetManaged(bool)

Controls whether this tween is automatically updated by the TweenManager each frame.

Declaration
public ITween SetManaged(bool managed)
Parameters
Type Name Description
bool managed

true to register the tween with TweenManager so that it receives automatic frame updates. false to remove it from the manager, requiring the caller to drive updates manually via Update(float). Switching from managed to unmanaged while a tween is playing unregisters it immediately.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

If the managed flag changes while the tween is actively playing or delayed, the tween is immediately registered or unregistered from TweenManager to keep the manager in a consistent state. Setting the same value as the current state is a no-op.

SetTarget(object)

Associates an arbitrary object with this tween as its logical target.

Declaration
public ITween SetTarget(object target)
Parameters
Type Name Description
object target

The object to associate with this tween. May be any reference type, including Unity Object instances. Pass null to clear the association.
Returns
Type Description
ITween

This tween instance for method chaining.
Remarks

The target is used by TweenManager to support batch operations such as KillTweensOf(object, bool) and IsTweening(object). Setting a target does not change whether the tween is managed; call SetManaged(bool) separately to opt into automatic updates.

SetTimeScale(float)

Sets the per-tween time scale that is multiplied against incoming delta time during each Update(float) call.

Declaration
public ITween SetTimeScale(float timeScale)
Parameters
Type Name Description
float timeScale

The time scale multiplier. Values greater than 1.0 speed up playback; values between 0.0 and 1.0 slow it down. A value of 0.0 effectively freezes the tween. Negative values are permitted but may produce unexpected results.
Returns
Type Description
ITween

This tween instance, enabling fluent method chaining.
Remarks

The time scale may be any value, including zero (which pauses the tween without triggering OnPause(Action)) or negative (which plays backward). For managed tweens, the effective speed is this value multiplied by GlobalTimeScale.

Update(float)

Advances the tween by the given amount of time, updating the animated value.

Declaration
public void Update(float deltaTime)
Parameters
Type Name Description
float deltaTime

The time elapsed since the last update call, in seconds. Must be non-negative. For manual tweens this is typically Time.deltaTime or Time.unscaledDeltaTime as appropriate for the use case. Managed tweens receive this call automatically from Update(float).
Remarks

The supplied deltaTime is scaled by the tween's own TimeScale. For managed tweens it is additionally scaled by GlobalTimeScale before being applied.

If the tween is not in Playing or Delayed state, this method is a no-op.

Implements

Extension Methods

See Also