com.wallstop-studios.unity-helpers 2.0.4 → 2.1.1

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/ILIST_SORTING_PERFORMANCE.md

@@ -0,0 +1,92 @@
+# IList Sorting Performance Benchmarks
+
+Unity Helpers ships several custom sorting algorithms for `IList<T>` that cover different trade-offs between adaptability, allocation patterns, and stability. This page gathers context and benchmark snapshots so you can choose the right algorithm for your workload and compare results across operating systems.
+
+## Algorithm Cheatsheet
+
+| Algorithm                   | Stable? | Best For                                                                   | Reference                                                                       |
+| --------------------------- | ------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| Ghost Sort                  | No      | Mixed workloads that benefit from adaptive gap sorting and few allocations | Upstream project by Will Stafford Parsons (public repository currently offline) |
+| Meteor Sort                 | No      | Almost-sorted data where gap shrinking beats plain insertion sort          | [meteorsort by Wiley Looper](https://github.com/wileylooper/meteorsort)         |
+| Pattern-Defeating QuickSort | No      | General-purpose quicksort with protections against worst-case inputs       | [pdqsort by Orson Peters](https://github.com/orlp/pdqsort)                      |
+| Grail Sort                  | Yes     | Large datasets where stability + low allocations matter                    | [GrailSort](https://github.com/Mrrl/GrailSort)                                  |
+| Power Sort                  | Yes     | Partially ordered data that benefits from adaptive run detection           | [PowerSort (Munro & Wild)](https://arxiv.org/abs/1805.04154)                    |
+| Insertion Sort              | Yes     | Tiny or nearly sorted collections where O(n²) is acceptable                | [Wikipedia - Insertion sort](https://en.wikipedia.org/wiki/Insertion_sort)      |
+
+> **What does “stable” mean?** Stable sorting algorithms preserve the relative order of elements that compare as equal. This matters when items carry secondary keys (e.g., sorting people by last name but keeping first-name order deterministic). Unstable algorithms can reshuffle equal entries, which is usually fine for numeric keys but can break deterministic pipelines.
+>
+> **Heads up:** The original Ghost Sort repository was formerly hosted on GitHub under `wstaffordp/ghostsort`, but it currently returns 404. The Unity Helpers implementation remains based on that source; we will relink if/when an official mirror returns.
+
+## Dataset Scenarios
+
+- **Sorted** – ascending integers, verifying best-case behavior.
+- **Nearly Sorted (2% swaps)** – deterministic neighbor swaps introduce light disorder to expose adaptive optimizations.
+- **Shuffled (deterministic)** – Fisher–Yates shuffle using a fixed seed for reproducibility across runs and machines.
+
+Each benchmark sorts a fresh copy of the dataset once and reports wall-clock duration. Insertion sort is skipped for lists larger than 10,000 elements because O(n²) quickly becomes impractical; the table shows `n/a` for those entries.
+
+Run the `IListSortingPerformanceTests.Benchmark` test inside Unity’s Test Runner to refresh the tables below. Results automatically land in the section that matches the current operating system.
+
+## Windows (Editor/Player)
+
+<!-- ILIST_SORT_WINDOWS_START -->
+
+_Last updated 2025-10-26 18:00 UTC on Windows 11 (10.0.26200) 64bit_
+
+Times are single-pass measurements in milliseconds (lower is better). `n/a` indicates the algorithm was skipped for the dataset size.
+
+### Sorted
+
+| List Size | Ghost    | Meteor   | Pattern-Defeating QuickSort | Grail    | Power    | Insertion |
+| --------- | -------- | -------- | --------------------------- | -------- | -------- | --------- |
+| 100       | 0.373 ms | 0.072 ms | 0.422 ms                    | 2.04 ms  | 0.907 ms | 0.071 ms  |
+| 1,000     | 0.021 ms | 0.025 ms | 0.007 ms                    | 0.040 ms | 0.005 ms | 0.005 ms  |
+| 10,000    | 0.288 ms | 0.368 ms | 0.067 ms                    | 0.555 ms | 0.041 ms | 0.054 ms  |
+| 100,000   | 3.35 ms  | 4.81 ms  | 0.703 ms                    | 10.7 ms  | 0.424 ms | n/a       |
+| 1,000,000 | 37.0 ms  | 57.1 ms  | 6.70 ms                     | 11.4 ms  | 4.08 ms  | n/a       |
+
+### Nearly Sorted (2% swaps)
+
+| List Size | Ghost    | Meteor   | Pattern-Defeating QuickSort | Grail    | Power    | Insertion |
+| --------- | -------- | -------- | --------------------------- | -------- | -------- | --------- |
+| 100       | 0.002 ms | 0.002 ms | 0.007 ms                    | 0.145 ms | 0.053 ms | 0.001 ms  |
+| 1,000     | 0.021 ms | 0.025 ms | 0.032 ms                    | 0.009 ms | 0.020 ms | 0.006 ms  |
+| 10,000    | 0.279 ms | 0.355 ms | 0.383 ms                    | 0.072 ms | 0.223 ms | 0.057 ms  |
+| 100,000   | 3.17 ms  | 4.64 ms  | 4.61 ms                     | 0.689 ms | 3.47 ms  | n/a       |
+| 1,000,000 | 37.3 ms  | 57.3 ms  | 53.9 ms                     | 7.45 ms  | 44.8 ms  | n/a       |
+
+### Shuffled (deterministic)
+
+| List Size | Ghost    | Meteor   | Pattern-Defeating QuickSort | Grail    | Power    | Insertion |
+| --------- | -------- | -------- | --------------------------- | -------- | -------- | --------- |
+| 100       | 0.009 ms | 0.007 ms | 0.007 ms                    | 0.011 ms | 0.010 ms | 0.015 ms  |
+| 1,000     | 0.143 ms | 0.123 ms | 0.089 ms                    | 0.106 ms | 0.111 ms | 1.34 ms   |
+| 10,000    | 1.97 ms  | 1.76 ms  | 1.16 ms                     | 1.38 ms  | 1.41 ms  | 131 ms    |
+| 100,000   | 28.3 ms  | 23.5 ms  | 14.4 ms                     | 17.3 ms  | 17.5 ms  | n/a       |
+| 1,000,000 | 395 ms   | 296 ms   | 171 ms                      | 207 ms   | 212 ms   | n/a       |
+
+<!-- ILIST_SORT_WINDOWS_END -->
+
+## macOS
+
+<!-- ILIST_SORT_MACOS_START -->
+
+Pending — run the IList sorting benchmark suite on macOS to capture results.
+
+<!-- ILIST_SORT_MACOS_END -->
+
+## Linux
+
+<!-- ILIST_SORT_LINUX_START -->
+
+Pending — run the IList sorting benchmark suite on Linux to capture results.
+
+<!-- ILIST_SORT_LINUX_END -->
+
+## Other Platforms
+
+<!-- ILIST_SORT_OTHER_START -->
+
+Pending — run the IList sorting benchmark suite on the target platform to capture results.
+
+<!-- ILIST_SORT_OTHER_END -->

package/Docs/ILIST_SORTING_PERFORMANCE.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 472ebf17c174498daf3ef01bda2a8c6b
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Docs/INDEX.md

@@ -139,6 +139,9 @@ Alphabetical index of all Unity Helpers features with quick links to documentati
 **Fit Texture Size** - Auto-adjust texture max size to source dimensions
 → [Editor Tools Guide](EDITOR_TOOLS_GUIDE.md#fit-texture-size)
 
+**FlurryBurstRandom** - Six-word ARX generator (FlurryBurst32 port)
+→ [README - Random Generators](../README.md#random-number-generators) | [Random Performance](RANDOM_PERFORMANCE.md)
+
 ---
 
 ## G
@@ -262,6 +265,9 @@ Alphabetical index of all Unity Helpers features with quick links to documentati
 **PcgRandom** - High-quality PCG random generator
 → [README - Random Generators](../README.md#random-number-generators) | [Random Performance](RANDOM_PERFORMANCE.md)
 
+**PhotonSpinRandom** - SHISHUA-inspired bulk generator
+→ [README - Random Generators](../README.md#random-number-generators) | [Random Performance](RANDOM_PERFORMANCE.md)
+
 **Point-in-Polygon** - 2D/3D containment tests
 → [Math & Extensions](MATH_AND_EXTENSIONS.md#geometry)
 
@@ -306,7 +312,7 @@ Alphabetical index of all Unity Helpers features with quick links to documentati
 **Random Extensions** - Random vectors, colors, weighted selection, subset sampling
 → [Math & Extensions](MATH_AND_EXTENSIONS.md#random-generators)
 
-**Random Generators** - 12 high-performance PRNG implementations
+**Random Generators** - 15 high-performance PRNG implementations
 → [README - Random Generators](../README.md#random-number-generators) | [Random Performance](RANDOM_PERFORMANCE.md)
 
 **Range<T>** - Inclusive/exclusive range helper
@@ -352,6 +358,9 @@ Alphabetical index of all Unity Helpers features with quick links to documentati
 **Singletons** - Runtime and ScriptableObject singleton patterns
 → [Singletons Guide](SINGLETONS.md) | [README](../README.md#singleton-utilities-odin-compatible)
 
+**StormDropRandom** - Large-buffer ARX generator
+→ [README - Random Generators](../README.md#random-number-generators) | [Random Performance](RANDOM_PERFORMANCE.md)
+
 **Sparse Set** - O(1) membership with dense iteration
 → [Data Structures](DATA_STRUCTURES.md#sparse-set) | [README](../README.md#data-structures)
 

package/Docs/Images/random_generators.svg

@@ -82,14 +82,14 @@
     <!-- pip patterns 1,2,5,6 -->
     <circle cx="392" cy="267" r="2"/>
     <circle cx="420" cy="262" r="2"/>
-    <circle cx="424" cy="276" r="2"/>
+    <circle cx="424" cy="272" r="2"/>
     <circle cx="450" cy="260" r="2"/>
-    <circle cx="452" cy="268" r="2"/>
-    <circle cx="458" cy="276" r="2"/>
-    <circle cx="480" cy="260" r="2"/>
-    <circle cx="490" cy="260" r="2"/>
-    <circle cx="480" cy="276" r="2"/>
-    <circle cx="490" cy="276" r="2"/>
+    <circle cx="453" cy="266" r="2"/>
+    <circle cx="456" cy="272" r="2"/>
+    <circle cx="478" cy="262" r="2"/>
+    <circle cx="488" cy="262" r="2"/>
+    <circle cx="478" cy="272" r="2"/>
+    <circle cx="488" cy="272" r="2"/>
   </g>
   <g font-family="Verdana,Arial,sans-serif" font-size="10" fill="#9fb3c8">
     <text x="390" y="315">discrete outcomes</text>

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.
 
@@ -81,18 +81,21 @@ This document contains performance benchmarks for the various random number gene
 
 | Random                      | NextBool    | Next        | NextUInt      | NextFloat   | NextDouble  | NextUint - Range | NextInt - Range |
 | --------------------------- | ----------- | ----------- | ------------- | ----------- | ----------- | ---------------- | --------------- |
-| DotNetRandom                | 550,600,000 | 53,100,000  | 57,400,000    | 45,600,000  | 26,900,000  | 53,700,000       | 53,900,000      |
-| LinearCongruentialGenerator | 814,800,000 | 538,900,000 | 1,335,100,000 | 184,700,000 | 296,500,000 | 591,500,000      | 508,400,000     |
-| IllusionFlow                | 800,200,000 | 489,500,000 | 892,600,000   | 167,600,000 | 268,200,000 | 444,600,000      | 396,100,000     |
-| PcgRandom                   | 796,400,000 | 537,900,000 | 889,500,000   | 184,300,000 | 291,400,000 | 456,500,000      | 412,000,000     |
-| RomuDuo                     | 794,300,000 | 359,300,000 | 766,200,000   | 167,200,000 | 191,600,000 | 446,000,000      | 397,600,000     |
-| SplitMix64                  | 801,100,000 | 537,400,000 | 972,300,000   | 183,800,000 | 296,600,000 | 487,500,000      | 446,600,000     |
-| SquirrelRandom              | 747,700,000 | 383,300,000 | 413,800,000   | 172,300,000 | 204,800,000 | 330,200,000      | 314,200,000     |
-| SystemRandom                | 146,800,000 | 148,300,000 | 65,700,000    | 132,500,000 | 139,500,000 | 59,800,000       | 61,300,000      |
-| UnityRandom                 | 647,700,000 | 77,800,000  | 87,800,000    | 62,100,000  | 39,500,000  | 81,500,000       | 82,400,000      |
-| WyRandom                    | 750,700,000 | 382,900,000 | 447,500,000   | 166,800,000 | 191,700,000 | 296,800,000      | 281,100,000     |
-| XorShiftRandom              | 792,900,000 | 536,400,000 | 606,000,000   | 184,100,000 | 287,300,000 | 442,800,000      | 391,200,000     |
-| XoroShiroRandom             | 789,200,000 | 359,300,000 | 715,100,000   | 167,300,000 | 192,500,000 | 428,900,000      | 383,500,000     |
+| DotNetRandom                | 535,000,000 | 54,400,000  | 56,700,000    | 45,200,000  | 28,200,000  | 52,200,000       | 51,800,000      |
+| LinearCongruentialGenerator | 798,300,000 | 823,200,000 | 1,329,100,000 | 179,900,000 | 402,000,000 | 577,800,000      | 493,300,000     |
+| IllusionFlow                | 778,000,000 | 662,100,000 | 895,100,000   | 178,000,000 | 331,100,000 | 444,000,000      | 384,900,000     |
+| PcgRandom                   | 762,500,000 | 668,400,000 | 892,700,000   | 179,700,000 | 345,200,000 | 450,000,000      | 400,200,000     |
+| RomuDuo                     | 758,600,000 | 579,300,000 | 767,300,000   | 167,200,000 | 255,900,000 | 446,500,000      | 397,400,000     |
+| SplitMix64                  | 800,900,000 | 670,400,000 | 943,700,000   | 179,000,000 | 346,600,000 | 473,300,000      | 432,800,000     |
+| FlurryBurstRandom           | 762,800,000 | 603,800,000 | 863,700,000   | 183,000,000 | 305,200,000 | 456,400,000      | 412,400,000     |
+| SquirrelRandom              | 759,700,000 | 393,600,000 | 413,500,000   | 172,300,000 | 187,800,000 | 329,600,000      | 307,100,000     |
+| SystemRandom                | 138,400,000 | 144,300,000 | 63,200,000    | 127,600,000 | 135,800,000 | 59,600,000       | 60,400,000      |
+| UnityRandom                 | 655,300,000 | 85,000,000  | 87,800,000    | 62,200,000  | 41,500,000  | 81,500,000       | 82,400,000      |
+| WyRandom                    | 758,600,000 | 390,600,000 | 457,100,000   | 166,800,000 | 191,100,000 | 293,600,000      | 274,700,000     |
+| XorShiftRandom              | 766,300,000 | 554,600,000 | 586,100,000   | 181,100,000 | 259,100,000 | 443,300,000      | 393,600,000     |
+| XoroShiroRandom             | 766,200,000 | 522,900,000 | 714,100,000   | 167,200,000 | 243,300,000 | 428,400,000      | 381,000,000     |
+| PhotonSpinRandom            | 677,900,000 | 232,100,000 | 258,000,000   | 116,900,000 | 114,800,000 | 209,700,000      | 201,100,000     |
+| StormDropRandom             | 758,100,000 | 538,100,000 | 698,600,000   | 184,100,000 | 271,800,000 | 406,300,000      | 365,900,000     |
 
 <!-- RANDOM_BENCHMARKS_END -->
 
@@ -110,8 +113,8 @@ This document contains performance benchmarks for the various random number gene
 
 Based on the benchmarks:
 
-- **For general use**: `IllusionFlow` (via `PRNG.Instance`) - Great balance of speed and quality
-- **For maximum speed**: `RomuDuo` or `LinearCongruentialGenerator` - Fastest overall
+- **For general use**: `IllusionFlow` (via `PRNG.Instance`) or `PCG` - Great balance of speed and quality
+- **For maximum speed**: `LinearCongruentialGenerator` - Fastest overall (but not recommended for statistical quality)
 - **For compatibility**: `DotNetRandom` - Uses .NET's built-in Random
 - **Avoid for performance**: `UnityRandom` - Significantly slower than alternatives
 

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