Fix typos and improve clarity in Tween docs
This commit is contained in:
snailrhymer
Rémi Verschelde
parent
2d28bb8364
commit
aff30b649e
|
|
@ -4,41 +4,41 @@
|
|||
Lightweight object used for general-purpose animation via script, using [Tweener]s.
|
||||
</brief_description>
|
||||
<description>
|
||||
Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name [i]tween[/i] comes from [i]in-betweening[/i], an animation technique where you specify [i]keyframes[/i] and the computer interpolates the frames that appear between them.
|
||||
Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name [i]tween[/i] comes from [i]in-betweening[/i], an animation technique where you specify [i]keyframes[/i] 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 [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 composed of a sequence of [Tweener]s, which by default are executed one after another. You can create a sequence by appending [Tweener]s to the [Tween]. Animating something with a [Tweener] is called tweening. Example tweening sequence looks like this:
|
||||
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]
|
||||
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]
|
||||
This sequence will make the [code]$Sprite[/code] node turn red, then shrink and finally the [method Node.queue_free] is called to remove the sprite. See methods [method tween_property], [method tween_interval], [method tween_callback] and [method tween_method] for more usage information.
|
||||
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 different transition type in the above example, you can do:
|
||||
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]
|
||||
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]
|
||||
Most of the [Tween] methods can be chained this way too. In this example the [Tween] is bound and have set a default transition:
|
||||
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]
|
||||
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]
|
||||
Another interesting use for [Tween]s is animating arbitrary set of objects:
|
||||
Another interesting use for [Tween]s is animating arbitrary sets of objects:
|
||||
[codeblock]
|
||||
var tween = create_tween()
|
||||
for sprite in get_children():
|
||||
tween.tween_property(sprite, "position", Vector2(), 1)
|
||||
tween.tween_property(sprite, "position", Vector2(0, 0), 1)
|
||||
[/codeblock]
|
||||
In the example above, all children of a node are moved one after another to position (0, 0).
|
||||
Some [Tweener]s use transitions and eases. The first accepts an [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.
|
||||
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 was created.
|
||||
[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.
|
||||
</description>
|
||||
<tutorials>
|
||||
</tutorials>
|
||||
|
|
@ -67,15 +67,15 @@
|
|||
<return type="bool" />
|
||||
<argument index="0" name="delta" type="float" />
|
||||
<description>
|
||||
Processes the [Tween] by given [code]delta[/code] value, in seconds. Mostly useful when the [Tween] is paused, for controlling it manually. Can also be used to end the [Tween] animation immediately, by using [code]delta[/code] longer than the whole duration.
|
||||
Processes the [Tween] by the given [code]delta[/code] 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 [code]delta[/code] longer than the whole duration of the [Tween] animation.
|
||||
Returns [code]true[/code] if the [Tween] still has [Tweener]s that haven't finished.
|
||||
[b]Note:[/b] The [Tween] will become invalid after finished, but you can call [method stop] after the step, to keep it and reset.
|
||||
[b]Note:[/b] The [Tween] will become invalid in the next processing frame after its animation finishes. Calling [method stop] after performing [method custom_step] instead keeps and resets the [Tween].
|
||||
</description>
|
||||
</method>
|
||||
<method name="get_total_elapsed_time" qualifiers="const">
|
||||
<return type="float" />
|
||||
<description>
|
||||
Returns the total time in seconds the [Tween] has been animating (i.e. time since it started, not counting pauses etc.). The time is affected by [method set_speed_scale] and [method stop] will reset it to [code]0[/code].
|
||||
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 [method set_speed_scale], and [method stop] will reset it to [code]0[/code].
|
||||
[b]Note:[/b] As it results from accumulating frame deltas, the time returned after the [Tween] has finished animating will be slightly greater than the actual [Tween] duration.
|
||||
</description>
|
||||
</method>
|
||||
|
|
@ -105,7 +105,7 @@
|
|||
<method name="is_valid">
|
||||
<return type="bool" />
|
||||
<description>
|
||||
Returns whether the [Tween] is valid. A valid [Tween] is a [Tween] contained by the scene tree (i.e. the array from [method SceneTree.get_processed_tweens] will contain this [Tween]). [Tween] might become invalid when it has finished tweening or was killed, also when created with [code]Tween.new()[/code]. Invalid [Tween] can't have [Tweener]s appended, because it can't animate them.
|
||||
Returns whether the [Tween] is valid. A valid [Tween] is a [Tween] contained by the scene tree (i.e. the array from [method SceneTree.get_processed_tweens] will contain this [Tween]). A [Tween] might become invalid when it has finished tweening, is killed, or when created with [code]Tween.new()[/code]. Invalid [Tween]s can't have [Tweener]s appended.
|
||||
</description>
|
||||
</method>
|
||||
<method name="kill">
|
||||
|
|
@ -152,8 +152,8 @@
|
|||
<argument index="0" name="loops" type="int" default="0" />
|
||||
<description>
|
||||
Sets the number of times the tweening sequence will be repeated, i.e. [code]set_loops(2)[/code] will run the animation twice.
|
||||
Calling this method without arguments will make the [Tween] run infinitely, until it is either killed by [method kill] or by freeing bound node, or all the animated objects have been freed (which makes further animation impossible).
|
||||
[b]Warning:[/b] Make sure to always add some duration/delay when using infinite loops. 0-duration looped animations (e.g. single [CallbackTweener] with no delay or [PropertyTweener] with invalid node) are equivalent to infinite [code]while[/code] loops and will freeze your game. If a [Tween]'s lifetime depends on some node, always use [method bind_node].
|
||||
Calling this method without arguments will make the [Tween] run infinitely, until either it is killed with [method kill], the [Tween]'s bound node is freed, or all the animated objects have been freed (which makes further animation impossible).
|
||||
[b]Warning:[/b] 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 [Tween]'s lifetime depends on some node, always use [method bind_node].
|
||||
</description>
|
||||
</method>
|
||||
<method name="set_parallel">
|
||||
|
|
@ -221,7 +221,7 @@
|
|||
<return type="IntervalTweener" />
|
||||
<argument index="0" name="time" type="float" />
|
||||
<description>
|
||||
Creates and appends an [IntervalTweener]. This method can be used to create delays in the tween animation, as an alternative for using the delay in other [Tweener]s or when there's no animation (in which case the [Tween] acts as a timer). [code]time[/code] is the length of the interval, in seconds.
|
||||
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). [code]time[/code] is the length of the interval, in seconds.
|
||||
Example: creating an interval in code execution.
|
||||
[codeblock]
|
||||
# ... some code
|
||||
|
|
@ -271,7 +271,7 @@
|
|||
<argument index="2" name="final_val" type="Variant" />
|
||||
<argument index="3" name="duration" type="float" />
|
||||
<description>
|
||||
Creates and appends a [PropertyTweener]. This method tweens a [code]property[/code] of an [code]object[/code] between an initial value and [code]final_val[/code] in a span of time equal to [code]duration[/code], in seconds. The initial value by default is a value at the time the tweening of the [PropertyTweener] start. For example:
|
||||
Creates and appends a [PropertyTweener]. This method tweens a [code]property[/code] of an [code]object[/code] between an initial value and [code]final_val[/code] in a span of time equal to [code]duration[/code], in seconds. The initial value by default is the property's value at the time the tweening of the [PropertyTweener] starts. For example:
|
||||
[codeblock]
|
||||
var tween = create_tween()
|
||||
tween.tween_property($Sprite, "position", Vector2(100, 200), 1)
|
||||
|
|
@ -292,19 +292,19 @@
|
|||
<signal name="finished">
|
||||
<description>
|
||||
Emitted when the [Tween] has finished all tweening. Never emitted when the [Tween] is set to infinite looping (see [method set_loops]).
|
||||
[b]Note:[/b] The [Tween] is removed (invalidated) after this signal is emitted, but it doesn't happen immediately, but on the next processing frame. Calling [method stop] inside the signal callback will preserve the [Tween].
|
||||
[b]Note:[/b] The [Tween] is removed (invalidated) in the next processing frame after this signal is emitted. Calling [method stop] inside the signal callback will prevent the [Tween] from being removed.
|
||||
</description>
|
||||
</signal>
|
||||
<signal name="loop_finished">
|
||||
<argument index="0" name="loop_count" type="int" />
|
||||
<description>
|
||||
Emitted when a full loop is complete (see [method set_loops]), providing the loop index. This signal is not emitted after final loop, use [signal finished] instead for this case.
|
||||
Emitted when a full loop is complete (see [method set_loops]), providing the loop index. This signal is not emitted after the final loop, use [signal finished] instead for this case.
|
||||
</description>
|
||||
</signal>
|
||||
<signal name="step_finished">
|
||||
<argument index="0" name="idx" type="int" />
|
||||
<description>
|
||||
Emitted when one step of the [Tween] is complete, providing the step index. One step is either a single [Tweener] or a group of [Tweener]s running parallelly.
|
||||
Emitted when one step of the [Tween] is complete, providing the step index. One step is either a single [Tweener] or a group of [Tweener]s running in parallel.
|
||||
</description>
|
||||
</signal>
|
||||
</signals>
|
||||
|
|
|
|||
Loading…
Reference in New Issue