summaryrefslogtreecommitdiff
path: root/doc/classes/Tween.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/classes/Tween.xml')
-rw-r--r--doc/classes/Tween.xml187
1 files changed, 157 insertions, 30 deletions
diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml
index 5186972477..acf900ae55 100644
--- a/doc/classes/Tween.xml
+++ b/doc/classes/Tween.xml
@@ -8,42 +8,85 @@
[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 [method SceneTree.create_tween] or [method Node.create_tween]. [Tween]s created manually (i.e. by using [code]Tween.new()[/code]) are invalid and can't be used for tweening values.
A tween animation is created by adding [Tweener]s to the [Tween] object, using [method tween_property], [method tween_interval], [method tween_callback] or [method tween_method]:
- [codeblock]
+ [codeblocks]
+ [gdscript]
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)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = GetTree().CreateTween();
+ tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
+ tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f);
+ tween.TweenCallback(new Callable(GetNode("Sprite").QueueFree));
+ [/csharp]
+ [/codeblocks]
This sequence will make the [code]$Sprite[/code] node turn red, then shrink, before finally calling [method Node.queue_free] to free the sprite. [Tweener]s are executed one after another by default. This behavior can be changed using [method parallel] and [method set_parallel].
When a [Tweener] is created with one of the [code]tween_*[/code] 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 [method set_trans]:
- [codeblock]
+ [codeblocks]
+ [gdscript]
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)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = GetTree().CreateTween();
+ tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f).SetTrans(Tween.TransitionType.Sine);
+ tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f).SetTrans(Tween.TransitionType.Bounce);
+ tween.TweenCallback(new Callable(GetNode("Sprite").QueueFree));
+ [/csharp]
+ [/codeblocks]
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 [Tweener]s:
- [codeblock]
+ [codeblocks]
+ [gdscript]
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)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ var tween = GetTree().CreateTween().BindNode(this).SetTrans(Tween.TransitionType.Elastic);
+ tween.TweenProperty(GetNode("Sprite"), "modulate", Colors.Red, 1.0f);
+ tween.TweenProperty(GetNode("Sprite"), "scale", Vector2.Zero, 1.0f);
+ tween.TweenCallback(new Callable(GetNode("Sprite").QueueFree));
+ [/csharp]
+ [/codeblocks]
Another interesting use for [Tween]s is animating arbitrary sets of objects:
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = create_tween()
for sprite in get_children():
tween.tween_property(sprite, "position", Vector2(0, 0), 1)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween();
+ foreach (Node sprite in GetChildren())
+ tween.TweenProperty(sprite, "position", Vector2.Zero, 1.0f);
+ [/csharp]
+ [/codeblocks]
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:
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween
func animate():
if tween:
tween.kill() # Abort the previous animation.
tween = create_tween()
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ private Tween tween;
+
+ public void Animate()
+ {
+ if (tween != null)
+ tween.Kill(); // Abort the previous animation
+ tween = CreateTween();
+ }
+ [/csharp]
+ [/codeblocks]
Some [Tweener]s use transitions and eases. The first accepts a [enum TransitionType] constant, and refers to the way the timing of the animation is handled (see [url=https://easings.net/]easings.net[/url] for some examples). The second accepts an [enum EaseType] constant, and controls where the [code]trans_type[/code] 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 [enum TransitionType] constants with [constant EASE_IN_OUT], and use the one that looks best.
[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/tween_cheatsheet.png]Tween easing and transition types cheatsheet[/url]
[b]Note:[/b] All [Tween]s will automatically start by default. To prevent a [Tween] from autostarting, you can call [method stop] immediately after it is created.
@@ -64,12 +107,20 @@
<return type="Tween" />
<description>
Used to chain two [Tweener]s after [method set_parallel] is called with [code]true[/code].
- [codeblock]
+ [codeblocks]
+ [gdscript]
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.
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween().SetParallel(true);
+ tween.TweenProperty(...);
+ tween.TweenProperty(...); // Will run parallelly with above.
+ tween.Chain().TweenProperty(...); // Will run after two above are finished.
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="custom_step">
@@ -127,12 +178,20 @@
<return type="Tween" />
<description>
Makes the next [Tweener] run parallelly to the previous one. Example:
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = create_tween()
tween.tween_property(...)
tween.parallel().tween_property(...)
tween.parallel().tween_property(...)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween();
+ tween.TweenProperty(...);
+ tween.Parallel().TweenProperty(...);
+ tween.Parallel().TweenProperty(...);
+ [/csharp]
+ [/codeblocks]
All [Tweener]s in the example will run at the same time.
You can make the [Tween] parallel by default by using [method set_parallel].
</description>
@@ -214,16 +273,30 @@
<description>
Creates and appends a [CallbackTweener]. This method can be used to call an arbitrary method in any object. Use [method Callable.bind] to bind additional arguments for the call.
Example: object that keeps shooting every 1 second.
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = get_tree().create_tween().set_loops()
tween.tween_callback(shoot).set_delay(1)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = GetTree().CreateTween().SetLoops();
+ tween.TweenCallback(new Callable(Shoot)).SetDelay(1.0f);
+ [/csharp]
+ [/codeblocks]
Example: turning a sprite red and then blue, with 2 second delay.
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = get_tree().create_tween()
tween.tween_callback($Sprite.set_modulate.bind(Color.red)).set_delay(2)
tween.tween_callback($Sprite.set_modulate.bind(Color.blue)).set_delay(2)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = GetTree().CreateTween();
+ Sprite2D sprite = GetNode&lt;Sprite2D&gt;("Sprite");
+ tween.TweenCallback(new Callable(() =&gt; sprite.Modulate = Colors.Red)).SetDelay(2.0f);
+ tween.TweenCallback(new Callable(() =&gt; sprite.Modulate = Colors.Blue)).SetDelay(2.0f);
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="tween_interval">
@@ -232,13 +305,21 @@
<description>
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 [Tweener]s, or when there's no animation (in which case the [Tween] acts as a timer). [param time] is the length of the interval, in seconds.
Example: creating an interval in code execution.
- [codeblock]
+ [codeblocks]
+ [gdscript]
# ... some code
await create_tween().tween_interval(2).finished
# ... more code
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ // ... some code
+ await ToSignal(CreateTween().TweenInterval(2.0f), Tween.SignalName.Finished);
+ // ... more code
+ [/csharp]
+ [/codeblocks]
Example: creating an object that moves back and forth and jumps every few seconds.
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = create_tween().set_loops()
tween.tween_property($Sprite, "position:x", 200.0, 1).as_relative()
tween.tween_callback(jump)
@@ -246,7 +327,17 @@
tween.tween_property($Sprite, "position:x", -200.0, 1).as_relative()
tween.tween_callback(jump)
tween.tween_interval(2)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween().SetLoops();
+ tween.TweenProperty(GetNode("Sprite"), "position:x", 200.0f, 1.0f).AsRelative();
+ tween.TweenCallback(new Callable(Jump));
+ tween.TweenInterval(2.0f);
+ tween.TweenProperty(GetNode("Sprite"), "position:x", -200.0f, 1.0f).AsRelative();
+ tween.TweenCallback(new Callable(Jump));
+ tween.TweenInterval(2.0f);
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="tween_method">
@@ -258,19 +349,41 @@
<description>
Creates and appends a [MethodTweener]. This method is similar to a combination of [method tween_callback] and [method tween_property]. It calls a method over time with a tweened value provided as an argument. The value is tweened between [param from] and [param to] over the time specified by [param duration], in seconds. Use [method Callable.bind] to bind additional arguments for the call. You can use [method MethodTweener.set_ease] and [method MethodTweener.set_trans] to tweak the easing and transition of the value or [method MethodTweener.set_delay] to delay the tweening.
Example: making a 3D object look from one point to another point.
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = create_tween()
tween.tween_method(look_at.bind(Vector3.UP), Vector3(-1, 0, -1), Vector3(1, 0, -1), 1) # The look_at() method takes up vector as second argument.
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween();
+ tween.TweenMethod(new Callable(() =&gt; LookAt(Vector3.Up)), new Vector3(-1.0f, 0.0f, -1.0f), new Vector3(1.0f, 0.0f, -1.0f), 1.0f); // The LookAt() method takes up vector as second argument.
+ [/csharp]
+ [/codeblocks]
Example: setting a text of a [Label], using an intermediate method and after a delay.
- [codeblock]
+ [codeblocks]
+ [gdscript]
func _ready():
var tween = create_tween()
tween.tween_method(set_label_text, 0, 10, 1).set_delay(1)
func set_label_text(value: int):
$Label.text = "Counting " + str(value)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ public override void _Ready()
+ {
+ base._Ready();
+
+ Tween tween = CreateTween();
+ tween.TweenMethod(new Callable(SetLabelText), 0.0f, 10.0f, 1.0f).SetDelay(1.0f);
+ }
+
+ private void SetLabelText(int value)
+ {
+ GetNode&lt;Label&gt;("Label").Text = $"Counting {value}";
+ }
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="tween_property">
@@ -281,19 +394,33 @@
<param index="3" name="duration" type="float" />
<description>
Creates and appends a [PropertyTweener]. This method tweens a [param property] of an [param object] between an initial value and [param final_val] in a span of time equal to [param duration], in seconds. The initial value by default is the property's value at the time the tweening of the [PropertyTweener] starts. For example:
- [codeblock]
+ [codeblocks]
+ [gdscript]
var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 200), 1)
tween.tween_property($Sprite, "position", Vector2(200, 300), 1)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween();
+ tween.TweenProperty(GetNode("Sprite"), "position", new Vector2(100.0f, 200.0f), 1.0f);
+ tween.TweenProperty(GetNode("Sprite"), "position", new Vector2(200.0f, 300.0f), 1.0f);
+ [/csharp]
+ [/codeblocks]
will move the sprite to position (100, 200) and then to (200, 300). If you use [method PropertyTweener.from] or [method 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.
[b]Note:[/b] 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 [code]"property:component"[/code] (eg. [code]position:x[/code]), where it would only apply to that particular component.
Example: moving object twice from the same position, with different transition types.
- [codeblock]
+ [codeblocks]
+ [gdscript]
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)
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ Tween tween = CreateTween();
+ tween.TweenProperty(GetNode("Sprite"), "position", Vector2.Right * 300.0f, 1.0f).AsRelative().SetTrans(Tween.TransitionType.Sine);
+ tween.TweenProperty(GetNode("Sprite"), "position", Vector2.Right * 300.0f, 1.0f).AsRelative().FromCurrent().SetTrans(Tween.TransitionType.Expo);
+ [/csharp]
+ [/codeblocks]
</description>
</method>
</methods>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-18 22:42:43 +0000