jimjastajay / gtweensgodot Goto Github PK

GTweens-Godot is a lightweight and versatile tweening library for Godot 4 with C#. This library simplifies the process of creating animations and transitions in your Godot projects, allowing you to bring your game elements to life with ease.

Unlike the default Godot tweening engine, which relies on nodes and their properties to create animations, this tweening engine doesn't require the use of nodes.

An extension that builds upon the GTweens library.

• Simple API: GTweens-Godot provides an intuitive and easy-to-use API with C# extension methods.

  public partial class TweenExample : Node
  {
      [Export] public Node2D Target;
  	
      public override void _Ready()
      {
          Target.TweenPosition(new Vector2(100, 0), 3)
              .SetEasing(Easing.InOutCubic)
              .Play();
      }
  }

• Sequencing: Easily chain multiple tweens together to create complex sequences of animations.

  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();
      }
  }

• Versatile Easing Functions: Choose from a variety of easing functions to achieve different animation effects, including linear, ease-in, ease-out, and custom curves.

  public partial class EasingExample : Node
  {
      [Export] public Node2D Target1;
      [Export] public Node2D Target2;
  
      [Export] public Easing Easing1;
      [Export] public Curve Easing2;
  	
      public override void _Ready()
      {
          GTween tween1 = Target1.TweenPositionX(100, 3);
          tween1.SetEasing(Easing1);
          tween1.Play();
          
          GTween tween2 = Target2.TweenPositionX(100, 3);
          tween2.SetEasing(Easing2);
          tween2.Play();
      }
  }

• Looping: Create looping animations with a single line of code, and control loop count and behavior.

  public partial class LoopingTweenExample : Node
  {
      [Export] public Node2D Target;
      [Export] public int Loops;
  	
      public override void _Ready()
      {
           GTween tween = Target.TweenPositionX(150, 1);
           tween.SetLoops(Loops);
           tween.Play();
      }
  }

• Delays: Specify delays, allowing precise timing of your animations.

  GTween tween = GTweenSequenceBuilder.New()
      .AppendTime(0.5f)
      .Build();

• Callbacks: Attach callbacks to tweens for event handling at various points in the animation timeline.

  void Callback()
  {
  }
  
  GTween tween = GTweenSequenceBuilder.New()
      .AppendCallback(Callback)
      .Build();

• Safety: When a node that's being tweened becomes invalid or gets destroyed, the tween is automatically destroyed, so you don't have to worry about object lifetime.

1. Install the GTweensGodot NuGet package in your godot project.
2. Create a new node script, anywhere in your project, that's going to update all the tweens. Copy and paste the code from here:

   public partial class GTweensGodotUpdater : Node
   {
       public override void _Process(double delta)
       {
           GodotGTweensContextNode.Context.Tick((float)delta);
       }
   }

3. On the Godot editor, go to Project/Project Settings/Autoload, and select the GTweensGodotUpdater.cs we just created, to be autoloaded.

To quickly check if everything has been setup properly, you can create a new script with this code, and assign any Node2D to the Target export, and play it.

public partial class TweenExample : Node
{
    [Export] public Node2D Target;
		
    public override void _Ready()
    {
        Target.TweenPosition(new Vector2(100, 0), 3)
            .SetEasing(Easing.InOutCubic)
            .Play();
    }
}

1. Download the latest GTweensGodot.zip release.
2. Unpack the GTweensGodot.zip folder into the Godot's project root folder.
3. On the Godot editor, go to Project/Project Settings/Autoload, and select GTweensGodot/Godot/Source/Contexts/GodotGTweensContextNode.cs to be autoloaded.

To quickly check if everything has been setup properly, you can go to GTweensGodot/Godot/Examples/Scenes/ and open any of the example scenes. When you run any of those scenes, a simple functionality example should play.

• If the example scenes cannot be opened, it probably means that the contents of GTweensGodot.zip were not placed on the root of your project, or that the extracted folder has been renamed. Make sure you don't change the path nor rename any folder, since this will break scene references.
• If after playing an example scene, nothing moves or gets animated, this means that the GodotGTweensContextNode.cs has not been autoloaded. Make sure to properly follow the second installation step.

• Tween: a generic word that indicates some or multiple values being animated.
• Sequence: an combination of tweens that get animated as a group.

Prefixes are important to use the most out of IntelliSense, so try to remember these:

• Tween: prefix for all tween shortcuts (operations that can be started directly from a known object, like a Node2D or a Control).

  node2D.TweenPositionX(100f, 1f);
  control.TweenSizeY(200f, 2f);

• Set: prefix for all settings that can be chained to a tween.

  myTween.SetLoops(4).SetEasing(Easing.InOutCubic);

• On: prefix for all callbacks that can be chained to a tween.

  myTween.OnStart(myStartFunction).OnComplete(myCompleteFunction);

This is the most flexible way of tweening and allows you to tween almost any value.

// For default C# values (int, float, etc)
GTweenExtensions.Tween(getter, setter, to, duration)

// For Godot specific values (Vector2, Vector3, etc)
GTweenGodotExtensions.Tween(getter, setter, to, duration)

• Getter: a delegate that returns the value of the property to tween. Can be written as a lambda like this: () => myValue where myValue is the name of the property to tween.
• Setter: a delegate that sets the value of the property to tween. Can be written as a lambda like this: x => myValue = x where myValue is the name of the property to tween.
• To: the end value to reach.
• Duration: the duration of the tween in seconds.
• Validation (optional): a delegate that every time the tween updates, checks if it should be running. Can be written as a lambda like this: () => shouldKeepRunning where shouldKeepRunning is a boolean.

// 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
);

GTweem includes shortcuts for some known C# and Godot objects, like Node2D, Node3D, Control, etc. You can start a tween directly from a reference to these objects, like:

node2D.TweenPositionX(100f, 1f);
node3D.TweenScale(new Vector3(2f, 2f, 2f), 1f);
control.TweenSizeY(200f, 2f);

See all shortcuts you can use.

Sequences are a combination of tweens that get animated as a group. Sequences can be contained inside other sequences without any limit to the depth of the hierarchy. To create sequences, you need to use the helper GTweenSequenceBuilder.

• First you call to start creating a new sequence New().
• Next you Append() or Join() any tweens to the sequence.
  • Append: Adds the given tween to the end of the Sequence. This tween will play after all the previous tweens have finished.
  • Join: Inserts the given tween at the same time position of the last tween added to the Sequence. This tween will play at the same time as the previous tween.
• Finally you call Build() to get the generated sequence Tween.

 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();

As it can be seen on the example, you can Append/Join different things with the builder:

• Append/Join Callback: adds a callback that will be called when this part of the sequence is executed.
• Append/Join Time: adds a time delay (in seconds) to the sequence.
• Append/Join Sequence: creates a new GTweenSequenceBuilder and provides it through the action. Then it automatically builds it and adds the resulting tween to the sequence.

Example of a complex sequence:

• Play: plays the tween.
• Kill: kills the tween. This means that the tween will instantly stop playing, leaving it at its current state.
• Complete: instantly reaches the final state of the tween, and stops playing.
• Reset: sets the tween to its initial state, and stops playing.
• SetLoops: sets the amount of times the tween should loop.
• SetEasing: sets the easing used by the tween. If the tween is a sequence, the easing will be applied to all child tweens. Set to linear by default.
• SetTimeScale: sets the time scale that will be used to tick the tween. Set to 1 by default.

• PlayAsync: plays the tween and returns a Task that waits until the tween is killed or completed. If the parameter CancellationToken is cancelled, the tween will be killed.
• AwaitCompleteOrKill: returns a Task that waits until the tween is killed or completed.

These are the currently avaliable shortcuts for Godot nodes (the list grows with time).

• Node2D: GlobalPosition, Position, GlobalRotation, Rotation, GlobalRotationDegrees, RotationDegrees, GlobalScale, Scale, GlobalSkew, Skew.
• Node3D: GlobalPosition, Position, GlobalRotation, Rotation, GlobalRotationDegrees, RotationDegrees, GlobalScale, Scale.
• Control: GlobalPosition, Position, Rotation, RotationDegrees, Scale, Size, PivotOffset.
• Sprite2D: Offset.
• SpriteBase3D: Modulate, Offset.
• Light2D: Color, Energy, ShadowColor.
• Light3D: LightColor, LightEnergy, LightIndirectEnergy, LightVolumetricFogEnergy, LightAngularDistance, ShadowBias, ShadowNormalBias, ShadowTransmittanceBias, ShadowOpacity, ShadowBlur.
• Camera2D: Offset, Zoom.
• Camera3D: HOffset, VOffset, Fov.
• AudioStreamPlayer2D: VolumeDb, PitchScale.
• AudioStreamPlayer3D: VolumeDb, PitchScale, AttenuationFilterDb, AttenuationFilterCutoffHz.
• CanvasModulate: Color.
• CanvasItem: Modulate, SelfModulate.
• ShaderMaterial: PropertyInt, PropertyFloat, PropertyVector2, PropertyVector2I, PropertyColor.
• BaseMaterial3D: AlbedoColor, Metallic, MetallicSpecular, Roughness.