com.wallstop-studios.dxmessaging 2.0.0 → 2.1.0

package/Docs/InterceptorsAndOrdering.md

@@ -82,28 +82,52 @@ Notes on handler groups
 Visual overview
 
 ```mermaid
-flowchart TD
-  subgraph Untargeted
-    U1[Interceptors<T>] --> U2[Global Accept‑All Untargeted]
-    U2 --> U3[Handlers<T>]
-    U3 --> U4[Post‑Processors<T>]
+flowchart LR
+  subgraph Untargeted["<b>Untargeted Messages</b>"]
+    direction TB
+    U1["Interceptors&lt;T&gt;"] --> U2[Global Accept‑All Untargeted]
+    U2 --> U3["Handlers&lt;T&gt;"]
+    U3 --> U4["Post‑Processors&lt;T&gt;"]
   end
 
-  subgraph Targeted
-    T1[Interceptors<T>] --> T2[Global Accept‑All Targeted]
-    T2 --> T3[Handlers<T> @ target]
-    T3 --> T4[Handlers<T> (All Targets)]
-    T4 --> T5[Post‑Processors<T> @ target]
-    T5 --> T6[Post‑Processors<T> (All Targets)]
+  subgraph Targeted["<b>Targeted Messages</b>"]
+    direction TB
+    T1["Interceptors&lt;T&gt;"] --> T2[Global Accept‑All Targeted]
+    T2 --> T3["Handlers&lt;T&gt; @ target"]
+    T3 --> T4["Handlers&lt;T&gt; (All Targets)"]
+    T4 --> T5["Post‑Processors&lt;T&gt; @ target"]
+    T5 --> T6["Post‑Processors&lt;T&gt; (All Targets)"]
   end
 
-  subgraph Broadcast
-    B1[Interceptors<T>] --> B2[Global Accept‑All Broadcast]
-    B2 --> B3[Handlers<T> @ source]
-    B3 --> B4[Handlers<T> (All Sources)]
-    B4 --> B5[Post‑Processors<T> @ source]
-    B5 --> B6[Post‑Processors<T> (All Sources)]
+  subgraph Broadcast["<b>Broadcast Messages</b>"]
+    direction TB
+    B1["Interceptors&lt;T&gt;"] --> B2[Global Accept‑All Broadcast]
+    B2 --> B3["Handlers&lt;T&gt; @ source"]
+    B3 --> B4["Handlers&lt;T&gt; (All Sources)"]
+    B4 --> B5["Post‑Processors&lt;T&gt; @ source"]
+    B5 --> B6["Post‑Processors&lt;T&gt; (All Sources)"]
   end
+
+  style Untargeted fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
+  style Targeted fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
+  style Broadcast fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
+
+  style U1 fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
+  style U2 fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
+  style U3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+  style U4 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+  style T1 fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
+  style T2 fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
+  style T3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+  style T4 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+  style T5 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+  style T6 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+  style B1 fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
+  style B2 fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
+  style B3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+  style B4 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
+  style B5 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+  style B6 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
 ```
 
 Example sequence
@@ -145,6 +169,336 @@ _ = bus.RegisterTargetedInterceptor<TookDamage>(
 );
 ```
 
+Real‑World Use Cases
+
+###### State‑Based Message Cancellation
+
+Prevent UI messages from being processed based on current UI state:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct OpenMenu
+{
+    public readonly string menuName;
+}
+
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct ShowDialog
+{
+    public readonly string dialogText;
+}
+
+public class UIStateManager
+{
+    private bool _isInCutscene;
+    private bool _isPaused;
+    private bool _isLoading;
+
+    public void RegisterInterceptors()
+    {
+        var bus = MessageHandler.MessageBus;
+
+        // Block all UI interactions during cutscenes, loading, or when paused
+        _ = bus.RegisterUntargetedInterceptor<OpenMenu>(
+            (ref OpenMenu m) => !_isInCutscene && !_isLoading,
+            priority: -100  // Run early
+        );
+
+        _ = bus.RegisterUntargetedInterceptor<ShowDialog>(
+            (ref ShowDialog m) => !_isInCutscene && !_isPaused,
+            priority: -100
+        );
+    }
+
+    public void EnterCutscene() => _isInCutscene = true;
+    public void ExitCutscene() => _isInCutscene = false;
+}
+
+// Usage: UI messages automatically blocked during cutscenes
+var uiManager = new UIStateManager();
+uiManager.RegisterInterceptors();
+uiManager.EnterCutscene();
+
+new OpenMenu("inventory").Emit();  // Cancelled by interceptor
+new ShowDialog("Hello!").Emit();   // Cancelled by interceptor
+```
+
+###### Value Clamping and Normalization
+
+Ensure message data stays within valid ranges:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+using UnityEngine;
+
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct MovementInput
+{
+    public readonly Vector2 direction;
+    public readonly float speed;
+}
+
+public class InputNormalizer
+{
+    public void RegisterInterceptors()
+    {
+        var bus = MessageHandler.MessageBus;
+
+        // Normalize and clamp movement input
+        _ = bus.RegisterUntargetedInterceptor<MovementInput>(
+            (ref MovementInput m) =>
+            {
+                // Normalize direction vector
+                var normalized = m.direction.normalized;
+
+                // Clamp speed to valid range
+                var clampedSpeed = Mathf.Clamp(m.speed, 0f, 10f);
+
+                // Mutate the message with cleaned values
+                m = new MovementInput(normalized, clampedSpeed);
+                return true;
+            },
+            priority: 0
+        );
+    }
+}
+
+// Usage: all movement input is automatically normalized
+var normalizer = new InputNormalizer();
+normalizer.RegisterInterceptors();
+
+// Even invalid input gets cleaned
+new MovementInput(new Vector2(100, 200), 9999f).Emit();
+// Handlers receive: direction=(0.45, 0.89), speed=10.0
+```
+
+###### Permission and Authorization Checks
+
+Block messages that violate game rules or permissions:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct SpendCurrency
+{
+    public readonly int amount;
+}
+
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct UnlockAchievement
+{
+    public readonly string achievementId;
+}
+
+public class PermissionSystem
+{
+    private readonly IPlayerDataService _playerData;
+
+    public PermissionSystem(IPlayerDataService playerData)
+    {
+        _playerData = playerData;
+    }
+
+    public void RegisterInterceptors()
+    {
+        var bus = MessageHandler.MessageBus;
+
+        // Block currency spending if player doesn't have enough
+        _ = bus.RegisterTargetedInterceptor<SpendCurrency>(
+            (ref InstanceId playerId, ref SpendCurrency m) =>
+            {
+                var balance = _playerData.GetCurrencyBalance(playerId);
+                if (balance < m.amount)
+                {
+                    Debug.LogWarning($"Player {playerId} attempted to spend {m.amount} but only has {balance}");
+                    return false;  // Cancel the message
+                }
+                return true;
+            },
+            priority: -50
+        );
+
+        // Block achievement unlocks if already unlocked (idempotency)
+        _ = bus.RegisterTargetedInterceptor<UnlockAchievement>(
+            (ref InstanceId playerId, ref UnlockAchievement m) =>
+            {
+                if (_playerData.HasAchievement(playerId, m.achievementId))
+                {
+                    return false;  // Already unlocked, skip
+                }
+                return true;
+            },
+            priority: -50
+        );
+    }
+}
+
+// Usage: invalid operations automatically blocked
+var permissions = new PermissionSystem(playerDataService);
+permissions.RegisterInterceptors();
+
+// This will be blocked if player doesn't have 100 currency
+new SpendCurrency(100).EmitTargeted(playerId);
+
+// This will be blocked if achievement is already unlocked
+new UnlockAchievement("first_boss").EmitTargeted(playerId);
+```
+
+###### Message Enrichment and Context Addition
+
+Add contextual data to messages as they flow through the system:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+using System;
+
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct PlayerAction
+{
+    public readonly string actionType;
+    [DxOptionalParameter]
+    public readonly long timestamp;  // Added by interceptor
+    [DxOptionalParameter]
+    public readonly string sessionId; // Added by interceptor
+}
+
+public class TelemetryEnricher
+{
+    private readonly string _currentSessionId;
+
+    public TelemetryEnricher(string sessionId)
+    {
+        _currentSessionId = sessionId;
+    }
+
+    public void RegisterInterceptors()
+    {
+        var bus = MessageHandler.MessageBus;
+
+        // Enrich player actions with timestamp and session context
+        _ = bus.RegisterTargetedInterceptor<PlayerAction>(
+            (ref InstanceId playerId, ref PlayerAction m) =>
+            {
+                // Add timestamp and session ID to every action
+                m = new PlayerAction(
+                    m.actionType,
+                    DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
+                    _currentSessionId
+                );
+                return true;
+            },
+            priority: -100  // Run very early to enrich before other interceptors
+        );
+    }
+}
+
+// Usage: messages automatically enriched with context
+var enricher = new TelemetryEnricher(Guid.NewGuid().ToString());
+enricher.RegisterInterceptors();
+
+// Emit without timestamp/session - interceptor adds them
+new PlayerAction("jump").EmitTargeted(playerId);
+// Handlers receive fully enriched message with timestamp and sessionId
+```
+
+###### Cooldown and Rate Limiting
+
+Prevent message spam by enforcing cooldowns:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
+using System;
+using System.Collections.Generic;
+
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct CastSpell
+{
+    public readonly string spellName;
+}
+
+public class CooldownManager
+{
+    private readonly Dictionary<(InstanceId, string), DateTime> _lastCastTimes = new();
+    private readonly TimeSpan _globalCooldown = TimeSpan.FromSeconds(1.5);
+
+    public void RegisterInterceptors()
+    {
+        var bus = MessageHandler.MessageBus;
+
+        _ = bus.RegisterTargetedInterceptor<CastSpell>(
+            (ref InstanceId casterId, ref CastSpell m) =>
+            {
+                var key = (casterId, m.spellName);
+                var now = DateTime.UtcNow;
+
+                if (_lastCastTimes.TryGetValue(key, out var lastCast))
+                {
+                    if (now - lastCast < _globalCooldown)
+                    {
+                        // Still on cooldown
+                        return false;
+                    }
+                }
+
+                _lastCastTimes[key] = now;
+                return true;
+            },
+            priority: -10
+        );
+    }
+}
+
+// Usage: rapid spell casts automatically throttled
+var cooldowns = new CooldownManager();
+cooldowns.RegisterInterceptors();
+
+new CastSpell("fireball").EmitTargeted(playerId);  // ✓ Allowed
+new CastSpell("fireball").EmitTargeted(playerId);  // ✗ Blocked (too soon)
+// ... wait 1.5s ...
+new CastSpell("fireball").EmitTargeted(playerId);  // ✓ Allowed
+```
+
+When to Use Interceptors
+
+✅ **Good use cases:**
+
+- Input validation and sanitization
+- Value clamping and normalization
+- Permission and authorization checks
+- State‑based message filtering
+- Rate limiting and cooldown enforcement
+- Message enrichment (adding timestamps, session IDs, etc.)
+- Early exit for duplicate or redundant messages
+- Logging suspicious or invalid message attempts
+
+⚠️ **Key principles:**
+
+- **Run before handlers**: Interceptors execute before any type‑specific handlers, making them perfect for preprocessing
+- **Can mutate**: Unlike post‑processors, interceptors can modify message data
+- **Can cancel**: Return `false` to prevent the message from reaching handlers
+- **Priority matters**: Lower priority values run first (use negative priorities for early interceptors)
+
+❌ **Avoid for:**
+
+- Read‑only observation (use handlers or post‑processors instead)
+- Actions that should run after message processing (use post‑processors)
+- Heavy computation that doesn't need to block the message
+
 Post‑processors
 
 - Observe after handlers. Great for logging, analytics, or follow‑up emission.

package/Docs/ListeningPatterns.md

@@ -47,6 +47,212 @@ var dereg = bus.RegisterGlobalAcceptAll(handler);
 // implement handler callbacks for generic categories on your MessageHandler
 ```
 
+Real‑World Use Cases
+
+## Development Debug Dump
+
+Capture all messages during development for debugging and diagnostics:
+
+```csharp
+using DxMessaging.Core;
+using DxMessaging.Core.Messages;
+using UnityEngine;
+
+public class DebugMessageLogger : MessageHandler
+{
+    public DebugMessageLogger() : base(new InstanceId(999)) { }
+
+    public override void Handle(ref IUntargetedMessage message)
+    {
+        Debug.Log($"[Untargeted] {message.GetType().Name}: {message}");
+    }
+
+    public override void Handle(ref InstanceId target, ref ITargetedMessage message)
+    {
+        Debug.Log($"[Targeted → {target}] {message.GetType().Name}: {message}");
+    }
+
+    public override void Handle(ref InstanceId source, ref IBroadcastMessage message)
+    {
+        Debug.Log($"[Broadcast ← {source}] {message.GetType().Name}: {message}");
+    }
+}
+
+// Register in development builds only
+#if DEVELOPMENT_BUILD || UNITY_EDITOR
+var logger = new DebugMessageLogger { active = true };
+_ = MessageHandler.MessageBus.RegisterGlobalAcceptAll(logger);
+#endif
+```
+
+### Attribute‑Based Network Replication
+
+Automatically replicate messages marked with custom attributes across the network:
+
+```csharp
+using System;
+using System.Reflection;
+using System.Collections.Generic;
+using DxMessaging.Core;
+using DxMessaging.Core.Messages;
+
+// Mark messages that should be replicated
+[AttributeUsage(AttributeTargets.Struct)]
+public class NetworkedAttribute : Attribute { }
+
+[Networked]
+[DxUntargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct PlayerMoved
+{
+    public readonly Vector3 position;
+}
+
+[Networked]
+[DxTargetedMessage]
+[DxAutoConstructor]
+public readonly partial struct DealDamage
+{
+    public readonly float amount;
+}
+
+// Network replication handler
+public class NetworkReplicator : MessageHandler
+{
+    private readonly INetworkManager _network;
+    private readonly HashSet<Type> _networkedTypes = new();
+
+    public NetworkReplicator(INetworkManager network) : base(new InstanceId(1000))
+    {
+        _network = network;
+        CacheNetworkedTypes();
+    }
+
+    private void CacheNetworkedTypes()
+    {
+        // Find all message types with [Networked] attribute
+        foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+        {
+            foreach (var type in assembly.GetTypes())
+            {
+                if (type.GetCustomAttribute<NetworkedAttribute>() != null)
+                {
+                    _networkedTypes.Add(type);
+                }
+            }
+        }
+    }
+
+    public override void Handle(ref IUntargetedMessage message)
+    {
+        if (_networkedTypes.Contains(message.GetType()))
+        {
+            _network.Send(message);  // Serialize and send
+        }
+    }
+
+    public override void Handle(ref InstanceId target, ref ITargetedMessage message)
+    {
+        if (_networkedTypes.Contains(message.GetType()))
+        {
+            _network.Send(target, message);
+        }
+    }
+
+    public override void Handle(ref InstanceId source, ref IBroadcastMessage message)
+    {
+        if (_networkedTypes.Contains(message.GetType()))
+        {
+            _network.Send(source, message);
+        }
+    }
+}
+
+// Usage: any message with [Networked] automatically replicates
+var replicator = new NetworkReplicator(networkManager) { active = true };
+_ = MessageHandler.MessageBus.RegisterGlobalAcceptAll(replicator);
+
+// These messages now "just work" across the network
+new PlayerMoved(playerPos).Emit();
+new DealDamage(50f).EmitTargeted(enemyId);
+```
+
+#### Message Analytics and Metrics
+
+Track message frequency and performance across your entire game:
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using DxMessaging.Core;
+using DxMessaging.Core.Messages;
+
+public class MessageAnalytics : MessageHandler
+{
+    private readonly Dictionary<Type, (int count, long totalMs)> _stats = new();
+    private readonly Stopwatch _stopwatch = new();
+
+    public MessageAnalytics() : base(new InstanceId(1001)) { }
+
+    public override void Handle(ref IUntargetedMessage message)
+    {
+        TrackMessage(message.GetType());
+    }
+
+    public override void Handle(ref InstanceId target, ref ITargetedMessage message)
+    {
+        TrackMessage(message.GetType());
+    }
+
+    public override void Handle(ref InstanceId source, ref IBroadcastMessage message)
+    {
+        TrackMessage(message.GetType());
+    }
+
+    private void TrackMessage(Type messageType)
+    {
+        _stopwatch.Restart();
+        // Message processing happens here
+        _stopwatch.Stop();
+
+        if (!_stats.TryGetValue(messageType, out var stat))
+        {
+            stat = (0, 0);
+        }
+        _stats[messageType] = (stat.count + 1, stat.totalMs + _stopwatch.ElapsedMilliseconds);
+    }
+
+    public void PrintStats()
+    {
+        foreach (var kvp in _stats)
+        {
+            var avg = kvp.Value.totalMs / (double)kvp.Value.count;
+            UnityEngine.Debug.Log($"{kvp.Key.Name}: {kvp.Value.count} messages, avg {avg:F2}ms");
+        }
+    }
+}
+```
+
+When to Use Global Accept‑All
+
+✅ **Good use cases:**
+
+- Development‑time debugging and logging
+- Cross‑cutting concerns (analytics, telemetry, metrics)
+- Attribute‑based systems (networking, serialization, persistence)
+- Testing and diagnostics tools
+- Message replay/recording systems
+
+⚠️ **Performance consideration:**
+Global Accept‑All handlers are invoked for **every** message of **every** type. For high‑performance gameplay logic, prefer type‑specific registrations which use O(1) lookup instead of O(N) iteration.
+
+❌ **Avoid for:**
+
+- Core gameplay logic that only needs specific message types
+- Hot paths with thousands of messages per frame
+- Production code that can use specific type registrations instead
+
 Tips
 
 - Use across‑all listeners for diagnostics, analytics, or cross‑cutting observers.