mirror of
https://gitlab.com/MaddoScientisto/cirnogodot.git
synced 2026-07-04 21:31:16 +00:00
Added GTWeen
This commit is contained in:
Marco
parent
457998788e
commit
2036e4e748
152 changed files with 5889 additions and 7 deletions
138
GTweensGodot/GTweens/README.md
Normal file
138
GTweensGodot/GTweens/README.md
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/Guillemsc/GTweens/blob/main/CONTRIBUTING.md)
|
||||
[](https://github.com/Guillemsc/GTweens/releases/latest)
|
||||
[](https://www.nuget.org/packages/GTweens)
|
||||
[](https://www.nuget.org/packages/GTweens)
|
||||
[](https://github.com/Guillemsc/GTweens/actions/workflows/tests.yml)
|
||||
[](https://twitter.com/6uillem)
|
||||
|
||||
|
||||
|
||||
GTweens is a lightweight and versatile tweening library for C#.
|
||||
This library simplifies the process of creating animations and transitions in your projects, allowing you to bring your game elements to life with ease.
|
||||
|
||||
## 🤜 Features
|
||||
- **Sequencing**: Easily chain multiple tweens together to create complex sequences of animations.
|
||||
- **Versatile Easing Functions**: Choose from a variety of easing functions to achieve different animation effects, including linear, ease-in, ease-out, etc.
|
||||
- **Looping**: Create looping animations with a single line of code, and control loop count and behavior.
|
||||
- **Delays**: Specify delays, allowing precise timing of your animations.
|
||||
- **Callbacks**: Attach callbacks to tweens for event handling at various points in the animation timeline.
|
||||
|
||||
## 📦 Installation
|
||||
1. [Download the latest release](https://github.com/Guillemsc/GTweens/releases/latest).
|
||||
2. Unpack the `GTweens` folder into the project.
|
||||
|
||||
## 📚 Getting started
|
||||
### Nomenclature
|
||||
- Tween: a generic word that indicates some or multiple values being animated.
|
||||
- Sequence: an combination of tweens that get animated as a group.
|
||||
|
||||
### Prefixes
|
||||
Prefixes are important to use the most out of IntelliSense, so try to remember these:
|
||||
- **Set**: prefix for all settings that can be chained to a tween.
|
||||
```csharp
|
||||
myTween.SetLoops(4).SetEasing(Easing.InOutCubic);
|
||||
```
|
||||
- **On**: prefix for all callbacks that can be chained to a tween.
|
||||
```csharp
|
||||
myTween.OnStart(myStartFunction).OnComplete(myCompleteFunction);
|
||||
```
|
||||
|
||||
### Generic tweening
|
||||
This is the most flexible way of tweening and allows you to tween almost any value.
|
||||
```csharp
|
||||
// For default C# values (int, float, etc)
|
||||
GTweenExtensions.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.
|
||||
|
||||
```csharp
|
||||
// For default C# values
|
||||
GTween tween = GTweenExtensions.Tween(
|
||||
() => Target.SomeFloat, // Getter
|
||||
x => Target.SomeFloat = x, // Setter
|
||||
100f, // To
|
||||
1 // Duration
|
||||
);
|
||||
```
|
||||
|
||||
### Tweens context
|
||||
Tweens require a system that updates them every frame. In GTweens, this system is referred to as a `GTweensContext`.
|
||||
|
||||
Essentially, `GTweensContext` is a class that maintains a list of active tweens and advances their progress collectively when the Tick method is called.
|
||||
To set a GTween in motion, it needs to be initiated through the `Play` method provided by the `GTweensContext`.
|
||||
Here's a practical example of how to implement this concept within an application:
|
||||
```csharp
|
||||
class MyApplication
|
||||
{
|
||||
// We need a single instance of a GTweensContext
|
||||
readonly GTweensContext _gTweensContext = new();
|
||||
|
||||
void UpdateApplication(float frameDeltaTime)
|
||||
{
|
||||
// With out aplication update, we tick the context with the frame delta time
|
||||
_gTweensContext.Tick(frameDeltaTime)
|
||||
}
|
||||
|
||||
void PlaySomeTween()
|
||||
{
|
||||
// We create a tween
|
||||
GTween tween = GTweenExtensions.Tween(
|
||||
() => Target.SomeFloat, // Getter
|
||||
x => Target.SomeFloat = x, // Setter
|
||||
100f, // To
|
||||
1 // Duration
|
||||
);
|
||||
|
||||
// We play the tween with the context
|
||||
_gTweensContext.Play(tween);
|
||||
}
|
||||
}
|
||||
```
|
||||
In this example:
|
||||
- We establish a single instance of GTweensContext, _gTweensContext, within the MyApplication class.
|
||||
- The UpdateApplication function is responsible for advancing the tweens within the context using the provided frameDeltaTime as the time increment.
|
||||
- To initiate a new tween, we use the GTweenExtensions.Tween method, specifying the getter, setter, target value, and duration.
|
||||
- Finally, we play the tween by adding it to the context using _gTweensContext.Play(tween).
|
||||
This approach allows for the management and synchronization of tweens within the application using a GTweensContext.
|
||||
|
||||
### Sequences
|
||||
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.
|
||||
```csharp
|
||||
GTween tween = GTweenSequenceBuilder.New()
|
||||
.Append(SomeTween)
|
||||
.Join(SomeOtherTween)
|
||||
.Append(SomeOtherOtherTween)
|
||||
.AppendTime(0.5f)
|
||||
.Append(AnotherTween)
|
||||
.AppendCallback(() => Console.WriteLine("I'm finished!"))
|
||||
.Build();
|
||||
|
||||
tween.SetEasing(Easing.InOutCubic);
|
||||
tween.Play();
|
||||
```
|
||||
|
||||
### Tween controls
|
||||
- **Kill**: kills the tween. This means that the tween will stop playing.
|
||||
- **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.
|
||||
|
||||
### Tasks
|
||||
- **AwaitCompleteOrKill**: returns a Task that waits until the tween is killed or completed.
|
||||
Loading…
Add table
Add a link
Reference in a new issue