mirror of
https://github.com/godotengine/godot.git
synced 2024-12-09 10:09:20 +08:00
b68dd2e189
This makes it easier to spot syntax errors when editing the class reference. The schema is referenced locally so validation can still work offline. Each class XML's schema conformance is also checked on GitHub Actions.
367 lines
22 KiB
XML
367 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="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>
|