Class TweenSequence

Orchestrates a timeline of ITween instances, callbacks, and intervals that play as a single coordinated unit.

Inheritance
object
TweenSequence
Implements
Inherited Members
Namespace: Scylla.Core.Util.Tween
Assembly: ScyllaCore.dll
Syntax
public sealed class TweenSequence : ITween
Remarks

A TweenSequence owns a flat list of SequenceItem entries, each carrying a start time measured in seconds from the beginning of the sequence. The sequence drives its children by advancing their individual elapsed time as the sequence's own elapsed time progresses, so child tweens never need to be registered with TweenManager independently.

Items are added with the following builder methods, all of which return this for fluent chaining:

Easing is not applied at the sequence level; each child tween retains its own EaseType. SetEase(EaseType) and SetEase(Func<float, float>) are no-ops on sequences.

The sequence participates fully in the managed update system. Call SetManaged(bool) to register it with TweenManager, which will call Update(float) automatically each frame. Alternatively, call Update(float) manually from your own update loop.

Instances are pooled and should normally be obtained via Sequence() rather than constructed directly. When finished, return the instance to the pool with Release(TweenSequence). The Reset() method clears all items and callbacks so the instance can be reused safely.

Constructors

TweenSequence()

Initializes a new TweenSequence in the Created state with an empty item list, a time scale of 1.0, and AutoKill set to the current value of DefaultAutoKill.

Declaration
public TweenSequence()
Remarks

Prefer obtaining instances from the pool via Sequence() or GetSequence() to avoid repeated heap allocations.

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).

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.

ItemCount

Gets the total number of SequenceItem entries in this sequence, including tweens, callbacks, and intervals.

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

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.

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

Append(ITween)

Appends a tween immediately after all currently scheduled items, advancing the internal append cursor by the tween's duration.

Declaration
public TweenSequence Append(ITween tween)
Parameters
Type Name Description
ITween tween

The tween to append. If null, the method is a no-op and returns this.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

The sequence total duration is recalculated after every Append call. Calling Join(ITween) immediately after Append places an item at the same start time as the appended tween, allowing parallel playback.

AppendCallback(Action)

Appends a zero-duration callback that fires at the current end of the timeline (i.e., at the current value of the internal append cursor).

Declaration
public TweenSequence AppendCallback(Action callback)
Parameters
Type Name Description
Action callback

The delegate to invoke when playback reaches the callback's position. If null, the method is a no-op and returns this.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

Callbacks are guaranteed to fire exactly once per loop iteration even if a single Update(float) step overshoots the callback's time position. They are NOT fired when the sequence is rewound or reset.

AppendInterval(float)

Advances the internal append cursor by interval seconds without adding any animated content, effectively inserting a pause in the timeline.

Declaration
public TweenSequence AppendInterval(float interval)
Parameters
Type Name Description
float interval

The duration of the empty interval in seconds. Values less than or equal to 0 are ignored and the method returns this unchanged.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.

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.

Insert(float, ITween)

Inserts a tween so that it begins at atPosition seconds from the start of the sequence, regardless of the current append cursor position.

Declaration
public TweenSequence Insert(float atPosition, ITween tween)
Parameters
Type Name Description
float atPosition

The absolute start time in seconds at which the tween should begin playing. May overlap, precede, or follow existing items.
ITween tween

The tween to insert. If null, the method is a no-op and returns this.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

Unlike Append(ITween), Insert does not move the append cursor. If the inserted tween extends beyond the current sequence end, the total duration is extended accordingly.

InsertCallback(float, Action)

Inserts a zero-duration callback that fires when the sequence's elapsed time first reaches or exceeds atPosition seconds.

Declaration
public TweenSequence InsertCallback(float atPosition, Action callback)
Parameters
Type Name Description
float atPosition

The absolute timeline position in seconds at which the callback fires.
Action callback

The delegate to invoke at the specified position. If null, the method is a no-op and returns this.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

Does not advance the append cursor. The callback is fired once per loop iteration, protected by the _completedCallbacks set.

Join(ITween)

Adds a tween that starts at the same timeline position as the most recently appended (non-joined) item, allowing multiple tweens to animate simultaneously.

Declaration
public TweenSequence Join(ITween tween)
Parameters
Type Name Description
ITween tween

The tween to run in parallel. If null, the method is a no-op and returns this.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

The join cursor is determined by walking backwards through Scylla.Core.Util.Tween.TweenSequence._items to find the last item whose IsJoined flag is false, then using its StartTime. If the sequence is empty, the joined tween starts at time zero.

The append cursor is NOT advanced by Join, so subsequent Append(ITween) calls still follow after the item that was joined to.

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.

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:

Prepend(ITween)

Inserts a tween at the very beginning of the timeline (time zero) and shifts every existing item forward by the duration of the prepended tween.

Declaration
public TweenSequence Prepend(ITween tween)
Parameters
Type Name Description
ITween tween

The tween to insert at position zero. If null, the method is a no-op and returns this.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

All existing items - tweens, callbacks, and intervals - are reconstructed with their start times offset by tween.Duration. The append cursor is also advanced by the same amount so that subsequent Append(ITween) calls remain correctly positioned.

PrependInterval(float)

Inserts an empty interval of interval seconds at the very beginning of the timeline and shifts all existing items forward by that amount.

Declaration
public TweenSequence PrependInterval(float interval)
Parameters
Type Name Description
float interval

Duration of the interval in seconds. Values less than or equal to 0 are ignored and the method returns this unchanged.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

Every existing item (tween, callback, or interval) is reconstructed with its start time increased by interval. The append cursor is also advanced so subsequent Append(ITween) calls remain correctly positioned.

Reset()

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

Declaration
public 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

The delay applies before any child tween starts. Negative values are clamped to zero. Setting the delay while the sequence is already past the Delayed phase has no retroactive effect.

SetEase(EaseType)

No-op on a sequence. Easing is controlled at the individual child tween level.

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

Ignored.
Returns
Type Description
ITween

This sequence for fluent method chaining.

SetEase(Func<float, float>)

No-op on a sequence. Easing is controlled at the individual child tween level.

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

Ignored.
Returns
Type Description
ITween

This sequence for fluent method chaining.

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

A value of 0 means no looping (the sequence plays once). A value of -1 loops indefinitely. Positive values specify an exact number of iterations.

The loopType parameter is stored but only Restart semantics are currently implemented for sequences - on each loop iteration all child tweens are rewound and replayed from the start.

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

When switching from unmanaged to managed while the sequence is already playing or delayed, the sequence is immediately registered with TweenManager so that it receives automatic updates. Switching from managed to unmanaged unregisters the sequence; the caller becomes responsible for calling Update(float) each frame.

SetTarget(object)

Associates an arbitrary object with this sequence so that KillTweensByTarget(object, bool), GetTweensByTarget(object), and related batch operations can locate and act on this sequence by its owner.

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

The object to associate with this sequence. Typically the Unity GameObject, Component, or other owner. Pass null to clear the current target association.
Returns
Type Description
TweenSequence

This sequence for fluent method chaining.
Remarks

The target is stored as a plain object reference. If the target is a UnityEngine.Object, TweenManager will automatically remove the sequence when the Unity object is destroyed.

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 sequence's own time scale is applied before GlobalTimeScale. Child tweens retain their own time scale multiplier, which is layered on top of the sequence's elapsed-time advancement.

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