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

package/AGENTS.md

@@ -26,6 +26,7 @@
 - Do not use underscores in function names, especially test function names.
 - Do not use regions, anywhere, ever.
 - Avoid `var` wherever possible, use expressive types.
+- Do not use nullable reference types.
 
 ## Testing Guidelines
 

package/Docs/ILIST_SORTING_PERFORMANCE.md

@@ -31,7 +31,7 @@ Run the `IListSortingPerformanceTests.Benchmark` test inside Unity’s Test Runn
 
 <!-- ILIST_SORT_WINDOWS_START -->
 
-_Last updated 2025-10-26 18:00 UTC on Windows 11 (10.0.26200) 64bit_
+_Last updated 2025-11-01 02:07 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.
 
@@ -39,31 +39,31 @@ Times are single-pass measurements in milliseconds (lower is better). `n/a` indi
 
 | 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       |
+| 100       | 0.180 ms | 0.072 ms | 0.285 ms                    | 0.113 ms | 0.393 ms | 0.067 ms  |
+| 1,000     | 0.025 ms | 0.029 ms | 0.008 ms                    | 0.027 ms | 0.005 ms | 0.006 ms  |
+| 10,000    | 0.307 ms | 0.414 ms | 0.071 ms                    | 0.122 ms | 0.043 ms | 0.063 ms  |
+| 100,000   | 3.70 ms  | 5.42 ms  | 0.711 ms                    | 1.20 ms  | 0.433 ms | n/a       |
+| 1,000,000 | 43.4 ms  | 67.0 ms  | 7.14 ms                     | 14.5 ms  | 4.36 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       |
+| 100       | 0.003 ms | 0.002 ms | 0.009 ms                    | 0.154 ms | 0.021 ms | 0.001 ms  |
+| 1,000     | 0.025 ms | 0.029 ms | 0.034 ms                    | 0.010 ms | 0.017 ms | 0.007 ms  |
+| 10,000    | 0.309 ms | 0.426 ms | 0.411 ms                    | 0.075 ms | 0.272 ms | 0.068 ms  |
+| 100,000   | 3.74 ms  | 5.47 ms  | 5.00 ms                     | 0.768 ms | 3.97 ms  | n/a       |
+| 1,000,000 | 43.7 ms  | 67.3 ms  | 58.2 ms                     | 7.83 ms  | 50.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       |
+| 100       | 0.010 ms | 0.008 ms | 0.007 ms                    | 0.013 ms | 0.011 ms | 0.017 ms  |
+| 1,000     | 0.157 ms | 0.135 ms | 0.094 ms                    | 0.114 ms | 0.118 ms | 1.52 ms   |
+| 10,000    | 2.22 ms  | 1.94 ms  | 1.21 ms                     | 1.46 ms  | 1.51 ms  | 150 ms    |
+| 100,000   | 31.6 ms  | 25.7 ms  | 15.1 ms                     | 18.3 ms  | 18.5 ms  | n/a       |
+| 1,000,000 | 443 ms   | 323 ms   | 179 ms                      | 219 ms   | 222 ms   | n/a       |
 
 <!-- ILIST_SORT_WINDOWS_END -->
 

package/Docs/INDEX.md

@@ -329,6 +329,7 @@ Alphabetical index of all Unity Helpers features with quick links to documentati
 
 **Relational Components** - Auto-wire hierarchy components
 → [Relational Components Guide](RELATIONAL_COMPONENTS.md) | [README](../README.md#component-attributes)
+→ [Relational Component Performance Benchmarks](RELATIONAL_COMPONENT_PERFORMANCE.md)
 
 **RTree2D** - 2D R-tree for bounding boxes
 → [2D Spatial Trees](SPATIAL_TREES_2D_GUIDE.md) | [2D Performance](SPATIAL_TREE_2D_PERFORMANCE.md)

package/Docs/RANDOM_PERFORMANCE.md

@@ -81,21 +81,21 @@ This document contains performance benchmarks for the various random number gene
 
 | Random                      | NextBool    | Next        | NextUInt      | NextFloat   | NextDouble  | NextUint - Range | NextInt - Range |
 | --------------------------- | ----------- | ----------- | ------------- | ----------- | ----------- | ---------------- | --------------- |
-| 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     |
+| DotNetRandom                | 543,400,000 | 53,000,000  | 58,000,000    | 44,900,000  | 27,100,000  | 53,700,000       | 53,700,000      |
+| LinearCongruentialGenerator | 807,000,000 | 489,000,000 | 1,328,100,000 | 172,500,000 | 333,300,000 | 593,300,000      | 507,300,000     |
+| IllusionFlow                | 791,100,000 | 489,600,000 | 894,000,000   | 172,400,000 | 331,900,000 | 446,100,000      | 395,300,000     |
+| PcgRandom                   | 796,800,000 | 538,000,000 | 914,300,000   | 176,800,000 | 344,900,000 | 452,000,000      | 406,200,000     |
+| RomuDuo                     | 778,400,000 | 336,400,000 | 767,400,000   | 148,300,000 | 206,900,000 | 446,100,000      | 398,200,000     |
+| SplitMix64                  | 779,900,000 | 489,600,000 | 1,063,600,000 | 172,300,000 | 332,900,000 | 483,200,000      | 442,000,000     |
+| FlurryBurstRandom           | 778,500,000 | 487,000,000 | 951,900,000   | 172,100,000 | 335,300,000 | 456,000,000      | 410,600,000     |
+| SquirrelRandom              | 756,400,000 | 355,100,000 | 409,300,000   | 151,400,000 | 200,900,000 | 366,500,000      | 311,700,000     |
+| SystemRandom                | 148,400,000 | 147,600,000 | 64,300,000    | 131,400,000 | 137,300,000 | 58,700,000       | 57,900,000      |
+| UnityRandom                 | 645,700,000 | 79,900,000  | 83,900,000    | 61,500,000  | 41,300,000  | 76,600,000       | 75,600,000      |
+| WyRandom                    | 755,900,000 | 356,600,000 | 455,000,000   | 152,300,000 | 190,400,000 | 290,700,000      | 276,100,000     |
+| XorShiftRandom              | 784,900,000 | 531,800,000 | 603,300,000   | 178,200,000 | 294,600,000 | 486,500,000      | 392,600,000     |
+| XoroShiroRandom             | 783,900,000 | 333,000,000 | 751,900,000   | 145,900,000 | 203,000,000 | 428,000,000      | 381,800,000     |
+| PhotonSpinRandom            | 702,200,000 | 217,000,000 | 264,500,000   | 116,000,000 | 116,800,000 | 211,500,000      | 214,100,000     |
+| StormDropRandom             | 779,700,000 | 484,800,000 | 717,300,000   | 172,300,000 | 255,800,000 | 401,500,000      | 369,600,000     |
 
 <!-- RANDOM_BENCHMARKS_END -->
 

package/Docs/REFLECTION_HELPERS.md

@@ -33,10 +33,62 @@ When to use it
 
 When not to use it
 
-- One‑off reflection (e.g., editor button pressed infrequently). Simpler `GetValue/SetValue` is fine.
+- One-off reflection (e.g., editor button pressed infrequently). Simpler `GetValue/SetValue` is fine.
 - If you need full runtime codegen in IL2CPP/WebGL: IL emit isn’t available there. ReflectionHelpers still works, but uses expression compilation or reflection fallback — benefits remain for caching and reduced allocations.
 - Setting struct instance fields using boxed setters: prefer the generic ref setter to mutate the original struct (see “Struct note” below).
 
+### Caching Strategy Overview
+
+ReflectionHelpers now partitions cached delegates by **capability strategy** so that expression, dynamic-IL, and reflection fallbacks never overwrite each other. Key points:
+
+- **Strategy fingerprinting**: every delegate cache entry is keyed by `CapabilityKey<TMember>` (member metadata + `ReflectionDelegateStrategy`). This applies to fields, properties, indexers, methods, and constructors (boxed + typed variants).
+- **Per-strategy blocklists**: when a strategy cannot produce a delegate (e.g., IL emit disabled on IL2CPP), we record the failure in a per-cache blocklist so later calls skip unnecessary work.
+- **Delegate provenance**: created delegates are tracked in a `ConditionalWeakTable<Delegate, StrategyHolder>` so diagnostics and tests can assert the producing strategy via `ReflectionHelpers.TryGetDelegateStrategy`.
+- **Capability overrides**: `ReflectionHelpers.OverrideReflectionCapabilities(expressions, dynamicIl)` temporarily toggles expression/IL support, letting tests (or runtime feature detection) confirm that caches store independent delegates per strategy.
+- **Test hooks**: `ClearFieldGetterCache`, `ClearPropertyCache`, `ClearMethodCache`, and `ClearConstructorCache` flush the relevant cache groups to keep unit tests deterministic.
+- **Fallback behaviour**: if neither expressions nor dynamic IL are available, the reflection-path delegates still benefit from caching and avoid repeated argument validation/boxing.
+
+### Current Implementation Summary
+
+| API Group                        | Representative methods                                                                              | Primary strategy (Mono/Editor)                                                                                                                                | Fallbacks (IL2CPP/WebGL/AOT)                                                                 | Caching                                                                                            | Notes                                                                                                         |
+| -------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Field access (boxed)             | `GetFieldGetter(FieldInfo)`, `GetFieldSetter(FieldInfo)`                                            | Emit `DynamicMethod` IL (`BuildFieldGetter/SetterIL`) to cast/unbox target and box return                                                                     | `CreateCompiled*` builds expression delegates; otherwise wraps `FieldInfo.GetValue/SetValue` | `FieldGetterCache`, `FieldSetterCache`, static equivalents                                         | Supports static + instance fields; struct writes box when IL emit unavailable (IL2CPP/WebGL)                  |
+| Field access (typed)             | `GetFieldGetter<TInstance,TValue>`, `GetFieldSetter<TInstance,TValue>`                              | Emit typed `DynamicMethod` (setters use by-ref) to avoid boxing                                                                                               | Falls back to `GetValue/SetValue` wrappers; setter fallback boxes then copies back           | None (callers must hold returned delegate)                                                         | `TInstance` must match declaring type; fastest only where IL emit allowed                                     |
+| Property access (boxed)          | `GetPropertyGetter(PropertyInfo)`, `GetPropertySetter(PropertyInfo)`                                | Emit `DynamicMethod` (`Call`/`Callvirt`) and box value types                                                                                                  | Expression-compiled wrapper; else `PropertyInfo.GetValue/SetValue`                           | `PropertyGetterCache`, `PropertySetterCache`, static equivalents                                   | Handles non-public accessors; fallback reintroduces boxing/allocations                                        |
+| Property access (typed)          | `GetPropertyGetter<TInstance,TValue>`, `GetPropertySetter<TInstance,TValue>`                        | Emit typed `DynamicMethod` with cast/unbox guards                                                                                                             | Direct reflection wrappers casting to `TValue`                                               | None                                                                                               | Avoids boxing only on IL paths; static typed getter limited to static properties                              |
+| Method invokers (boxed)          | `GetMethodInvoker`, `GetStaticMethodInvoker`, `InvokeMethod`                                        | Emit `DynamicMethod` to unpack `object[]` args and box return                                                                                                 | Expression wrappers; otherwise call `MethodInfo.Invoke` directly                             | `MethodInvokers`, `StaticMethodInvokers`                                                           | Works with private members; fallback incurs reflection cost per call                                          |
+| Method invokers (typed static)   | `GetStaticMethodInvoker<…>`, `GetStaticActionInvoker<…>`                                            | Emit `DynamicMethod` per arity (0–4) for direct call                                                                                                          | Try `MethodInfo.CreateDelegate`; else expression compile                                     | `TypedStaticInvoker0-4`, `TypedStaticAction0-4`                                                    | Signature-checked upfront; limited to four parameters today                                                   |
+| Method invokers (typed instance) | `GetInstanceMethodInvoker<TInstance,…>`, `GetInstanceActionInvoker<TInstance,…>`                    | Emit `DynamicMethod` using `ldarga` for structs and `Callvirt` for refs                                                                                       | Falls back to `Delegate.CreateDelegate` / expression lambdas                                 | `TypedInstanceInvoker0-4`, `TypedInstanceAction0-4`                                                | Requires `TInstance` assignable to declaring type; fallback boxes structs                                     |
+| Constructors & factories         | `GetConstructor`, `CreateInstance`, `GetParameterlessConstructor<T>`, `GetParameterlessConstructor` | Delegate factory prefers expression lambdas, falls back to dynamic IL `newobj` and finally reflection (`ConstructorInfo.Invoke` / `Activator.CreateInstance`) | Reflection invoke (no emit)                                                                  | `Constructors`, `ParameterlessConstructors`, `TypedParameterlessConstructors`                      | Works across Editor/IL2CPP; capability overrides let tests force fallback paths                               |
+| Indexer helpers                  | `GetIndexerGetter`, `GetIndexerSetter`                                                              | Expression lambdas or dynamic IL to handle struct receivers and value conversions                                                                             | Reflection `PropertyInfo.Get/SetValue` with argument validation                              | `IndexerGetters`, `IndexerSetters`                                                                 | Throws `IndexOutOfRangeException`/`InvalidCastException` when indices mismatch; respects capability overrides |
+| Collection creators              | `CreateArray`, `GetListCreator(Type)`, `GetDictionaryWithCapacityCreator`                           | Emit `DynamicMethod` for `newarr`/`newobj`, plus `HashSet.Add` wrappers                                                                                       | Use `Array.CreateInstance`, `Activator.CreateInstance`, or reflection `Invoke`               | `ArrayCreators`, `ListCreators`, `ListWithCapacityCreators`, `HashSetWithCapacityCreators`, adders | `Create*` APIs cache by element type; fallback still functional but allocates                                 |
+| Type/attribute scanning          | `GetAllLoadedAssemblies`, `GetTypesDerivedFrom<T>`, `HasAttributeSafe`                              | Direct reflection with guarded iteration; Editor uses `UnityEditor.TypeCache` shortcuts                                                                       | Gracefully skips assemblies/types on error; no IL emit needed                                | `TypeResolutionCache`, `FieldLookup`, `PropertyLookup`, `MethodLookup`                             | Depends on link.xml or addressables to keep members under IL2CPP stripping                                    |
+
+### Current Consumers Snapshot
+
+- `Runtime/Core/Serialization/Serializer.cs` and `Runtime/Core/Serialization/JsonConverters/TypeConverter.cs` lean on static method invokers and type resolution to integrate ProtoBuf and JSON pipelines.
+- `Runtime/Core/Attributes` (`BaseRelationalComponentAttribute`, `RelationalComponentInitializer`, `NotNullAttribute`) depend on field getters/setters and collection factories for relational wiring.
+- `Runtime/Tags` (`AttributeMetadataCache`, `AttributeUtilities`, `AttributeMetadataFilters`) use attribute scanning plus cached getters/setters to hydrate metadata tables at startup.
+- `Runtime/Core/Helper/StringInList.cs` and `Runtime/Core/Helper/Logging/UnityLogTagFormatter.cs` use helper invokers for dynamic lookups during logging and formatting.
+- `Editor/AnimationEventEditor.cs`, `Editor/Tags/AttributeMetadataCacheGenerator.cs`, and `Editor/Utils/ScriptableObjectSingletonCreator.cs` call into the helpers for TypeCache-driven discovery and editor automation.
+- `Runtime/Utils/ScriptableObjectSingleton.cs` relies on safe attribute retrieval to locate singleton assets without repeating reflection calls.
+
+### Platform Capability Matrix
+
+| Target Environment                             | Unity Backend       | `DynamicMethod` IL Emit                                                | `Expression.Compile`                                                                                    | ReflectionHelpers Behaviour                                                                                                    | Notes                                                                                                                                |
+| ---------------------------------------------- | ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| **Editor (Windows/macOS/Linux)**               | Mono / JIT          | ✅ Enabled (`EMIT_DYNAMIC_IL`)                                         | ✅ Enabled (`SUPPORT_EXPRESSION_COMPILE`)                                                               | Uses IL-generated delegates for getters/setters/invokers; expression compile is a fallback if IL creation fails at runtime     | Same behaviour for play mode in editor; fastest path used during authoring tools and tests.                                          |
+| **Standalone Player (Mono scripting backend)** | Mono / JIT          | ✅ Enabled                                                             | ✅ Enabled                                                                                              | Matches editor experience; cached IL delegates provide best throughput                                                         | Applies to legacy desktop Mono builds (Windows/Mac/Linux) where JIT is available.                                                    |
+| **Standalone / Mobile / Console (IL2CPP)**     | IL2CPP / AOT        | ❌ Disabled at compile time (`ENABLE_IL2CPP` blocks `EMIT_DYNAMIC_IL`) | ⚠️ Disabled (`SUPPORT_EXPRESSION_COMPILE` undefined; `CheckExpressionCompilationSupport` returns false) | Falls back to pre-built delegate wrappers or direct `Invoke`/`GetValue` with caching; still avoids repeated reflection lookups | Covers Windows/macOS/iOS/Android/Consoles when built with IL2CPP. Requires link.xml (or addressables) to preserve reflected members. |
+| **WebGL Player**                               | IL2CPP / AOT (wasm) | ❌ Disabled (`UNITY_WEBGL && !UNITY_EDITOR`)                           | ⚠️ Disabled                                                                                             | Uses expression-free reflection paths identical to IL2CPP builds; object boxing unavoidable for struct setters/invokers        | WebGL disallows runtime codegen; helpers rely on cached reflection only.                                                             |
+| **Burst-compiled jobs**                        | Burst               | ❌ Not permitted                                                       | ❌ Not permitted                                                                                        | ReflectionHelpers should not be called from Burst jobs; wrap calls on main thread or use precomputed data                      | Burst forbids managed reflection; guard usage with `Unity.Burst.NoAlias` patterns or pre-bake data.                                  |
+| **Server builds / headless (Mono)**            | Mono / JIT          | ✅ Enabled                                                             | ✅ Enabled                                                                                              | Same as desktop Mono path; suitable for dedicated servers running on JIT                                                       | Confirm `EMIT_DYNAMIC_IL` stays enabled unless IL2CPP server build is selected.                                                      |
+| **Continuous Integration**                     | Any                 | Depends on selected backend                                            | Depends on backend                                                                                      | Benchmarks skip doc writes when `Helpers.IsRunningInContinuousIntegration` is true, but helpers themselves behave per backend  | Use automated tests to validate both IL2CPP fallback and Mono fast paths.                                                            |
+
+- `DynamicMethod` support is controlled at compile time by `#if !((UNITY_WEBGL && !UNITY_EDITOR) || ENABLE_IL2CPP)` in `ReflectionHelpers.cs`.
+- `Expression.Compile` support is gated by the same define; the runtime guard `CheckExpressionCompilationSupport()` prevents usage when the platform forbids JIT compilation even if the symbols are present.
+- `SINGLE_THREADED` builds remove `System.Collections.Concurrent` usage and swap to simple dictionaries; this is rarely needed but remains AOT-friendly for constrained platforms.
+
 Key APIs at a glance
 
 - Fields
@@ -185,6 +237,37 @@ Performance tips
 - Prefer typed APIs (`GetFieldGetter<TInstance, TValue>`, typed static invokers) to avoid boxing and object[] allocations.
 - Use creators (`GetListCreator`, `GetArrayCreator`) in loops to avoid reflection/Activator costs.
 
+### Benchmarking & Verification
+
+- **Unit coverage**: `ReflectionHelperCapabilityMatrixTests` resets caches and toggles capabilities around each helper. Run these suites in both expression-enabled and expression-disabled modes when changing caching internals.
+- **Micro-benchmarks**: Use `Tests/Runtime/Performance/ReflectionPerformanceTests` to capture before/after numbers for getters, setters, method invokers, and constructors (now including expression vs. dynamic IL comparisons). Record results with each `ReflectionDelegateStrategy` forced via `OverrideReflectionCapabilities` so regressions are easy to spot.
+- **Cache hygiene**: when adding new delegate families, update the appropriate `Clear*Cache` helper and call it from tests to keep scenarios isolated.
+- **Documentation updates**: note the Unity version, scripting backend, and OS whenever you refresh timing data, and sync any tables in the [Reflection Performance docs](Docs/REFLECTION_PERFORMANCE.md) so contributors can compare against baseline numbers.
+- **Execution recipe**:
+  1. Run `Tests/Runtime/Helper/ReflectionHelperCapabilityMatrixTests` twice—once normally and once with `REFLECTION_HELPERS_FORCE_REFLECTION=1` (or by wrapping the suite in `OverrideReflectionCapabilities(false, false)`) to cover accelerated and fallback paths.
+  2. Export raw benchmark data by running the `ReflectionPerformanceTests` category inside the Unity Test Runner with `LogFullResults` enabled; copy the markdown summary into the [Reflection Performance benchmarks](Docs/REFLECTION_PERFORMANCE.md).
+  3. Validate editor/runtime builds (Mono + IL2CPP) to ensure blocklists behave consistently across backends.
+
+### Testing fallback behaviour
+
+When you need to validate the pure-reflection paths (for example, to mimic IL2CPP/WebGL behaviour), override the runtime capability probes inside a `using` scope:
+
+```csharp
+using (ReflectionHelpers.OverrideReflectionCapabilities(expressions: false, dynamicIl: false))
+{
+    // Force expression + IL emit to be unavailable
+    Func<TestConstructorClass> ctor = ReflectionHelpers.GetParameterlessConstructor<TestConstructorClass>();
+    TestConstructorClass instance = ctor(); // Uses reflection fallback
+
+    PropertyInfo indexer = typeof(IndexerClass).GetProperty("Item");
+    var getter = ReflectionHelpers.GetIndexerGetter(indexer);
+    var setter = ReflectionHelpers.GetIndexerSetter(indexer);
+    setter(new IndexerClass(), 42, new object[] { 0 }); // reflection-based path
+}
+```
+
+The helper restores the original capability state when disposed, so nested overrides remain safe. Runtime regression tests now cover constructors and indexers in both accelerated and fallback modes.
+
 IL2CPP/WebGL notes
 
 - Dynamic IL emit is disabled on IL2CPP/WebGL; ReflectionHelpers automatically falls back to expression compilation or direct reflection where necessary.

package/Docs/REFLECTION_PERFORMANCE.md

@@ -0,0 +1,169 @@
+# Reflection Performance Benchmarks
+
+Unity Helpers replaces ad-hoc reflection with cached delegates that favour expression lambdas on IL2CPP-safe platforms and fall back to dynamic IL emit or plain reflection where available. These benchmarks compare raw `System.Reflection` against the helpers for common access patterns.
+
+Each run updates the table for the current operating system only. Sections that still show `_No benchmark data generated yet._` simply have not been executed on that platform.
+
+## Windows
+
+<!-- REFLECTION_PERFORMANCE_WINDOWS_START -->
+
+Generated on 2025-11-01 02:10:30 UTC
+
+### Strategy: Default (auto)
+
+#### Boxed Access (object)
+
+| Scenario                       | Helper (ops/sec) | System.Reflection (ops/sec) | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------- |
+| Instance Field Get (boxed)     | 26.90M           | 6.43M                       | 4.18x                 |
+| Instance Field Set (boxed)     | 28.65M           | 4.50M                       | 6.36x                 |
+| Static Field Get (boxed)       | 28.95M           | 7.23M                       | 4.00x                 |
+| Static Field Set (boxed)       | 28.12M           | 6.28M                       | 4.48x                 |
+| Instance Property Get (boxed)  | 24.12M           | 26.34M                      | 0.92x                 |
+| Instance Property Set (boxed)  | 27.55M           | 1.51M                       | 18.25x                |
+| Static Property Get (boxed)    | 26.47M           | 27.45M                      | 0.96x                 |
+| Static Property Set (boxed)    | 22.39M           | 2.93M                       | 7.65x                 |
+| Instance Method Invoke (boxed) | 23.55M           | 1.97M                       | 11.98x                |
+| Static Method Invoke (boxed)   | 22.89M           | 2.67M                       | 8.58x                 |
+| Constructor Invoke (boxed)     | 18.01M           | 1.70M                       | 10.58x                |
+
+#### Typed Access (no boxing)
+
+| Scenario                       | Helper (ops/sec) | Baseline Delegate (ops/sec) | System.Reflection (ops/sec) | Speedup vs Delegate | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------------- | ------------------- | --------------------- |
+| Instance Field Get (typed)     | 544.26M          | 614.88M                     | 6.43M                       | 0.89x               | 84.68x                |
+| Instance Field Set (typed)     | 636.55M          | 669.32M                     | 4.50M                       | 0.95x               | 141.37x               |
+| Static Field Get (typed)       | 608.91M          | 694.14M                     | 7.23M                       | 0.88x               | 84.20x                |
+| Static Field Set (typed)       | 623.04M          | 664.87M                     | 6.28M                       | 0.94x               | 99.27x                |
+| Instance Property Get (typed)  | 594.54M          | 695.13M                     | 26.34M                      | 0.86x               | 22.57x                |
+| Instance Property Set (typed)  | 637.69M          | 700.01M                     | 1.51M                       | 0.91x               | 422.38x               |
+| Static Property Get (typed)    | 626.49M          | 692.86M                     | 27.45M                      | 0.90x               | 22.82x                |
+| Static Property Set (typed)    | 624.91M          | 662.31M                     | 2.93M                       | 0.94x               | 213.60x               |
+| Instance Method Invoke (typed) | 592.71M          | 688.29M                     | 1.97M                       | 0.86x               | 301.58x               |
+| Static Method Invoke (typed)   | 596.62M          | 685.29M                     | 2.67M                       | 0.87x               | 223.62x               |
+
+### Strategy: Expressions
+
+#### Boxed Access (object)
+
+| Scenario                       | Helper (ops/sec) | System.Reflection (ops/sec) | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------- |
+| Instance Field Get (boxed)     | 28.61M           | 7.44M                       | 3.84x                 |
+| Instance Field Set (boxed)     | 20.64M           | 5.46M                       | 3.78x                 |
+| Static Field Get (boxed)       | 28.66M           | 7.03M                       | 4.08x                 |
+| Static Field Set (boxed)       | 27.93M           | 6.28M                       | 4.45x                 |
+| Instance Property Get (boxed)  | 21.52M           | 25.54M                      | 0.84x                 |
+| Instance Property Set (boxed)  | 26.48M           | 1.71M                       | 15.50x                |
+| Static Property Get (boxed)    | 22.02M           | 25.15M                      | 0.88x                 |
+| Static Property Set (boxed)    | 27.33M           | 2.14M                       | 12.79x                |
+| Instance Method Invoke (boxed) | 23.92M           | 1.95M                       | 12.28x                |
+| Static Method Invoke (boxed)   | 27.02M           | 2.09M                       | 12.95x                |
+| Constructor Invoke (boxed)     | 28.46M           | 2.60M                       | 10.96x                |
+
+#### Typed Access (no boxing)
+
+| Scenario                       | Helper (ops/sec) | Baseline Delegate (ops/sec) | System.Reflection (ops/sec) | Speedup vs Delegate | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------------- | ------------------- | --------------------- |
+| Instance Field Get (typed)     | 608.49M          | 669.38M                     | 7.44M                       | 0.91x               | 81.76x                |
+| Instance Field Set (typed)     | 636.85M          | 666.03M                     | 5.46M                       | 0.96x               | 116.70x               |
+| Static Field Get (typed)       | 600.54M          | 692.53M                     | 7.03M                       | 0.87x               | 85.40x                |
+| Static Field Set (typed)       | 621.80M          | 665.52M                     | 6.28M                       | 0.93x               | 99.05x                |
+| Instance Property Get (typed)  | 586.55M          | 696.86M                     | 25.54M                      | 0.84x               | 22.96x                |
+| Instance Property Set (typed)  | 637.48M          | 700.05M                     | 1.71M                       | 0.91x               | 373.18x               |
+| Static Property Get (typed)    | 626.64M          | 692.26M                     | 25.15M                      | 0.91x               | 24.92x                |
+| Static Property Set (typed)    | 617.44M          | 652.06M                     | 2.14M                       | 0.95x               | 288.83x               |
+| Instance Method Invoke (typed) | 588.93M          | 680.02M                     | 1.95M                       | 0.87x               | 302.26x               |
+| Static Method Invoke (typed)   | 604.99M          | 677.46M                     | 2.09M                       | 0.89x               | 289.97x               |
+
+### Strategy: Dynamic IL
+
+#### Boxed Access (object)
+
+| Scenario                       | Helper (ops/sec) | System.Reflection (ops/sec) | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------- |
+| Instance Field Get (boxed)     | 9.63M            | 3.55M                       | 2.71x                 |
+| Instance Field Set (boxed)     | 28.14M           | 5.53M                       | 5.09x                 |
+| Static Field Get (boxed)       | 21.41M           | 8.79M                       | 2.43x                 |
+| Static Field Set (boxed)       | 28.71M           | 5.03M                       | 5.71x                 |
+| Instance Property Get (boxed)  | 28.48M           | 24.35M                      | 1.17x                 |
+| Instance Property Set (boxed)  | 23.24M           | 2.07M                       | 11.20x                |
+| Static Property Get (boxed)    | 25.03M           | 22.55M                      | 1.11x                 |
+| Static Property Set (boxed)    | 28.12M           | 2.86M                       | 9.84x                 |
+| Instance Method Invoke (boxed) | 21.85M           | 1.60M                       | 13.65x                |
+| Static Method Invoke (boxed)   | 26.94M           | 2.66M                       | 10.14x                |
+| Constructor Invoke (boxed)     | 26.74M           | 2.27M                       | 11.79x                |
+
+#### Typed Access (no boxing)
+
+| Scenario                       | Helper (ops/sec) | Baseline Delegate (ops/sec) | System.Reflection (ops/sec) | Speedup vs Delegate | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------------- | ------------------- | --------------------- |
+| Instance Field Get (typed)     | 596.97M          | 665.13M                     | 3.55M                       | 0.90x               | 168.16x               |
+| Instance Field Set (typed)     | 628.92M          | 658.63M                     | 5.53M                       | 0.95x               | 113.81x               |
+| Static Field Get (typed)       | 610.06M          | 693.76M                     | 8.79M                       | 0.88x               | 69.40x                |
+| Static Field Set (typed)       | 629.61M          | 658.60M                     | 5.03M                       | 0.96x               | 125.18x               |
+| Instance Property Get (typed)  | 595.85M          | 687.51M                     | 24.35M                      | 0.87x               | 24.47x                |
+| Instance Property Set (typed)  | 631.56M          | 692.86M                     | 2.07M                       | 0.91x               | 304.37x               |
+| Static Property Get (typed)    | 620.22M          | 684.44M                     | 22.55M                      | 0.91x               | 27.51x                |
+| Static Property Set (typed)    | 611.44M          | 655.34M                     | 2.86M                       | 0.93x               | 213.92x               |
+| Instance Method Invoke (typed) | 588.65M          | 680.04M                     | 1.60M                       | 0.87x               | 367.87x               |
+| Static Method Invoke (typed)   | 600.46M          | 677.57M                     | 2.66M                       | 0.89x               | 226.04x               |
+
+### Strategy: Reflection Fallback
+
+#### Boxed Access (object)
+
+| Scenario                       | Helper (ops/sec) | System.Reflection (ops/sec) | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------- |
+| Instance Field Get (boxed)     | 7.29M            | 7.32M                       | 0.99x                 |
+| Instance Field Set (boxed)     | 4.40M            | 5.47M                       | 0.80x                 |
+| Static Field Get (boxed)       | 8.55M            | 4.84M                       | 1.77x                 |
+| Static Field Set (boxed)       | 2.72M            | 4.55M                       | 0.60x                 |
+| Instance Property Get (boxed)  | 26.15M           | 26.84M                      | 0.97x                 |
+| Instance Property Set (boxed)  | 1.81M            | 2.10M                       | 0.86x                 |
+| Static Property Get (boxed)    | 22.27M           | 26.45M                      | 0.84x                 |
+| Static Property Set (boxed)    | 2.55M            | 2.96M                       | 0.86x                 |
+| Instance Method Invoke (boxed) | 2.00M            | 1.97M                       | 1.02x                 |
+| Static Method Invoke (boxed)   | 2.47M            | 1.91M                       | 1.30x                 |
+| Constructor Invoke (boxed)     | 2.55M            | 2.57M                       | 0.99x                 |
+
+#### Typed Access (no boxing)
+
+| Scenario                       | Helper (ops/sec) | Baseline Delegate (ops/sec) | System.Reflection (ops/sec) | Speedup vs Delegate | Speedup vs Reflection |
+| ------------------------------ | ---------------- | --------------------------- | --------------------------- | ------------------- | --------------------- |
+| Instance Field Get (typed)     | 7.28M            | 625.84M                     | 7.32M                       | 0.01x               | 0.99x                 |
+| Instance Field Set (typed)     | 5.29M            | 654.42M                     | 5.47M                       | 0.01x               | 0.97x                 |
+| Static Field Get (typed)       | 7.07M            | 691.26M                     | 4.84M                       | 0.01x               | 1.46x                 |
+| Static Field Set (typed)       | 6.19M            | 658.10M                     | 4.55M                       | 0.01x               | 1.36x                 |
+| Instance Property Get (typed)  | 590.82M          | 688.57M                     | 26.84M                      | 0.86x               | 22.01x                |
+| Instance Property Set (typed)  | 631.83M          | 696.20M                     | 2.10M                       | 0.91x               | 300.24x               |
+| Static Property Get (typed)    | 626.19M          | 690.57M                     | 26.45M                      | 0.91x               | 23.67x                |
+| Static Property Set (typed)    | 621.38M          | 662.49M                     | 2.96M                       | 0.94x               | 210.10x               |
+| Instance Method Invoke (typed) | 587.96M          | 689.37M                     | 1.97M                       | 0.85x               | 298.85x               |
+| Static Method Invoke (typed)   | 604.95M          | 685.12M                     | 1.91M                       | 0.88x               | 317.35x               |
+
+<!-- REFLECTION_PERFORMANCE_WINDOWS_END -->
+
+## macOS
+
+<!-- REFLECTION_PERFORMANCE_MACOS_START -->
+
+_No benchmark data generated yet._
+
+<!-- REFLECTION_PERFORMANCE_MACOS_END -->
+
+## Linux
+
+<!-- REFLECTION_PERFORMANCE_LINUX_START -->
+
+_No benchmark data generated yet._
+
+<!-- REFLECTION_PERFORMANCE_LINUX_END -->
+
+## Unknown / Other
+
+<!-- REFLECTION_PERFORMANCE_UNKNOWN_START -->
+
+_No benchmark data generated yet._
+
+<!-- REFLECTION_PERFORMANCE_UNKNOWN_END -->

package/{package-lock.json.meta → Docs/REFLECTION_PERFORMANCE.md.meta}

@@ -1,5 +1,5 @@
 fileFormatVersion: 2
-guid: eb975aaa9a7b55842a63ac0105034aa4
+guid: 1a27457c1ce047a68daffaad6fd63704
 TextScriptImporter:
   externalObjects: {}
   userData: 

package/Docs/RELATIONAL_COMPONENTS.md

@@ -23,6 +23,8 @@ Having issues? Jump to Troubleshooting: see [Troubleshooting](#troubleshooting).
 
 Related systems: For data‑driven gameplay effects (attributes, tags, cosmetics), see [Effects System](EFFECTS_SYSTEM.md) and the README section Effects, Attributes, and Tags (#effects-attributes-and-tags).
 
+Curious how these attributes stack up against manual `GetComponent*` loops? Check the [Relational Component Performance Benchmarks](RELATIONAL_COMPONENT_PERFORMANCE.md) for operations-per-second and allocation snapshots.
+
 ## TL;DR — What Problem This Solves
 
 - **⭐ Replace 20+ lines of repetitive GetComponent boilerplate with 3 attributes + 1 method call.**
@@ -208,6 +210,8 @@ Examples:
 [SiblingComponent] private HashSet<Renderer> allRenderers;     // HashSet<T> supported
 ```
 
+> **Performance note:** Sibling lookups do not cache results between calls. In profiling we found these assignments typically run once per GameObject (e.g., during `Awake`), so the extra bookkeeping and invalidation cost of a cache outweighed the benefits. If you need updated references later, call `AssignSiblingComponents` again after the hierarchy changes.
+
 ### ParentComponent
 
 - Scope: Up the transform chain (optionally excluding self)
@@ -247,6 +251,8 @@ Examples:
 [ChildComponent(OnlyDescendants = true, MaxCount = 10)] private HashSet<Rigidbody2D> firstTenRigidbodies;
 ```
 
+> **Performance note:** When you avoid depth limits and interface filtering, child assignments run through a cached `GetComponentsInChildren<T>()` delegate to stay allocation-free. Turning on `MaxDepth` or interface searches still works, but the assigner reverts to the breadth-first traversal to honour those constraints.
+
 ## Common Options (All Attributes)
 
 - `Optional` (default: false)

package/Docs/RELATIONAL_COMPONENT_PERFORMANCE.md

@@ -0,0 +1,63 @@
+# Relational Component Performance Benchmarks
+
+Relational component attributes (`[SiblingComponent]`, `[ParentComponent]`, `[ChildComponent]`) remove repetitive `GetComponent*` code. These benchmarks quantify the runtime cost of calling `Assign*Components` for common field shapes (single component, array, `List<T>`, and `HashSet<T>`) against hand-written lookups.
+
+**How to refresh these tables:**
+
+1. Open Unity’s Test Runner (EditMode/PlayMode as appropriate for your setup).
+2. Run `RelationalComponentBenchmarkTests.Benchmark` inside `Tests/Runtime/Performance`.
+3. The test logs the tables to the console and rewrites the section that matches the current operating system.
+
+The script executes the benchmark test in batch mode, captures the markdown tables to `BenchmarkLogs/RelationalBenchmark.log`, and preserves the raw `TestResults.xml` when `-KeepResults` is specified.
+
+## Windows (Editor/Player)
+
+<!-- RELATIONAL_COMPONENTS_WINDOWS_START -->
+
+_Last updated 2025-11-01 02:11 UTC on Windows 11 (10.0.26200) 64bit_
+
+Numbers capture repeated `Assign*Components` calls for one second per scenario.
+Higher operations per second are better.
+
+### Operations per second (higher is better)
+
+| Scenario          | Relational Ops/s | Manual Ops/s | Rel/Manual | Iterations |
+| ----------------- | ---------------: | -----------: | ---------: | ---------: |
+| Parent - Single   |        1,009,079 |    5,700,123 |      0.18x |  1,010,000 |
+| Parent - Array    |          676,149 |    3,327,317 |      0.20x |    680,000 |
+| Parent - List     |          766,704 |    4,238,343 |      0.18x |    770,000 |
+| Parent - HashSet  |          746,757 |    2,906,359 |      0.26x |    750,000 |
+| Child - Single    |          948,288 |    3,562,341 |      0.27x |    950,000 |
+| Child - Array     |          263,898 |    2,357,185 |      0.11x |    270,000 |
+| Child - List      |          247,098 |    2,623,979 |      0.09x |    250,000 |
+| Child - HashSet   |          247,462 |    1,708,595 |      0.14x |    250,000 |
+| Sibling - Single  |        3,855,983 |   14,542,964 |      0.27x |  3,860,000 |
+| Sibling - Array   |          925,080 |    2,537,309 |      0.36x |    930,000 |
+| Sibling - List    |        1,170,239 |    3,356,368 |      0.35x |  1,180,000 |
+| Sibling - HashSet |        1,137,739 |    1,773,824 |      0.64x |  1,140,000 |
+
+<!-- RELATIONAL_COMPONENTS_WINDOWS_END -->
+
+## macOS
+
+<!-- RELATIONAL_COMPONENTS_MACOS_START -->
+
+Pending — run the relational component benchmark suite on macOS to capture results.
+
+<!-- RELATIONAL_COMPONENTS_MACOS_END -->
+
+## Linux
+
+<!-- RELATIONAL_COMPONENTS_LINUX_START -->
+
+Pending — run the relational component benchmark suite on Linux to capture results.
+
+<!-- RELATIONAL_COMPONENTS_LINUX_END -->
+
+## Other Platforms
+
+<!-- RELATIONAL_COMPONENTS_OTHER_START -->
+
+Pending — run the relational component benchmark suite on the target platform to capture results.
+
+<!-- RELATIONAL_COMPONENTS_OTHER_END -->

package/Docs/RELATIONAL_COMPONENT_PERFORMANCE.md.meta

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