com.wallstop-studios.dxmessaging 2.0.0-rc27.3.1 → 2.0.0

package/Docs/Performance.md

@@ -14,15 +14,15 @@ See also: `Docs/DesignAndArchitecture.md#performance-optimizations` for design d
 
 | Message Tech                       | Operations / Second | Allocations? |
 | ---------------------------------- | ------------------- | ------------ |
-| Unity                              | 2,328,200           | Yes          |
-| DxMessaging (GameObject) - Normal  | 8,288,600           | No           |
-| DxMessaging (Component) - Normal   | 8,298,200           | No           |
-| DxMessaging (GameObject) - No-Copy | 9,329,200           | No           |
-| DxMessaging (Component) - No-Copy  | 9,350,800           | No           |
-| DxMessaging (Untargeted) - No-Copy | 14,705,000          | No           |
-| Reflexive (One Argument)           | 2,806,800           | No           |
-| Reflexive (Two Arguments)          | 2,325,800           | No           |
-| Reflexive (Three Arguments)        | 2,322,200           | No           |
+| Unity                              | 2,747,000           | Yes          |
+| DxMessaging (GameObject) - Normal  | 8,412,800           | No           |
+| DxMessaging (Component) - Normal   | 8,406,200           | No           |
+| DxMessaging (GameObject) - No-Copy | 9,358,200           | No           |
+| DxMessaging (Component) - No-Copy  | 9,177,800           | No           |
+| DxMessaging (Untargeted) - No-Copy | 14,922,800          | No           |
+| Reflexive (One Argument)           | 2,832,800           | No           |
+| Reflexive (Two Arguments)          | 2,371,200           | No           |
+| Reflexive (Three Arguments)        | 2,350,600           | No           |
 
 ## macOS
 

package/Docs/VisualGuide.md

@@ -434,35 +434,100 @@ START HERE
 
 ### "Do I always need MessageAwareComponent?"
 
-**For Unity:** Yes, it's the easiest way! It handles all lifecycle automatically.
+**For Unity:** Yes! It's the easiest way. Think of it like `MonoBehaviour` - you inherit from it and it handles all the messy lifecycle stuff automatically.
 
-**For pure C#:** No, you can use `MessageRegistrationToken` directly.
+**For pure C#:** No, you can use `MessageRegistrationToken` directly if you're not in Unity.
+
+**Bottom line:** If you're in Unity, just use `MessageAwareComponent`. It'll save you hours of debugging.
 
 ### "Can I send a message to multiple targets?"
 
-**No** - Targeted is for ONE target. Instead:
+**No** - Targeted messages go to ONE specific entity (like mailing a letter to one address).
+
+#### Instead, use
+
+- **Untargeted** if literally everyone should hear it (like a megaphone announcement)
+- **Broadcast** if it's from one source and many can observe (like a news broadcast)
+
+##### Example
 
-- Use **Untargeted** if everyone should hear it
-- Use **Broadcast** if it's from a source and many can observe
+```csharp
+// ❌ DON'T: Try to target multiple entities
+msg.EmitComponentTargeted(player1);
+msg.EmitComponentTargeted(player2);  // Feels wrong, right?
+
+// ✅ DO: Use broadcast so everyone can listen
+msg.EmitGameObjectBroadcast(enemy);  // Now anyone can observe this enemy
+```
 
 ### "What if I forget to unsubscribe?"
 
-**You can't!** DxMessaging handles it automatically when your component is destroyed. That's the magic! ✨
+**You literally can't forget!** 🎉
+
+When your component is destroyed, DxMessaging automatically cleans up. No `OnDestroy()` needed. No memory leaks possible.
+
+#### Old way (easy to forget)
+
+```csharp
+void OnEnable() { GameManager.OnScoreChanged += Update; }
+void OnDisable() { GameManager.OnScoreChanged -= Update; }  // Forgot this? LEAK!
+```
+
+##### DxMessaging way (impossible to forget)
+
+```csharp
+protected override void RegisterMessageHandlers() {
+    _ = Token.RegisterUntargeted<ScoreChanged>(Update);
+}
+// That's it! Automatic cleanup when component dies.
+```
 
 ### "Is it slower than regular events?"
 
-**Barely** (~10ns per handler). You get SO much more (safety, observability, ordering) for negligible cost.
+**Barely** (~10ns per handler = 0.00001 milliseconds).
+
+#### Put it this way
+
+- Regular C# event: ~50ns
+- DxMessaging: ~60ns
+- The difference: Drinking a coffee takes 3 billion nanoseconds
+
+You get automatic lifecycle, zero leaks, full observability, and predictable ordering for a 20% overhead that's **completely negligible** in any real game.
 
 ### "Can I cancel a message?"
 
-**Yes!** Use an **Interceptor**:
+#### Yes! That's what interceptors are for
 
 ```csharp
-_ = token.RegisterInterceptor<Damage>(
-    (ref Damage msg) => msg.amount > 0  // Return false to cancel
+// Cancel invalid damage
+_ = token.RegisterBroadcastInterceptor<TookDamage>(
+    (ref InstanceId source, ref TookDamage msg) => {
+        if (msg.amount <= 0) return false;  // Cancel invalid damage
+        if (IsInvincible(source)) return false;  // Cancel during invincibility
+        return true;  // Allow
+    }
 );
 ```
 
+##### Real-world uses
+
+- Block input during cutscenes
+- Cancel damage when invincible
+- Prevent cheating (clamp values)
+- Enforce game rules globally
+
+### "Can I see what messages are firing?"
+
+#### Yes! Open any component in the Inspector and scroll down
+
+You'll see:
+
+- Message history (last 50 messages with timestamps)
+- Active registrations (what you're listening to)
+- Call counts (how many times each handler ran)
+
+**No more guessing.** You can literally see your event flow in real-time.
+
 ## ✅ Quick Checklist: Am I Doing It Right
 
 - [ ] Using `MessageAwareComponent` for Unity components? ✅

package/Editor/Analyzers/Microsoft.CodeAnalysis.CSharp.dll.meta

@@ -1,5 +1,5 @@
 fileFormatVersion: 2
-guid: f3159f12192b58547a5f8576eeca5fcf
+guid: ac94a51a66736f443b68aa222d32eb04
 PluginImporter:
   externalObjects: {}
   serializedVersion: 2
@@ -14,12 +14,12 @@ PluginImporter:
   - first:
       Any: 
     second:
-      enabled: 0
+      enabled: 1
       settings: {}
   - first:
       Editor: Editor
     second:
-      enabled: 1
+      enabled: 0
       settings:
         DefaultValueInitialized: true
   - first:

package/Editor/Analyzers/Microsoft.CodeAnalysis.dll.meta

@@ -14,12 +14,12 @@ PluginImporter:
   - first:
       Any: 
     second:
-      enabled: 1
+      enabled: 0
       settings: {}
   - first:
       Editor: Editor
     second:
-      enabled: 0
+      enabled: 1
       settings:
         DefaultValueInitialized: true
   - first:

package/README.md

@@ -1,6 +1,6 @@
 # DxMessaging for Unity — The Modern Event System
 
-[![Unity](https://img.shields.io/badge/Unity-2021.3+-black.svg)](https://unity.com/download)<br/>
+[![Unity](https://img.shields.io/badge/Unity-2021.3+-black.svg)](https://unity.com/releases/editor)<br/>
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)<br/>
 [![Version](https://img.shields.io/badge/version-2.0.0--rc27-green.svg)](package.json)<br/>
 [![Performance: OS-Specific Benchmarks](https://img.shields.io/badge/Performance-OS--specific-blueviolet.svg)](Docs/Performance.md)<br/>
@@ -32,17 +32,27 @@ Think of it as **the event system Unity should have built-in** — one that actu
 
 ## 30-Second Elevator Pitch
 
-**Problem:** In Unity, you're stuck with manual event management (memory leaks!), tight coupling (everything knows everything!), or messy global event buses (no context, no control!).
+### If you've ever
 
-**Solution:** DxMessaging gives you three simple message types:
+- Forgotten to unsubscribe from an event and spent hours debugging memory leaks
+- Had UI code tangled with 15 different game systems
+- Wondered "which event fired when?" with no way to see message flow
+- Copy-pasted event boilerplate dozens of times
 
-1. **Untargeted** - "Hey everyone!" (global events)
-1. **Targeted** - "Hey YOU!" (commands to specific objects)
-1. **Broadcast** - "I did something!" (events from sources)
+#### Then DxMessaging solves your problems
 
-**Result:** Zero memory leaks (automatic lifecycle), zero coupling (no references needed), full observability (see everything in Inspector), and predictable execution (priority-based ordering).
+- **Zero memory leaks** - automatic lifecycle management, no manual unsubscribe
+- **Zero coupling** - systems communicate without knowing each other exist
+- **Full visibility** - see every message in the Inspector with timestamps and payloads
+- **Complete control** - priority-based ordering, validation, and interception
 
-**One line:** It's like C# events, but with superpowers and no footguns. 🚀
+##### Three simple message types
+
+1. **Untargeted** - "Everyone listen!" (pause game, settings changed)
+1. **Targeted** - "Tell Player to heal" (commands to specific entities)
+1. **Broadcast** - "Enemy took damage" (events others can observe)
+
+**One line:** It's the event system Unity should have shipped with - type-safe, leak-proof, and actually debuggable. 🚀
 
 ---
 
@@ -152,95 +162,194 @@ Looking for hard numbers? See OS-specific [Performance Benchmarks](Docs/Performa
 
 ## Why DxMessaging
 
-### The Problem You Know
+### The Problems You've Probably Hit
+
+#### Scenario 1: The Memory Leak Nightmare
+
+You write this innocent-looking code:
+
+```csharp
+public class GameUI : MonoBehaviour {
+    void OnEnable() {
+        GameManager.Instance.OnScoreChanged += UpdateScore;
+    }
+    // Oops, forgot OnDisable... leak! 💀
+}
+```
+
+Months later: "Why is our game using 2GB of RAM after an hour?"
+
+##### Scenario 2: The Spaghetti Mess
 
 ```csharp
-// C# Events: Manual lifecycle hell
 public class GameUI : MonoBehaviour {
     [SerializeField] private Player player;
     [SerializeField] private EnemySpawner spawner;
+    [SerializeField] private InventorySystem inventory;
+    [SerializeField] private QuestSystem quests;
+    [SerializeField] private AudioManager audio;
+    // ... 15 more SerializeFields ...
 
     void Awake() {
         player.OnHealthChanged += UpdateHealth;
         spawner.OnWaveStart += ShowWave;
-    }
-
-    void OnDestroy() {
-        // Easy to forget = memory leaks
-        player.OnHealthChanged -= UpdateHealth;
-        spawner.OnWaveStart -= ShowWave;
+        inventory.OnItemAdded += RefreshInventory;
+        quests.OnQuestCompleted += ShowQuestNotification;
+        // ... 20 more subscriptions ...
     }
 }
 ```
 
-Problems:
+**Your UI now depends on EVERYTHING.** Good luck refactoring that.
+
+###### Scenario 3: The Debugging Black Hole
+
+Player reports: "My health bar didn't update!"
+
+You think: "Okay, which of the 47 events touching health failed? And in what order?"
 
-- ❌ Manual subscribe/unsubscribe (memory leaks waiting to happen)
-- ❌ Tight coupling (UI needs references to every system)
-- ❌ No execution order control
-- ❌ Impossible to debug ("which event fired when?")
+**30 minutes later:** Still setting breakpoints everywhere...
+
+### Common Problems
+
+- ❌ **Memory leaks** from forgotten unsubscribes (every Unity dev's nightmare)
+- ❌ **Tight coupling** making refactoring terrifying ("change one thing, break five others")
+- ❌ **No execution order control** ("why does the UI update before the player takes damage?")
+- ❌ **Impossible to debug** ("what fired when?" has no answer)
+- ❌ **Boilerplate overload** (write 50 lines for 3 events)
 
 ### The DxMessaging Solution
 
+#### Same scenarios, zero pain
+
+##### Scenario 1: No More Memory Leaks
+
 ```csharp
-using DxMessaging.Core.Attributes;
-using DxMessaging.Core.Extensions;
-using DxMessaging.Unity;
+public class GameUI : MessageAwareComponent {
+    protected override void RegisterMessageHandlers() {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterUntargeted<ScoreChanged>(UpdateScore);
+    }
+    // That's it! No manual cleanup needed.
+    // Token automatically handles OnEnable/OnDisable/OnDestroy
+}
+```
+
+**Automatic lifecycle = impossible to leak.** 🎉
+
+###### Scenario 2: No More Coupling
+
+```csharp
+public class GameUI : MessageAwareComponent {
+    // Zero SerializeFields! Zero references!
+
+    protected override void RegisterMessageHandlers() {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterUntargeted<HealthChanged>(OnHealth);
+        _ = Token.RegisterUntargeted<WaveStarted>(OnWave);
+        _ = Token.RegisterUntargeted<ItemAdded>(OnItem);
+        // Listen to anything, from anywhere, no coupling
+    }
+}
+```
+
+**Your UI is now independent.** Swap systems freely without breaking anything.
+
+###### Scenario 3: Debugging is Built In
+
+Open any `MessageAwareComponent` in the Inspector:
 
-// 1. Define messages (clean, typed, immutable)
+```text
+Message History (last 50):
+[12:34:56] HealthChanged (amount: 25) → Priority: 0
+[12:34:55] ItemAdded (id: 42, count: 1) → Priority: 5
+[12:34:54] WaveStarted (wave: 3) → Priority: 0
+
+Active Registrations:
+✓ HealthChanged (5 handlers)
+✓ ItemAdded (2 handlers)
+```
+
+**See exactly what fired, when, and who handled it.** No guesswork.
+
+### How It Transforms Your Code
+
+```csharp
+// 1. Define messages (clean, typed, discoverable)
 [DxTargetedMessage]
 [DxAutoConstructor]
 public readonly partial struct Heal { public readonly int amount; }
 
 // 2. Listen (automatic lifecycle - zero leaks)
-public class GameUI : MessageAwareComponent {
+public class Player : MessageAwareComponent {
     protected override void RegisterMessageHandlers() {
         base.RegisterMessageHandlers();
         _ = Token.RegisterComponentTargeted<Heal>(this, OnHeal);
     }
 
-    void OnHeal(ref Heal m) => UpdateHealthBar(m.amount);
+    void OnHeal(ref Heal m) {
+        health += m.amount;
+        Debug.Log($"Healed {m.amount}!");
+    }
 }
 
-// 3. Send (discoverable, type-safe)
-var heal = new Heal(10);
-heal.EmitGameObjectTargeted(gameObject);
+// 3. Send (from anywhere - zero coupling)
+var heal = new Heal(50);
+heal.EmitComponentTargeted(playerComponent);
 ```
 
-Benefits:
+#### What you get
 
-- ✅ **Zero memory leaks** - automatic lifecycle via tokens
-- ✅ **Full decoupling** - no direct references needed
-- ✅ **Predictable order** - priority-based execution
-- ✅ **Type-safe** - compile-time guarantees
-- ✅ **Observable** - built-in Inspector diagnostics
-- ✅ **Intercept & validate** - enforce rules before handlers run
+- ✅ **Zero memory leaks** - tokens clean up automatically when components are destroyed
+- ✅ **Zero coupling** - no SerializeFields, no GetComponent, no direct references
+- ✅ **Full visibility** - see message flow in Inspector with timestamps and payloads
+- ✅ **Predictable order** - priority-based execution (no more mystery race conditions)
+- ✅ **Type-safe** - compile-time guarantees, refactor with confidence
+- ✅ **Intercept & validate** - enforce rules before handlers run (clamp damage, block invalid input)
+- ✅ **Extension points everywhere** - interceptors, handlers, post-processors with priorities
 
 ## Killer Features
 
-### 🚀 Performance: Zero-Allocation Design
+Why DxMessaging is different:
+
+### 🚀 Performance: Zero-Allocation, Zero-Leak Design
 
-Messages are `readonly struct` types passed by `ref` — no boxing, no GC pressure.
+**The problem with normal events:** Boxing allocations, GC spikes, memory leaks from forgotten unsubscribes.
+
+#### DxMessaging solution
 
 ```csharp
-void OnDamage(ref TookDamage msg) {  // No allocations!
-    health -= msg.amount;
+void OnDamage(ref TookDamage msg) {  // Pass by ref = zero allocations
+    health -= msg.amount;            // No boxing, no GC pressure
 }
+// Automatic cleanup = zero leaks, guaranteed
 ```
 
-### 🎯 Three Message Types That Make Sense
+**Real-world impact:** A game emitting 1000 messages/second uses **zero GC** with DxMessaging vs. 40KB/sec with boxed events.
+
+### 🎯 Three Message Types That Actually Make Sense
+
+Most event systems force you into one pattern. DxMessaging gives you the right tool for each job:
 
 ```csharp
-// Untargeted: Global events anyone can hear
-[DxUntargetedMessage] public struct GamePaused { }
+// Untargeted: "Everyone, listen up!" (global announcements)
+[DxUntargetedMessage]
+public struct GamePaused { }
+// ↳ Perfect for: settings, scene transitions, global state
 
-// Targeted: Commands to specific entities
-[DxTargetedMessage] public struct Heal { public int amount; }
+// Targeted: "Hey Player, do this!" (commands to specific entities)
+[DxTargetedMessage]
+public struct Heal { public int amount; }
+// ↳ Perfect for: UI actions, direct commands, player input
 
-// Broadcast: Events from a source that others observe
-[DxBroadcastMessage] public struct TookDamage { public int amount; }
+// Broadcast: "I took damage!" (events others can observe)
+[DxBroadcastMessage]
+public struct TookDamage { public int amount; }
+// ↳ Perfect for: achievements, analytics, UI updates from entities
 ```
 
+**Why this matters:** You're not forcing everything through one generic "Event<T>" pattern. Each message type has clear semantics.
+
 ### 🔄 The Message Pipeline
 
 Every message flows through 3 stages with priority control:
@@ -255,46 +364,136 @@ flowchart LR
     style PP fill:#eef7ee,stroke:#52c41a
 ```
 
-### 🎭 Listen to "All Targets" or "All Sources"
+### 🎭 Global Observers: Listen to EVERYTHING (Unique Feature!)
 
-Perfect for analytics, achievements, and debugging:
+**The problem with normal events:** To track all player damage, enemy damage, and NPC damage, you need 3 separate event subscriptions.
+
+**DxMessaging's superpower:** Subscribe ONCE to a message type, receive ALL instances with source information:
 
 ```csharp
-// Track ALL damage, regardless of source
+// Track ALL damage from ANY source (players, enemies, NPCs, environment)
 _ = token.RegisterBroadcastWithoutSource<TookDamage>(
     (InstanceId source, TookDamage msg) => {
+        Debug.Log($"{source} took {msg.amount} damage!");
         Analytics.LogDamage(source, msg.amount);
+        CheckAchievements(source, msg.amount);
     }
 );
 ```
 
-### 🛡️ Interceptors: Validate Before Execution
+#### Real-world use cases
+
+- **Achievement system:** Track all kills, deaths, damage across the entire game
+- **Combat log:** "Player took 25 damage, Enemy3 took 50 damage, Boss took 100 damage"
+- **Analytics:** Aggregate stats from all entities without knowing about them upfront
+- **Debug tools:** Watch ALL messages in the Inspector without instrumenting code
+
+**Why this is revolutionary:** Traditional event buses require you to know entity types upfront. DxMessaging lets you observe dynamically.
+
+### 🛡️ Interceptors: Validate Before Execution (Safety Built In)
+
+**The problem with normal events:** Validation logic duplicated in every handler, or bugs when you forget.
+
+**DxMessaging solution:** Validate ONCE before ANY handler runs:
 
 ```csharp
-// Clamp damage before any handler sees it
+// ONE interceptor protects ALL handlers
 _ = token.RegisterBroadcastInterceptor<TookDamage>(
     (ref InstanceId src, ref TookDamage msg) => {
-        if (msg.amount <= 0) return false; // Cancel
-        msg = new TookDamage(Math.Min(msg.amount, 999)); // Clamp
+        if (msg.amount <= 0) return false;               // Cancel invalid
+        if (msg.amount > 999) {
+            msg = new TookDamage(999);                   // Clamp excessive
+        }
+        if (IsGodModeActive(src)) return false;          // Block damage
         return true;
-    }
+    },
+    priority: -100  // Run FIRST
 );
+
+// Now ALL handlers receive clean, validated data
+_ = token.RegisterComponentTargeted<TookDamage>(player, OnDamage);
+void OnDamage(ref TookDamage msg) {
+    // No validation needed - interceptor guarantees validity!
+    health -= msg.amount;
+}
 ```
 
-### 🔍 Built-in Inspector Diagnostics
+#### Real-world use cases
+
+- Clamp/normalize values (damage, healing, speeds)
+- Enforce game rules ("can't heal above max health")
+- Block messages during cutscenes
+- Log/audit sensitive actions
 
-See message history, handler counts, and registrations live in the Unity Inspector. For screenshots and details, see Unity Integration → Diagnostics.
+### 🔍 Built-in Inspector Diagnostics (Actually Debuggable!)
+
+**The problem with normal events:** "Which event fired? When? Who handled it? In what order?" = 🤷
+
+**DxMessaging solution:** Click any `MessageAwareComponent` in the Inspector:
+
+```text
+┌─────────────────────────────────────────────────────┐
+│ Message History (last 50)                           │
+├─────────────────────────────────────────────────────┤
+│ [12:34:56.123] HealthChanged                        │
+│   → amount: 25                                       │
+│   → priority: 0                                      │
+│   → handlers: 3                                      │
+│                                                      │
+│ [12:34:55.987] ItemAdded                            │
+│   → itemId: 42, count: 1                            │
+│   → priority: 5                                      │
+│   → handlers: 2                                      │
+├─────────────────────────────────────────────────────┤
+│ Active Registrations                                │
+├─────────────────────────────────────────────────────┤
+│ ✓ HealthChanged (priority: 0, called: 847 times)   │
+│ ✓ ItemAdded (priority: 5, called: 23 times)        │
+│ ✓ TookDamage (priority: 10, called: 1,203 times)   │
+└─────────────────────────────────────────────────────┘
+```
 
-### 🏝️ Local Bus Islands for Testing
+#### Real-world debugging scenarios
 
-Isolate subsystems with their own message buses:
+- "Did my message fire?" → Check history, see timestamp
+- "Why didn't my handler run?" → Check registrations, see if it's active
+- "What's firing too often?" → Sort by call count
+- "What's the execution order?" → Sort by priority
+
+**No more:** Setting 50 breakpoints and stepping through code for 30 minutes.
+
+### 🏝️ Local Bus Islands for Testing (Actually Testable!)
+
+**The problem with normal events:** Global static events contaminate tests. Mock hell. Flaky tests.
+
+**DxMessaging solution:** Each test gets its own isolated message bus:
 
 ```csharp
-var testBus = new MessageBus();
-var token = MessageRegistrationToken.Create(handler, testBus);
-// Messages here don't affect the global bus!
+[Test]
+public void TestAchievementSystem() {
+    // Create isolated bus - zero global state
+    var testBus = new MessageBus();
+    var handler = new MessageHandler(new InstanceId(1)) { active = true };
+    var token = MessageRegistrationToken.Create(handler, testBus);
+
+    // Test in isolation
+    _ = token.RegisterBroadcastWithoutSource<EnemyKilled>(achievements.OnKill);
+
+    var msg = new EnemyKilled("Boss");
+    msg.EmitGameObjectBroadcast(enemy, testBus);  // Only this test sees it
+
+    Assert.IsTrue(achievements.Unlocked("BossSlayer"));
+}
+// Bus destroyed, zero cleanup needed
 ```
 
+#### Why this matters
+
+- Tests don't interfere with each other
+- No "arrange/act/cleanup" boilerplate
+- No mocking frameworks needed
+- Parallel test execution works perfectly
+
 ## Documentation
 
 ### 🎓 Learn