com.wallstop-studios.unity-helpers 2.0.0-rc81.9 → 2.0.0

package/GETTING_STARTED.md

@@ -1,81 +1,65 @@
 # Getting Started with Unity Helpers
 
-Welcome! Unity Helpers is a comprehensive toolkit designed to make Unity development faster,
-more reliable, and more enjoyable. This guide will help you get started based on your learning style.
+**Welcome! You're about to save yourself weeks of repetitive work.**
 
-## What Makes Unity Helpers Special?
+Unity Helpers is a battle-tested toolkit that eliminates the boring, repetitive code you're tired of writing. This guide gets you productive in 5 minutes, whether you're a beginner or a senior engineer.
 
-Unity Helpers isn't just another utility library - it's built on three core principles:
+## What Makes This Worth Your Time?
 
-### 1. Developer-Friendly First
+**Three core principles that save you actual hours:**
 
-**Extensive APIs that handle edge cases you'd otherwise code manually:**
+### 1. 🎯 Zero Boilerplate
 
-- Random selection with weights? One method call.
-- Weighted bool with probability? Built-in.
-- Gaussian distribution? Perlin noise maps? Already there.
+**APIs that handle the tedious stuff:**
 
-**Self-documenting attributes and patterns:**
+- Random selection with weights? → `random.NextWeightedIndex(weights)`
+- Auto-wire components? → `[SiblingComponent] private Animator animator;`
+- Gaussian distribution? Perlin noise? → Built-in, one method call
+
+**Self-documenting code:**
 
 ```csharp
-[SiblingComponent] private Animator animator;  // Clear intent
+[SiblingComponent] private Animator animator;                      // Clear intent
 [ParentComponent(OnlyAncestors = true)] private Rigidbody2D rb;  // Explicit search
-[ChildComponent(MaxDepth = 1)] private Collider2D[] colliders;  // Limited scope
+[ChildComponent(MaxDepth = 1)] private Collider2D[] colliders;   // Limited scope
 ```
 
-**Fail-fast with helpful error messages:**
-
-- Missing required components? Detailed logs with GameObject names and paths.
-- Invalid spatial tree queries? Clear explanations of what went wrong.
-- Schema evolution issues? Specific guidance on fixing serialization problems.
-
-### 2. Performance-Backed
-
-**10-15x faster random generation:**
-
-- `PRNG.Instance` vs `UnityEngine.Random`: 655M ops/sec vs 65M ops/sec
-- Thread-safe via thread-local instances
-- Fully seedable for deterministic gameplay
-
-**Zero-allocation spatial queries:**
-
-- Buffering pattern eliminates GC spikes
-- Reusable collections keep frame times stable
-- O(log n) trees scale to millions of objects
+**Helpful errors that save debugging time:**
 
-**IL-emitted reflection:**
+- Missing components? → Full GameObject path + component type
+- Invalid queries? → Explanation of what went wrong + how to fix it
+- Schema issues? → Specific guidance for your serialization problem
 
-- 10-100x faster than System.Reflection
-- Field access: ~2ns vs ~200ns (100x speedup)
-- IL2CPP safe and fully tested
+### 2. ⚡ Performance-Proven
 
-### 3. Production-Ready
+**Measurable speed improvements:**
 
-**4,000+ automated test cases:**
+- **10-15x faster** random generation (655M ops/sec vs 65M ops/sec)
+- **100x faster** reflection (2ns vs 200ns field access)
+- **O(log n)** spatial queries scale to millions of objects
+- **Zero GC** with buffering pattern
 
-- Cover edge cases you haven't thought of
-- Run before each release to catch regressions
-- Prevent bugs before they reach your players
+**Real-world impact:**
 
-**Used in shipped commercial games:**
+- Stable 60 FPS with 1000+ AI agents querying neighbors
+- No allocation spikes from pooled collections
+- Deterministic replays with seedable RNG
 
-- Battle-tested in real production environments
-- Performance-critical paths proven at scale
-- API stability from real-world feedback
+### 3. ✅ Production-Ready
 
-**Protobuf schema evolution:**
+**Quality you can trust:**
 
-- Add/remove fields without breaking old saves
-- Players never lose progress from updates
-- Forward and backward compatible serialization
+- ✅ **4,000+ automated tests** - Edge cases covered before you hit them
+- ✅ **Shipped in commercial games** - Battle-tested at scale
+- ✅ **IL2CPP/WebGL compatible** - Works with aggressive compilers
+- ✅ **Schema evolution** - Player saves never break from updates
+- ✅ **SINGLE_THREADED optimized** - 10-20% faster on WebGL
 
-**IL2CPP and WebGL optimized:**
+**What this means for you:**
 
-- Works with Unity's aggressive compiler
-- No reflection issues in release builds
-- Full AOT compatibility
-- SINGLE_THREADED define for optimized WebGL hot paths
-- 10-20% faster on single-threaded platforms
+- Ship confidently knowing edge cases are handled
+- No "works in editor but not in build" surprises
+- Update your game without corrupting player data
 
 ---
 
@@ -396,8 +380,8 @@ Pick one feature that solves your immediate problem:
 
 **Ready to dive deeper?** Return to the [main README](README.md) for the complete feature list.
 
-**Building something cool?** We'd love to hear about it! Share your experience in
-[GitHub Discussions](https://github.com/wallstop/unity-helpers/discussions).
+**Building something cool?** We'd love to hear about it! Share your experience by opening an
+[issue](https://github.com/wallstop/unity-helpers/issues).
 
 ---
 

package/RANDOM_PERFORMANCE.md

@@ -81,18 +81,18 @@ This document contains performance benchmarks for the various random number gene
 
 | Random                      | NextBool    | Next        | NextUInt      | NextFloat   | NextDouble  | NextUint - Range | NextInt - Range |
 | --------------------------- | ----------- | ----------- | ------------- | ----------- | ----------- | ---------------- | --------------- |
-| DotNetRandom                | 548,300,000 | 54,900,000  | 58,300,000    | 48,000,000  | 28,100,000  | 54,800,000       | 54,100,000      |
-| LinearCongruentialGenerator | 805,700,000 | 829,700,000 | 1,334,700,000 | 212,300,000 | 411,000,000 | 558,500,000      | 503,400,000     |
-| IllusionFlow                | 787,300,000 | 655,900,000 | 885,100,000   | 203,500,000 | 309,000,000 | 442,200,000      | 392,100,000     |
-| PcgRandom                   | 793,900,000 | 662,100,000 | 919,300,000   | 211,700,000 | 341,200,000 | 453,800,000      | 407,700,000     |
-| RomuDuo                     | 796,900,000 | 556,300,000 | 707,100,000   | 189,500,000 | 254,800,000 | 423,300,000      | 390,900,000     |
-| SplitMix64                  | 803,400,000 | 739,200,000 | 1,063,900,000 | 212,600,000 | 381,300,000 | 485,700,000      | 439,400,000     |
-| SquirrelRandom              | 781,900,000 | 394,900,000 | 413,800,000   | 198,000,000 | 203,400,000 | 365,900,000      | 311,700,000     |
-| SystemRandom                | 143,400,000 | 148,500,000 | 65,200,000    | 131,400,000 | 137,200,000 | 59,000,000       | 60,000,000      |
-| UnityRandom                 | 657,500,000 | 85,000,000  | 87,800,000    | 65,200,000  | 41,500,000  | 81,500,000       | 82,200,000      |
-| WyRandom                    | 771,400,000 | 389,300,000 | 456,500,000   | 183,500,000 | 194,200,000 | 297,000,000      | 282,100,000     |
-| XorShiftRandom              | 796,600,000 | 563,800,000 | 603,100,000   | 212,800,000 | 286,800,000 | 481,000,000      | 392,200,000     |
-| XoroShiroRandom             | 793,500,000 | 557,600,000 | 712,900,000   | 190,200,000 | 244,000,000 | 428,100,000      | 379,800,000     |
+| DotNetRandom                | 534,500,000 | 55,300,000  | 57,600,000    | 46,500,000  | 27,400,000  | 53,700,000       | 53,500,000      |
+| LinearCongruentialGenerator | 801,300,000 | 876,500,000 | 1,307,000,000 | 188,400,000 | 376,000,000 | 584,200,000      | 501,200,000     |
+| IllusionFlow                | 778,600,000 | 631,500,000 | 880,200,000   | 183,400,000 | 324,000,000 | 438,700,000      | 389,100,000     |
+| PcgRandom                   | 785,600,000 | 653,100,000 | 909,700,000   | 188,800,000 | 312,600,000 | 450,700,000      | 406,500,000     |
+| RomuDuo                     | 778,000,000 | 588,000,000 | 754,900,000   | 170,200,000 | 251,600,000 | 439,200,000      | 391,900,000     |
+| SplitMix64                  | 780,500,000 | 750,100,000 | 1,058,400,000 | 191,300,000 | 358,800,000 | 485,500,000      | 441,300,000     |
+| SquirrelRandom              | 758,000,000 | 408,100,000 | 413,800,000   | 178,200,000 | 188,100,000 | 367,900,000      | 339,500,000     |
+| SystemRandom                | 148,000,000 | 148,900,000 | 64,500,000    | 132,000,000 | 139,200,000 | 59,000,000       | 59,000,000      |
+| UnityRandom                 | 657,400,000 | 85,100,000  | 87,800,000    | 63,000,000  | 41,500,000  | 81,100,000       | 82,100,000      |
+| WyRandom                    | 759,500,000 | 383,800,000 | 454,200,000   | 171,600,000 | 189,000,000 | 295,600,000      | 280,100,000     |
+| XorShiftRandom              | 788,000,000 | 592,100,000 | 603,600,000   | 190,900,000 | 262,100,000 | 479,000,000      | 420,900,000     |
+| XoroShiroRandom             | 780,600,000 | 557,000,000 | 754,300,000   | 172,800,000 | 251,700,000 | 421,300,000      | 376,300,000     |
 
 <!-- RANDOM_BENCHMARKS_END -->