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

package/Docs/Overview.md

@@ -4,22 +4,89 @@
 
 ---
 
-DxMessaging is a high‑performance, type‑safe messaging system for Unity and .NET that decouples producers and consumers without sprawling events or brittle global hooks. It gives you clear message categories, predictable ordering, and tooling to observe, intercept, and diagnose message flows.
+DxMessaging is a high-performance, type-safe messaging system for Unity that **eliminates the three biggest pain points** of traditional event systems:
 
-What it solves
+1. **Memory leaks** from forgotten unsubscribes → Automatic lifecycle management
+1. **Tight coupling** creating refactoring nightmares → Full decoupling with no direct references
+1. **Debugging black holes** ("what fired when?") → Built-in Inspector diagnostics
 
-- Decoupling without tight references: producers don’t need to know consumers.
-- Predictable lifecycle: explicit registration tokens that you enable/disable with Unity components.
-- Ergonomics and performance: struct‑friendly APIs, by‑ref handlers, zero‑boxing patterns.
-- Observability: interceptors, post‑processors, diagnostics buffers, and registration logs.
-- Scalable message taxonomy: Untargeted, Targeted, and Broadcast messages fit most gameplay/UI flows.
+## What Problems Does It Solve?
 
-When to consider DxMessaging
+### For Beginners: "I'm calling methods manually everywhere"
 
-- You’re fighting complex webs of C# events/delegates with manual attach/detach and order issues.
-- You need to decouple systems that span scenes or don’t share direct references.
-- You want to model Gameplay/UI flows as messages with clear ownership (global vs to one entity vs from one entity).
-- You need to inspect, validate, and sometimes cancel or normalize emissions.
+#### Your code probably looks like this
+
+```csharp
+public class Player : MonoBehaviour {
+    public HealthBar healthBar;
+    public AudioManager audio;
+    public AchievementSystem achievements;
+
+    void TakeDamage(int amount) {
+        health -= amount;
+        healthBar.UpdateHealth(health);  // Manual call
+        audio.PlayDamageSound();         // Manual call
+        achievements.CheckDamage(amount); // Manual call
+        // Add analytics? More manual calls...
+    }
+}
+```
+
+**Every new system = another SerializeField + another manual call.** It's exhausting and brittle.
+
+##### DxMessaging fixes this
+
+```csharp
+void TakeDamage(int amount) {
+    health -= amount;
+    new TookDamage(amount).EmitComponentBroadcast(this);
+    // Done! Everything else reacts automatically.
+}
+```
+
+### For Intermediate Devs: "I use C# events but they leak"
+
+#### You know this pain
+
+```csharp
+void OnEnable() { GameManager.OnScoreChanged += UpdateUI; }
+void OnDisable() { /* Forgot this? 💀 LEAK! */ }
+```
+
+**DxMessaging makes leaks impossible** - automatic cleanup when components die.
+
+### For Advanced Devs: "I need observability and control"
+
+- ✅ See message history in Inspector (timestamps, payloads, call counts)
+- ✅ Priority-based execution (no more race conditions)
+- ✅ Interceptors (validate/normalize before handlers)
+- ✅ Global observers (track ALL instances of a message type)
+- ✅ Local bus islands (isolated testing, zero global state)
+
+## What It Solves (Technical)
+
+- **Decoupling without references** - producers/consumers never know about each other
+- **Predictable lifecycle** - explicit tokens tied to Unity component lifecycles
+- **Performance** - struct messages passed by-ref, zero allocations, zero boxing
+- **Observability** - interceptors, post-processors, diagnostics, registration logs
+- **Scalable taxonomy** - three message types (Untargeted/Targeted/Broadcast) cover 99% of use cases
+
+## When to Consider DxMessaging
+
+### Use it when
+
+- You have 3+ systems that need to communicate
+- You've debugged memory leaks from forgotten unsubscribes
+- You're tired of UI depending on 15 different gameplay systems
+- You want to see "what fired when" without setting 50 breakpoints
+- You're building for the long term (months/years, not days)
+
+#### Skip it when
+
+- Game jam prototype (<1 week)
+- Tiny project (<1000 lines)
+- Single-system communication (just call the method directly)
+- You need synchronous return values (DxMessaging is fire-and-forget)
 
 Core ideas
 
@@ -31,15 +98,42 @@ Core ideas
 - Pipeline: Interceptors → Handlers → Post‑Processors, with diagnostics optionally enabled.
 - Unity integration: `MessagingComponent` and `MessageAwareComponent` manage lifecycles cleanly.
 
-Killer features
+## Killer Features (What Makes It Special)
+
+### 🚀 Global Observers: The Unique Advantage
+
+#### Traditional event systems force you to do this
+
+```csharp
+// Subscribe to each entity type separately
+PlayerEvents.OnDamaged += TrackPlayerDamage;
+EnemyEvents.OnDamaged += TrackEnemyDamage;
+NPCEvents.OnDamaged += TrackNPCDamage;
+// Add a new entity type? More subscriptions...
+```
+
+##### DxMessaging lets you do this
+
+```csharp
+// Subscribe ONCE to ALL damage, regardless of source
+_ = Token.RegisterBroadcastWithoutSource<TookDamage>(
+    (InstanceId source, TookDamage msg) => {
+        Analytics.Log($"{source} took {msg.amount} damage");
+    }
+);
+```
+
+**Real-world impact:** Build achievement systems, combat logs, and analytics that work with ANY entity - even ones that don't exist yet.
+
+### Other Killer Features
 
-- **🚀 Global Observers: Listen to ALL messages** — Subscribe to all targeted/broadcast messages of a type without knowing specific targets/sources. **Unlike traditional event buses** where you need separate subscriptions per entity type (PlayerDamaged, EnemyDamaged, etc.), DxMessaging lets you subscribe ONCE to ALL damage events and get the source/target as a parameter. Perfect for analytics, debugging, achievements, and combat logs.
-- **Priority ordering** and explicit pipeline stages (interceptors, handlers, post‑processors).
-- **Local bus islands** for test isolation and modular subsystems.
-- **Struct‑friendly, by‑ref handlers** to avoid boxing and copies.
-- **Attributes + source generation** (`DxAutoConstructor`) reduce boilerplate while keeping strong typing.
-- **Unity‑first helpers** (GameObject/Component emit) and a powerful MessagingComponent inspector.
-- **Global accept‑all** for building inspectors and profilers.
+- **Priority-based ordering** - eliminate race conditions, control execution flow explicitly
+- **Interceptor pipeline** - validate/normalize messages BEFORE handlers run (one validation, all handlers protected)
+- **Local bus islands** - isolated testing with zero global state contamination
+- **Zero-allocation design** - struct messages passed by-ref, no boxing, no GC spikes
+- **Auto-constructor generation** - `[DxAutoConstructor]` eliminates boilerplate while keeping type safety
+- **Unity-first helpers** - `EmitGameObjectTargeted()`, `EmitComponentBroadcast()` feel natural
+- **Inspector diagnostics** - see message history, registrations, call counts in real-time
 
 ---
 

package/Docs/Patterns.md

@@ -1,10 +1,50 @@
-# DxMessaging Patterns
+# DxMessaging Patterns: Real-World Solutions
 
 [← Back to Index](Index.md) | [Getting Started](GettingStarted.md) | [Message Types](MessageTypes.md) | [Samples](../Samples~/)
 
 ---
 
-This document captures practical patterns for building systems with DxMessaging. It complements the README by focusing on composition, structure, and problem-solving techniques.
+**You're here because:** You understand DxMessaging basics, now you want to see "How do I actually build X?"
+
+## What you'll find
+
+- **Basic Patterns** - Fundamental building blocks (scene transitions, commands, observability)
+- **Advanced Patterns** - Power user techniques (diagnostics, testing, legacy integration)
+- **Scale Patterns** - Production-ready examples (100+ entities, cross-scene systems, large UI)
+
+### Reading guide
+
+- **New to DxMessaging?** Start with Basic Patterns 1-8
+- **Intermediate user?** Jump to Advanced Patterns 9-12
+- **Building at scale?** Go straight to Real-World Scale Patterns
+- **Specific problem?** Use Ctrl+F / Cmd+F to search
+
+**Philosophy:** These aren't toy examples. They're patterns from real games with real problems.
+
+---
+
+## Quick Links: "I Want To..."
+
+### Find your use case, jump to the pattern
+
+| I want to...                                 | Go to                                                                                                        |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Make UI react to gameplay                    | [Pattern 2: Directed Commands](#2-directed-commands-targeted)                                                |
+| Coordinate scene transitions                 | [Pattern 1: Scene-wide Events](#1-scene-wide-events-untargeted)                                              |
+| Build an achievement system                  | [Pattern 3: Observability](#3-observability-broadcast) + [Global Accept-All](#10-global-accept-all-handlers) |
+| Validate input/damage before it happens      | [Pattern 4: Interceptors](#4-validation-and-normalization-interceptors)                                      |
+| Add analytics without touching gameplay      | [Pattern 5: Post-Processors](#5-analyticslogging-post-processors)                                            |
+| Track ALL damage from ANY entity             | [Pattern: Managing 100+ Entities](#pattern-managing-100-combat-entities)                                     |
+| Build a large UI system (20+ panels)         | [Pattern: Large-Scale UI](#pattern-large-scale-ui-system-20-panels)                                          |
+| Make systems run in a specific order         | [Pattern: Priority Ordering](#pattern-priority-ordered-execution-for-complex-systems)                        |
+| Test in isolation                            | [Pattern 6: Local Bus Islands](#6-local-bus-islands)                                                         |
+| Migrate from C# events                       | [Pattern 9: Bridging Legacy](#9-bridging-legacy-unity-messaging)                                             |
+| Handle persistent systems across scene loads | [Pattern: Cross-Scene Persistent](#pattern-cross-scene-persistent-systems)                                   |
+| See what's happening (debug message flow)    | [Pattern 11: Diagnostics](#11-diagnostics-and-tuning)                                                        |
+| Build a battle royale / large multiplayer    | [Pattern: Battle Royale Example](#real-world-production-example-battle-royale-game)                          |
+| Use with Scriptable Object Architecture      | [Pattern 14: SOA Compatibility](#14-compatibility-with-scriptable-object-architecture-soa)                   |
+
+---
 
 ## Table of Contents
 
@@ -25,6 +65,7 @@ This document captures practical patterns for building systems with DxMessaging.
 - [Global Accept-All Handlers](#10-global-accept-all-handlers)
 - [Diagnostics and Tuning](#11-diagnostics-and-tuning)
 - [Testing](#12-testing)
+- [Compatibility with Scriptable Object Architecture (SOA)](#14-compatibility-with-scriptable-object-architecture-soa)
 
 ### Real-World Scale Patterns
 
@@ -729,6 +770,290 @@ public class MatchStats : MessageAwareComponent {
 
 ---
 
+## 14) Compatibility with Scriptable Object Architecture (SOA)
+
+**Disclaimer:** Scriptable Object Architecture (SOA) is a debated pattern in the Unity community. While it has proponents, there are documented criticisms regarding its scalability and maintainability. See [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture) for a detailed critique. **SOA is not a recommended pattern** for most projects, unless you need designers wiring events. Consider alternatives like dependency injection (Zenject, VContainer), reactive systems (UniRx), or messaging systems (DxMessaging, MessagePipe), as they often provide better long-term maintainability.
+
+That said, if your project uses or requires SOA, DxMessaging can work alongside it.
+
+### What is Scriptable Object Architecture?
+
+**SOA Background:** Popularized by Ryan Hipple's [Unite Austin 2017 talk](https://www.youtube.com/watch?v=raQ3iHhE_Kk), SOA uses ScriptableObject assets as:
+
+1. **Shared Variables** - `FloatVariable`, `IntVariable`, etc. (ScriptableObject assets that hold runtime state)
+1. **Event Channels** - `GameEvent` + `GameEventListener` pattern (designer-created events)
+1. **Runtime Sets** - Collections of active game objects (e.g., all enemies)
+
+**Core idea:** Systems communicate through serialized SO assets instead of direct references.
+
+#### Key resources
+
+- [Unite 2017 Talk by Ryan Hipple](https://www.youtube.com/watch?v=raQ3iHhE_Kk)
+- [Official Unity Guide](https://unity.com/how-to/architect-game-code-scriptable-objects)
+- [Reference Implementation](https://github.com/roboryantron/Unite2017)
+- [Community Package](https://github.com/DanielEverland/ScriptableObject-Architecture)
+
+### Why SOA is Controversial
+
+From [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture), key criticisms include:
+
+1. **Wrong Purpose** - ScriptableObjects are designed for immutable design data, not runtime mutable state
+1. **Redundant Complexity** - Standard C# objects achieve the same goals without SO restrictions
+1. **Inspector Dependency** - Binds architecture to Unity's GUI, complicating debugging and maintenance
+1. **Limited Scalability** - Runtime-created variables undermine the pattern; managing numerous assets becomes unwieldy
+1. **Domain Reload Issues** - Disabled domain reloading causes ScriptableObjects to retain values unpredictably
+1. **Testability Concerns** - SO assets persist between tests, requiring manual cleanup
+
+#### Recommended alternatives
+
+- **Dependency Injection** - Zenject, VContainer, Reflex (see [DxMessaging DI Integrations](Integrations/))
+- **Reactive Systems** - UniRx, UniTask
+- **Messaging** - DxMessaging (this framework), MessagePipe
+- **Configuration Data** - Spreadsheet-based solutions (e.g., BakingSheet)
+
+Use ScriptableObjects for their intended purpose: **immutable design-time data** (configs, balance tables, prefab references).
+
+### Can DxMessaging Work with SOA?
+
+**Yes, but with caveats.** DxMessaging and SOA solve similar problems (decoupling, communication) with different philosophies:
+
+| Aspect               | SOA                                                                                 | DxMessaging                               |
+| -------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- |
+| **Paradigm**         | Asset-based, persistent state                                                       | Runtime message passing, transient        |
+| **Designer-Centric** | ✅ High (create events in Inspector)                                                | ❌ Low (code-driven)                      |
+| **Type Safety**      | ⚠️ Mixed (SO refs typed, but UnityEvent inspector wiring loses compile-time safety) | ✅ Strong (compile-time validation)       |
+| **Lifecycle**        | ⚠️ Manual (SO assets persist)                                                       | ✅ Automatic (tokens clean up)            |
+| **Debugging**        | ⚠️ Inspector-dependent                                                              | ✅ Built-in diagnostics                   |
+| **Performance**      | ⚠️ List iteration, UnityAction overhead                                             | ✅ Zero-allocation structs                |
+| **Use Case**         | Shared state, designer-driven configs                                               | Event-driven communication, runtime logic |
+| **Testability**      | ⚠️ Requires SO asset cleanup                                                        | ✅ Isolated buses per test                |
+
+**Bottom line:** If you're starting fresh, prefer DxMessaging or DI. If you have legacy SOA code, the patterns below show coexistence strategies.
+
+### Pattern Overview
+
+| Pattern | What it shows                                          | When to use                                           | SOA involvement              |
+| ------- | ------------------------------------------------------ | ----------------------------------------------------- | ---------------------------- |
+| **A**   | SOA Events (GameEvent) forwarding to DxMessaging       | Designer-created event assets, modern code downstream | ✅ Yes - SOA Event pattern   |
+| **B**   | ScriptableObjects for configs + DxMessaging for events | New projects / best practice                          | ❌ No - proper SO usage only |
+
+### Pattern A: SOA → DxMessaging (Event Forwarding)
+
+**Use case:** Designer-created SOA events, but you want DxMessaging benefits downstream.
+
+**Strategy:** SOA GameEventListener forwards to DxMessaging.
+
+> **This uses the SOA GameEvent pattern:** If you're NOT using designer-created GameEvent assets
+> with `Raise()`/listener management, you don't need this pattern. For immutable config data,
+> see Pattern B instead.
+
+#### Example: Scene Transitions
+
+```csharp
+using DxMessaging.Core.Messages;
+using DxMessaging.Core.Attributes;
+using DxMessaging.Core.Extensions;
+using UnityEngine;
+using UnityEngine.Events;
+
+// Traditional SOA event
+[CreateAssetMenu(menuName = "Events/Game Event")]
+public class GameEvent : ScriptableObject
+{
+    private readonly List<UnityAction> listeners = new();
+
+    public void Raise()
+    {
+        for (int i = listeners.Count - 1; i >= 0; i--)
+            listeners[i]?.Invoke();
+    }
+
+    public void RegisterListener(UnityAction listener) => listeners.Add(listener);
+    public void UnregisterListener(UnityAction listener) => listeners.Remove(listener);
+}
+
+// DxMessaging message (modern, type-safe)
+[DxUntargetedMessage]
+public readonly struct SceneTransitionRequested { }
+
+// Bridge: SOA Event → DxMessaging
+public class SOAEventBridge : MonoBehaviour
+{
+    [SerializeField] private GameEvent onSceneTransitionSO; // Designer-created asset
+
+    void OnEnable()
+    {
+        onSceneTransitionSO.RegisterListener(OnSOAEvent);
+    }
+
+    void OnDisable()
+    {
+        onSceneTransitionSO.UnregisterListener(OnSOAEvent);
+    }
+
+    void OnSOAEvent()
+    {
+        // Forward to DxMessaging
+        var message = new SceneTransitionRequested();
+        message.Emit();
+    }
+}
+
+// Modern DxMessaging listeners (no SO dependency)
+public class AudioSystem : MessageAwareComponent
+{
+    protected override void RegisterMessageHandlers()
+    {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterUntargeted<SceneTransitionRequested>(OnTransition);
+    }
+
+    void OnTransition(ref SceneTransitionRequested msg)
+    {
+        FadeOutMusic(); // Type-safe, debuggable via DxMessaging Inspector
+    }
+}
+```
+
+##### Benefits
+
+- ✅ Designers create events in Inspector (SOA workflow preserved)
+- ✅ Code uses DxMessaging (type-safe, lifecycle-safe)
+
+###### Drawbacks
+
+- ⚠️ Bridge boilerplate for each SOA event
+- ⚠️ Double registration (SOA listener + DxMessaging handler)
+
+### Pattern B: Proper ScriptableObject Usage (Recommended)
+
+**Use case:** ScriptableObjects for immutable config data, DxMessaging for runtime events.
+
+**Strategy:** Use each tool for its intended purpose; avoid bridging.
+
+> **Important:** This pattern uses ScriptableObjects CORRECTLY (immutable design data),
+> NOT as SOA (mutable runtime state). This is standard Unity best practice, not SOA.
+> If you're only using SOs for config data like this, you don't need SOA patterns at all.
+
+#### Example: Combat with Designer-Tunable Data
+
+```csharp
+using DxMessaging.Core.Messages;
+using DxMessaging.Core.Attributes;
+using DxMessaging.Unity;
+using UnityEngine;
+
+// ScriptableObject: Designer-tunable balance data (immutable at runtime)
+// This is CORRECT SO usage, NOT SOA
+[CreateAssetMenu(menuName = "Config/Weapon Stats")]
+public class WeaponStats : ScriptableObject
+{
+    public int baseDamage = 10;      // Designer tweaks in Inspector
+    public float critMultiplier = 2f;
+}
+
+// DxMessaging: Runtime event (code-driven)
+[DxBroadcastMessage]
+[DxAutoConstructor]
+public readonly partial struct DamageDealt
+{
+    public readonly int amount;
+    public readonly bool wasCrit;
+}
+
+// Combat system: Reads immutable SO data, emits DxMessaging events
+public class Weapon : MessageAwareComponent
+{
+    [SerializeField] private WeaponStats stats; // Immutable config (correct SO usage)
+
+    public void Fire()
+    {
+        bool crit = Random.value < 0.1f;
+        int damage = Mathf.RoundToInt(stats.baseDamage * (crit ? stats.critMultiplier : 1f));
+
+        var msg = new DamageDealt(damage, crit);
+        msg.EmitComponentBroadcast(this); // Runtime event via DxMessaging
+    }
+}
+
+// Analytics: Pure DxMessaging (no SOA dependency)
+public class CombatAnalytics : MessageAwareComponent
+{
+    protected override void RegisterMessageHandlers()
+    {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterBroadcastWithoutSource<DamageDealt>(OnDamage);
+    }
+
+    void OnDamage(InstanceId source, DamageDealt msg)
+    {
+        Debug.Log($"{source} dealt {msg.amount} damage (crit: {msg.wasCrit})");
+    }
+}
+```
+
+##### Benefits
+
+- ✅ **Best of both worlds** - ScriptableObjects for static configs, DxMessaging for runtime events
+- ✅ No bridging overhead
+- ✅ Uses each system correctly: SOs for their intended purpose (immutable design data), messaging for runtime communication
+- ✅ This is NOT SOA - it's proper Unity architecture
+
+###### This is the recommended pattern for all projects
+
+### When to Use Each Pattern
+
+| Pattern                     | Use When                                                | Complexity | Performance |
+| --------------------------- | ------------------------------------------------------- | ---------- | ----------- |
+| **A: SOA → DxMessaging**    | Designers create SOA events, modern code uses messaging | Medium     | ⚠️ Medium   |
+| **B: Proper SO Usage**      | Immutable configs only, messaging for events            | Low        | ✅ Good     |
+| **None (Pure DxMessaging)** | Greenfield project or full SOA migration                | Lowest     | ✅ Best     |
+
+### Migration Path: SOA → DxMessaging
+
+If you're moving away from SOA:
+
+1. **Phase 1:** Identify SOA event usage (GameEvent/GameEventListener patterns)
+1. **Phase 2:** Create equivalent DxMessaging messages (Untargeted/Broadcast)
+1. **Phase 3:** Add bridges (Pattern A or B) to maintain compatibility
+1. **Phase 4:** Migrate listeners to DxMessaging incrementally
+1. **Phase 5:** Remove bridges and SOA assets once all references gone
+
+For SOA variables:
+
+1. Convert read-only SO configs → Keep as-is (correct SO usage) or move to JSON/ScriptableObjects for data
+1. Convert mutable SO variables → DxMessaging messages or DI-injected services
+1. Convert RuntimeSets → DxMessaging global observers (`RegisterBroadcastWithoutSource`)
+
+### Final Recommendations
+
+#### If you're using SOA
+
+- ✅ **Do:** Use Pattern B (Proper SO Usage) - SOs for immutable configs ONLY, DxMessaging for runtime events
+- ✅ **Do:** Use Pattern A to bridge existing SOA GameEvent assets to DxMessaging during migration
+- ✅ **Do:** Read [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture) to understand risks
+- ✅ **Do:** Consider gradual migration to DxMessaging or DI frameworks
+- ❌ **Don't:** Use SOs for mutable runtime state (health, scores, etc.)
+- ❌ **Don't:** Create new SOA event assets—use DxMessaging messages instead
+
+##### If you're starting fresh
+
+- ✅ **Do:** Use DxMessaging for all messaging/events
+- ✅ **Do:** Use ScriptableObjects ONLY for immutable design data (weapon stats, level configs)
+- ✅ **Do:** Consider DI frameworks (Zenject/VContainer) for service dependencies
+- ❌ **Don't:** Adopt SOA's GameEvent/Variable patterns—they're superseded by better tools
+
+###### Resources
+
+- [Anti-ScriptableObject Architecture](https://github.com/cathei/AntiScriptableObjectArchitecture) - Detailed critique
+- [Ryan Hipple Unite 2017 Talk](https://www.youtube.com/watch?v=raQ3iHhE_Kk) - Original SOA presentation
+- [Unity Official Guide](https://unity.com/how-to/architect-game-code-scriptable-objects) - Unity's perspective
+- [DxMessaging DI Integrations](Integrations/) - Better alternatives for dependency management
+- [Zenject](https://github.com/modesttree/Zenject) - Recommended DI framework
+- [VContainer](https://github.com/hadashiA/VContainer) - Lightweight DI alternative
+
+---
+
 ## Related Documentation
 
 ### Learn the Basics First?

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,490,000           | Yes          |
+| DxMessaging (GameObject) - Normal  | 8,520,000           | No           |
+| DxMessaging (Component) - Normal   | 8,542,000           | No           |
+| DxMessaging (GameObject) - No-Copy | 9,426,000           | No           |
+| DxMessaging (Component) - No-Copy  | 9,552,000           | No           |
+| DxMessaging (Untargeted) - No-Copy | 14,900,000          | No           |
+| Reflexive (One Argument)           | 2,832,000           | No           |
+| Reflexive (Two Arguments)          | 2,348,000           | No           |
+| Reflexive (Three Arguments)        | 2,364,000           | No           |
 
 ## macOS
 

package/Docs/QuickReference.md

@@ -9,6 +9,7 @@ Do’s
 - Use GameObject/Component emit helpers (no manual `InstanceId`).
 - Register once; enable/disable with component state.
 - Prefer named handler methods over inline lambdas for reuse and clarity.
+- When using DI, inject `IMessageRegistrationBuilder` instead of newing `MessageHandler`s manually.
 
 Don’ts
 
@@ -77,6 +78,36 @@ _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
 void OnAnyDamage(ref InstanceId src, ref TookDamage m) { /* ... */ }
 ```
 
+Register (DI / services)
+
+```csharp
+using DxMessaging.Core.MessageBus;
+
+public sealed class DamageSystem : IStartable, IDisposable
+{
+    private readonly MessageRegistrationLease lease;
+
+    public DamageSystem(IMessageRegistrationBuilder registrationBuilder)
+    {
+        lease = registrationBuilder.Build(new MessageRegistrationBuildOptions
+        {
+            Configure = token =>
+            {
+                _ = token.RegisterUntargeted<TookDamage>(OnDamage);
+            }
+        });
+    }
+
+    public void Start() => lease.Activate();
+
+    public void Dispose() => lease.Dispose();
+
+    private static void OnDamage(ref TookDamage message) { /* respond */ }
+}
+```
+
+Tip: Define `ZENJECT_PRESENT`, `VCONTAINER_PRESENT`, or `REFLEX_PRESENT` to enable the optional shims under `Runtime/Unity/Integrations/` that bind the builder automatically for those containers.
+
 Interceptors and post‑processors
 
 ```csharp