Merge branch 'release/3.0.0'

Author: adamgraham

CHANGELOG.md

@@ -5,11 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2023/10/22
+
+### Added
+
+- Support for creating generic tweens with `short` values
+- New extension methods for tweening `MaterialPropertyBlock`
+- New extension method `Shadow.TweenAlpha`
+- New interface `ITweenEventHandler` that can be used to respond to tween events without allocating GC from delegates
+- New utility functions to change color components
+
+### Changed
+
+- Refactored tween extensions to not use closures to reduce GC allocations
+  - Source objects are now cached in the tween and passed to the getter/setter functions
+- Changed property name casing to match C# conventions
+- Renamed `Transform.TweenScale` to `Transform.TweenLocalScale`
+- Renamed `Shadow.TweenEffectColor` to `Shadow.TweenColor`
+- Renamed `Shadow.TweenEffectDistance` to `Shadow.TweenDistance`
+
+### Fixed
+
+- Fixed tweens not updating when the duration is set to zero
+- Fixed interpolation snapping to round to the nearest integer instead of always rounding down
+
 ## [2.6.1] - 2022/05/11
 
 ### Fixed
 
-- Prevented errors caused when tweens are created while the game or scene is unloading
+- Prevented errors when tweens are created while the game or scene is unloading
 
 ### Changed
 

Documentation~/articles/callbacks.md

@@ -0,0 +1,95 @@
+---
+slug: "/manual/events"
+---
+
+# Events
+
+Various events are invoked throughout the tween lifecycle. A [TweenCallback](/api/Zigurous.Tweening/TweenCallback) function delegate can be used to respond to the following events:
+
+- [onUpdate](/api/Zigurous.Tweening/Tween/onUpdate): Invoked every time the tween is updated
+- [onStart](/api/Zigurous.Tweening/Tween/onStart): Invoked when the tween is started
+- [onStop](/api/Zigurous.Tweening/Tween/onStop): Invoked when the tween is stopped
+- [onLoop](/api/Zigurous.Tweening/Tween/onLoop): Invoked when the tween is looped
+- [onComplete](/api/Zigurous.Tweening/Tween/onComplete): Invoked when the tween is completed
+- [onKill](/api/Zigurous.Tweening/Tween/onKill): Invoked when the tween is killed
+
+<hr/>
+
+## 🗣️ Assigning callbacks
+
+Tween callbacks can be assigned with delegates or lambdas. They have no parameters or return types. You can also use [property chaining](/manual/property-chaining) to make it easier to set multiple callbacks.
+
+```csharp
+// assigning callbacks with functions
+tween.onUpdate += OnTweenUpdated
+tween.onStart += OnTweenStarted;
+tween.onStop += OnTweenStopped;
+tween.onLoop += OnTweenLooped;
+tween.onComplete += OnTweenCompleted;
+tween.onKill += OnTweenKilled;
+```
+
+```csharp
+// assigning callbacks with lambdas
+tween.onUpdate += () => Debug.Log("Updated");
+tween.onStart += () => Debug.Log("Started");
+tween.onStop += () => Debug.Log("Stopped");
+tween.onLoop += () => Debug.Log("Looped");
+tween.onComplete += () => Debug.Log("Completed");
+tween.onKill += () => Debug.Log("Killed");
+```
+
+```csharp
+// assigning callbacks with property chaining
+transform.TweenPosition(Vector3.zero, 1f)
+         .OnUpdate(OnTweenUpdated)
+         .OnStart(OnTweenStarted)
+         .OnStop(OnTweenStopped)
+         .OnLoop(OnTweenLooped)
+         .OnComplete(OnTweenCompleted)
+         .OnKill(OnTweenKilled);
+```
+
+## 🎫 Event Handler
+
+One drawback of using delegates is that it produces GC allocations. If you are highly concerned about performance, you can use the [ITweenEventHandler](/api/Zigurous.Tweening/ITweenEventHandler) interface to avoid allocations.
+
+```csharp
+public class Example : MonoBehaviour, ITweenEventHandler
+{
+    private void Start()
+    {
+        transform.TweenPosition(Vector3.zero, 1f)
+                 .SetEventHandler(this);
+    }
+
+    public void OnTweenUpdate(Tween tween)
+    {
+        Debug.Log("Updated");
+    }
+
+    public void OnTweenStart(Tween tween)
+    {
+        Debug.Log("Started");
+    }
+
+    public void OnTweenStop(Tween tween)
+    {
+        Debug.Log("Stopped");
+    }
+
+    public void OnTweenLoop(Tween tween)
+    {
+        Debug.Log("Looped");
+    }
+
+    public void OnTweenComplete(Tween tween)
+    {
+        Debug.Log("Completed");
+    }
+
+    public void OnTweenKill(Tween tween)
+    {
+        Debug.Log("Killed");
+    }
+}

Documentation~/articles/events.md

@@ -10,22 +10,32 @@ The system is lightweight, optimized, type-safe, and memory efficient. Hundreds
 
 <hr/>
 
-## 📌 Overview
+## Overview
 
-- [Scripting API](/api/Zigurous.Tweening)
-- [Installation](/manual/installation)
-- [Changelog](/changelog)
-- [License](/license)
+#### ⚙️ [Installation](/installation)
+
+#### 🧰 [Scripting API](/api/Zigurous.Tweening)
+
+#### 📋 [Changelog](/changelog)
+
+#### ⚖️ [License](/license)
 
 <hr/>
 
-## 📖 Reference
+## Reference
+
+#### 🚀 [Tweens](/manual/tweens)
+
+#### 🧬 [Sequences](/manual/sequences)
+
+#### 〽️ [Easing](/manual/easing)
+
+#### 🎫 [Events](/manual/events)
+
+#### ⛓️ [Property Chaining](/manual/property-chaining)
+
+#### 🏷️ [Managing Tweens](/manual/managing-tweens)
+
+#### 💠 [Supported Types](/manual/supported-types)
 
-- [Tweens](/manual/tweens)
-- [Sequences](/manual/sequences)
-- [Easing](/manual/easing)
-- [Callbacks](/manual/callbacks)
-- [Property Chaining](/manual/property-chaining)
-- [Managing Tweens](/manual/managing-tweens)
-- [Supported Types](/manual/supported-types)
-- [Settings](/manual/settings)
+#### 🎛️ [Settings](/manual/settings)

Documentation~/articles/index.md

@@ -17,15 +17,15 @@ Tweening.KillAll();
 You can also get the current amount of tweens:
 
 ```csharp
-int count = Tweening.Count; // the number of tweens alive (not necessarily active)
-int alive = Tweening.ActiveCount; // the number of tween active
+int count = Tweening.Count; // the number of alive tweens (not necessarily active)
+int activeCount = Tweening.ActiveCount; // the number of active tweens
 ```
 
 <hr/>
 
 ## 🏷️ Tween Ids
 
-You can also target specific tweens by id. Every tween has an `id` property which allows you to distinguish it from others. However, this is not required, nor is the id unique. The id is set automatically unless you create tweens manually using the generic approach.
+You can also target specific tweens by id. Every tween has an `id` property which allows you to distinguish it from others. However, this is not required, nor is the id unique. The id is set automatically unless you create tweens manually using the generic approach. All ids are implement as `int` values.
 
 ```csharp
 Tweening.Play(id);
@@ -35,6 +35,12 @@ Tweening.Complete(id);
 Tweening.Kill(id);
 ```
 
+To manually set the id of a tween:
+
+```csharp
+tween.id = id;
+```
+
 <hr/>
 
 ## 🎯 Target References
@@ -49,18 +55,18 @@ Tweening.Complete(transform);
 Tweening.Kill(transform);
 ```
 
-If you create tweens manually using the generic approach, you should indicate to the tween what its target game object or component is, which will set the id of the tween based on that object's hash code.
+If you create tweens manually using the generic approach, you should indicate to the tween what game object or component it is referencing. This sets both the id (see above) and scene index (see below) of the tween.
 
 ```csharp
-tween.SetTarget(gameObject);
-tween.SetTarget(component);
+tween.SetReference(gameObject);
+tween.SetReference(component);
 ```
 
 <hr/>
 
 ## 🎬 Scene Unloading
 
-Tweens will be killed automatically when the scene they are apart of is unloaded which prevents errors. However, this only works automatically if the tween knows which target object it is animating (see above). You should only need to worry about this if you are creating tweens manually using the generic approach.
+Tweens will be killed automatically when the scene they are apart of is unloaded which prevents errors accessing objects that have been destroyed. However, this only works automatically if the tween knows which target object it is animating (see above). You should only need to worry about this if you are creating tweens manually using the generic approach.
 
 Make sure to kill your tweens before transitioning scenes, or set the target reference as outlined above. You can also manually set the scene index if desired.
 

Documentation~/articles/managing-tweens.md

@@ -8,13 +8,25 @@ Property/method chaining is a technique that allows multiple properties to be as
 
 <hr/>
 
-## ⛓️ Example
+## ⛓️ Examples
 
 ```csharp
+// using a tween shortcut
 transform.TweenPosition(Vector3.zero, 1f)
          .SetDelay(3f)
-         .SetReversed(true)
+         .SetReversed()
          .SetEase(Ease.CubicInOut)
          .SetLoops(-1, LoopType.PingPong)
          .OnLoop(() => Debug.Log("looped!"));
 ```
+
+```csharp
+// building from scratch
+Tween tween = new Tweener<Transform, Vector3>(transform)
+     .SetGetter((target) => target.position)
+     .SetSetter((target, value) => target.position = value)
+     .SetEndValue(Vector3.zero)
+     .SetDuration(1f)
+     .SetEase(Ease.QuadOut)
+     .OnComplete(() => Debug.Log("complete!"));
+```

Documentation~/articles/property-chaining.md

@@ -43,6 +43,6 @@ Sequences can be controlled the same way as any other tween, meaning you can pla
 ```csharp
 Sequence sequence = Tweening.Sequence();
 sequence.SetLoops(-1, LoopType.PingPong);
-sequence.OnComplete(() => Debug.Log("sucess!"));
+sequence.OnComplete(() => Debug.Log("success!"));
 sequence.Play();
 ```

Documentation~/articles/sequences.md

@@ -35,7 +35,7 @@ Settings.recyclable = true;
 
 <hr/>
 
-## 🖥️ Changing settings in the editor
+## 🎛️ Changing settings in the editor
 
 The [Settings](/api/Zigurous.Tweening/Settings) class can also be used as a MonoBehaviour added to your scene. This is generally used to provide a simple interface for changing settings in the Unity editor rather than with code. You can, of course, still use this behavior to change settings at runtime if desired, in which case there is a function to set each respective setting.
 

Documentation~/articles/settings.md

@@ -10,8 +10,9 @@ When creating tweens using the generic functions, the following types of values
 
 - `float`
 - `double`
-- `long`
 - `int`
+- `long`
+- `short`
 - `Vector2`
 - `Vector2Int`
 - `Vector3`
@@ -75,6 +76,7 @@ All of the following types offer shortcut functions for creating tweens:
 - `LineRenderer`
 - `LookAtConstraint`
 - `Material`
+- `MaterialPropertyBlock`
 - `NavMeshAgent`
 - `NavMeshObstacle`
 - `OcclusionArea`