codingwatching · pull · Jun 25, 2023 · Jun 25, 2023 · Jun 25, 2023 · Jun 26, 2023
diff --git a/CHANGELOG.md b/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
 

diff --git a/Documentation~/articles/callbacks.md b/Documentation~/articles/callbacks.md
diff --git a/Documentation~/articles/events.md b/Documentation~/articles/events.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");
+    }
+}
diff --git a/Documentation~/articles/index.md b/Documentation~/articles/index.md
@@ -30,7 +30,7 @@ The system is lightweight, optimized, type-safe, and memory efficient. Hundreds
 
 #### 〽️ [Easing](/manual/easing)
 
-#### 🗣️ [Callbacks](/manual/callbacks)
+#### 🎫 [Events](/manual/events)
 
 #### ⛓️ [Property Chaining](/manual/property-chaining)
 

diff --git a/Documentation~/articles/managing-tweens.md b/Documentation~/articles/managing-tweens.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.
 

diff --git a/Documentation~/articles/property-chaining.md b/Documentation~/articles/property-chaining.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!"));
+```
diff --git a/Documentation~/articles/supported-types.md b/Documentation~/articles/supported-types.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`

diff --git a/Documentation~/articles/tweens.md b/Documentation~/articles/tweens.md
@@ -6,7 +6,7 @@ slug: "/manual/tweens"
 
 A tween is an animation of a value from a start position to an end position using an easing function, providing a natural sense of motion. The **Tweening** package provides two main types of tweens, both of which inherit from the base class [Tween](/api/Zigurous.Tweening/Tween).
 
-- [Tweener](/api/Zigurous.Tweening/Tweener-1)
+- [Tweener](/api/Zigurous.Tweening/Tweener-2)
 - [Sequence](/api/Zigurous.Tweening/Sequence)
 
 <hr/>
@@ -18,29 +18,25 @@ A tween is an animation of a value from a start position to an end position usin
 Most of the time you will be creating tweens by using the shortcut extension methods available on most Unity objects. See the [Supported Types](/manual/supported-types) manual for the full list of classes that provide shortcut functions. Here are just a few examples:
 
 ```csharp
-transform.TweenPosition(endValue, duration);
-material.TweenColor(endValue, duration);
-camera.TweenFieldOfView(endValue, duration);
-light.TweenIntensity(endValue, duration);
+transform.TweenPosition(Vector3.zero, duration);
+material.TweenColor(Color.white, duration);
+camera.TweenFieldOfView(90f, duration);
+light.TweenIntensity(1f, duration);
 ```
 <br/>
 
 ### Generic Approach
 
-Although most of the time you will not be creating tweens with this approach, it is the basis of the entire tweening system so it is valuable to understand how it works. Essentially any value represented by a number can be tweened. The [Supported Types](/manual/supported-types) manual lists all of the specific types that can be tweened.
+Although most of the time you will not be creating tweens with this approach, it is the basis of the entire tweening system so it is valuable to understand how it works. Essentially any value represented by a number can be tweened. The [Supported Types](/manual/supported-types) manual provides a list of all types that can be tweened.
 
 ```csharp
-float currentValue, endValue, duration;
-
 // Setup delegates to get and set a value
-TweenGetter<float> getter = () => { return currentValue; };
-TweenSetter<float> setter = newValue => { currentValue = newValue; };
-
-// Create a tween that animates to the end value from the current value
-Tweening.To<float>(getter, setter, endValue, duration);
+TweenGetter<Transform, Vector3> getter = (target) => target.position;
+TweenSetter<Transform, Vector3> setter = (target, value) => target.position = value;
 
-// Create a tween that animates from the end value to the current value
-Tweening.From<float>(getter, setter, endValue, duration);
+// Create a tween that animates to the end value over a duration
+Tweening.To(transform, getter, setter, Vector3.one, 1f);
+Tweening.From(transform, getter, setter, Vector3.one, 1f);
 ```
 
 <hr/>
@@ -62,17 +58,17 @@ tween.autoStart = true; // starts the tween automatically after being initialize
 tween.autoKill = true; // kills the tween automatically after completing
 ```
 
-There are also [callback functions](/manual/callbacks) that can be set on any tween.<br/>
+There are also [callback functions](/manual/events) that can be set on any tween.<br/>
 All of these properties can be set with [property chaining](/manual/property-chaining) methods.
 
 <hr/>
 
 ## 🌪️ Controlling tweens
 
-Often times you might want to manually control the state of the tween, even if it is just pausing and resuming a tween. There are several methods available to transition a tween to a different state. *Note*: not all states can be transitioned to depending on the current state. See [Managing Tweens](/manual/managing-tweens) for ways to control tweens globally.
+Often times you might want to manually control the state of the tween, even if it is just pausing and resuming a tween. There are several methods available to transition a tween to a different state. *Note:* not all states can be transitioned to depending on the current state. See [Managing Tweens](/manual/managing-tweens) for ways to control tweens globally.
 
 ```csharp
-tween.Play(); // starts or resumes the the tween
+tween.Play(); // starts or resumes the tween
 tween.Stop(); // pauses the tween if it is already playing
 tween.Restart(); // restarts the tween from the beginning if not killed
 tween.Complete(); // completes the tween, jumping to the end value
@@ -92,17 +88,17 @@ There are a number of properties available to read the current state of a tween.
 - `Killed`: The tween is killed, making it no longer usable.
 
 ```csharp
-TweenState state = tween.state; // the current animation state of the tween
+TweenState state = tween.State; // the current animation state of the tween
 
 bool playing = tween.IsPlaying; // true if playing
 bool stopped = tween.IsStopped; // true if stopped
 bool complete = tween.IsComplete; // true if complete
 bool killed = tween.IsKilled; // true if killed
 bool delayed = tween.IsDelayed; // true if delayed
 
-float elapsed = tween.elapsed; // the amount of seconds playing
+float elapsed = tween.Elapsed; // the amount of seconds playing
 float percent = tween.PercentComplete; // the percentage of completion
-float delayElapsed = tween.delayElapsed; // the amount of seconds delayed
+float delayElapsed = tween.DelayElapsed; // the amount of seconds delayed
 
-int iterations = tween.iterations; // the number of times completed
+int iterations = tween.Iterations; // the number of times completed
 ```
diff --git a/Documentation~/data/sidenav.json b/Documentation~/data/sidenav.json
@@ -36,8 +36,8 @@
         "path": "/manual/easing"
       },
       {
-        "name": "Callbacks",
-        "path": "/manual/callbacks"
+        "name": "Events",
+        "path": "/manual/events"
       },
       {
         "name": "Property Chaining",

diff --git a/Documentation~/filterconfig.yml b/Documentation~/filterconfig.yml
@@ -16,10 +16,10 @@ apiRules:
 - exclude:
     uidRegex: ^Zigurous.Tweening.Tween.On*
 - exclude:
-    uidRegex: ^Zigurous.Tweening.Tweener`1.Animate
+    uidRegex: ^Zigurous.Tweening.Tweener`2.Animate
 - exclude:
-    uidRegex: ^Zigurous.Tweening.Tweener`1.IsFinished
+    uidRegex: ^Zigurous.Tweening.Tweener`2.IsFinished
 - exclude:
-    uidRegex: ^Zigurous.Tweening.Tweener`1.On*
+    uidRegex: ^Zigurous.Tweening.Tweener`2.On*
 - exclude:
     uidRegex: ^Zigurous.Tweening.*.Tweens