mirror of
https://github.com/godotengine/godot.git
synced 2024-12-09 10:09:20 +08:00
374 lines
22 KiB
XML
374 lines
22 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="Tween" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
|
|
<brief_description>
|
|
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.
|
|
[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. They can't be used for tweening values, but you can do manual interpolation with [method interpolate_value].
|
|
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:
|
|
[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:
|
|
[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:
|
|
[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:
|
|
[codeblock]
|
|
var tween = create_tween()
|
|
for sprite in get_children():
|
|
tween.tween_property(sprite, "position", Vector2(), 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.
|
|
[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.
|
|
</description>
|
|
<tutorials>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="bind_node">
|
|
<return type="Tween" />
|
|
<argument index="0" name="node" type="Node" />
|
|
<description>
|
|
Binds this [Tween] with the given [code]node[/code]. [Tween]s 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 [constant TWEEN_PAUSE_BOUND] will make the pausing behavior dependent on the bound node.
|
|
For a shorter way to create and bind a [Tween], you can use [method Node.create_tween].
|
|
</description>
|
|
</method>
|
|
<method name="chain">
|
|
<return type="Tween" />
|
|
<description>
|
|
Used to chain two [Tweener]s after [method set_parallel] is called with [code]true[/code].
|
|
[codeblock]
|
|
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]
|
|
</description>
|
|
</method>
|
|
<method name="custom_step">
|
|
<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.
|
|
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.
|
|
</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].
|
|
[b]Note:[/code] 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>
|
|
<method name="interpolate_value">
|
|
<return type="Variant" />
|
|
<argument index="0" name="initial_value" type="Variant" />
|
|
<argument index="1" name="delta_value" type="Variant" />
|
|
<argument index="2" name="elapsed_time" type="float" />
|
|
<argument index="3" name="duration" type="float" />
|
|
<argument index="4" name="trans_type" type="int" enum="Tween.TransitionType" />
|
|
<argument index="5" name="ease_type" type="int" enum="Tween.EaseType" />
|
|
<description>
|
|
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 [method @GlobalScope.lerp], but with support for custom transition and easing.
|
|
[code]initial_value[/code] is the starting value of the interpolation.
|
|
[code]delta_value[/code] is the change of the value in the interpolation, i.e. it's equal to [code]final_value - initial_value[/code].
|
|
[code]elapsed_time[/code] 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 [code]duration[/code], the interpolated value will be halfway between initial and final values. This value can also be greater than [code]duration[/code] or lower than 0, which will extrapolate the value.
|
|
[code]duration[/code] is the total time of the interpolation.
|
|
[b]Note:[/b] If [code]duration[/code] is equal to [code]0[/code], the method will always return the final value, regardless of [code]elapsed_time[/code] provided.
|
|
</description>
|
|
</method>
|
|
<method name="is_running">
|
|
<return type="bool" />
|
|
<description>
|
|
Returns whether the [Tween] is currently running, i.e. it wasn't paused and it's not finished.
|
|
</description>
|
|
</method>
|
|
<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. You can however still use [method interpolate_value].
|
|
</description>
|
|
</method>
|
|
<method name="kill">
|
|
<return type="void" />
|
|
<description>
|
|
Aborts all tweening operations and invalidates the [Tween].
|
|
</description>
|
|
</method>
|
|
<method name="parallel">
|
|
<return type="Tween" />
|
|
<description>
|
|
Makes the next [Tweener] run parallelly to the previous one. Example:
|
|
[codeblock]
|
|
var tween = create_tween()
|
|
tween.tween_property(...)
|
|
tween.parallel().tween_property(...)
|
|
tween.parallel().tween_property(...)
|
|
[/codeblock]
|
|
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>
|
|
</method>
|
|
<method name="pause">
|
|
<return type="void" />
|
|
<description>
|
|
Pauses the tweening. The animation can be resumed by using [method play].
|
|
</description>
|
|
</method>
|
|
<method name="play">
|
|
<return type="void" />
|
|
<description>
|
|
Resumes a paused or stopped [Tween].
|
|
</description>
|
|
</method>
|
|
<method name="set_ease">
|
|
<return type="Tween" />
|
|
<argument index="0" name="ease" type="int" enum="Tween.EaseType" />
|
|
<description>
|
|
Sets the default ease type for [PropertyTweener]s and [MethodTweener]s animated by this [Tween].
|
|
</description>
|
|
</method>
|
|
<method name="set_loops">
|
|
<return type="Tween" />
|
|
<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].
|
|
</description>
|
|
</method>
|
|
<method name="set_parallel">
|
|
<return type="Tween" />
|
|
<argument index="0" name="parallel" type="bool" default="true" />
|
|
<description>
|
|
If [code]parallel[/code] is [code]true[/code], the [Tweener]s appended after this method will by default run simultaneously, as opposed to sequentially.
|
|
</description>
|
|
</method>
|
|
<method name="set_pause_mode">
|
|
<return type="Tween" />
|
|
<argument index="0" name="mode" type="int" enum="Tween.TweenPauseMode" />
|
|
<description>
|
|
Determines the behavior of the [Tween] when the [SceneTree] is paused. Check [enum TweenPauseMode] for options.
|
|
Default value is [constant TWEEN_PAUSE_BOUND].
|
|
</description>
|
|
</method>
|
|
<method name="set_process_mode">
|
|
<return type="Tween" />
|
|
<argument index="0" name="mode" type="int" enum="Tween.TweenProcessMode" />
|
|
<description>
|
|
Determines whether the [Tween] should run during idle frame (see [method Node._process]) or physics frame (see [method Node._physics_process].
|
|
Default value is [constant TWEEN_PROCESS_IDLE].
|
|
</description>
|
|
</method>
|
|
<method name="set_speed_scale">
|
|
<return type="Tween" />
|
|
<argument index="0" name="speed" type="float" />
|
|
<description>
|
|
Scales the speed of tweening. This affects all [Tweener]s and their delays.
|
|
</description>
|
|
</method>
|
|
<method name="set_trans">
|
|
<return type="Tween" />
|
|
<argument index="0" name="trans" type="int" enum="Tween.TransitionType" />
|
|
<description>
|
|
Sets the default transition type for [PropertyTweener]s and [MethodTweener]s animated by this [Tween].
|
|
</description>
|
|
</method>
|
|
<method name="stop">
|
|
<return type="void" />
|
|
<description>
|
|
Stops the tweening and resets the [Tween] to its initial state. This will not remove any appended [Tweener]s.
|
|
</description>
|
|
</method>
|
|
<method name="tween_callback">
|
|
<return type="CallbackTweener" />
|
|
<argument index="0" name="callback" type="Callable" />
|
|
<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]
|
|
var tween = get_tree().create_tween().set_loops()
|
|
tween.tween_callback(shoot).set_delay(1)
|
|
[/codeblock]
|
|
Example: turning a sprite red and then blue, with 2 second delay.
|
|
[codeblock]
|
|
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]
|
|
</description>
|
|
</method>
|
|
<method name="tween_interval">
|
|
<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.
|
|
Example: creating an interval in code execution.
|
|
[codeblock]
|
|
# ... some code
|
|
await create_tween().tween_interval(2).finished
|
|
# ... more code
|
|
[/codeblock]
|
|
Example: creating an object that moves back and forth and jumps every few seconds.
|
|
[codeblock]
|
|
var tween = create_tween().set_loops()
|
|
tween.tween_property("position:x", 200, 1).as_relative()
|
|
tween.tween_callback(jump)
|
|
tween.tween_interval(2)
|
|
tween.tween_property("position:x", -200, 1).as_relative()
|
|
tween.tween_callback(jump)
|
|
tween.tween_interval(2)
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="tween_method">
|
|
<return type="MethodTweener" />
|
|
<argument index="0" name="method" type="Callable" />
|
|
<argument index="1" name="from" type="Variant" />
|
|
<argument index="2" name="to" type="Variant" />
|
|
<argument index="3" name="duration" type="float" />
|
|
<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 [code]from[/code] and [code]to[/code] over the time specified by [code]duration[/code], 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]
|
|
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]
|
|
Example: setting a text of a [Label], using an intermediate method and after a delay.
|
|
[codeblock]
|
|
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]
|
|
</description>
|
|
</method>
|
|
<method name="tween_property">
|
|
<return type="PropertyTweener" />
|
|
<argument index="0" name="object" type="Object" />
|
|
<argument index="1" name="property" type="NodePath" />
|
|
<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:
|
|
[codeblock]
|
|
var tween = create_tween()
|
|
tween.tween_property($Sprite, "position", Vector2(100, 200)
|
|
tween.tween_property($Sprite, "position", Vector2(200, 300)
|
|
[/codeblock]
|
|
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]
|
|
var tween = create_tween()
|
|
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300).as_relative().set_trans(Tween.TRANS_SINE)
|
|
tween.tween_property($Sprite, "position", Vector2.RIGHT * 300).as_relative().from_current().set_trans(Tween.TRANS_EXPO)
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<signals>
|
|
<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].
|
|
</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.
|
|
</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.
|
|
</description>
|
|
</signal>
|
|
</signals>
|
|
<constants>
|
|
<constant name="TWEEN_PROCESS_PHYSICS" value="0" enum="TweenProcessMode">
|
|
The [Tween] updates during the physics frame.
|
|
</constant>
|
|
<constant name="TWEEN_PROCESS_IDLE" value="1" enum="TweenProcessMode">
|
|
The [Tween] updates during the idle frame.
|
|
</constant>
|
|
<constant name="TWEEN_PAUSE_BOUND" value="0" enum="TweenPauseMode">
|
|
If the [Tween] has a bound node, it will process when that node can process (see [member Node.process_mode]). Otherwise it's the same as [constant TWEEN_PAUSE_STOP].
|
|
</constant>
|
|
<constant name="TWEEN_PAUSE_STOP" value="1" enum="TweenPauseMode">
|
|
If [SceneTree] is paused, the [Tween] will also pause.
|
|
</constant>
|
|
<constant name="TWEEN_PAUSE_PROCESS" value="2" enum="TweenPauseMode">
|
|
The [Tween] will process regardless of whether [SceneTree] is paused.
|
|
</constant>
|
|
<constant name="TRANS_LINEAR" value="0" enum="TransitionType">
|
|
The animation is interpolated linearly.
|
|
</constant>
|
|
<constant name="TRANS_SINE" value="1" enum="TransitionType">
|
|
The animation is interpolated using a sine function.
|
|
</constant>
|
|
<constant name="TRANS_QUINT" value="2" enum="TransitionType">
|
|
The animation is interpolated with a quintic (to the power of 5) function.
|
|
</constant>
|
|
<constant name="TRANS_QUART" value="3" enum="TransitionType">
|
|
The animation is interpolated with a quartic (to the power of 4) function.
|
|
</constant>
|
|
<constant name="TRANS_QUAD" value="4" enum="TransitionType">
|
|
The animation is interpolated with a quadratic (to the power of 2) function.
|
|
</constant>
|
|
<constant name="TRANS_EXPO" value="5" enum="TransitionType">
|
|
The animation is interpolated with an exponential (to the power of x) function.
|
|
</constant>
|
|
<constant name="TRANS_ELASTIC" value="6" enum="TransitionType">
|
|
The animation is interpolated with elasticity, wiggling around the edges.
|
|
</constant>
|
|
<constant name="TRANS_CUBIC" value="7" enum="TransitionType">
|
|
The animation is interpolated with a cubic (to the power of 3) function.
|
|
</constant>
|
|
<constant name="TRANS_CIRC" value="8" enum="TransitionType">
|
|
The animation is interpolated with a function using square roots.
|
|
</constant>
|
|
<constant name="TRANS_BOUNCE" value="9" enum="TransitionType">
|
|
The animation is interpolated by bouncing at the end.
|
|
</constant>
|
|
<constant name="TRANS_BACK" value="10" enum="TransitionType">
|
|
The animation is interpolated backing out at ends.
|
|
</constant>
|
|
<constant name="EASE_IN" value="0" enum="EaseType">
|
|
The interpolation starts slowly and speeds up towards the end.
|
|
</constant>
|
|
<constant name="EASE_OUT" value="1" enum="EaseType">
|
|
The interpolation starts quickly and slows down towards the end.
|
|
</constant>
|
|
<constant name="EASE_IN_OUT" value="2" enum="EaseType">
|
|
A combination of [constant EASE_IN] and [constant EASE_OUT]. The interpolation is slowest at both ends.
|
|
</constant>
|
|
<constant name="EASE_OUT_IN" value="3" enum="EaseType">
|
|
A combination of [constant EASE_IN] and [constant EASE_OUT]. The interpolation is fastest at both ends.
|
|
</constant>
|
|
</constants>
|
|
</class>
|