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

package/Docs/VisualGuide.md

@@ -6,45 +6,67 @@ If you're brand new to messaging systems, this visual guide will help you unders
 
 ### The Old Way (Spaghetti Code)
 
-````text
-┌─────────────┐
-│   Player    │───────┐
-└─────────────┘       │
-                      ├──→ ┌─────────┐
-┌─────────────┐       │    │   UI    │
-│   Enemy     │───────┤    └─────────┘
-└─────────────┘       │
-                      │    ┌─────────┐
-┌─────────────┐       └───→│  Audio  │
-│ Inventory   │───────────→└─────────┘
-└─────────────┘
-
-Problems:
-❌ Everyone needs to know everyone else
-❌ Hard to add/remove systems
-❌ Memory leaks from forgotten unsubscribes
-```text
+```mermaid
+graph LR
+    Player[Player]
+    Enemy[Enemy]
+    Inventory[Inventory]
+    UI[UI]
+    Audio[Audio]
+
+    Player -->|direct ref| UI
+    Player -->|direct ref| Audio
+    Enemy -->|direct ref| UI
+    Enemy -->|direct ref| Audio
+    Inventory -->|direct ref| Audio
+
+    style Player fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
+    style Enemy fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
+    style Inventory fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
+    style UI fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
+    style Audio fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
+```
+
+#### Problems
+
+- ❌ Everyone needs to know everyone else
+- ❌ Hard to add/remove systems
+- ❌ Memory leaks from forgotten unsubscribes
 
 ### The DxMessaging Way (Clean Separation)
 
-```text
-┌─────────┐                    ┌─────────┐
-│ Player  │──→ Message ──→     │   UI    │
-└─────────┘        ↓           └─────────┘
-                   │
-┌─────────┐        ↓           ┌─────────┐
-│ Enemy   │──→  BUS   ──→      │  Audio  │
-└─────────┘        ↓           └─────────┘
-                   │
-┌──────────┐       ↓           ┌──────────┐
-│Inventory │──→ Message ──→    │Analytics │
-└──────────┘                   └──────────┘
-
-Benefits:
-✅ Nobody knows about anyone else
-✅ Easy to add/remove systems
-✅ Zero memory leaks (automatic cleanup)
-```text
+```mermaid
+graph TB
+    Player[Player]
+    Enemy[Enemy]
+    Inventory[Inventory]
+    Bus((Message<br/>Bus))
+    UI[UI]
+    Audio[Audio]
+    Analytics[Analytics]
+
+    Player -->|message| Bus
+    Enemy -->|message| Bus
+    Inventory -->|message| Bus
+
+    Bus -->|notify| UI
+    Bus -->|notify| Audio
+    Bus -->|notify| Analytics
+
+    style Player fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+    style Enemy fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+    style Inventory fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+    style Bus fill:#ffd591,stroke:#d46b08,stroke-width:3px,color:#000
+    style UI fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+    style Audio fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+    style Analytics fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+```
+
+#### Benefits
+
+- ✅ Nobody knows about anyone else
+- ✅ Easy to add/remove systems
+- ✅ Zero memory leaks (automatic cleanup)
 
 ## 📨 The Three Message Types (Simple!)
 
@@ -66,9 +88,9 @@ msg.Emit();
 
 // Anyone can listen
 _ = token.RegisterUntargeted<GamePaused>(OnPause);
-```text
+```
 
-#### Real-world uses:
+#### Real-world uses
 
 - "Game paused!"
 - "Settings changed!"
@@ -90,9 +112,9 @@ heal.EmitGameObjectTargeted(playerObject);
 
 // Only the player listens
 _ = token.RegisterComponentTargeted<Heal>(this, OnHeal);
-```text
+```
 
-#### Real-world uses:
+#### Real-world uses
 
 - "Player, heal yourself!"
 - "Enemy #3, take damage!"
@@ -117,9 +139,9 @@ _ = token.RegisterGameObjectBroadcast<TookDamage>(enemyObject, OnThisEnemy);
 
 // OR achievement system can listen to ALL enemies
 _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyEnemy);
-```text
+```
 
-#### Real-world uses:
+#### Real-world uses
 
 - "I (player) took damage!"
 - "I (enemy) died!"
@@ -129,33 +151,49 @@ _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyEnemy);
 
 When you send a message, here's what happens:
 
-```text
-1. You create a message
-   var heal = new Heal(10);
-
-2. You emit it
-   heal.EmitGameObjectTargeted(player);
-
-3. [OPTIONAL] Interceptors check it
-   ┌─────────────────────────────┐
-   │ Is damage valid? (>0)       │
-   │ Should we clamp it? (<999)  │
-   │ Cancel bad messages? ❌     │
-   └─────────────────────────────┘
-
-4. Handlers receive it (your main logic)
-   ┌─────────────────────────────┐
-   │ priority: 0  → SaveSystem   │
-   │ priority: 5  → AudioSystem  │
-   │ priority: 10 → UISystem     │
-   └─────────────────────────────┘
-
-5. [OPTIONAL] Post-processors log it
-   ┌─────────────────────────────┐
-   │ Analytics.Track(...)        │
-   │ Debug.Log(...)              │
-   └─────────────────────────────┘
-```text
+```mermaid
+sequenceDiagram
+    participant You as Your Code
+    participant Msg as Message
+    participant Int as Interceptors<br/>(Optional)
+    participant H0 as Handler<br/>priority: 0
+    participant H5 as Handler<br/>priority: 5
+    participant H10 as Handler<br/>priority: 10
+    participant PP as Post-Processors<br/>(Optional)
+
+    Note over You: 1. Create message
+    You->>Msg: var heal = new Heal(10);
+
+    Note over You,Msg: 2. Emit message
+    You->>Msg: heal.EmitGameObjectTargeted(player);
+
+    Note over Int: 3. Validate & Normalize
+    Msg->>Int: Check message
+    Int->>Int: Is valid? (>0)<br/>Clamp if needed (<999)
+    alt Invalid message
+        Int--xMsg: ❌ Cancel
+    else Valid message
+        Int->>H0: ✅ Continue
+    end
+
+    Note over H0,H10: 4. Execute handlers (by priority)
+    H0->>H0: SaveSystem runs first
+    H0->>H5: Next priority
+    H5->>H5: AudioSystem runs
+    H5->>H10: Next priority
+    H10->>H10: UISystem runs last
+
+    Note over PP: 5. Analytics & Logging
+    H10->>PP: All handlers complete
+    PP->>PP: Analytics.Track(...)<br/>Debug.Log(...)
+```
+
+### Key points
+
+- **Step 1-2:** You create and emit the message
+- **Step 3 (Optional):** Interceptors can validate, modify, or cancel
+- **Step 4:** Handlers run in priority order (lower number = earlier)
+- **Step 5 (Optional):** Post-processors run after everything (perfect for analytics)
 
 ## 🎮 Your First Message (3 Easy Steps)
 
@@ -169,7 +207,7 @@ using DxMessaging.Core.Attributes;
 public readonly partial struct Heal {
     public readonly int amount;
 }
-````
+```
 
 #### What are those `[DxSomething]` tags?
 
@@ -228,20 +266,29 @@ healMsg.EmitComponentTargeted(playerComponent);
 
 ### Pattern: Scene Transition
 
-```text
-SceneManager               AudioSystem
-     │                          │
-     │  [SceneChanged]          │
-     ├────────────────────────→ │ FadeOutMusic()
-     │                          │
-     │                     SaveSystem
-     │                          │
-     │  [SceneChanged]          │
-     └────────────────────────→ │ SaveGame()
-
-All independent! No coupling!
+```mermaid
+sequenceDiagram
+    participant SM as SceneManager
+    participant Bus as Message Bus
+    participant Audio as AudioSystem
+    participant Save as SaveSystem
+
+    Note over SM: Scene is changing
+    SM->>Bus: SceneChanged(sceneIndex: 2)
+
+    Note over Bus: Message broadcast to all listeners
+
+    Bus->>Audio: SceneChanged received
+    Audio->>Audio: FadeOutMusic()
+
+    Bus->>Save: SceneChanged received
+    Save->>Save: SaveGame()
+
+    Note over Audio,Save: ✅ All independent!<br/>No coupling!
 ```
 
+**Why this works:** AudioSystem and SaveSystem don't know about SceneManager or each other. They just listen for `SceneChanged` messages and react independently.
+
 Code:
 
 ```csharp
@@ -261,16 +308,23 @@ _ = saveToken.RegisterUntargeted<SceneChanged>(OnScene);
 
 ### Pattern: Player Input → Action
 
-```text
-InputSystem          Player
-     │                 │
-     │   [Jump]        │
-     ├───────────────→ │ ApplyForce()
-     │                 │
+```mermaid
+sequenceDiagram
+    participant Input as InputSystem
+    participant Bus as Message Bus
+    participant Player as Player
+
+    Note over Input: User presses Space
+    Input->>Bus: Jump(force: 10f)<br/>[Targeted to Player]
 
-Decoupled! Input doesn't need reference to Player.
+    Bus->>Player: Jump message received
+    Player->>Player: ApplyForce()<br/>rb.AddForce(...)
+
+    Note over Input,Player: ✅ Decoupled!<br/>Input doesn't reference Player
 ```
 
+**Why this works:** InputSystem doesn't need a reference to Player. It just sends a `Jump` message targeted at the player, and the player responds.
+
 Code:
 
 ```csharp
@@ -291,15 +345,29 @@ void OnJump(ref Jump msg) {
 
 ### Pattern: Achievement Tracking
 
-````text
-Any System                Achievement System
-     │                           │
-     │  [Any Message]            │
-     ├─────────────────────────→ │ CheckProgress()
-     │                           │ UnlockIfReady()
+```mermaid
+sequenceDiagram
+    participant E as Enemy
+    participant P as Player
+    participant C as Chest
+    participant Bus as Message Bus
+    participant Ach as Achievement System
+
+    Note over Ach: Listens to ALL messages
+
+    E->>Bus: EnemyKilled
+    Bus->>Ach: CheckProgress()<br/>UnlockIfReady()
 
-Achievements see EVERYTHING without coupling!
-```text
+    P->>Bus: LevelCompleted
+    Bus->>Ach: CheckProgress()<br/>UnlockIfReady()
+
+    C->>Bus: ChestOpened
+    Bus->>Ach: CheckProgress()<br/>UnlockIfReady()
+
+    Note over Ach: ✅ Sees EVERYTHING<br/>without coupling!
+```
+
+**Why this works:** Achievement System uses `RegisterGlobalAcceptAll()` to observe every message type, tracking progress across the entire game without any system knowing about it.
 
 Code:
 
@@ -315,7 +383,7 @@ public class AchievementSystem : MessageAwareComponent {
         );
     }
 }
-````
+```
 
 ## 🚦 When to Use Which Message Type
 
@@ -344,64 +412,51 @@ Think of DxMessaging like a restaurant:
 
 ### Untargeted = Restaurant Announcement
 
-````text
-"Attention all customers: We're closing in 10 minutes!"
-→ Everyone hears it
-```text
+> "Attention all customers: We're closing in 10 minutes!"
+>
+> → Everyone hears it
 
 ### Targeted = Waiter Delivering Food
 
-```text
-"Order for table 5: Here's your burger"
-→ Only table 5 gets it
-````
+> "Order for table 5: Here's your burger"
+>
+> → Only table 5 gets it
 
 ### Broadcast = Customer Calling Waiter
 
-````text
-"Excuse me, I need a refill!" (from table 3)
-→ Comes from table 3
-→ Any available waiter can respond
-→ Manager might track it for statistics
-```text
+> "Excuse me, I need a refill!" (from table 3)
+>
+> → Comes from table 3
+>
+> → Any available waiter can respond
+>
+> → Manager might track it for statistics
 
 ## 🔍 Debugging Visualized
 
 DxMessaging has built-in Inspector support!
 
-```text
-MessagingComponent Inspector:
-┌─────────────────────────────────────┐
-│ Message History (last 10)           │
-│ ┌─────────────────────────────────┐ │
-│ │ 12:34:05 - Heal → Player (50)   │ │
-│ │ 12:34:03 - Jump → Player        │ │
-│ │ 12:34:01 - GamePaused (global)  │ │
-│ └─────────────────────────────────┘ │
-│                                     │
-│ Registrations:                      │
-│ ┌─────────────────────────────────┐ │
-│ │ ✓ Heal (priority: 0, 5 calls)   │ │
-│ │ ✓ Jump (priority: 0, 2 calls)   │ │
-│ │ ✓ TookDamage (priority: 10)     │ │
-│ └─────────────────────────────────┘ │
-└─────────────────────────────────────┘
-````
+### MessagingComponent Inspector
 
-## ⚡ Performance at a Glance
+#### Message History (last 10)
 
-```text
-Traditional C# Event: ████░░░░░░ (baseline)
-DxMessaging:          █████░░░░░ (~10ns slower, negligible)
+- `12:34:05 - Heal → Player (50)`
+- `12:34:03 - Jump → Player`
+- `12:34:01 - GamePaused (global)`
 
-Memory:
-Traditional Events:   ████████░░ (can leak!)
-DxMessaging:          ██░░░░░░░░ (zero leaks, struct messages)
+##### Registrations
 
-Coupling:
-Traditional Events:   ██████████ (tight!)
-DxMessaging:          ░░░░░░░░░░ (zero!)
-```
+- ✓ Heal (priority: 0, 5 calls)
+- ✓ Jump (priority: 0, 2 calls)
+- ✓ TookDamage (priority: 10)
+
+## ⚡ Performance at a Glance
+
+| Metric       | Traditional C# Events | DxMessaging                         |
+| ------------ | --------------------- | ----------------------------------- |
+| **Speed**    | ⚡⚡⚡⚡ (baseline)   | ⚡⚡⚡⚡ (~10ns slower, negligible) |
+| **Memory**   | ⚠️ Can leak!          | ✅ Zero leaks (struct messages)     |
+| **Coupling** | ❌ Tight coupling     | ✅ Zero coupling                    |
 
 **Bottom line:** Slightly slower than raw events, but:
 
@@ -412,57 +467,116 @@ DxMessaging:          ░░░░░░░░░░ (zero!)
 
 ## 🎓 Learning Path
 
-```text
-START HERE
-    │
-    ├─→ 1. Read this Visual Guide (5 min) ✓
-    │
-    ├─→ 2. Try Quick Start example (5 min)
-    │      [Define → Listen → Send]
-    │
-    ├─→ 3. Import Mini Combat sample (10 min)
-    │      [See it in action!]
-    │
-    ├─→ 4. Read Common Patterns (15 min)
-    │      [Real-world solutions]
-    │
-    └─→ 5. Build your first feature! (30 min)
-        [You're ready!]
+```mermaid
+graph TD
+    Start[START HERE<br/>Read this Visual Guide<br/>5 min ✓]
+    Start --> Step2[Try Quick Start example<br/>5 min<br/>Define → Listen → Send]
+    Step2 --> Step3[Import Mini Combat sample<br/>10 min<br/>See it in action!]
+    Step3 --> Step4[Read Common Patterns<br/>15 min<br/>Real-world solutions]
+    Step4 --> Step5[Build your first feature!<br/>30 min<br/>You're ready!]
+
+    style Start fill:#91d5ff,stroke:#096dd9,stroke-width:3px,color:#000
+    style Step5 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
 ```
 
 ## 🆘 Common Beginner Questions
 
 ### "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 if you're not in Unity.
 
-**For pure C#:** No, you can use `MessageRegistrationToken` directly.
+**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
+
+```csharp
+// ❌ DON'T: Try to target multiple entities
+msg.EmitComponentTargeted(player1);
+msg.EmitComponentTargeted(player2);  // Feels wrong, right?
 
-- Use **Untargeted** if everyone should hear it
-- Use **Broadcast** if it's from a source and many can observe
+// ✅ 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: