Documentation
¶
Overview ¶
Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name tween comes from in-betweening, an animation technique where you specify keyframes 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 SceneTree.CreateTween or Node.CreateTween. Tweens created manually (i.e. by using Tween.new()) are invalid and can't be used for tweening values.
A tween animation is created by adding Tweeners to the Tween object, using TweenProperty, TweenInterval, TweenCallback or TweenMethod:
package main
import (
"graphics.gd/classdb/Node"
"graphics.gd/classdb/PropertyTweener"
"graphics.gd/classdb/SceneTree"
"graphics.gd/classdb/Sprite2D"
"graphics.gd/variant/Color"
"graphics.gd/variant/Vector2"
)
func ExampleTween(node Node.Instance, sprite Sprite2D.Instance) {
var tween = SceneTree.Get(node).CreateTween()
PropertyTweener.Make(tween, sprite.AsObject(), "modulate", Color.W3C.Red, 1)
PropertyTweener.Make(tween, sprite.AsObject(), "scale", Vector2.Zero, 1)
tween.TweenCallback(sprite.AsNode().QueueFree)
}
This sequence will make the $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 SetParallel.
When a 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 SetTrans:
package main
import (
"graphics.gd/classdb/Node"
"graphics.gd/classdb/PropertyTweener"
"graphics.gd/classdb/SceneTree"
"graphics.gd/classdb/Sprite2D"
"graphics.gd/classdb/Tween"
"graphics.gd/variant/Color"
"graphics.gd/variant/Vector2"
)
func ExampleTweenSetTrans(node Node.Instance, sprite Sprite2D.Instance) {
var tween = SceneTree.Get(node).CreateTween()
PropertyTweener.Make(tween, sprite.AsObject(), "modulate", Color.W3C.Red, 1).SetTrans(Tween.TransSine)
PropertyTweener.Make(tween, sprite.AsObject(), "scale", Vector2.Zero, 1).SetTrans(Tween.TransBounce)
tween.TweenCallback(sprite.AsNode().QueueFree)
}
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 Tweeners:
package main
import (
"graphics.gd/classdb/Node"
"graphics.gd/classdb/PropertyTweener"
"graphics.gd/classdb/SceneTree"
"graphics.gd/classdb/Sprite2D"
"graphics.gd/classdb/Tween"
"graphics.gd/variant/Color"
"graphics.gd/variant/Vector2"
)
func ExampleTweenBound(node Node.Instance, sprite Sprite2D.Instance) {
var tween = Tween.Instance(Tween.Advanced(SceneTree.Get(node).CreateTween()).BindNode(node)).SetTrans(Tween.TransElastic)
PropertyTweener.Make(tween, sprite.AsObject(), "modulate", Color.W3C.Red, 1)
PropertyTweener.Make(tween, sprite.AsObject(), "scale", Vector2.Zero, 1)
tween.TweenCallback(sprite.AsNode().QueueFree)
}
Another interesting use for Tweens is animating arbitrary sets of objects:
package main
import (
"graphics.gd/classdb/Node"
"graphics.gd/classdb/PropertyTweener"
"graphics.gd/variant/Vector2"
)
func ExampleTweenObjects(node Node.Instance) {
var tween = node.CreateTween()
for _, sprite := range node.GetChildren() {
PropertyTweener.Make(tween, sprite.AsObject(), "position", Vector2.Zero, 1.0)
}
}
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:
package main
import (
"graphics.gd/classdb/Node"
"graphics.gd/classdb/Tween"
)
var tween Tween.Instance
func Animate(node Node.Instance) {
if tween != Tween.Nil {
tween.Kill()
}
tween = node.CreateTween()
}
Some 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 EaseInOut, and use the one that looks best.
Tween easing and transition types cheatsheet
Note: Tweens are not designed to be reused and trying to do so results in an undefined behavior. Create a new Tween for each animation and every time you replay an animation from start. Keep in mind that Tweens start immediately, so only create a Tween when you want to start animating.
Note: The tween is processed after all of the nodes in the current frame, i.e. node's Node.Process method would be called before the tween (or Node.PhysicsProcess depending on the value passed to SetProcessMode).
Index ¶
- func InterpolateValue(initial_value any, delta_value any, elapsed_time Float.X, duration Float.X, ...) any
- type Advanced
- type Any
- type EaseType
- type Expanded
- type Extension
- type ID
- type Instance
- func (self Instance) AsObject() [1]gd.Object
- func (self Instance) AsRefCounted() [1]gd.RefCounted
- func (self Instance) AsTween() Instance
- func (self Instance) Chain() Instance
- func (self Instance) CustomStep(delta Float.X) bool
- func (self Instance) GetLoopsLeft() int
- func (self Instance) GetTotalElapsedTime() Float.X
- func (self Instance) ID() ID
- func (self Instance) IsRunning() bool
- func (self Instance) IsValid() bool
- func (self Instance) Kill()
- func (self Instance) MoreArgs() MoreArgs
- func (self Instance) OnFinished(cb func(), flags ...Signal.Flags)
- func (self Instance) OnLoopFinished(cb func(loop_count int), flags ...Signal.Flags)
- func (self Instance) OnStepFinished(cb func(idx int), flags ...Signal.Flags)
- func (self Instance) Parallel() Instance
- func (self Instance) Pause()
- func (self Instance) Play()
- func (self Instance) SetEase(ease EaseType) Instance
- func (self Instance) SetIgnoreTimeScale() Instance
- func (self Instance) SetLoops() Instance
- func (self *Instance) SetObject(obj [1]gd.Object) bool
- func (self Instance) SetParallel() Instance
- func (self Instance) SetPauseMode(mode TweenPauseMode) Instance
- func (self Instance) SetProcessMode(mode TweenProcessMode) Instance
- func (self Instance) SetSpeedScale(speed Float.X) Instance
- func (self Instance) SetTrans(trans TransitionType) Instance
- func (self Instance) Stop()
- func (self Instance) TweenCallback(callback func()) CallbackTweener.Instance
- func (self Instance) TweenInterval(time Float.X) IntervalTweener.Instance
- func (self Instance) TweenSubtween(subtween Instance) SubtweenTweener.Instance
- func (self Instance) Virtual(name string) reflect.Value
- type MoreArgs
- type TransitionType
- type TweenPauseMode
- type TweenProcessMode
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InterpolateValue ¶
func InterpolateValue(initial_value any, delta_value any, elapsed_time Float.X, duration Float.X, trans_type TransitionType, ease_type EaseType) any
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 @GlobalScope.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.
Types ¶
type Advanced ¶
type Advanced = class
Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.
type EaseType ¶
type EaseType int //gd:Tween.EaseType
const ( // The interpolation starts slowly and speeds up towards the end. EaseIn EaseType = 0 // The interpolation starts quickly and slows down towards the end. EaseOut EaseType = 1 // A combination of [EaseIn] and [EaseOut]. The interpolation is slowest at both ends. EaseInOut EaseType = 2 // A combination of [EaseIn] and [EaseOut]. The interpolation is fastest at both ends. EaseOutIn EaseType = 3 )
type Extension ¶
Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension
func (*Extension[T]) AsRefCounted ¶
func (self *Extension[T]) AsRefCounted() [1]gd.RefCounted
type ID ¶
ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.
type Instance ¶
Instance of the class with convieniently typed arguments and results.
var Nil Instance
Nil is a nil/null instance of the class. Equivalent to the zero value.
func (Instance) AsRefCounted ¶
func (self Instance) AsRefCounted() [1]gd.RefCounted
func (Instance) Chain ¶
Used to chain two Tweeners after SetParallel is called with true.
func (Instance) CustomStep ¶
Processes the Tween by the given 'delta' 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 'delta' longer than the whole duration of the Tween animation.
Returns true if the Tween still has Tweeners that haven't finished.
func (Instance) GetLoopsLeft ¶
Returns the number of remaining loops for this Tween (see SetLoops). A return value of -1 indicates an infinitely looping Tween, and a return value of 0 indicates that the Tween has already finished.
func (Instance) GetTotalElapsedTime ¶
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 SetSpeedScale, and Stop will reset it to 0.
Note: 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.
func (Instance) IsRunning ¶
Returns whether the Tween is currently running, i.e. it wasn't paused and it's not finished.
func (Instance) IsValid ¶
Returns whether the Tween is valid. A valid Tween is a Tween contained by the scene tree (i.e. the array from SceneTree.GetProcessedTweens will contain this Tween). A Tween might become invalid when it has finished tweening, is killed, or when created with Tween.new(). Invalid Tweens can't have Tweeners appended.
func (Instance) Kill ¶
func (self Instance) Kill()
Aborts all tweening operations and invalidates the Tween.
func (Instance) MoreArgs ¶
MoreArgs enables certain functions to be called with additional 'optional' arguments.
func (Instance) OnFinished ¶
func (Instance) OnLoopFinished ¶
func (Instance) OnStepFinished ¶
func (Instance) Parallel ¶
Makes the next Tweener run parallelly to the previous one.
All Tweeners in the example will run at the same time.
You can make the Tween parallel by default by using SetParallel.
func (Instance) Pause ¶
func (self Instance) Pause()
Pauses the tweening. The animation can be resumed by using Play.
Note: If a Tween is paused and not bound to any node, it will exist indefinitely until manually started or invalidated. If you lose a reference to such Tween, you can retrieve it using SceneTree.GetProcessedTweens.
func (Instance) SetEase ¶
Sets the default ease type for PropertyTweeners and MethodTweeners appended after this method.
Before this method is called, the default ease type is EaseInOut.
func (Instance) SetIgnoreTimeScale ¶
If 'ignore' is true, the tween will ignore Engine.TimeScale and update with the real, elapsed time. This affects all Tweeners and their delays. Default value is false.
func (Instance) SetLoops ¶
Sets the number of times the tweening sequence will be repeated, i.e. set_loops(2) will run the animation twice.
Calling this method without arguments will make the Tween run infinitely, until either it is killed with Kill, the Tween'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 Tween's lifetime depends on some node, always use BindNode.
func (Instance) SetParallel ¶
If 'parallel' is true, the Tweeners appended after this method will by default run simultaneously, as opposed to sequentially.
Note: Just like with Parallel, the tweener added right before this method will also be part of the parallel step.
func (Instance) SetPauseMode ¶
func (self Instance) SetPauseMode(mode TweenPauseMode) Instance
Determines the behavior of the Tween when the SceneTree is paused.
Default value is TweenPauseBound.
func (Instance) SetProcessMode ¶
func (self Instance) SetProcessMode(mode TweenProcessMode) Instance
Determines whether the Tween should run after process frames (see Node.Process) or physics frames (see Node.PhysicsProcess).
Default value is TweenProcessIdle.
func (Instance) SetSpeedScale ¶
Scales the speed of tweening. This affects all Tweeners and their delays.
func (Instance) SetTrans ¶
func (self Instance) SetTrans(trans TransitionType) Instance
Sets the default transition type for PropertyTweeners and MethodTweeners appended after this method.
Before this method is called, the default transition type is TransLinear.
func (Instance) Stop ¶
func (self Instance) Stop()
Stops the tweening and resets the Tween to its initial state. This will not remove any appended Tweeners.
Note: This does not reset targets of PropertyTweeners to their values when the Tween first started.
Note: If a Tween is stopped and not bound to any node, it will exist indefinitely until manually started or invalidated. If you lose a reference to such Tween, you can retrieve it using SceneTree.GetProcessedTweens.
func (Instance) TweenCallback ¶
func (self Instance) TweenCallback(callback func()) CallbackTweener.Instance
Creates and appends a CallbackTweener. This method can be used to call an arbitrary method in any object. Use Callable.Bind to bind additional arguments for the call.
Example: Object that keeps shooting every 1 second:
Example: Turning a sprite red and then blue, with 2 second delay:
func (Instance) TweenInterval ¶
func (self Instance) TweenInterval(time Float.X) IntervalTweener.Instance
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 Tweeners, or when there's no animation (in which case the Tween acts as a timer). 'time' is the length of the interval, in seconds.
Example: Creating an interval in code execution:
Example: Creating an object that moves back and forth and jumps every few seconds:
func (Instance) TweenSubtween ¶
func (self Instance) TweenSubtween(subtween Instance) SubtweenTweener.Instance
Creates and appends a SubtweenTweener. This method can be used to nest 'subtween' within this Tween, allowing for the creation of more complex and composable sequences.
Note: The methods Pause, Stop, and SetLoops can cause the parent Tween to get stuck on the subtween step; see the documentation for those methods for more information.
Note: The pause and process modes set by SetPauseMode and SetProcessMode on 'subtween' will be overridden by the parent Tween's settings.
type MoreArgs ¶
MoreArgs is a container for Instance functions with additional 'optional' arguments.
func (MoreArgs) SetIgnoreTimeScale ¶
If 'ignore' is true, the tween will ignore Engine.TimeScale and update with the real, elapsed time. This affects all Tweeners and their delays. Default value is false.
func (MoreArgs) SetLoops ¶
Sets the number of times the tweening sequence will be repeated, i.e. set_loops(2) will run the animation twice.
Calling this method without arguments will make the Tween run infinitely, until either it is killed with Kill, the Tween'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 Tween's lifetime depends on some node, always use BindNode.
func (MoreArgs) SetParallel ¶
If 'parallel' is true, the Tweeners appended after this method will by default run simultaneously, as opposed to sequentially.
Note: Just like with Parallel, the tweener added right before this method will also be part of the parallel step.
type TransitionType ¶
type TransitionType int //gd:Tween.TransitionType
const ( // The animation is interpolated linearly. TransLinear TransitionType = 0 // The animation is interpolated using a sine function. TransSine TransitionType = 1 // The animation is interpolated with a quintic (to the power of 5) function. TransQuint TransitionType = 2 // The animation is interpolated with a quartic (to the power of 4) function. TransQuart TransitionType = 3 // The animation is interpolated with a quadratic (to the power of 2) function. TransQuad TransitionType = 4 // The animation is interpolated with an exponential (to the power of x) function. TransExpo TransitionType = 5 // The animation is interpolated with elasticity, wiggling around the edges. TransElastic TransitionType = 6 // The animation is interpolated with a cubic (to the power of 3) function. TransCubic TransitionType = 7 // The animation is interpolated with a function using square roots. TransCirc TransitionType = 8 // The animation is interpolated by bouncing at the end. TransBounce TransitionType = 9 // The animation is interpolated backing out at ends. TransBack TransitionType = 10 // The animation is interpolated like a spring towards the end. TransSpring TransitionType = 11 )
type TweenPauseMode ¶
type TweenPauseMode int //gd:Tween.TweenPauseMode
const ( // If the [Tween] has a bound node, it will process when that node can process (see [Node.ProcessMode]). Otherwise it's the same as [TweenPauseStop]. // // [Node.ProcessMode]: https://pkg.go.dev/graphics.gd/classdb/Node#Instance.ProcessMode // [Tween]: https://pkg.go.dev/graphics.gd/classdb/Tween TweenPauseBound TweenPauseMode = 0 // If [SceneTree] is paused, the [Tween] will also pause. // // [SceneTree]: https://pkg.go.dev/graphics.gd/classdb/SceneTree // [Tween]: https://pkg.go.dev/graphics.gd/classdb/Tween TweenPauseStop TweenPauseMode = 1 // The [Tween] will process regardless of whether [SceneTree] is paused. // // [SceneTree]: https://pkg.go.dev/graphics.gd/classdb/SceneTree // [Tween]: https://pkg.go.dev/graphics.gd/classdb/Tween TweenPauseProcess TweenPauseMode = 2 )
type TweenProcessMode ¶
type TweenProcessMode int //gd:Tween.TweenProcessMode
const ( // The [Tween] updates after each physics frame (see [Node.PhysicsProcess]). // // [Node.PhysicsProcess]: https://pkg.go.dev/graphics.gd/classdb/Node#Instance.PhysicsProcess // [Tween]: https://pkg.go.dev/graphics.gd/classdb/Tween TweenProcessPhysics TweenProcessMode = 0 // The [Tween] updates after each process frame (see [Node.Process]). // // [Node.Process]: https://pkg.go.dev/graphics.gd/classdb/Node#Instance.Process // [Tween]: https://pkg.go.dev/graphics.gd/classdb/Tween TweenProcessIdle TweenProcessMode = 1 )
Source Files
