com.wallstop-studios.unity-helpers 2.0.3 → 2.1.0

package/Docs/EFFECTS_SYSTEM_TUTORIAL.md

@@ -61,8 +61,9 @@ public class PlayerStats : AttributesComponent
 {
     // Define attributes that effects can modify
     public Attribute Speed = 5f;
-    public Attribute Health = 100f;
-    public Attribute Damage = 10f;
+    public Attribute MaxHealth = 100f;
+    public Attribute AttackDamage = 10f;
+    public Attribute Defense = 5f;
 
     void Start()
     {
@@ -80,6 +81,15 @@ public class PlayerStats : AttributesComponent
 - Calculates final value automatically (Add → Multiply → Override)
 - Raises events when value changes
 
+**⚠️ Important: Use Attributes for "max" or "rate" values, NOT "current" depleting values!**
+
+- ✅ **MaxHealth** - modified by buffs (good)
+- ❌ **CurrentHealth** - modified by damage/healing from many systems (bad - causes state conflicts)
+- ✅ **AttackDamage** - modified by strength buffs (good)
+- ✅ **Speed** - modified by haste/slow effects (good)
+
+If a value is frequently modified by systems outside the effects system (like health being reduced by damage), use a regular field instead. See the main documentation for details.
+
 ---
 
 ## Step 2: Add Stats to Your Player (30 seconds)
@@ -88,8 +98,9 @@ public class PlayerStats : AttributesComponent
 2. Add Component → `PlayerStats`
 3. Set values in Inspector:
    - Speed: `5`
-   - Health: `100`
-   - Damage: `10`
+   - MaxHealth: `100`
+   - AttackDamage: `10`
+   - Defense: `5`
 
 That's it! Your player now has modifiable attributes.
 
@@ -282,8 +293,8 @@ One effect can modify multiple attributes:
 **Create "Berserker Rage" effect:**
 
 - Modification 1: Speed × 1.3
-- Modification 2: Damage × 2.0
-- Modification 3: Health × 0.8 (trade-off!)
+- Modification 2: AttackDamage × 2.0
+- Modification 3: Defense × 0.5 (trade-off - more damage but less defense!)
 - Duration: 10 seconds
 - Tags: `"Berserker"`, `"Buff"`
 
@@ -312,23 +323,63 @@ if (handle.HasValue)
 
 ```csharp
 // Create "Poison" effect:
-// - Modification: Health + (-2) per second
+// - periodicEffects: interval = 1s, maxTicks = 10, modifications = []
+// - behaviors: PoisonDamageBehavior (below)
 // - Duration: 10 seconds
-// - Tags: "Poison", "DoT", "Debuff"
+// - Tags: "Poisoned", "DoT", "Debuff"
+
+void ApplyPoison(GameObject target)
+{
+    target.ApplyEffect(poisonEffect);
+}
+
+[CreateAssetMenu(menuName = "Combat/Effects/Poison Damage")]
+public sealed class PoisonDamageBehavior : EffectBehavior
+{
+    [SerializeField]
+    private float damagePerTick = 2f;
+
+    public override void OnPeriodicTick(
+        EffectBehaviorContext context,
+        PeriodicEffectTickContext tickContext
+    )
+    {
+        if (!context.Target.TryGetComponent(out PlayerHealth health))
+        {
+            return;
+        }
 
-// Apply to enemy
-enemy.ApplyEffect(poisonEffect);
+        health.ApplyDamage(damagePerTick);
+    }
+}
 
-// In PlayerStats, handle negative health:
-void Update()
+public sealed class PlayerHealth : MonoBehaviour
 {
-    if (Health.Value <= 0)
+    [SerializeField]
+    private float currentHealth = 100f;
+
+    public float CurrentHealth => currentHealth;
+
+    public void ApplyDamage(float amount)
     {
-        Die();
+        currentHealth -= amount;
+
+        if (currentHealth <= 0f)
+        {
+            currentHealth = 0f;
+            Die();
+        }
+    }
+
+    private void Die()
+    {
+        // Handle player death
     }
 }
 ```
 
+This keeps `CurrentHealth` as a regular gameplay field while the effect system triggers damage through behaviours.
+
 ### Cooldown Reduction
 
 ```csharp
@@ -376,6 +427,13 @@ void TryApplyBuff(AttributeEffect effect)
 
 ## Troubleshooting
 
+### "Should I use CurrentHealth as an Attribute?"
+
+- **No!** Use `MaxHealth` as an Attribute (modified by buffs), but keep `CurrentHealth` as a regular field (modified by damage/healing)
+- **Why:** CurrentHealth is modified by many systems (combat, regeneration, etc.). Using it as an Attribute causes state conflicts when effects and other systems both try to modify it
+- **Pattern:** Attribute for max/cap, regular field for current/depleting value
+- **See:** "Understanding Attributes: What to Model and What to Avoid" in main documentation
+
 ### "Attribute 'Speed' not found"
 
 - **Cause:** Attribute name in effect doesn't match field name in AttributesComponent
@@ -409,11 +467,12 @@ You now have a complete buff/debuff system! Here are some ideas to expand:
 
 ### Create More Effects
 
-- **Shield:** Health × 2.0, visual shield sprite
+- **Shield:** MaxHealth × 1.5, visual shield sprite
 - **Slow:** Speed × 0.5, "Slowed" tag
-- **Critical:** Damage × 1.5, "Critical" tag
-- **Invisibility:** Just tags ("Invisible"), no stat changes
-- **Burn:** Health + (-5) per second, fire particles
+- **Critical Strike:** AttackDamage × 2.0, "CriticalHit" tag, brief flash effect
+- **Invisibility:** Just tags ("Invisible"), no stat changes, transparency effect
+- **Armor Buff:** Defense + 10, metallic sheen cosmetic
+- **Strength Potion:** AttackDamage × 1.5, red particle aura
 
 ### Build Systems Around Tags
 

package/Docs/HULLS.md

@@ -18,7 +18,7 @@ This guide explains convex and concave hulls, when to use each, and how they dif
 
 Illustration:
 
-![Convex Hull](Docs/Images/convex_hull.svg)
+![Convex Hull](Images/convex_hull.svg)
 
 ## Concave Hull
 
@@ -31,7 +31,7 @@ Illustration:
 
 Illustration:
 
-![Concave Hull](Docs/Images/concave_hull.svg)
+![Concave Hull](Images/concave_hull.svg)
 
 ## Choosing Between Them
 

package/Docs/RANDOM_PERFORMANCE.md

@@ -71,7 +71,7 @@ Threading
 
 Visual
 
-![Random Generators](Docs/Images/random_generators.svg)
+![Random Generators](Images/random_generators.svg)
 
 This document contains performance benchmarks for the various random number generators included in Unity Helpers.
 

package/Docs/REFLECTION_HELPERS.md

@@ -7,7 +7,7 @@
 
 Visual
 
-![Reflection Scan](Docs/Images/reflection_scan.svg)
+![Reflection Scan](Images/reflection_scan.svg)
 
 ReflectionHelpers is a set of utilities for high‑performance reflection in Unity projects. It generates and caches delegates to access fields and properties, call methods and constructors, and quickly create common collections — with safe fallbacks when dynamic IL isn’t available.
 

package/Docs/RELATIONAL_COMPONENTS.md

@@ -2,7 +2,7 @@
 
 Visual
 
-![Relational Wiring](Docs/Images/relational_wiring.svg)
+![Relational Wiring](Images/relational_wiring.svg)
 
 Auto-wire components in your hierarchy without `GetComponent` boilerplate. These attributes make common relationships explicit, robust, and easy to maintain.
 
@@ -10,7 +10,14 @@ Auto-wire components in your hierarchy without `GetComponent` boilerplate. These
 - `ParentComponent` — up the transform hierarchy
 - `ChildComponent` — down the transform hierarchy (breadth-first)
 
-Each works with single fields, arrays, `List<T>`, and `HashSet<T>`, supports optional assignment, filters (tag/name), depth limits, max results, and interface/base-type resolution.
+**Collection Type Support:** Each attribute works with:
+
+- Single fields (e.g., `Transform`)
+- Arrays (e.g., `Collider2D[]`)
+- **Lists** (e.g., `List<Rigidbody2D>`)
+- **HashSets** (e.g., `HashSet<Renderer>`)
+
+All attributes support optional assignment, filters (tag/name), depth limits, max results, and interface/base-type resolution.
 
 Having issues? Jump to Troubleshooting: see [Troubleshooting](#troubleshooting).
 
@@ -197,7 +204,8 @@ Examples:
 [SiblingComponent] private Animator animator;                 // required by default
 [SiblingComponent(Optional = true)] private Rigidbody2D rb;   // optional
 [SiblingComponent(TagFilter = "Visual", NameFilter = "Sprite")] private Component[] visuals;
-[SiblingComponent(MaxCount = 2)] private List<Collider2D> firstTwo;
+[SiblingComponent(MaxCount = 2)] private List<Collider2D> firstTwo;  // List<T> supported
+[SiblingComponent] private HashSet<Renderer> allRenderers;     // HashSet<T> supported
 ```
 
 ### ParentComponent
@@ -232,7 +240,10 @@ Examples:
 // First matching descendant with a tag
 [ChildComponent(OnlyDescendants = true, TagFilter = "Weapon")] private Collider2D weaponCollider;
 
-// Gather into a hash set (unique results) and limit count
+// Gather into a List (preserves insertion order)
+[ChildComponent(OnlyDescendants = true)] private List<MeshRenderer> childRenderers;
+
+// Gather into a HashSet (unique results, no duplicates) and limit count
 [ChildComponent(OnlyDescendants = true, MaxCount = 10)] private HashSet<Rigidbody2D> firstTenRigidbodies;
 ```
 
@@ -261,6 +272,39 @@ Examples:
 - `AllowInterfaces` (default: true)
   - If `true`, can assign by interface or base type; set `false` to restrict to concrete types
 
+### Choosing the Right Collection Type
+
+**Use Arrays (`T[]`)** when:
+
+- Collection size is fixed or rarely changes
+- Need the smallest memory footprint
+- Interoperating with APIs that require arrays
+
+**Use Lists (`List<T>`)** when:
+
+- Need insertion order preserved
+- Plan to add/remove elements after assignment
+- Want indexed access with `[]` operator
+- Need compatibility with most LINQ operations
+
+**Use HashSets (`HashSet<T>`)** when:
+
+- Need guaranteed uniqueness (no duplicates)
+- Performing frequent membership tests (`Contains()`)
+- Order doesn't matter
+- Want O(1) lookup performance
+
+```csharp
+// Arrays: Fixed size, minimal overhead
+[ChildComponent] private Collider2D[] colliders;
+
+// Lists: Dynamic, ordered, index-based access
+[ChildComponent] private List<Renderer> renderers;
+
+// HashSets: Unique, fast lookups, unordered
+[ChildComponent] private HashSet<AudioSource> audioSources;
+```
+
 ## Recipes
 
 - UI hierarchy references
@@ -564,7 +608,8 @@ Common pitfalls and how to avoid them
 
 **DI Integration Samples:**
 
-- [VContainer Integration](Samples~/DI%20-%20VContainer/README.md) - Complete VContainer setup guide
-- [Zenject Integration](Samples~/DI%20-%20Zenject/README.md) - Complete Zenject setup guide
+- [VContainer Integration](../Samples~/DI%20-%20VContainer/README.md) - Complete VContainer setup guide
+- [Zenject Integration](../Samples~/DI%20-%20Zenject/README.md) - Complete Zenject setup guide
+- [Reflex Integration](../Samples~/DI%20-%20Reflex/README.md) - Complete Reflex setup guide
 
 **Need help?** [Open an issue](https://github.com/wallstop/unity-helpers/issues) | [Troubleshooting](#troubleshooting)

package/Docs/SERIALIZATION.md

@@ -8,7 +8,7 @@
 
 Visuals
 
-![Serialization Flow](Docs/Images/serialization_flow.svg)
+![Serialization Flow](Images/serialization_flow.svg)
 
 This package provides fast, compact serialization for save systems, configuration, and networking with a unified API.
 

package/Docs/SINGLETONS.md

@@ -2,7 +2,7 @@
 
 Visual
 
-![Singletons Lifecycle](Docs/Images/singletons_lifecycle.svg)
+![Singletons Lifecycle](Images/singletons_lifecycle.svg)
 
 This package includes two lightweight, production‑ready singleton helpers that make global access patterns safe, consistent, and testable:
 
@@ -403,7 +403,7 @@ Use alternatives when one or more of these apply:
 
 Use this chart to pick an approach based on constraints:
 
-![Data Distribution Strategy](Docs/Images/data_distribution_decision.svg)
+![Data Distribution Strategy](Images/data_distribution_decision.svg)
 
 <a id="troubleshooting"></a>
 

package/Docs/SPATIAL_TREES_2D_GUIDE.md

@@ -188,7 +188,7 @@ See [Buffering Pattern](../README.md#buffering-pattern) for the complete guide a
 - Pros: Simple structure; predictable performance; incremental updates straightforward.
 - Cons: Data hotspots deepen local trees; nearest neighbors slower than KDTree.
 
-Diagram: ![QuadTree2D](Docs/Images/quadtree_2d.svg)
+Diagram: ![QuadTree2D](Images/quadtree_2d.svg)
 
 ### KDTree2D
 
@@ -197,7 +197,7 @@ Diagram: ![QuadTree2D](Docs/Images/quadtree_2d.svg)
 - Pros: Strong NN performance; balanced variant gives consistent query time.
 - Cons: Costly to maintain under heavy churn; unbalanced variant can degrade.
 
-Diagram: ![KDTree2D](Docs/Images/kdtree_2d.svg)
+Diagram: ![KDTree2D](Images/kdtree_2d.svg)
 
 ### RTree2D
 
@@ -206,7 +206,7 @@ Diagram: ![KDTree2D](Docs/Images/kdtree_2d.svg)
 - Pros: Great for large bounds queries; matches bounds semantics.
 - Cons: Overlapping MBRs can increase node visits; not optimal for point NN.
 
-Diagram: ![RTree2D](Docs/Images/rtree_2d.svg)
+Diagram: ![RTree2D](Images/rtree_2d.svg)
 
 ## Choosing a Structure
 

package/Docs/SPATIAL_TREES_3D_GUIDE.md

@@ -178,7 +178,7 @@ See [Buffering Pattern](../README.md#buffering-pattern) for the complete guide a
 - Pros: Good spatial locality; intuitive partitioning; balanced performance.
 - Cons: Nearest neighbors slower than KDTree on pure point data.
 
-![Octree3D](Docs/Images/octree_3d.svg)
+![Octree3D](Images/octree_3d.svg)
 
 ### KDTree3D
 
@@ -187,7 +187,7 @@ See [Buffering Pattern](../README.md#buffering-pattern) for the complete guide a
 - Pros: Strong NN performance; balanced variant gives consistent query time.
 - Cons: Costly to maintain under heavy churn; unbalanced variant can degrade.
 
-![KDTree3D](Docs/Images/kdtree_3d.svg)
+![KDTree3D](Images/kdtree_3d.svg)
 
 ### RTree3D
 
@@ -196,7 +196,7 @@ See [Buffering Pattern](../README.md#buffering-pattern) for the complete guide a
 - Pros: Great for large bounds queries; matches volumetric semantics.
 - Cons: Overlapping boxes can increase node visits; not optimal for point NN.
 
-![RTree3D](Docs/Images/rtree_3d.svg)
+![RTree3D](Images/rtree_3d.svg)
 
 ## Choosing a Structure
 

package/Docs/SPATIAL_TREE_SEMANTICS.md

@@ -16,19 +16,19 @@ This page explains how the 2D and 3D spatial structures compare in terms of corr
 
 Illustrations:
 
-![QuadTree2D](Docs/Images/quadtree_2d.svg)
+![QuadTree2D](Images/quadtree_2d.svg)
 
-![KDTree2D](Docs/Images/kdtree_2d.svg)
+![KDTree2D](Images/kdtree_2d.svg)
 
-![RTree2D](Docs/Images/rtree_2d.svg)
+![RTree2D](Images/rtree_2d.svg)
 
 3D Variants
 
-![Octree3D](Docs/Images/octree_3d.svg)
+![Octree3D](Images/octree_3d.svg)
 
-![KDTree3D](Docs/Images/kdtree_3d.svg)
+![KDTree3D](Images/kdtree_3d.svg)
 
-![RTree3D](Docs/Images/rtree_3d.svg)
+![RTree3D](Images/rtree_3d.svg)
 
 Diagram notes
 
@@ -91,7 +91,7 @@ Key reasons and scenarios:
 
 ## Boundary Semantics
 
-![Query Boundaries](Docs/Images/query_boundaries.svg)
+![Query Boundaries](Images/query_boundaries.svg)
 
 Tips
 

package/Editor/CustomDrawers/WShowIfPropertyDrawer.cs

@@ -42,63 +42,153 @@ namespace WallstopStudios.UnityHelpers.Editor.CustomDrawers
             SerializedProperty conditionProperty = property.serializedObject.FindProperty(
                 showIf.conditionField
             );
-            if (conditionProperty is not { propertyType: SerializedPropertyType.Boolean })
+            if (conditionProperty != null)
             {
-                if (conditionProperty != null)
+                if (TryEvaluateCondition(conditionProperty, showIf, out bool serializedResult))
                 {
-                    return true;
+                    return serializedResult;
                 }
+                return true;
+            }
 
-                // This might not be a unity object, so fall back to reflection
-                object enclosingObject = property.GetEnclosingObject(out _);
-                if (enclosingObject == null)
-                {
-                    return true;
-                }
+            object enclosingObject = property.GetEnclosingObject(out _);
+            if (enclosingObject == null)
+            {
+                return true;
+            }
 
-                Type type = enclosingObject.GetType();
-                Dictionary<string, Func<object, object>> cachedFields = CachedFields.GetOrAdd(type);
-                if (
-                    !cachedFields.TryGetValue(
-                        showIf.conditionField,
-                        out Func<object, object> accessor
-                    )
-                )
+            Type type = enclosingObject.GetType();
+            Dictionary<string, Func<object, object>> cachedFields = CachedFields.GetOrAdd(type);
+            if (!cachedFields.TryGetValue(showIf.conditionField, out Func<object, object> accessor))
+            {
+                FieldInfo field = type.GetField(
+                    showIf.conditionField,
+                    BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic
+                );
+                if (field == null)
                 {
-                    FieldInfo field = type.GetField(
-                        showIf.conditionField,
-                        BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic
+                    Debug.LogError(
+                        $"Failed to find conditional field {showIf.conditionField} on {type.Name}!"
                     );
-                    if (field == null)
-                    {
-                        Debug.LogError(
-                            $"Failed to find conditional field {showIf.conditionField} on {type.Name}!"
-                        );
-                        accessor = _ => null;
-                    }
-                    else
-                    {
-                        accessor = ReflectionHelpers.GetFieldGetter(field);
-                    }
-                    cachedFields[showIf.conditionField] = accessor;
+                    accessor = _ => null;
                 }
-                object fieldValue = accessor(enclosingObject);
-                if (fieldValue is bool maybeCondition)
+                else
                 {
-                    return showIf.inverse ? !maybeCondition : maybeCondition;
+                    accessor = ReflectionHelpers.GetFieldGetter(field);
                 }
+                cachedFields[showIf.conditionField] = accessor;
+            }
+            object fieldValue = accessor(enclosingObject);
+            return !TryEvaluateCondition(fieldValue, showIf, out bool reflectedResult)
+                ? true
+                : reflectedResult;
+        }
 
-                int index = Array.IndexOf(showIf.expectedValues, fieldValue);
-                if (showIf.inverse)
+        private static bool TryEvaluateCondition(
+            SerializedProperty conditionProperty,
+            WShowIfAttribute showIf,
+            out bool shouldShow
+        )
+        {
+            if (conditionProperty == null)
+            {
+                shouldShow = true;
+                return false;
+            }
+
+            if (conditionProperty.propertyType == SerializedPropertyType.Boolean)
+            {
+                bool condition = conditionProperty.boolValue;
+                shouldShow = showIf.inverse ? !condition : condition;
+                return true;
+            }
+
+            object conditionValue = conditionProperty.GetTargetObjectWithField(out _);
+            return TryEvaluateCondition(conditionValue, showIf, out shouldShow);
+        }
+
+        private static bool TryEvaluateCondition(
+            object conditionValue,
+            WShowIfAttribute showIf,
+            out bool shouldShow
+        )
+        {
+            if (conditionValue is bool boolean)
+            {
+                shouldShow = showIf.inverse ? !boolean : boolean;
+                return true;
+            }
+
+            object[] expectedValues = showIf.expectedValues;
+            if (expectedValues == null || expectedValues.Length == 0)
+            {
+                shouldShow = true;
+                return false;
+            }
+
+            bool match = false;
+            for (int i = 0; i < expectedValues.Length; ++i)
+            {
+                if (ValuesEqual(conditionValue, expectedValues[i]))
                 {
-                    return index < 0;
+                    match = true;
+                    break;
                 }
+            }
+
+            shouldShow = showIf.inverse ? !match : match;
+            return true;
+        }
+
+        private static bool ValuesEqual(object actual, object expected)
+        {
+            if (ReferenceEquals(actual, expected))
+            {
+                return true;
+            }
+
+            if (actual == null || expected == null)
+            {
+                return false;
+            }
+
+            if (actual.Equals(expected))
+            {
+                return true;
+            }
+
+            Type actualType = actual.GetType();
+            Type expectedType = expected.GetType();
+
+            try
+            {
+                if (actualType.IsEnum || expectedType.IsEnum)
+                {
+                    long actualValue = Convert.ToInt64(actual);
+                    long expectedValue = Convert.ToInt64(expected);
+                    return actualValue == expectedValue;
+                }
+            }
+            catch
+            {
+                return false;
+            }
 
-                return 0 <= index;
+            if (actual is IConvertible && expected is IConvertible)
+            {
+                try
+                {
+                    double actualValue = Convert.ToDouble(actual);
+                    double expectedValue = Convert.ToDouble(expected);
+                    return Math.Abs(actualValue - expectedValue) < double.Epsilon;
+                }
+                catch
+                {
+                    return false;
+                }
             }
 
-            bool condition = conditionProperty.boolValue;
-            return showIf.inverse ? !condition : condition;
+            return false;
         }
     }
 #endif