\n\n[](https://unity.com/releases/editor/archive) \n[](LICENSE.md) \n[](https://openupm.com/packages/com.wallstop-studios.dxmessaging/) \n[](https://www.npmjs.com/package/com.wallstop-studios.dxmessaging) \n[![Performance: Standalone (IL2CPP)]()](docs/architecture/performance.md) \n[](https://github.com/Ambiguous-Interactive/DxMessaging/actions/workflows/markdown-link-validity.yml)\n\n> **AI Assistance Disclosure:**\n>\n> This project has been actively developed and maintained by human authors for over a decade. Recent versions have utilized AI assistance for documentation, test coverage, and performance optimizations.\n\n**DxMessaging is a synchronous, type-safe Unity message bus for decoupled, simple systems.** It replaces sprawling C# events, brittle UnityEvents, and global static event buses with explicit message contracts, lifecycle-managed registrations, and editor-visible routing.\n\nUse it when one system needs to announce a fact, command a target, or broadcast from a source without keeping a direct scene reference to the receiver.\n\n```bash\nopenupm add com.wallstop-studios.dxmessaging\n```\n\nThe core taxonomy is small: **Untargeted** announcements, **Targeted** commands, and **Broadcast** facts from a source. Diagnostics mark them blue, purple, and green, respectively, and reserve red for problems. Message Monitor shows recent emissions and filters, Flow Graph shows registration topology and trace evidence, and the Inspector overlay catches `MessageAwareComponent` lifecycle mistakes.\n\nSee the [Install Guide](docs/getting-started/install.md) for Git URL, scoped registry, and release tarball options.\n\n## Table of Contents\n\n- [30-Second Elevator Pitch](#30-second-elevator-pitch)\n- [Mental Model: How to Think About DxMessaging](#mental-model-how-to-think-about-dxmessaging)\n- [Quick Start (5 Minutes)](#quick-start-5-minutes)\n- [Dependency Injection (DI) Compatible](#dependency-injection-di-compatible)\n- [Is DxMessaging Right for You?](#is-dxmessaging-right-for-you)\n- [Why DxMessaging](#why-dxmessaging)\n- [Key Features](#key-features)\n- [The DxMessaging Solution](#the-dxmessaging-solution)\n- [Real-World Examples](#real-world-examples)\n- [Performance](#performance)\n- [Comparison Table](#comparison-table)\n- [Samples](#samples)\n- [Documentation](#documentation)\n- [Requirements](#requirements)\n- [Contributing](#contributing)\n- [Links](#links)\n- [AI Agent Integration](#ai-agent-integration)\n\n---\n\n## 30-Second Elevator Pitch\n\n### If you've ever\n\n- Forgotten to unsubscribe from an event and spent hours debugging memory leaks\n- Had UI code tangled with 15 different game systems\n- Wondered \"which event fired when?\" with no way to see message flow\n- Copy-pasted event boilerplate dozens of times\n\n#### Then DxMessaging can help address these challenges\n\n- **Automatic lifecycle management** - manages subscription lifecycle automatically, no manual unsubscribe\n- **Zero coupling** - systems communicate without knowing each other exist\n- **Full visibility** - see every message in the Inspector with timestamps and payloads\n- **Complete control** - priority-based ordering, validation, and interception\n\n##### Three simple message types\n\n1. **Untargeted** - Global announcements\n1. **Targeted** - Commands to specific entities\n1. **Broadcast** - Observable facts from a source\n\nSee [Mental Model](#mental-model-how-to-think-about-dxmessaging) for how to choose the right type.\n\n**One line:** It's a type-safe messaging system with automatic lifecycle management and built-in inspection tools.\n\n---\n\n## Mental Model: How to Think About DxMessaging\n\n### The Core Idea\n\nDxMessaging is built around one principle: **it gets out of your way**.\n\nYou have data. You need to pass it around. That's the problem. DxMessaging provides fast, simple primitives as building blocks. You model changes as message types with optional context, using game primitives (GameObjects, components) as that context.\n\n**You don't build your game INTO the messaging system.** It's opt-in and optional -- a tool you reach for when it helps.\n\n### The Three Message Types: Real-World Analogies\n\n> 💡 _Diagrams below require Mermaid support. If they don't render, try viewing this file directly on [GitHub](https://github.com/Ambiguous-Interactive/DxMessaging)._\n\nEach message type maps to a real-world communication pattern:\n\n#### 1. Untargeted = PA System\n\n```mermaid\nflowchart LR\n S[Someone] -->|announces| PA[PA System]\n PA --> L1[Listener A]\n PA --> L2[Listener B]\n PA --> L3[Listener C]\n```\n\nAnnouncements with no specific recipient. Everyone who cares can hear it.\n\n**Examples:** \"The game is paused\", \"Settings changed\", \"Scene finished loading\"\n\n#### 2. Targeted = Addressed Letter\n\n```mermaid\nflowchart LR\n S[Sender] -->|\"To: Player\"| Letter[Message Bus]\n Letter --> Player[Player receives]\n Other1[Enemy A] -.->|ignores| Letter\n Other2[Enemy B] -.->|ignores| Letter\n```\n\nCommands to a specific recipient. Only that entity receives them.\n\n**Examples:** \"Player, heal for 10 HP\", \"Door #7, open\", \"This enemy, take 25 damage\"\n\n#### 3. Broadcast = Radio Station\n\n```mermaid\nflowchart LR\n Source[Enemy] -->|\"I took damage!\"| Radio[Message Bus]\n Radio --> L1[Damage Numbers UI]\n Radio --> L2[Achievement Tracker]\n Radio --> L3[Analytics]\n Radio --> L4[Combat Log]\n```\n\nFacts emitted by a specific source. No intended recipient -- just an origin. Anyone can tune in.\n\n**Examples:** \"This enemy took 25 damage\", \"The player picked up item X\", \"This chest opened\"\n\n### Choosing the Right Message Type\n\n```mermaid\nflowchart TD\n Start([I need to send a message])\n Start --> Q1{Does it matter WHO sent it?}\n\n Q1 -->|No| Q2{Does it matter WHO receives it?}\n Q2 -->|No| Untargeted[Use UNTARGETED Global announcement]\n Q2 -->|Yes| Targeted[Use TARGETED Directed command]\n\n Q1 -->|Yes| Q3{Am I commanding someone to act?}\n Q3 -->|Yes| Targeted\n Q3 -->|No| Broadcast[Use BROADCAST Observable fact]\n```\n\n| Question | Untargeted | Targeted | Broadcast |\n| ----------------------------------- | :--------: | :------: | :-------: |\n| Has a specific sender that matters? | No | No | Yes |\n| Has a specific recipient? | No | Yes | No |\n| Is it a command? | No | Yes | No |\n| Is it an observable fact? | Maybe | No | Yes |\n| Is it a global announcement? | Yes | No | No |\n\n> **Common Mistakes:**\n>\n> - **Forgetting to enable the token** -- Messages won't be received. Use `MessageAwareComponent` (auto-enables) or call `Token.Enable()` manually.\n> - **Targeting Component when you meant GameObject** -- These are distinct registration paths. Component-targeted messages won't reach GameObject-level handlers.\n> - **Using Broadcast when you need Targeted** -- Broadcasts have no recipient, just an origin. Use Targeted when commanding a specific entity.\n> - **Missing `[Dx*Message]` attribute** -- The source generator won't process the struct without the marker attribute.\n>\n> 📖 See [Troubleshooting](docs/reference/troubleshooting.md) for solutions to these and other issues.\n\n**Want more depth?** See the full [Mental Model documentation](docs/concepts/mental-model.md) for detailed examples, lifecycle patterns, and edge cases.\n\n**Ready to code?** Jump to [Quick Start](#quick-start-5-minutes) to send your first message!\n\n---\n\n## Quick Start (5 Minutes)\n\n**New to messaging?** Start with the [Visual Guide](docs/getting-started/visual-guide.md) (5 min) for a beginner-friendly introduction!\n\n### 1. Install\n\n#### Via OpenUPM (Recommended)\n\n```bash\nopenupm add com.wallstop-studios.dxmessaging\n```\n\n#### Or via Git URL\n\n```bash\n# Unity Package Manager > Add package from git URL...\nhttps://github.com/Ambiguous-Interactive/DxMessaging.git\n```\n\nSee the [Install Guide](docs/getting-started/install.md) for all options including NPM scoped registries and local tarballs.\n\n### 2. Define a Damage Command\n\n```csharp\nusing DxMessaging.Core.Attributes;\n\n[DxTargetedMessage]\n[DxAutoConstructor]\npublic readonly partial struct DamageRequested\n{\n public readonly int Amount;\n}\n```\n\n### 3. Receive Damage\n\n```csharp\nusing UnityEngine;\nusing DxMessaging.Unity;\n\npublic sealed class DamageReceiver : MessageAwareComponent\n{\n public int Health { get; private set; } = 100;\n\n protected override void RegisterMessageHandlers()\n {\n base.RegisterMessageHandlers();\n _ = Token.RegisterGameObjectTargeted(gameObject, OnDamageRequested);\n }\n\n private void OnDamageRequested(ref DamageRequested message)\n {\n Health = Mathf.Max(0, Health - Mathf.Max(0, message.Amount));\n }\n}\n```\n\n> **Heads-up:** When you override `Awake`, `OnEnable`, `OnDisable`, `OnDestroy`, or `RegisterMessageHandlers`, call the base method first or handlers fail silently. See [DXMSG006](docs/reference/analyzers.md#dxmsg006-missing-base-call).\n\n### 4. Add a Hazard\n\n```csharp\nusing DxMessaging.Core.Extensions;\nusing UnityEngine;\n\npublic sealed class Hazard : MonoBehaviour\n{\n public int Damage = 25;\n\n private void OnTriggerEnter(Collider other)\n {\n DamageRequested request = new DamageRequested(Damage);\n request.EmitGameObjectTargeted(other.gameObject);\n }\n}\n```\n\nOn the hazard GameObject, enable **Is Trigger** on its collider and add a kinematic `Rigidbody` with\n**Use Gravity** disabled. Put `DamageReceiver` and the entering collider on the same target\nGameObject. The hazard targets that exact object without knowing its concrete type. Registration\ncleanup follows the receiver's Unity lifecycle.\n\n**Stuck?** See [Troubleshooting](docs/reference/troubleshooting.md) or [FAQ](docs/reference/faq.md)\n\n---\n\n## Dependency Injection (DI) Compatible\n\n**Using Zenject, VContainer, or Reflex?** DxMessaging is fully DI-compatible out of the box!\n\n```csharp\n[DxUntargetedMessage]\npublic readonly struct GameStarted { }\n\n// Inject IMessageBus in any class\npublic class PlayerService : IInitializable, IDisposable\n{\n private readonly IMessageBus _messageBus;\n private readonly MessageRegistrationLease _lease;\n\n public PlayerService(IMessageBus messageBus, IMessageRegistrationBuilder builder)\n {\n _messageBus = messageBus;\n // Builder automatically resolves your container-managed bus\n _lease = builder.Build(new MessageRegistrationBuildOptions\n {\n Configure = token => token.RegisterUntargeted(OnGameStarted)\n });\n }\n\n public void Initialize() => _lease.Activate();\n public void Dispose() => _lease.Dispose();\n\n public void PublishGameStarted()\n {\n var started = new GameStarted();\n started.EmitUntargeted(_messageBus);\n }\n\n private static void OnGameStarted(GameStarted message)\n {\n Debug.Log(\"Game started\");\n }\n}\n```\n\n### Why use DI + Messaging?\n\n- **DI for construction** -- Inject services, repositories, managers via constructors\n- **Messaging for events** -- Reactive, decoupled communication for gameplay events\n- **Combined approach** -- Clean architecture with testable, isolated buses\n\n#### Automatic integration for\n\n- [x] **Zenject/Extenject** -- Full-featured DI with extensive Unity support\n- [x] **VContainer** -- Lightweight, high-performance DI with scoped lifetimes\n- [x] **Reflex** -- Minimal API, high-performance dependency injection\n\n##### Get started\n\n- [Zenject Integration Guide](docs/integrations/zenject.md) -- Complete setup with examples\n- [VContainer Integration Guide](docs/integrations/vcontainer.md) -- Scoped buses for scene isolation\n- [Reflex Integration Guide](docs/integrations/reflex.md) -- Minimal, lightweight patterns\n\n##### Core DI concepts\n\n- [Runtime Configuration](docs/advanced/runtime-configuration.md) -- Setting message buses at runtime, re-binding registrations\n- [Message Bus Providers](docs/advanced/message-bus-providers.md) -- Provider system for design-time and runtime bus configuration\n\n**Not using DI?** No problem. DxMessaging works standalone with zero dependencies.\n\n---\n\n## Is DxMessaging Right for You?\n\n### Use DxMessaging When\n\n- **You have cross-system communication** - UI needs to react to gameplay, achievements track events, analytics observe everything\n- **You're building for scale** - 10+ systems that need to communicate, or growing from prototype to production\n- **Memory leaks are a concern** - You've been bitten by forgotten event unsubscribes before\n- **You value observability** - Need to debug \"what fired when?\" or track message flow\n- **Teams/long-term maintenance** - Multiple developers, or you'll maintain this code for years\n- **You want decoupling** - When UI classes need references to many game systems\n- **You're using DI frameworks** - Compatible with Zenject/VContainer/Reflex (see [DI Compatible](#dependency-injection-di-compatible))\n\n### Don't Use DxMessaging When\n\n- **Tiny prototypes/game jams** - If your game is <1000 lines and will be done in a week, C# events are fine\n- **Simple, local communication** - A single button calling a single method? Just use UnityEvents or direct references\n- **Performance is THE constraint** - Building a physics engine or ECS with millions of events/frame? Raw delegates are faster\n- **Team is unfamiliar** - Learning curve exists; if the team isn't on board, it won't be used correctly\n- **You need synchronous return values** - DxMessaging is fire-and-forget; if you need bidirectional request/response, consider other patterns\n\n### Maybe Use DxMessaging (Start Small)\n\n- **Existing large codebase** - Migrate incrementally: start with new features, refactor old code gradually (see [Migration Guide](docs/guides/migration-guide.md))\n- **Small team learning** - Try it for one system (e.g., achievements) before going all-in\n- **Mid-size projects (5-20k lines)** - Evaluate after trying it for one complex interaction (e.g., combat or scene transitions)\n\n### Decision Flow\n\n```mermaid\nflowchart TD\n Q1{Does your project have 3+ systems that need to talk to each other?}\n Q1 -->|NO| A1[Stick with C# events or direct references]\n Q1 -->|YES| Q2\n\n Q2{Are you okay with a small upfront learning investment?}\n Q2 -->|NO| A2[Stick with what you know]\n Q2 -->|YES| Q3\n\n Q3{Do you need observable, decoupled, lifecycle-safe messaging?}\n Q3 -->|YES| A3[\" Use DxMessaging\"]\n Q3 -->|NO| A4[\" Keep it simple\"]\n```\n\n**Rule of thumb:** If decoupling, lifecycle leaks, or handler-ordering bugs match what you're hitting today, DxMessaging fits. If none of those describe your project, start with the [Visual Guide](docs/getting-started/visual-guide.md) or stick with simpler patterns.\n\nLooking for hard numbers? See the Standalone IL2CPP dispatch and library-comparison [Performance Benchmarks](docs/architecture/performance.md).\n\n## Why DxMessaging\n\n### The Problems You've Probably Hit\n\n#### Scenario 1: The Memory Leak Nightmare\n\nYou write this innocent-looking code:\n\n```csharp\npublic class GameUI : MonoBehaviour {\n void OnEnable() {\n GameManager.Instance.OnScoreChanged += UpdateScore;\n }\n // Oops, forgot OnDisable... leak!\n}\n```\n\nMonths later: \"Why is our game using 2GB of RAM after an hour?\"\n\n#### Scenario 2: The Spaghetti Mess\n\n```csharp\npublic class GameUI : MonoBehaviour {\n [SerializeField] private Player player;\n [SerializeField] private EnemySpawner spawner;\n [SerializeField] private InventorySystem inventory;\n [SerializeField] private QuestSystem quests;\n [SerializeField] private AudioManager audio;\n // ... 15 more SerializeFields ...\n\n void Awake() {\n player.OnHealthChanged += UpdateHealth;\n spawner.OnWaveStart += ShowWave;\n inventory.OnItemAdded += RefreshInventory;\n quests.OnQuestCompleted += ShowQuestNotification;\n // ... 20 more subscriptions ...\n }\n}\n```\n\n**Your UI now depends on many systems.** Refactoring becomes more difficult.\n\n#### Scenario 3: The Debugging Black Hole\n\nPlayer reports: \"My health bar didn't update!\"\n\nYou think: \"Okay, which of the 47 events touching health failed? And in what order?\"\n\n**30 minutes later:** Still setting breakpoints everywhere...\n\n### Common Challenges\n\nSome developers encounter these challenges when working with traditional event systems:\n\n- **Memory leaks** from forgotten unsubscribes\n- **Tight coupling** making refactoring difficult\n- **No execution order control** leading to unpredictable behavior\n- **Limited debugging visibility** for tracking message flow\n- **Boilerplate code** when managing many event subscriptions\n\n### The DxMessaging Solution\n\n#### Same scenarios, simplified handling\n\n##### Scenario 1: No More Memory Leaks\n\n```csharp\npublic class GameUI : MessageAwareComponent {\n protected override void RegisterMessageHandlers() {\n base.RegisterMessageHandlers();\n _ = Token.RegisterUntargeted(UpdateScore);\n }\n // No manual cleanup needed.\n // Token automatically handles OnEnable/OnDisable/OnDestroy\n}\n```\n\n###### Automatic lifecycle = leaks are prevented by default\n\n##### Scenario 2: No More Coupling\n\n```csharp\npublic class GameUI : MessageAwareComponent {\n // Zero SerializeFields! Zero references!\n\n protected override void RegisterMessageHandlers() {\n base.RegisterMessageHandlers();\n _ = Token.RegisterBroadcastWithoutSource(OnHealth);\n _ = Token.RegisterUntargeted(OnWave);\n _ = Token.RegisterUntargeted(OnItem);\n // Observe entity facts by source and global events without direct references\n }\n}\n```\n\n**Your UI is now independent.** Swapping systems no longer requires updating UI references.\n\n##### Scenario 3: Debugging is Built In\n\nOpen any `MessageAwareComponent` in the Inspector:\n\n```text\nMessage History (last 50):\n[12:34:56] HealthChanged (amount: 25) -> Priority: 0\n[12:34:55] ItemAdded (id: 42, count: 1) -> Priority: 5\n[12:34:54] WaveStarted (wave: 3) -> Priority: 0\n\nActive Registrations:\n HealthChanged (5 handlers)\n ItemAdded (2 handlers)\n```\n\n**See exactly what fired, when, and who handled it.** No guesswork.\n\n### How It Transforms Your Code\n\n```csharp\n// 1. Define messages (typed, discoverable)\n[DxTargetedMessage]\n[DxAutoConstructor]\npublic readonly partial struct Heal { public readonly int amount; }\n\n// 2. Listen (automatic lifecycle - prevents leaks)\npublic class Player : MessageAwareComponent {\n protected override void RegisterMessageHandlers() {\n base.RegisterMessageHandlers();\n _ = Token.RegisterComponentTargeted(this, OnHeal);\n }\n\n void OnHeal(ref Heal m) {\n health += m.amount;\n Debug.Log($\"Healed {m.amount}!\");\n }\n}\n\n// 3. Send (from anywhere - zero coupling)\nvar heal = new Heal(50);\nheal.EmitComponentTargeted(playerComponent);\n```\n\n#### What you get\n\n- [x] **Automatic cleanup** - tokens clean up when components are destroyed\n- [x] **Zero coupling** - no SerializeFields, no GetComponent, no direct references\n- [x] **Full visibility** - see message flow in Inspector with timestamps and payloads\n- [x] **Predictable order** - priority-based execution (no more mystery race conditions)\n- [x] **Type-safe** - compile-time guarantees, refactor with confidence\n- [x] **Intercept & validate** - enforce rules before handlers run (clamp damage, block invalid input)\n- [x] **Extension points everywhere** - interceptors, handlers, post-processors with priorities\n\n## Key Features\n\nWhat DxMessaging offers:\n\n### Performance: Zero-Allocation Design\n\n**The problem with normal events:** Boxing allocations, GC spikes, memory leaks from forgotten unsubscribes.\n\n#### DxMessaging solution\n\n```csharp\nvoid OnDamage(ref ApplyDamage msg) { // Pass by ref = zero allocations\n health -= msg.amount; // No boxing, no GC pressure\n}\n// Automatic cleanup prevents common leak patterns\n```\n\n**Note:** Struct messages passed by ref avoid GC allocations, which is standard behavior for value types in C#.\n\n### Three Message Types\n\nMost event systems force you into one pattern. DxMessaging gives you the right tool for each job:\n\n```csharp\n// Untargeted: \"Everyone, listen up!\" (global announcements)\n[DxUntargetedMessage]\npublic struct GamePaused { }\n// -> Perfect for: settings, scene transitions, global state\n\n// Targeted: \"Hey Player, do this!\" (commands to specific entities)\n[DxTargetedMessage]\npublic struct Heal { public int amount; }\n// -> Perfect for: UI actions, direct commands, player input\n\n// Broadcast: \"I took damage!\" (events others can observe)\n[DxBroadcastMessage]\npublic struct TookDamage { public int amount; }\n// -> Perfect for: achievements, analytics, UI updates from entities\n```\n\n**Why this matters:** You're not forcing everything through one generic \"Event\" pattern. Each message type has clear semantics.\n\n### The Message Pipeline\n\nEvery message flows through 3 stages with priority control:\n\n```mermaid\nflowchart LR\n P[Producer] --> I[Interceptors validate/mutate]\n I --> H[Handlers main logic]\n H --> PP[Post-Processors metrics/replay]\n```\n\n### Global Observers: Listen to All Events\n\n**The problem with normal events:** To track all player damage, enemy damage, and NPC damage, you need 3 separate event subscriptions.\n\n**DxMessaging approach:** Subscribe once to a message type, receive all instances with source information:\n\n```csharp\n// Track ALL damage from ANY source (players, enemies, NPCs, environment)\n_ = token.RegisterBroadcastWithoutSource(\n (InstanceId source, TookDamage msg) => {\n Debug.Log($\"{source} took {msg.amount} damage!\");\n Analytics.LogDamage(source, msg.amount);\n CheckAchievements(source, msg.amount);\n }\n);\n```\n\n#### Real-world use cases\n\n- **Achievement system:** Track all kills, deaths, damage across the entire game\n- **Combat log:** \"Player took 25 damage, Enemy3 took 50 damage, Boss took 100 damage\"\n- **Analytics:** Aggregate stats from all entities without knowing about them upfront\n- **Debug tools:** Watch ALL messages in the Inspector without instrumenting code\n\n**How this differs:** Some event bus patterns require subscribing to each entity type separately. DxMessaging allows observing all instances of a message type in one registration.\n\n### Interceptors: Validate Before Execution\n\n**The problem with normal events:** Validation logic duplicated in every handler, or bugs when you forget.\n\n**DxMessaging solution:** Validate ONCE before ANY handler runs:\n\n```csharp\n[DxTargetedMessage]\npublic struct ApplyDamage { public int amount; }\n\n// ONE interceptor protects ALL handlers\n_ = token.RegisterTargetedInterceptor(\n (ref InstanceId target, ref ApplyDamage msg) => {\n if (msg.amount <= 0) return false; // Cancel invalid\n if (msg.amount > 999) {\n msg = new ApplyDamage(999); // Clamp excessive\n }\n if (IsGodModeActive(target)) return false; // Block damage\n return true;\n },\n priority: -100 // Run FIRST\n);\n\n// Now ALL handlers receive clean, validated data\n_ = token.RegisterComponentTargeted(player, OnDamage);\nvoid OnDamage(ref ApplyDamage msg) {\n // No validation needed - interceptor guarantees validity!\n health -= msg.amount;\n}\n```\n\n#### Real-world use cases\n\n- Clamp/normalize values (damage, healing, speeds)\n- Enforce game rules (\"can't heal above max health\")\n- Block messages during cutscenes\n- Log/audit sensitive actions\n\n### Built-in Editor Diagnostics\n\n**The problem with normal events:** \"Which event fired? When? Who handled it? In what order?\" = unknown\n\n**DxMessaging solution:** turn on diagnostics in the Inspector or Project Settings, then use the\ndedicated Unity editor tools under **Tools > Wallstop Studios > DxMessaging**.\n\n#### Message Monitor\n\n- Recent global-bus emissions, most-recent first\n- Message type, context, and stack trace details\n- Plain text filtering, `type:` / `message:` / `context:` / `stack:` field\n filters, an active-filter summary with Clear, and Copy JSON export\n- Visible message-type lanes showing per-filter entry counts, context breadth,\n and message-volume share, plus context lanes showing context volume and\n message breadth, with row-level Filter shortcuts and exact quoted context\n shortcuts\n- Loaded-scene `MessagingComponent` diagnostics, including listener counts,\n registrations, calls, local messages, and provider warnings\n\n#### Flow Graph\n\n- Crossing-aware layered message and receiver nodes with ordered connection\n ports, feathered arrow paths, arrowhead direction, and shape-and-color route\n selectors; click anywhere along a route to inspect it\n- Fit, zoom-out, and zoom-in controls for dense graphs, with automatic framing\n down to 20 percent so hundreds of routes remain available in one overview\n- Named node metrics for sources or targets, receivers, handlers, calls, and\n state instead of compact `+N` overflow summaries; multi-kind message types\n use neutral `MIXED` metrics until filtered to one route kind\n- No default selection or details wall on open; responsive route details split\n route and activity from collapsed emission, trace, and technical evidence\n- Recent registration-exact delivery call sites for targeted and broadcast\n routes; call sites identify the script and method when token diagnostics are\n enabled without leaking evidence across components or message buses, and\n source links open the exact message declaration or captured call-site line\n- Global accept-all registrations shown as `ANY MESSAGE` observer scope rather\n than as an `IMessage` message type\n- Route summaries that surface busy, inactive, and uncalled paths\n- Message, target, route-kind, and context lanes for narrowing dense graphs\n- Recent delivery evidence and trace details for the selected route\n- JSON export for sharing a filtered diagnostic snapshot\n\n#### Inspector integration\n\nClick any `MessagingComponent` in the Inspector for component-local diagnostics\nand any `MessageAwareComponent` subclass for base-call warning surfaces.\n\n#### Real-world debugging scenarios\n\n- \"Did my message fire?\" -> Check Message Monitor history.\n- \"Why didn't my handler run?\" -> Check registrations and Flow Graph edges.\n- \"What's firing too often?\" -> Compare call counts in component and route summaries.\n- \"Which source/target context was involved?\" -> Check Message Monitor context\n and Flow Graph trace paths.\n\n**No more:** Setting 50 breakpoints and stepping through code for 30 minutes.\n\nSee [Diagnostics](docs/guides/diagnostics.md) for the current editor tooling and\ntrace-path semantics. The\n[Diagnostics Tooling Exerciser](Samples~/Diagnostics%20Tooling%20Exerciser/README.md)\nsample imports a deterministic scene that drives Message Monitor, Flow Graph,\nInspector diagnostics, and Project Settings together.\n\n### Local Bus Islands for Testing\n\n**The problem with normal events:** Global static events contaminate tests. Mock complexity. Flaky tests.\n\n**DxMessaging solution:** Each test gets its own isolated message bus:\n\n```csharp\n[Test]\npublic void TestAchievementSystem() {\n // Create isolated bus - zero global state\n var testBus = new MessageBus();\n var handler = new MessageHandler(new InstanceId(1), testBus) { active = true };\n var token = MessageRegistrationToken.Create(handler, testBus);\n\n // Test in isolation\n _ = token.RegisterBroadcastWithoutSource(achievements.OnKill);\n\n var gameObject = new GameObject();\n var msg = new EnemyKilled(\"Boss\");\n msg.EmitGameObjectBroadcast(gameObject, testBus); // Only this test sees it\n\n Assert.IsTrue(achievements.Unlocked(\"BossSlayer\"));\n}\n// Bus destroyed, zero cleanup needed\n```\n\n#### Why this matters\n\n- Tests don't interfere with each other\n- No \"arrange/act/cleanup\" boilerplate\n- No mocking frameworks needed\n- Parallel test execution is supported\n\n## Documentation\n\n- **[Documentation Site](https://ambiguous-interactive.github.io/DxMessaging/)** - Full searchable documentation\n- **[Wiki](https://github.com/Ambiguous-Interactive/DxMessaging/wiki)** - Quick reference wiki\n- **[Changelog](CHANGELOG.md)** - Version history\n\n### Learn\n\n- **New here?** Start with [Getting Started Guide](docs/getting-started/getting-started.md) (10 min read)\n- **Want patterns?** See [Common Patterns](docs/guides/patterns.md)\n- **Deep dive?** Read [Design & Architecture](docs/architecture/design-and-architecture.md)\n\n### Core Concepts\n\n- [Overview](docs/getting-started/overview.md) -- What and why\n- [Quick Start](docs/getting-started/quick-start.md) -- First message in 5 minutes\n- [Message Types](docs/concepts/message-types.md) -- When to use Untargeted/Targeted/Broadcast\n- [Interceptors & Ordering](docs/concepts/interceptors-and-ordering.md) -- Control execution flow\n- [Listening Patterns](docs/concepts/listening-patterns.md) -- All the ways to receive messages\n\n### Unity Integration\n\n- [Unity Integration](docs/guides/unity-integration.md) -- MessagingComponent deep dive\n- [Targeting & Context](docs/concepts/targeting-and-context.md) -- GameObject vs Component\n- [Diagnostics](docs/guides/diagnostics.md) -- editor tools, traces, and debugging\n- [Memory Reclamation](docs/guides/memory-reclamation.md) -- idle eviction, explicit Trim, and tuning the runtime settings asset\n\nImportant: Inheritance with MessageAwareComponent\n\n- If you override lifecycle or registration hooks, call the base method.\n- Use `base.RegisterMessageHandlers()` to keep default string-message registrations.\n- Use `base.OnEnable()` / `base.OnDisable()` to preserve token enable/disable.\n- If you need to opt out of string demos, override `RegisterForStringMessages => false` instead of skipping the base call.\n- Don't hide Unity methods with `new` (e.g., `new void OnEnable()`); always `override` and call `base.*`.\n\n### DI Framework Integrations\n\nDxMessaging works standalone (zero dependencies) or with any major DI framework. For detailed setup guides and code examples:\n\n- **[Zenject Integration Guide](docs/integrations/zenject.md)** -- Full-featured DI with extensive Unity support\n- **[VContainer Integration Guide](docs/integrations/vcontainer.md)** -- Lightweight DI with scoped lifetimes for scene isolation\n- **[Reflex Integration Guide](docs/integrations/reflex.md)** -- Minimal API, high-performance DI\n\n#### Core DI concepts\n\n- **[Runtime Configuration](docs/advanced/runtime-configuration.md)** -- Setting and overriding message buses at runtime, re-binding registrations\n- **[Message Bus Providers](docs/advanced/message-bus-providers.md)** -- Provider system and MessageBusProviderHandle for flexible bus configuration\n\nEach guide includes:\n\n- [x] Complete setup instructions with installers\n- [x] Multiple usage patterns (plain classes, MonoBehaviours, direct injection)\n- [x] Testing examples with isolated buses\n- [x] Advanced patterns (pooling, scene scopes, signal bridges)\n\nSee the [DI Compatible section](#dependency-injection-di-compatible) above for a quick overview.\n\n### Comparisons\n\n- [Compare with Other Unity Messaging Frameworks](docs/architecture/comparisons.md) -- In-depth comparison with UniRx, MessagePipe, Zenject Signals, C# events, UnityEvents, and more\n- [Scriptable Object Architecture (SOA) Compatibility](docs/guides/patterns.md#14-compatibility-with-scriptable-object-architecture-soa) -- Migration patterns and interoperability with SOA\n\n#### Quick Framework Comparison\n\n| Framework | Best For | Key Strength | Unity Support | Learning Curve |\n| ------------------- | --------------------------------- | -------------------------------- | --------------- | -------------- |\n| **DxMessaging** | Unity pub/sub with lifecycle mgmt | Inspector debugging + control | Built for Unity | Moderate |\n| **UniRx** | Complex event stream transforms | Reactive operators (LINQ) | Built for Unity | Easy |\n| **MessagePipe** | High-performance DI messaging | Highest throughput (74M ops/sec) | Built for Unity | Steep |\n| **Zenject Signals** | DI-integrated messaging | Zenject ecosystem | Built for Unity | Easy |\n| **C# Events** | Simple, local communication | Minimal overhead | Native C# | Steepest |\n\n##### Choose DxMessaging when you want\n\n- Unity-first design with GameObject/Component targeting\n- Automatic lifecycle management (prevents common memory leaks)\n- Inspector debugging to see message flow and history\n- Execution order control (priority-based handlers)\n- Message validation/interception pipeline\n- Global observers (listen to all message instances)\n- Post-processing stage (analytics, logging after handlers)\n- No dependencies, plug-and-play setup\n\nSee [full comparison](docs/architecture/comparisons.md) for detailed analysis with code examples, performance benchmarks, and decision guides.\n\n> **📦 Using Scriptable Object Architecture (SOA)?**\n>\n> DxMessaging can work alongside or replace SOA patterns. See [SOA Compatibility Guide](docs/guides/patterns.md#14-compatibility-with-scriptable-object-architecture-soa) for:\n>\n> - Fair comparison of SOA vs. DxMessaging\n> - Migration patterns from GameEvent/FloatVariable to DxMessaging\n> - How to use both systems together (SOs for configs, DxMessaging for events)\n> - When to keep using ScriptableObjects (immutable design data)\n\n### Reference\n\n- [Install Guide](docs/getting-started/install.md) -- All install options (OpenUPM, Git URL, scoped registry, tarball)\n- [Glossary](docs/reference/glossary.md) -- All terms explained in plain English\n- [Quick Reference](docs/reference/quick-reference.md) -- Cheat sheet\n- [API Reference](docs/reference/reference.md) -- Complete API\n- [Helpers](docs/reference/helpers.md) -- Source generators and utilities\n- [FAQ](docs/reference/faq.md) -- Common questions\n- [Troubleshooting](docs/reference/troubleshooting.md)\n\n### Full Documentation\n\nBrowse all docs: [Documentation Hub](docs/getting-started/index.md)\n\n## Real-World Examples\n\n### Scene Transitions\n\n```csharp\n[DxUntargetedMessage]\n[DxAutoConstructor]\npublic readonly partial struct SceneTransition {\n public readonly string sceneName;\n}\n\n// Multiple systems react independently\npublic class AudioSystem : MessageAwareComponent {\n protected override void RegisterMessageHandlers() {\n base.RegisterMessageHandlers();\n _ = Token.RegisterUntargeted(OnScene, priority: 0);\n }\n void OnScene(ref SceneTransition m) => FadeOutMusic();\n}\n\npublic class SaveSystem : MessageAwareComponent {\n protected override void RegisterMessageHandlers() {\n base.RegisterMessageHandlers();\n _ = Token.RegisterUntargeted(OnScene, priority: 0);\n }\n void OnScene(ref SceneTransition m) => SaveGame();\n}\n```\n\n### Achievement System\n\n```csharp\n// Listen to ALL events for achievement tracking\npublic class AchievementTracker : MessageAwareComponent {\n protected override void RegisterMessageHandlers() {\n base.RegisterMessageHandlers();\n _ = Token.RegisterGlobalAcceptAll(\n acceptAllUntargeted: m => Check(m),\n acceptAllTargeted: (t, m) => Check(m),\n acceptAllBroadcast: (s, m) => Check(m)\n );\n }\n}\n```\n\n## Performance\n\n- **Zero GC allocations** for struct messages\n- **~10ns overhead** per handler (compared to C# events)\n- **Type-indexed caching** for O(1) lookups\n- **Optimized for hot paths** with aggressive inlining\n\nSee [Design & Architecture](docs/architecture/design-and-architecture.md#performance-optimizations) for details.\n\nFor live, CI-generated Standalone IL2CPP dispatch tables and a cross-library comparison matrix, see [Performance Benchmarks](docs/architecture/performance.md). Those numbers are auto-generated on every push with the .NET Standard 2.1 profile and a Release build; the comparison table below is a static summary, not the live data.\n\n## Comparison Table\n\n### Comparison with Unity Messaging Frameworks\n\n| Feature | DxMessaging | UniRx | MessagePipe | Zenject Signals |\n| ------------------------ | --------------- | --------------- | --------------- | --------------- |\n| **Unity Compatibility** | Built for Unity | Built for Unity | Built for Unity | Built for Unity |\n| **Decoupling** | Full | Full | Full | Full |\n| **Lifecycle Safety** | Auto | Manual | Manual | DI-managed |\n| **Execution Order** | Priority | None | None | None |\n| **Type Safety** | Strong | Strong | Strong | Strong |\n| **Inspector Debug** | Built-in | No | No | No |\n| **GameObject Targeting** | Yes | No | No | No |\n| **Global Observers** | Yes | No | No | No |\n| **Interceptors** | Pipeline | No | Filters | No |\n| **Post-Processing** | Dedicated | No | Filters | No |\n| **Stream Operators** | No | Extensive | No | With UniRx |\n| **Performance** | Good (27M) | Moderate (4M) | High (74M) | Moderate (2M) |\n| **Dependencies** | None | UniTask | None | Zenject |\n\n### Comparison with Traditional Approaches\n\n| Feature | DxMessaging | C# Events | UnityEvents | Static Event Bus |\n| ---------------------- | ----------- | --------- | ----------- | ---------------- |\n| **Decoupling** | Full | Tight | Hidden | Yes |\n| **Lifecycle Safety** | Auto | Manual | Unity-only | Manual |\n| **Execution Order** | Priority | Undefined | Undefined | Undefined |\n| **Type Safety** | Strong | Strong | Weak | Weak |\n| **Context (Who/What)** | Rich | None | None | None |\n| **Interception** | Yes | No | No | No |\n| **Observability** | Built-in | No | No | No |\n| **Performance** | Zero-alloc | Good | Boxing | Good |\n\n## Samples\n\nImport samples from Package Manager:\n\n- **[Mini Combat](Samples~/Mini%20Combat/README.md)** -- Simple combat with Heal/Damage messages\n- **[UI Buttons + Inspector](Samples~/UI%20Buttons%20%2B%20Inspector/README.md)** -- Interactive diagnostics demo\n- **[Diagnostics Tooling Exerciser](Samples~/Diagnostics%20Tooling%20Exerciser/README.md)** -- Deterministic scene for Message Monitor, Flow Graph, Inspector diagnostics, and Project Settings\n\n## Requirements\n\n- Unity 2021.3 or later\n- .NET Standard 2.1\n- Works with all render pipelines (URP, HDRP, Built-in)\n\nSee [Compatibility](docs/reference/compatibility.md) for details.\n\n## Contributing\n\nContributions welcome! See [Contributing](CONTRIBUTING.md).\n\n## License\n\nMIT License - see [License](LICENSE.md)\n\n## Credits\n\nCreated and maintained by [wallstop studios](https://wallstopstudios.com)\n\n## Links\n\n- [Package on GitHub](https://github.com/Ambiguous-Interactive/DxMessaging)\n- [Report Issues](https://github.com/Ambiguous-Interactive/DxMessaging/issues)\n- [Documentation Site](https://ambiguous-interactive.github.io/DxMessaging/)\n- [Wiki](https://github.com/Ambiguous-Interactive/DxMessaging/wiki)\n\n## AI Agent Integration\n\nDxMessaging publishes machine-readable context for AI agents through [llms.txt](llms.txt), following the [llmstxt.org](https://llmstxt.org/) standard. The file collects the project overview, API surface, conventions, and links into one document.\n\n### For AI Agents\n\n- **[llms.txt](llms.txt)** -- Complete project overview, API reference, and context in a single file\n- **[Repository Guidelines](.llm/context.md)** -- Coding standards and development workflows\n- **[AI Agent Skills](.llm/skills/)** -- 31+ specialized skills covering documentation, testing, GitHub Actions, and more\n\nThe `llms.txt` file is automatically updated via CI/CD to stay current with project changes. It includes:\n\n- Project overview and quick facts\n- Core concepts and architecture\n- Complete documentation links\n- Development commands and standards\n- Common pitfalls and solutions\n- Performance characteristics\n- Code examples and patterns\n\n### Keeping llms.txt Updated\n\nThe automation script ensures llms.txt stays current:\n\n```bash\n# Update llms.txt\nnpm run update:llms-txt\n\n# Verify llms.txt is current\nnpm run check:llms-txt\n```\n\nGitHub Actions automatically validates and updates llms.txt:\n\n- **Validation:** Runs on PRs to ensure llms.txt is up-to-date\n- **Auto-update:** Runs weekly and on relevant file changes\n\n---\n","readmeFilename":"README.md"}
![\"DxMessaging](\"docs/images/DxMessaging-banner.svg\")
\n![\"Documentation\"](\"https://img.shields.io/badge/Docs-ambiguous--interactive.github.io-f4a836?style=for-the-badge\"){kind=icon}