Open Classmigueldeicaza.swiftgodot 0.45.0SwiftGodot

Tween

Lightweight object used for general-purpose animation via script, using Tweeners.

class Tween

Mangled symbol

s10SwiftGodot5TweenCWhat are these?

FNV24: [53BJI]

Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name tween comes from in-betweening, an animation technique where you specify keyframes and the computer interpolates the frames that appear between them. Animating something with a Tween is called tweening.

Tween is more suited than AnimationPlayer for animations where you don’t know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a Tween; it would be difficult to do the same thing with an AnimationPlayer node. Tweens are also more light-weight than AnimationPlayer, so they are very much suited for simple animations or general tasks that don’t require visual tweaking provided by the editor. They can be used in a fire-and-forget manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped CallbackTweener with a delay.

A Tween can be created by using either createTween or createTween. Tweens created manually (i.e. by using Tween.new()) are invalid and can’t be used for tweening values.

A tween animation is created by adding Tweeners to the Tween object, using tweenProperty(object:property:finalVal:duration:), tweenInterval(time:), tweenCallback(_:) or tweenMethod(_:from:to:duration:):

This sequence will make the $Sprite node turn red, then shrink, before finally calling queueFree to free the sprite. Tweeners are executed one after another by default. This behavior can be changed using parallel and setParallel(_:).

When a Tweener is created with one of the tween_* methods, a chained method call can be used to tweak the properties of this Tweener. For example, if you want to set a different transition type in the above example, you can use setTrans(_:):

Most of the Tween methods can be chained this way too. In the following example the Tween is bound to the running script’s node and a default transition is set for its Tweeners:

Another interesting use for Tweens is animating arbitrary sets of objects:

In the example above, all children of a node are moved one after another to position (0, 0).

You should avoid using more than one Tween per object’s property. If two or more tweens animate one property at the same time, the last one created will take priority and assign the final value. If you want to interrupt and restart an animation, consider assigning the Tween to a variable:

Some Tweeners use transitions and eases. The first accepts a TransitionType constant, and refers to the way the timing of the animation is handled (see easings.net for some examples). The second accepts an EaseType constant, and controls where the trans_type is applied to the interpolation (in the beginning, the end, or both). If you don’t know which transition and easing to pick, you can try different TransitionType constants with .easeInOut, and use the one that looks best.

Tween easing and transition types cheatsheet

This object emits the following signals:

Superclasses

class RefCounted
Base class for reference-counted objects.

Citizens in SwiftGodot

Conformances

protocol CustomStringConvertible
A type with a customized textual representation.
protocol Equatable
A type that can be compared for value equality.
protocol Hashable
A type that can be hashed into a Hasher to produce an integer hash value.
protocol Identifiable<ID>
A class of types whose instances hold the value of an entity with stable identity.
protocol VariantRepresentable
Types that conform to VariantRepresentable can be stored directly in Variant with no conversion. These include all of the Variant types from Godot (for example GString, Rect, Plane), Godot objects (those that subclass SwiftGodot.Object) as well as the built-in Swift types UInt8, Int64 and Double.
protocol VariantStorable
Types that conform to VariantStorable can be stored in a Variant and can be extracted back out of a Variant.

Types

Type members

static func interpolateValue(initialValue: Variant, deltaValue: Variant, elapsedTime: Double, duration: Double, transType: Tween.TransitionType, easeType: Tween.EaseType) -> Variant
This method can be used for manual interpolation of a value, when you don’t want Tween to do animating for you. It’s similar to @GlobalScope.lerp, but with support for custom transition and easing.
class var godotClassName: StringName

Instance members

var finished: SimpleSignal
Emitted when the Tween has finished all tweening. Never emitted when the Tween is set to infinite looping (see setLoops(_:)).
var loopFinished: Signal2
Emitted when a full loop is complete (see setLoops(_:)), providing the loop index. This signal is not emitted after the final loop, use [signal finished] instead for this case.
var stepFinished: Signal1
Emitted when one step of the Tween is complete, providing the step index. One step is either a single Tweener or a group of Tweeners running in parallel.
func bindNode(Node?) -> Tween?
Binds this Tween with the given node. Tweens are processed directly by the SceneTree, so they run independently of the animated nodes. When you bind a Node with the Tween, the Tween will halt the animation when the object is not inside tree and the Tween will be automatically killed when the bound object is freed. Also .tweenPauseBound will make the pausing behavior dependent on the bound node.
func chain() -> Tween?
Used to chain two Tweeners after setParallel(_:) is called with true.
func customStep(delta: Double) -> Bool
Processes the Tween by the given delta value, in seconds. This is mostly useful for manual control when the Tween is paused. It can also be used to end the Tween animation immediately, by setting delta longer than the whole duration of the Tween animation.
func getLoopsLeft() -> Int32
Returns the number of remaining loops for this Tween (see setLoops(_:)). A return value of -1 indicates an infinitely looping Tween, and a return value of 0 indicates that the Tween has already finished.
func getTotalElapsedTime() -> Double
Returns the total time in seconds the Tween has been animating (i.e. the time since it started, not counting pauses etc.). The time is affected by setSpeedScale(speed:), and stop will reset it to 0.
func isRunning() -> Bool
Returns whether the Tween is currently running, i.e. it wasn’t paused and it’s not finished.
func isValid() -> Bool
Returns whether the Tween is valid. A valid Tween is a Tween contained by the scene tree (i.e. the array from getProcessedTweens will contain this Tween). A Tween might become invalid when it has finished tweening, is killed, or when created with Tween.new(). Invalid Tweens can’t have Tweeners appended.
func kill()
Aborts all tweening operations and invalidates the Tween.
func parallel() -> Tween?
Makes the next Tweener run parallelly to the previous one.
func pause()
Pauses the tweening. The animation can be resumed by using play.
func play()
Resumes a paused or stopped Tween.
func setEase(Tween.EaseType) -> Tween?
Sets the default ease type for PropertyTweeners and MethodTweeners animated by this Tween.
func setLoops(Int32) -> Tween?
Sets the number of times the tweening sequence will be repeated, i.e. set_loops(2) will run the animation twice.
func setParallel(Bool) -> Tween?
If parallel is true, the Tweeners appended after this method will by default run simultaneously, as opposed to sequentially.
func setPauseMode(Tween.TweenPauseMode) -> Tween?
Determines the behavior of the Tween when the SceneTree is paused. Check TweenPauseMode for options.
func setProcessMode(Tween.TweenProcessMode) -> Tween?
Determines whether the Tween should run after process frames (see _process(delta:)) or physics frames (see _physicsProcess(delta:)).
func setSpeedScale(speed: Double) -> Tween?
Scales the speed of tweening. This affects all Tweeners and their delays.
func setTrans(Tween.TransitionType) -> Tween?
Sets the default transition type for PropertyTweeners and MethodTweeners animated by this Tween.
func stop()
Stops the tweening and resets the Tween to its initial state. This will not remove any appended Tweeners.
func tweenCallback(Callable) -> CallbackTweener?
Creates and appends a CallbackTweener. This method can be used to call an arbitrary method in any object. Use Callable/bind() to bind additional arguments for the call.
func tweenInterval(time: Double) -> IntervalTweener?
Creates and appends an IntervalTweener. This method can be used to create delays in the tween animation, as an alternative to using the delay in other Tweeners, or when there’s no animation (in which case the Tween acts as a timer). time is the length of the interval, in seconds.
func tweenMethod(Callable, from: Variant, to: Variant, duration: Double) -> MethodTweener?
Creates and appends a MethodTweener. This method is similar to a combination of tweenCallback(_:) and tweenProperty(object:property:finalVal:duration:). It calls a method over time with a tweened value provided as an argument. The value is tweened between from and to over the time specified by duration, in seconds. Use Callable/bind() to bind additional arguments for the call. You can use setEase(_:) and setTrans(_:) to tweak the easing and transition of the value or setDelay(_:) to delay the tweening.
func tweenProperty(object: Object?, property: NodePath, finalVal: Variant, duration: Double) -> PropertyTweener?
Creates and appends a PropertyTweener. This method tweens a property of an object between an initial value and finalVal in a span of time equal to duration, in seconds. The initial value by default is the property’s value at the time the tweening of the PropertyTweener starts.