SceneTreeTween

Inherits: Reference < Object Tweeners.

Description

SceneTreeTween is a tween managed by the scene tree. As opposed to Tween, it does not require the instantiation of a node. SceneTreeTweens are 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. SceneTreeTween can be created by using either SceneTree.create_tween or Node.create_tween. SceneTreeTweens created manually (i.e. by using Tween.new()) are invalid. They can’t be used for tweening values, but you can do manual interpolation with interpolate_value. Tweeners to the SceneTreeTween object, using tween_property, tween_interval, tween_callback or tween_method:

var tween = get_tree().create_tween()tween.tween_property($Sprite, "modulate", Color.red, 1)tween.tween_property($Sprite, "scale", Vector2(), 1)tween.tween_callback($Sprite, "queue_free")

$Sprite node turn red, then shrink, before finally calling Node.queuefree to free the sprite. Tweeners are executed one after another by default. This behavior can be changed using parallel and set_parallel. 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 set_trans:

var tween = get_tree().create_tween()tween.tween_property($Sprite, "modulate", Color.red, 1).set_trans(Tween.TRANS_SINE)tween.tween_property($Sprite, "scale", Vector2(), 1).set_trans(Tween.TRANS_BOUNCE)tween.tween_callback($Sprite, "queue_free")

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

var tween = get_tree().create_tween().bind_node(self).set_trans(Tween.TRANS_ELASTIC)tween.tween_property($Sprite, "modulate", Color.red, 1)tween.tween_property($Sprite, "scale", Vector2(), 1)tween.tween_callback($Sprite, "queue_free")

SceneTreeTweens is animating arbitrary sets of objects:

var tween = create_tween()for sprite in get_children():    tween.tween_property(sprite, "position", Vector2(0, 0), 1)

In the example above, all children of a node are moved one after another to position (0, 0). 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 Tween.EASE_IN_OUT, and use the one that looks best. Tween easing and transition types cheatsheet Note: All SceneTreeTweens will automatically start by default. To prevent a SceneTreeTween from autostarting, you can call stop immediately after it is created.

Methods

Signals

• finished ( ) SceneTreeTween has finished all tweening. Never emitted when the SceneTreeTween is set to infinite looping (see set_loops). Note: The SceneTreeTween is removed (invalidated) in the next processing frame after this signal is emitted. Calling stop inside the signal callback will prevent the SceneTreeTween from being removed.

• loop_finished ( int loop_count ) set_loops), providing the loop index. This signal is not emitted after the final loop, use finished instead for this case.

• step_finished ( int idx ) SceneTreeTween is complete, providing the step index. One step is either a single Tweener or a group of Tweeners running in parallel.

  Enumerations

  TweenPauseMode:
• TWEEN_PAUSE_BOUND = 0 —- If the SceneTreeTween has a bound node, it will process when that node can process (see Node.pause_mode). Otherwise it’s the same as TWEEN_PAUSE_STOP.
• TWEEN_PAUSE_STOP = 1 —- If SceneTree is paused, the SceneTreeTween will also pause.
• TWEEN_PAUSE_PROCESS = 2 —- The SceneTreeTween will process regardless of whether SceneTree is paused.

  Method Descriptions

• SceneTreeTween bind_node ( Node node ) SceneTreeTween with the given node. SceneTreeTweens are processed directly by the SceneTree, so they run independently of the animated nodes. When you bind a Node with the SceneTreeTween, the SceneTreeTween will halt the animation when the object is not inside tree and the SceneTreeTween will be automatically killed when the bound object is freed. Also TWEEN_PAUSE_BOUND will make the pausing behavior dependent on the bound node. SceneTreeTween, you can use Node.create_tween.

• SceneTreeTween chain ( ) Tweeners after set_parallel is called with true.

  var tween = create_tween().set_parallel(true)tween.tween_property(...)tween.tween_property(...) # Will run parallelly with above.tween.chain().tween_property(...) # Will run after two above are finished.

• bool custom_step ( float delta ) SceneTreeTween by the given delta value, in seconds. This is mostly useful for manual control when the SceneTreeTween is paused. It can also be used to end the SceneTreeTween animation immediately, by setting delta longer than the whole duration of the SceneTreeTween animation. true if the SceneTreeTween still has Tweeners that haven’t finished. Note: The SceneTreeTween will become invalid in the next processing frame after its animation finishes. Calling stop after performing custom_step instead keeps and resets the SceneTreeTween.

• float get_total_elapsed_time ( ) const SceneTreeTween has been animating (i.e. the time since it started, not counting pauses etc.). The time is affected by set_speed_scale, and stop will reset it to 0. Note: As it results from accumulating frame deltas, the time returned after the SceneTreeTween has finished animating will be slightly greater than the actual SceneTreeTween duration.

• Variant interpolate_value ( Variant initial_value, Variant delta_value, float elapsed_time, float duration, TransitionType trans_type, EaseType ease_type ) const SceneTreeTween to do animating for you. It’s similar to @GDScript.lerp, but with support for custom transition and easing. initial_value is the starting value of the interpolation. delta_value is the change of the value in the interpolation, i.e. it’s equal to final_value - initial_value. elapsed_time is the time in seconds that passed after the interpolation started and it’s used to control the position of the interpolation. E.g. when it’s equal to half of the duration, the interpolated value will be halfway between initial and final values. This value can also be greater than duration or lower than 0, which will extrapolate the value. duration is the total time of the interpolation. Note: If duration is equal to 0, the method will always return the final value, regardless of elapsed_time provided.

• bool is_running ( ) const SceneTreeTween is currently running, i.e. it wasn’t paused and it’s not finished.

• bool is_valid ( ) const SceneTreeTween is valid. A valid SceneTreeTween is a SceneTreeTween contained by the scene tree (i.e. the array from SceneTree.get_processed_tweens will contain this SceneTreeTween). A SceneTreeTween might become invalid when it has finished tweening, is killed, or when created with SceneTreeTween.new(). Invalid SceneTreeTweens can’t have Tweeners appended. You can however still use interpolate_value.

• kill ( ) SceneTreeTween.

• SceneTreeTween parallel ( ) Tweener run parallelly to the previous one. Example:

  var tween = create_tween()tween.tween_property(...)tween.parallel().tween_property(...)tween.parallel().tween_property(...)

  Tweeners in the example will run at the same time. SceneTreeTween parallel by default by using set_parallel.

• pause ( ) play.

• play ( ) SceneTreeTween.

• SceneTreeTween set_ease ( EaseType ease ) PropertyTweeners and MethodTweeners animated by this SceneTreeTween.

• SceneTreeTween set_loops ( int loops=0 ) set_loops(2) will run the animation twice. SceneTreeTween run infinitely, until either it is killed with kill, the SceneTreeTween‘s bound node is freed, or all the animated objects have been freed (which makes further animation impossible). Warning: Make sure to always add some duration/delay when using infinite loops. To prevent the game freezing, 0-duration looped animations (e.g. a single CallbackTweener with no delay) are stopped after a small number of loops, which may produce unexpected results. If a SceneTreeTween‘s lifetime depends on some node, always use bind_node.

• SceneTreeTween set_parallel ( bool parallel=true ) parallel is true, the Tweeners appended after this method will by default run simultaneously, as opposed to sequentially.

• SceneTreeTween set_pause_mode ( TweenPauseMode mode ) SceneTreeTween when the SceneTree is paused. Check TweenPauseMode for options. TWEEN_PAUSE_BOUND.

• SceneTreeTween set_process_mode ( TweenProcessMode mode ) SceneTreeTween should run during idle frame (see Node._process) or physics frame (see Node._physics_process. Tween.TWEEN_PROCESS_IDLE.

• SceneTreeTween set_speed_scale ( float speed ) Tweeners and their delays.

• SceneTreeTween set_trans ( TransitionType trans ) PropertyTweeners and MethodTweeners animated by this SceneTreeTween.

• stop ( ) SceneTreeTween to its initial state. This will not remove any appended Tweeners.

• CallbackTweener tween_callback ( Object object, String method, Array binds=[ ] ) CallbackTweener. This method can be used to call an arbitrary method in any object. Use binds to bind additional arguments for the call. Example: object that keeps shooting every 1 second.

  var tween = get_tree().create_tween().set_loops()tween.tween_callback(self, "shoot").set_delay(1)

  Example: turning a sprite red and then blue, with 2 second delay.

  var tween = get_tree().create_tween()tween.tween_callback($Sprite, "set_modulate", [Color.red]).set_delay(2)tween.tween_callback($Sprite, "set_modulate", [Color.blue]).set_delay(2)

• IntervalTweener tween_interval ( float time ) 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 SceneTreeTween acts as a timer). time is the length of the interval, in seconds. Example: creating an interval in code execution.

  # ... some codeyield(create_tween().tween_interval(2), "finished")# ... more code

  Example: creating an object that moves back and forth and jumps every few seconds.

  var tween = create_tween().set_loops()tween.tween_property($Sprite, "position:x", 200.0, 1).as_relative()tween.tween_callback(self, "jump")tween.tween_interval(2)tween.tween_property($Sprite, "position:x", -200.0, 1).as_relative()tween.tween_callback(self, "jump")tween.tween_interval(2)

• MethodTweener tween_method ( Object object, String method, Variant from, Variant to, float duration, Array binds=[ ] ) MethodTweener. This method is similar to a combination of tween_callback and tween_property. 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 binds to bind additional arguments for the call. You can use MethodTweener.set_ease and MethodTweener.set_trans to tweak the easing and transition of the value or MethodTweener.set_delay to delay the tweening. Example: making a 3D object look from one point to another point.

  var tween = create_tween()tween.tween_method(self, "look_at", Vector3(-1, 0, -1), Vector3(1, 0, -1), 1, [Vector3.UP]) # The look_at() method takes up vector as second argument.

  Label, using an intermediate method and after a delay.

  func _ready():    var tween = create_tween()    tween.tween_method(self, "set_label_text", 0, 10, 1).set_delay(1)func set_label_text(value: int):    $Label.text = "Counting " + str(value)

• PropertyTweener tween_property ( Object object, NodePath property, Variant final_val, float duration ) PropertyTweener. This method tweens a property of an object between an initial value and final_val 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. For example:

  var tween = create_tween()tween.tween_property($Sprite, "position", Vector2(100, 200), 1)tween.tween_property($Sprite, "position", Vector2(200, 300), 1)

  PropertyTweener.from or PropertyTweener.from_current, the starting position will be overwritten by the given value instead. See other methods in PropertyTweener to see how the tweening can be tweaked further. Note: You can find the correct property name by hovering over the property in the Inspector. You can also provide the components of a property directly by using "property:component" (eg. position:x), where it would only apply to that particular component. Example: moving object twice from the same position, with different transition types.

  var tween = create_tween()tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1).as_relative().set_trans(Tween.TRANS_SINE)tween.tween_property($Sprite, "position", Vector2.RIGHT * 300, 1).as_relative().from_current().set_trans(Tween.TRANS_EXPO)