GTweens-Godot

Use GTweenSequenceBuilder to chain multiple animations, delays, and callbacks together.

• .Append(): Adds a tween that starts after the previous one finishes.
• .Join(): Adds a tween that runs concurrently with the previous one.
• .AppendTime(float): Adds a delay in the sequence.
• .JoinCallback(Action) / .AppendCallback(Action): Executes a callback at a specific point in the timeline.

public partial class PlayTweenSequenceExample : Node
{
    [Export] public Node2D Target;
    
    public override void _Ready()
    {
        GTween tween = GTweenSequenceBuilder.New()
            .Append(Target.TweenPositionX(100f, 0.5f))
                .Join(Target.TweenScale(new Vector2(2f, 2f), 1f))
            .AppendTime(0.5f)
                .JoinCallback(() => GD.Print("I'm waiting some time!"))
            .Append(Target.TweenPositionX(0f, 1f))
                .AppendCallback(() => GD.Print("I'm finished!"))
            .Build();

        tween.SetEasing(Easing.InOutCubic);
        tween.Play();
    }
}

Once a tween is created, you can control its playback and lifecycle using the following methods:

Playback:

• Play(): Runs the tween on _Process. Pauses if the Godot tree is paused.
• PlayConfigured(...): Plays with custom configuration (process mode, pause behavior, or instantly to skip to the end).
• PlayAsync(...): Returns a Task that completes when the tween is killed or finished. Supports CancellationToken.
• PlayConfiguredAsync(...): Returns a Task with custom configuration and CancellationToken support.

Lifecycle & State:

• Kill(): Stops the tween immediately at its current state.
• Complete(): Instantly jumps to the final state and stops.
• Reset(): Returns to the initial state and stops.
• AwaitCompleteOrKill(): Returns a Task that waits for the tween to finish or be killed.

Configuration:

• SetLoops(int): Sets the number of loops.
• SetEasing(Easing): Sets the easing curve (applies to all child tweens if it is a sequence).
• SetTimeScale(float): Sets the playback speed (default is 1).

Generic tweening is the most flexible method, allowing you to animate almost any property by providing a getter and a setter delegate.

• Use GTweenExtensions.Tween for standard C# types (int, float, etc.).
• Use GTweenGodotExtensions.Tween for Godot-specific types (Vector2, Vector3, etc.).

Parameters:

• Getter: A delegate () => value that returns the current property value.
• Setter: A delegate x => value = x that sets the property value.
• To: The target end value.
• Duration: The time in seconds.
• Validation (optional): A delegate () => bool that checks every update if the tween should continue running.

// For default C# values
GTween tween = GTweenExtensions.Tween(
    () => Target.SomeFloat, // Getter
    x => Target.SomeFloat = x, // Setter
    100f, // To
    1 // Duration
);

// For Godot specific values
GTween tween = GTweenGodotExtensions.Tween(
    () => Target.Position, // Getter
    x => Target.Position = x, // Setter
    new Vector2(100f, 100f), // To
    1 // Duration
);

Sequences allow you to group multiple tweens and animate them as a single unit. You can nest sequences within other sequences indefinitely. Use the GTweenSequenceBuilder to construct them.

Builder Methods:

• GTweenSequenceBuilder.New(): Starts a new sequence.
• Append(tween): Adds a tween to the end of the sequence (plays after previous tweens finish).
• Join(tween): Adds a tween to play simultaneously with the last added tween.
• AppendTime(seconds): Adds a delay to the sequence.
• AppendCallback(action): Adds a callback to execute at that point in the sequence.
• AppendSequence(action): Nests a new sequence using a builder provided via an action.
• Build(): Finalizes and returns the GTween sequence object.

 GTween tween = GTweenSequenceBuilder.New()
    .Append(Target.TweenPositionX(100, 0.5f))
        .Join(Target.TweenScale(new Vector2(2, 2), 1))
    .Append(Target.TweenPositionY(100, 1))
    .AppendTime(0.5f)
    .Append(Target.TweenPositionX(0, 1))
    .AppendSequence(s => s
        .AppendTime(0.5f)
        .Append(Target.TweenPositionX(1, 1))
        )
    .AppendCallback(() => GD.Print("I'm finished!"))
    .Build();
        
tween.SetEasing(Easing.InOutCubic);
tween.Play();