com.wallstop-studios.unity-helpers 2.0.0 → 2.0.2

package/EFFECTS_SYSTEM.md

@@ -1,242 +0,0 @@
-# Effects, Attributes, and Tags — Deep Dive
-
-## TL;DR — What Problem This Solves
-
-- **⭐ Build buff/debuff systems without writing custom code for every effect.**
-- Data‑driven ScriptableObjects: designers create 100s of effects, programmers build system once.
-- **Time saved: Weeks of boilerplate eliminated + designers empowered to iterate freely.**
-
-### ⭐ The Designer Empowerment Killer Feature
-
-**The Problem - Hardcoded Effects:**
-
-```csharp
-// Every buff needs its own custom MonoBehaviour:
-
-public class HasteEffect : MonoBehaviour
-{
-    private float duration = 5f;
-    private float originalSpeed;
-    private PlayerStats player;
-
-    void Start()
-    {
-        player = GetComponent<PlayerStats>();
-        originalSpeed = player.speed;
-        player.speed *= 1.5f;  // Apply speed boost
-    }
-
-    void Update()
-    {
-        duration -= Time.deltaTime;
-        if (duration <= 0)
-        {
-            player.speed = originalSpeed;  // Restore
-            Destroy(this);
-        }
-    }
-}
-
-// 20 effects × 50 lines each = 1000 lines of repetitive code
-// Designers can't create effects without programmer
-```
-
-**The Solution - Data-Driven:**
-
-```csharp
-// Programmers build system once (Unity Helpers provides this):
-// - AttributesComponent base class
-// - EffectHandler manages application/removal
-// - ScriptableObject authoring
-
-// Designers create effects in Editor (NO CODE):
-// 1. Right-click → Create → Attribute Effect
-// 2. Name: "Haste"
-// 3. Add modification: Speed × 1.5
-// 4. Duration: 5 seconds
-// 5. Done!
-
-// Apply at runtime (one line):
-target.ApplyEffect(hasteEffect);
-```
-
-**Designer Workflow:**
-
-1. Create effect asset in 30 seconds (no code)
-2. Test in-game immediately
-3. Tweak values and iterate freely
-4. Create variations (Haste II, Haste III) by duplicating assets
-
-**Impact:**
-
-- **Programmer time saved**: Weeks of boilerplate → system built once
-- **Designer empowerment**: Block creating 100s of effects instantly
-- **Iteration speed**: Change values without code changes/recompiles
-- **Maintainability**: All effects in one system vs scattered scripts
-
-Data‑driven gameplay effects that modify stats, apply tags, and drive cosmetic presentation.
-
-This guide explains the concepts, how they work together, authoring patterns, recipes, best practices, and FAQs.
-
-Visuals
-
-![Effects Pipeline](Docs/Images/effects_pipeline.svg)
-
-![Attribute Resolution](Docs/Images/attribute_resolution.svg)
-
-## Concepts
-
-- `Attribute` — A dynamic numeric value with a base and a calculated current value. Current value applies all active modifications.
-- `AttributeModification` — Declarative change to an `Attribute`. Actions: Addition, Multiplication, Override. Applied in that order.
-- `AttributeEffect` — ScriptableObject asset bundling modifications, tags, cosmetic data, and duration policy.
-- `EffectHandle` — Opaque identifier for a specific application instance (for Duration/Infinite effects). Used to remove one stack.
-- `AttributesComponent` — Base MonoBehaviour exposing modifiable `Attribute` fields (e.g., Health, Speed) on your character.
-- `EffectHandler` — Component that applies/removes effects, tracks durations, forwards modifications to `AttributesComponent`, applies tags and cosmetics.
-- `TagHandler` — Counts and queries string tags for gating gameplay (e.g., "Stunned"). Removes tags only when all sources are gone.
-- `CosmeticEffectData` — Prefab‑like container with `CosmeticEffectComponent` behaviours; reused or instanced per effect application.
-
-## How It Works
-
-1. You author an `AttributeEffect` with modifications, tags, cosmetics, and duration.
-2. You apply it to a GameObject: `EffectHandle? handle = target.ApplyEffect(effect);`
-3. `EffectHandler` will:
-   - Create an `EffectHandle` (for Duration/Infinite) and track expiration
-   - Apply tags via `TagHandler` (counted; multiple sources safe)
-   - Apply cosmetic behaviours (`CosmeticEffectData`)
-   - Forward `AttributeModification`s to all `AttributesComponent`s on the GameObject
-4. On removal (manual or expiration), all of the above are cleanly reversed.
-
-Instant effects modify base values permanently and return `null` instead of a handle.
-
-## Authoring Guide
-
-1. Define stats:
-
-```csharp
-public class CharacterStats : AttributesComponent
-{
-    public Attribute Health = 100f;
-    public Attribute Speed = 5f;
-    public Attribute Defense = 10f;
-}
-```
-
-1. Create an `AttributeEffect` asset (Project view → Create → Wallstop Studios → Unity Helpers → Attribute Effect):
-
-- modifications: e.g., `{ attribute: "Speed", action: Multiplication, value: 1.5f }`
-- durationType: `Duration` with `duration = 5`
-- resetDurationOnReapplication: true to refresh timer on reapply
-- effectTags: e.g., `[ "Haste" ]`
-- cosmeticEffects: prefab with `CosmeticEffectData` + `CosmeticEffectComponent` scripts
-
-1. Apply/remove at runtime:
-
-```csharp
-GameObject player = ...;
-AttributeEffect haste = ...; // ScriptableObject reference
-EffectHandle? handle = player.ApplyEffect(haste);
-// ... later ...
-if (handle.HasValue)
-{
-    player.RemoveEffect(handle.Value);
-}
-```
-
-1. Query tags anywhere:
-
-```csharp
-if (player.HasTag("Stunned"))
-{
-    // Disable input, play animation, etc.
-}
-```
-
-## Recipes
-
-### 1) Buff with % Speed for 5s (refreshable)
-
-- Effect: Multiplication `Speed *= 1.5f`, `Duration=5`, `resetDurationOnReapplication=true`, tag `Haste`.
-- Apply to extend: reapply before expiry to reset the timer.
-
-### 2) Poison: −5 Health instantly and "Poisoned" tag for 10s
-
-- modifications: Addition `{ attribute: "Health", value: -5f }`
-- durationType: Duration `10s`
-- effectTags: `[ "Poisoned" ]`
-- cosmetics: particles + UI icon
-
-### 3) Equipment Aura: +10 Defense while equipped
-
-- durationType: Infinite
-- modifications: Addition `{ attribute: "Defense", value: 10f }`
-- Apply on equip, store handle, remove on unequip.
-
-### 4) One‑off Permanent Bonus
-
-- durationType: Instant (returns null)
-- modifications: Addition or Override on base value (no handle; cannot be removed).
-
-### 5) Stacking Multiple Instances
-
-- Apply the same effect multiple times → multiple `EffectHandle`s; remove one handle to remove one stack.
-- Use tags to gate behaviour regardless of which instance applied it.
-
-### 6) Shared vs Instanced Cosmetics
-
-- In `CosmeticEffectData`, set a component’s `RequiresInstance = true` for per‑application instances (e.g., particles).
-- Keep `RequiresInstance = false` for shared presenters (e.g., status icon overlay).
-
-## Best Practices
-
-- Use Addition for flat changes; Multiplication for percentage changes; Override sparingly (wins last).
-- Use the Attribute Metadata Cache generator to power editor dropdowns for `attribute` names and avoid typos.
-- Centralize tag strings as constants to prevent mistakes and improve refactor safety.
-- Prefer shared cosmetics where feasible; instantiate only when state must be isolated per application.
-- If reapplication should refresh timers, set `resetDurationOnReapplication = true` on the effect.
-
-## FAQ
-
-Q: Why didn’t I get an `EffectHandle`?
-
-- Instant effects modify the base value permanently and do not return a handle (`null`). Duration/Infinite do.
-
-Q: Do modifications stack across multiple effects?
-
-- Yes. Each `Attribute` applies all active modifications ordered by action: Addition → Multiplication → Override.
-
-Q: How do I remove just one instance of an effect?
-
-- Keep the `EffectHandle` returned from `ApplyEffect` and pass it to `RemoveEffect(handle)`.
-
-Q: Two systems apply the same tag. Who owns removal?
-
-- The tag is reference‑counted. Each application increments the count; removal decrements it. The tag is removed when the count reaches 0.
-
-Q: When should I use tags vs checking stats?
-
-- Use tags to represent categorical states (e.g., Stunned/Poisoned/Invulnerable) independent from numeric values. Check stats for numeric thresholds or calculations.
-
-## Troubleshooting
-
-- Attribute name doesn’t apply
-  - Ensure the `attribute` field matches a public/private `Attribute` field name on an `AttributesComponent` subclass.
-  - Regenerate the Attribute Metadata Cache to update editor dropdowns.
-
-- Effect didn’t clean up cosmetics
-  - Confirm `RequiresInstance` is set correctly and components either clean up themselves (`CleansUpSelf`) or are destroyed by `EffectHandler`.
-
-- Duration didn’t refresh on reapply
-  - Set `resetDurationOnReapplication = true` on the `AttributeEffect`.
-
-## Performance Notes
-
-- Attribute field discovery is cached (and can be precomputed by the Attribute Metadata Cache generator).
-- Tag queries provide overloads for lists to minimize allocations; prefer `IReadOnlyList<string>` overloads in hot paths.
-- Cosmetics can be a significant cost; prefer shared presenters when possible.
-
----
-
-Related:
-
-- README section: “Effects, Attributes, and Tags”
-- Attribute Metadata Cache (Editor Tools) for dropdowns and performance

package/MATH_AND_EXTENSIONS.md

@@ -1,316 +0,0 @@
-# Core Math & Extensions
-
-## TL;DR — Why Use These
-
-- Small helpers that fix everyday math and Unity annoyances: safe modulo, wrapped indices, robust equality, fast bounds math, color utilities, and more.
-- Copy/paste examples and diagrams show intent; use as building blocks in hot paths.
-
-This guide summarizes the math primitives and extension helpers in this package and shows how to apply them effectively, with examples, performance notes, and practical scenarios.
-
-Contents
-
-- [Numeric helpers](#numeric-helpers) — Positive modulo, wrapped arithmetic, approximate equality, clamping
-- [Geometry](#geometry) — Lines, ranges, parabolas, point-in-polygon, polyline simplification
-- [Unity extensions](#unity-extensions) — Rect/Bounds conversions, RectTransform bounds, camera bounds, bounds aggregation
-- [Color utilities](#color-utilities) — Averaging (LAB/HSV/Weighted/Dominant), hex conversion
-- [Collections](#collections) — IEnumerable helpers, buffering, infinite sequences
-- [Strings](#strings) — Casing, encoding/decoding, distance
-- [Direction helpers](#directions) — Enum conversions and operations
-- [Best Practices](#best-practices)
-
-<a id="numeric-helpers"></a>
-
-## Numeric Helpers
-
-- Positive modulo and wrap-around arithmetic
-  - Use `PositiveMod` to ensure non-negative modulo results for indices and cyclic counters.
-  - Use `WrappedAdd`/`WrappedIncrement` for ring buffer indexes and cursor navigation.
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Helper;
-
-int i = -1;
-i = i.PositiveMod(5); // 4
-i = i.WrappedAdd(2, 5); // 1
-
-float angle = -30f;
-float normalized = angle.PositiveMod(360f); // 330f
-```
-
-Diagram (wrap-around on a ring of size 5):
-
-```text
-Index:   0   1   2   3   4
-           ↖           ↙
-            \  +2 from 4  => 1
-
-Start at 4, add 2 → 6 → 6 % 5 = 1
-```
-
-- Approximate equality
-  - `float.Approximately(rhs, tolerance)` and `double.Approximately` add a magnitude-scaled fudge factor.
-
-Example:
-
-```csharp
-bool close = 0.1f.Approximately(0.10001f, 0.0001f); // true
-```
-
-- Generic `Clamp`
-  - `Clamp<T>(min, max)` works for any `IComparable<T>`.
-
-<a id="geometry"></a>
-
-## Geometry
-
-- `Line2D`/`Line3D` operations
-  - Length, direction, contains, intersections and closest point calculations.
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Math;
-var a = new Line2D(new Vector2(0,0), new Vector2(2,0));
-var b = new Line2D(new Vector2(1,-1), new Vector2(1,1));
-bool hit = a.Intersects(b); // true
-```
-
-Diagram (segment intersection):
-
-```text
-y↑           b.to (1,1)
- |             │
- |             │  b
- |   a ────────┼────────▶ x
- |         (1,0)×  ← intersection
- |             │
- |             │
- +─────────────┼────────
-               b.from (1,-1)
-```
-
-- `Range<T>` inclusive/exclusive ranges
-  - `Contains`, `Overlaps`, and factory methods for inclusive/exclusive endpoints.
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Math;
-var r = Range<int>.Inclusive(0, 10);
-bool inside = r.Contains(10); // true
-```
-
-- `Parabola`
-  - Construct by height/length or coefficients; evaluate by x or normalized position.
-
-Example:
-
-```csharp
-var p = new Parabola(maxHeight: 5f, length: 10f);
-if (p.TryGetValueAtNormalized(0.5f, out float y)) { /* y == 5 */ }
-```
-
-Diagram (normalized parabola):
-
-```text
-y↑          * vertex (0.5, 5)
- |        *
- |      *
- |    *
- |  *
- |*           *
- +────────*────────▶ x (t from 0..1)
- 0        0.5       1
-```
-
-- Point-in-polygon
-  - 2D and 3D (projected) tests; remarks on precision and assumptions.
-
-- Polyline simplification (Douglas–Peucker)
-  - `Simplify` (float epsilon) and `SimplifyPrecise` (double tolerance) reduce vertex count while preserving shape.
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Helper;
-List<Vector2> simplified = LineHelper.Simplify(points, epsilon: 0.1f);
-```
-
-Diagram (original vs simplified):
-
-```text
-Original:     *----*--*---*--*-----*
-Simplified:   *-----------*--------*
-
-Fewer vertices within epsilon of the original polyline.
-```
-
-Visual:
-![Polyline Simplification](Docs/Images/polyline_simplify.svg)
-
-Convex hull (monotone chain / Jarvis examples used by helpers):
-
-```text
-Points:     ·  ·   ·
-          ·      ·   ·
-            ·  ·
-
-Hull:     ┌───────────┐
-          │           │
-          └───────┬───┘
-                  └─┐
-```
-
-Visual:
-![Convex Hull](Docs/Images/convex_hull.svg)
-
-Edge Cases Gallery
-
-![Geometry Edge Cases](Docs/Images/geometry_edge_cases.svg)
-
-<a id="unity-extensions"></a>
-
-## Unity Extensions
-
-- Rect/Bounds conversions, RectTransform world bounds
-- Camera `OrthographicBounds`
-- Bounds aggregation from collections
-
-Example:
-
-```csharp
-Rect r = rectTransform.GetWorldRect();
-Bounds view = Camera.main.OrthographicBounds();
-```
-
-Diagrams:
-
-- RectTransform world rect (axis-aligned bounds of rotated UI):
-
-```text
-   • corner         ┌───────────────┐
-      ╲             │   AABB (r)    │
-       ╲  rotated   │   ┌──────┐    │
-        ╲ rectangle │  ╱│ UI  ╱│    │
-         •          │ ╱ └────╱─┘    │
-                    └───────────────┘
-```
-
-- Orthographic camera bounds (centered on camera):
-
-```text
-            ┌──────── view (Bounds) ────────┐
-            │           height=2*size      │
-            │         ┌────────────────┐    │
-   near ───▶│         │   camera FOV   │    │◀── far
-            │         └────────────────┘    │
-            └────────────────────────────────┘
-```
-
-<a id="color-utilities"></a>
-
-## Color Utilities
-
-- Averaging methods:
-  - LAB: perceptually accurate
-  - HSV: preserves vibrancy
-  - Weighted: luminance-aware
-  - Dominant: bucket-based mode
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Extension;
-Color avg = sprite.GetAverageColor(ColorAveragingMethod.LAB);
-string html = avg.ToHex();
-```
-
-Dominant color example (bucket-based):
-
-```csharp
-// Emphasize palette extraction (posterized sprites, UI swatches)
-var dominant = pixels.GetAverageColor(ColorAveragingMethod.Dominant, alphaCutoff: 0.05f);
-```
-
-Diagram (dominant buckets):
-
-```text
-RGB space buckets → counts
- [R][G][B] …  [R+Δ][G][B]  …  [R][G+Δ][B]  …
-          ↑ pick max bucket centroid as dominant
-```
-
-<a id="collections"></a>
-
-## Collections
-
-- Readable helpers: `AsList`, `ToLinkedList`, `OrderBy(Func)`
-- Utilities: `Infinite`, min-bounds from points, bounds aggregation
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Extension;
-foreach (var v in someList.Infinite()) { /* cycles forever */ }
-```
-
-Bounds from points example:
-
-```csharp
-// Compute BoundsInt for occupied grid cells
-BoundsInt? area = positions.GetBounds(inclusive: false);
-if (area is BoundsInt b) { /* use b */ }
-```
-
-Bounds aggregation example:
-
-```csharp
-// Merge many Bounds (e.g., from Renderers)
-Bounds? merged = renderers.Select(r => r.bounds).GetBounds();
-```
-
-<a id="strings"></a>
-
-## Strings
-
-- Casing conversions (Pascal, Camel, Snake, Kebab, Title)
-- Encoding helpers: `GetBytes`, `GetString`
-- Similarity: `LevenshteinDistance`
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Extension;
-string s = "hello_world";
-int distance = s.LevenshteinDistance("hello-world");
-```
-
-<a id="directions"></a>
-
-## Directions
-
-- Conversions between enum and vectors; splitting flag sets; combining
-
-Example:
-
-```csharp
-using WallstopStudios.UnityHelpers.Core.Extension;
-Vector2Int v = Direction.NorthWest.AsVector2Int(); // (-1, 1)
-```
-
-## Best Practices
-
-- Use `PositiveMod` instead of `%` for indices and angles when negatives are possible.
-- Prefer `SimplifyPrecise` for offline tooling; use `Simplify` during gameplay for speed.
-- Choose color averaging method per goal: LAB for perceptual palette, Weighted for speed, Dominant for swatches.
-- Favor IReadOnlyList/HashSet specializations to minimize allocations; pooled buffers are used where applicable.
-- Run Unity-dependent extensions (e.g., `RectTransform`, `Camera`, `Grid`) on the main thread.
-
-## Related Docs
-
-- Random performance details — [Random Performance](RANDOM_PERFORMANCE.md)
-- Serialization formats — [Serialization Guide](SERIALIZATION.md)
-- Effects system — [Effects System](EFFECTS_SYSTEM.md)
-- Relational Components — [Relational Components](RELATIONAL_COMPONENTS.md)