com.wallstop-studios.dxmessaging 2.0.0 → 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]
+
+    Bus->>Player: Jump message received
+    Player->>Player: ApplyForce()<br/>rb.AddForce(...)
 
-Decoupled! Input doesn't need reference to Player.
+    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
 
-Achievements see EVERYTHING without coupling!
-```text
+    E->>Bus: EnemyKilled
+    Bus->>Ach: CheckProgress()<br/>UnlockIfReady()
+
+    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,22 +467,16 @@ 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

package/Editor/CustomEditors/MessagingComponentEditor.cs

@@ -5,6 +5,7 @@ namespace DxMessaging.Editor.CustomEditors
     using System.Linq;
     using Core;
     using Core.Diagnostics;
+    using Core.MessageBus;
     using Core.Messages;
     using Unity;
     using UnityEditor;
@@ -107,18 +108,26 @@ namespace DxMessaging.Editor.CustomEditors
                 }
             }
 
-            if (!MessageHandler.MessageBus.DiagnosticsMode)
+            IMessageBus globalBus = MessageHandler.MessageBus;
+            if (globalBus is not MessageBus concreteBus)
+            {
+                EditorGUILayout.HelpBox(
+                    "Global diagnostics controls are unavailable because the active global bus is not the default DxMessaging MessageBus implementation.",
+                    MessageType.Info
+                );
+            }
+            else if (!concreteBus.DiagnosticsMode)
             {
                 if (GUILayout.Button("Enable Global Diagnostics"))
                 {
-                    MessageHandler.MessageBus.DiagnosticsMode = true;
+                    concreteBus.DiagnosticsMode = true;
                 }
             }
             else
             {
                 if (GUILayout.Button("Disable Global Diagnostics"))
                 {
-                    MessageHandler.MessageBus.DiagnosticsMode = false;
+                    concreteBus.DiagnosticsMode = false;
                 }
                 else
                 {
@@ -130,7 +139,7 @@ namespace DxMessaging.Editor.CustomEditors
                         "Global Messages",
                         true
                     );
-                    int totalGlobalMessages = MessageHandler.MessageBus._emissionBuffer.Count;
+                    int totalGlobalMessages = concreteBus._emissionBuffer.Count;
                     if (_globalBufferExpanded && totalGlobalMessages > 0)
                     {
                         int page = _globalBufferPaging;
@@ -163,8 +172,8 @@ namespace DxMessaging.Editor.CustomEditors
                             }
                         }
 
-                        MessageEmissionData[] pagedGlobalMessages = MessageHandler
-                            .MessageBus._emissionBuffer.Reverse()
+                        MessageEmissionData[] pagedGlobalMessages = concreteBus
+                            ._emissionBuffer.Reverse()
                             .Skip(page * PageSize)
                             .Take(PageSize)
                             .ToArray();