Interface ITween

Core interface implemented by all tween types in the Scylla Tween system.

Namespace: Scylla.Core.Util.Tween

Assembly: ScyllaCore.dll

Syntax

public interface ITween

Remarks

ITween defines the complete contract for a single animation tween: its observable state, timing and looping configuration, lifecycle control, and callback registration. All concrete tween types (TweenFloat, TweenVector3, TweenColor, etc.) and the TweenSequence implement this interface through TweenBase.

Managed vs. manual tweens
A tween whose IsManaged flag is true is registered with the TweenManager and is ticked automatically each frame via ScyllaTween.Update(deltaTime). A manual tween must have Update(float) called explicitly by the caller every frame.

Method chaining
All configuration and callback methods return ITween (the same instance) so they can be chained in a fluent style:

<pre><code class="lang-csharp">ScyllaTween.To(() => transform.position, v => transform.position = v, target, 0.5f)
.SetEase(EaseType.OutBack)
.SetDelay(0.1f)
.SetManaged(true)
.OnComplete(() => Debug.Log("Done"))
.Play();</code></pre>

Lifecycle
The tween moves through states defined by TweenState: Created -> Delayed (optional) -> Playing -> Complete -> Killed. It may also transition to Paused from Playing or Delayed. Once a tween reaches Killed it should be treated as invalid and released back to the pool.

Properties

AutoKill

Gets whether this tween is automatically killed when it completes.

Declaration

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

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

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

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

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

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

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

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

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

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

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

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.

LoopType

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

Declaration

LoopType LoopType { get; }

Property Value

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

Loops

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

Declaration

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

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

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.

Target

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

Declaration

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

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

Complete()

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

Declaration

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

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

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

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

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

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

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

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

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

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

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:

Created or Complete - begins playback from the start. If a Delay greater than zero is configured, the tween first enters Delayed before moving to Playing. If the tween is managed it is registered with the TweenManager at this point.
Paused - resumes from the saved ElapsedTime and fires the OnResume(Action) callback.
Killed - no-op; a killed tween cannot be replayed without resetting it first.

Reset()

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

Declaration

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

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

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

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

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.

SetEase(EaseType)

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

Declaration

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.

SetEase(Func<float, float>)

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

Declaration

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.

SetLoops(int, LoopType)

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

Declaration

ITween SetLoops(int loops, LoopType loopType = LoopType.Restart)

Parameters

Type Name Description

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.

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.

SetManaged(bool)

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

Declaration

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.

SetTimeScale(float)

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

Declaration

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.

Update(float)

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

Declaration

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.