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

package/Samples~/DI/README.md

@@ -0,0 +1,51 @@
+# DxMessaging DI Samples
+
+These snippets illustrate how to consume `IMessageRegistrationBuilder` inside common Unity dependency injection containers. The scripts compile only when the corresponding scripting define is enabled and the container package is present.
+
+## Setup
+
+1. Install the relevant container package (Zenject/Extenject, VContainer, or Reflex) into your Unity project.
+2. Enable the matching scripting define symbol in **Project Settings › Player › Scripting Define Symbols**:
+   - `ZENJECT_PRESENT`
+   - `VCONTAINER_PRESENT`
+   - `REFLEX_PRESENT`
+3. Import the sample folder you need into your Unity project (`Assets/Samples/DxMessaging/*`).
+
+Each sample shows:
+
+- Registering `IMessageRegistrationBuilder` via the provided shim under `Runtime/Unity/Integrations/`.
+- Constructing a `MessageRegistrationLease` in a container-managed service.
+- Activating/deactivating the lease using the container lifecycle.
+
+### Structure
+
+- `Zenject/SampleInstaller.cs`
+- `VContainer/SampleLifetimeScope.cs`
+- `Reflex/SampleInstaller.cs`
+- `Providers/CurrentGlobalMessageBusProvider.asset` — ScriptableObject that resolves whichever bus is currently configured as global.
+- `Providers/InitialGlobalMessageBusProvider.asset` — ScriptableObject that always returns the original startup global bus, ignoring later overrides.
+- `Prefabs/MessagingInstallerSample.prefab` — ready-to-use hierarchy with `MessagingComponentInstaller` configuring a child `MessagingComponent` using the provider asset. Drop it into a scene to see provider-driven wiring without writing setup code.
+
+## Walkthrough
+
+1. **Place the prefab**  
+   Drag `Prefabs/MessagingInstallerSample.prefab` into your test scene. The root object carries `MessagingComponentInstaller` with its provider handle already pointing at the global provider ScriptableObject.
+
+2. **Hook up the container**  
+   - **Zenject**:  
+     - Add `DxMessagingRegistrationInstaller` (from `Runtime/Unity/Integrations/`) to your ProjectContext or scene installer list.  
+     - Drop `Zenject/SampleInstaller.cs` into your project and register it alongside other installers. When the scene runs, the installer resolves `IMessageRegistrationBuilder`, stages a `PlayerSpawned` listener, and activates via the Zenject lifecycle.
+   - **VContainer**:  
+     - Define `VCONTAINER_PRESENT` and reference the optional extension under `Runtime/Unity/Integrations/VContainerRegistrationExtensions.cs`.  
+     - Add `VContainer/SampleLifetimeScope` to the scene (or derive from it); the sample scope registers the builder and an entry point that emits/consumes `ScoreUpdated` messages each tick.
+   - **Reflex**:  
+     - Enable `REFLEX_PRESENT` and install `DxMessagingRegistrationInstaller` into your container bootstrap.  
+     - Include `Reflex/SampleInstaller` in your installer chain. The sample service resolves `IMessageRegistrationBuilder`, subscribes to `PlayerAlert`, and can emit alerts via `EmitAlertFor`.
+
+3. **Emit a message**  
+   Use the service exposed by the container (e.g., call into `ScoreboardService` or `PlayerAlertService`) to emit a message. Because the prefab already configured `MessagingComponent` instances via the installer, the listeners run immediately.
+
+4. **Swap providers** (optional)  
+   Duplicate `Providers/CurrentGlobalMessageBusProvider.asset`, modify it to return a custom bus, assign it on the prefab root, and observe how builder-created leases now resolve that bus instead.
+
+Feel free to duplicate these scripts into your own project and adjust lifecycles or message types as needed.

package/Samples~/DI/README.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: e3bac3e795986eb44becc1eadeb7756d
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI/Reflex/SampleInstaller.cs

@@ -0,0 +1,75 @@
+#if REFLEX_PRESENT
+namespace DxMessaging.Samples.DI.Reflex
+{
+    using DxMessaging.Core;
+    using DxMessaging.Core.MessageBus;
+    using DxMessaging.Core.Messages;
+    using DxMessaging.Unity.Integrations.Reflex;
+    using Reflex.Core;
+    using UnityEngine;
+
+    /// <summary>
+    /// Demonstrates wiring <see cref="IMessageRegistrationBuilder"/> inside a Reflex container.
+    /// Requires the Reflex package and the REFLEX_PRESENT scripting define.
+    /// </summary>
+    public sealed class SampleInstaller : Installer
+    {
+        protected override void InstallBindings()
+        {
+            Container.Bind<MessageBus>().AsSingleton();
+            Container.Bind<IMessageBus>().FromContainer<MessageBus>();
+
+            // The DxMessagingRegistrationInstaller shim will have been installed elsewhere; we simply resolve the builder.
+            Container.Bind<PlayerAlertService>().AsSingleton();
+        }
+
+        private sealed class PlayerAlertService : System.IDisposable
+        {
+            private readonly IMessageBus _messageBus;
+            private readonly MessageRegistrationLease _lease;
+
+            public PlayerAlertService(IMessageBus messageBus, IMessageRegistrationBuilder builder)
+            {
+                _messageBus = messageBus;
+                _lease = builder.Build(
+                    new MessageRegistrationBuildOptions
+                    {
+                        Configure = token =>
+                        {
+                            _ = token.RegisterBroadcastWithoutSource<PlayerAlert>(OnPlayerAlert);
+                        },
+                        HandlerStartsActive = true,
+                        ActivateOnBuild = true,
+                    }
+                );
+            }
+
+            public void EmitAlertFor(GameObject source)
+            {
+                PlayerAlert alert = new PlayerAlert(source);
+                _messageBus.Emit(ref alert);
+            }
+
+            public void Dispose()
+            {
+                _lease.Dispose();
+            }
+
+            private void OnPlayerAlert(ref InstanceId source, ref PlayerAlert alert)
+            {
+                Debug.Log($"Reflex alert from {source.Id}");
+            }
+        }
+
+        private readonly struct PlayerAlert : IBroadcastMessage
+        {
+            public PlayerAlert(InstanceId source)
+            {
+                Source = source;
+            }
+
+            public InstanceId Source { get; }
+        }
+    }
+}
+#endif

package/Samples~/DI/Reflex/SampleInstaller.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 7d4c41a51a756ed40a140efe764197a9
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI/Reflex.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 0ea2325747ab75e4589eac788c59b276
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI/VContainer/SampleLifetimeScope.cs

@@ -0,0 +1,81 @@
+#if VCONTAINER_PRESENT
+namespace DxMessaging.Samples.DI.VContainer
+{
+    using System;
+    using Core.Attributes;
+    using Core.Extensions;
+    using Core.MessageBus;
+    using DxMessaging.Unity.Integrations.VContainer;
+    using UnityEngine;
+    using VContainer;
+    using VContainer.Unity;
+
+    /// <summary>
+    /// Sample lifetime scope showing DI-friendly registration via IMessageRegistrationBuilder.
+    /// Requires the VCONTAINER_PRESENT scripting define and VContainer package.
+    /// </summary>
+    public sealed class SampleLifetimeScope : LifetimeScope
+    {
+        protected override void Configure(IContainerBuilder builder)
+        {
+            builder.Register<MessageBus.MessageBus>(Lifetime.Singleton).As<IMessageBus>();
+            builder.RegisterMessageRegistrationBuilder();
+
+            builder.RegisterEntryPoint<ScoreboardService>(Lifetime.Singleton);
+        }
+
+        [DxUntargetedMessage]
+        private readonly struct ScoreUpdated
+        {
+            public readonly int Value;
+
+            public ScoreUpdated(int value)
+            {
+                Value = value;
+            }
+        }
+
+        private sealed class ScoreboardService : IStartable, ITickable, IDisposable
+        {
+            private readonly MessageRegistrationLease lease;
+            private int observedScores;
+
+            public ScoreboardService(IMessageRegistrationBuilder registrationBuilder)
+            {
+                lease = registrationBuilder.Build(
+                    new MessageRegistrationBuildOptions
+                    {
+                        Configure = token =>
+                        {
+                            _ = token.RegisterUntargeted<ScoreUpdated>(OnScoreUpdated);
+                        },
+                    }
+                );
+            }
+
+            public void Start()
+            {
+                lease.Activate();
+            }
+
+            public void Tick()
+            {
+                // Emit periodically for demo purposes
+                ScoreUpdated message = new ScoreUpdated(UnityEngine.Random.Range(0, 100));
+                message.Emit();
+            }
+
+            public void Dispose()
+            {
+                lease.Dispose();
+            }
+
+            private void OnScoreUpdated(ref ScoreUpdated message)
+            {
+                observedScores = message.Value;
+                Debug.Log($"Score observed: {observedScores}");
+            }
+        }
+    }
+}
+#endif

package/Samples~/DI/VContainer/SampleLifetimeScope.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 6dea981cef444594bbffa73a5e6905d5
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI/VContainer.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: e08544c97dd3b1540886f6b5f5f8f111
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI/Zenject/SampleInstaller.cs

@@ -0,0 +1,67 @@
+#if ZENJECT_PRESENT
+namespace DxMessaging.Samples.DI.Zenject
+{
+    using System;
+    using Core.Attributes;
+    using Core.MessageBus;
+    using UnityEngine;
+    using Zenject;
+
+    /// <summary>
+    /// Sample scene installer demonstrating how to bridge the registration builder into Zenject services.
+    /// Requires the DxMessaging Zenject registration shim and the ZENJECT_PRESENT scripting define.
+    /// </summary>
+    public sealed class SampleInstaller : MonoInstaller
+    {
+        public override void InstallBindings()
+        {
+            // Ensure the builder is available (provided by DxMessagingRegistrationInstaller).
+            Container.BindInterfacesTo<PlayerSpawnTracker>().AsSingle();
+        }
+
+        [DxUntargetedMessage]
+        private readonly struct PlayerSpawned
+        {
+            public readonly string PlayerName;
+
+            public PlayerSpawned(string playerName)
+            {
+                PlayerName = playerName;
+            }
+        }
+
+        private sealed class PlayerSpawnTracker : IInitializable, IDisposable
+        {
+            private readonly MessageRegistrationLease lease;
+
+            public PlayerSpawnTracker(IMessageRegistrationBuilder builder)
+            {
+                lease = builder.Build(
+                    new MessageRegistrationBuildOptions
+                    {
+                        Configure = token =>
+                        {
+                            _ = token.RegisterUntargeted<PlayerSpawned>(OnPlayerSpawned);
+                        },
+                    }
+                );
+            }
+
+            public void Initialize()
+            {
+                lease.Activate();
+            }
+
+            public void Dispose()
+            {
+                lease.Dispose();
+            }
+
+            private static void OnPlayerSpawned(ref PlayerSpawned message)
+            {
+                Debug.Log($"Player spawned: {message.PlayerName}");
+            }
+        }
+    }
+}
+#endif

package/Samples~/DI/Zenject/SampleInstaller.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 85ad1f9014b26d34caddf778e694f493
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI/Zenject.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: f772f4742ae2c4d4d8160700ab28009b
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/DI.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 7f6cc70d4b4c2684b82c30c14d1ae67e
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Samples~/Mini Combat/README.md

@@ -1,16 +1,79 @@
 # Mini Combat Sample
 
-> **What You'll Learn**: This sample demonstrates a simple combat system using DxMessaging to show how components communicate through messages. Perfect for beginners learning the messaging system!
+> **Perfect for:** First-time users who want to see messaging in action with a working combat example
 
-## Overview
+## What You'll Learn in 10 Minutes
 
-This mini-sample showcases a basic combat loop using DxMessaging with Unity-friendly APIs. You'll see how different game objects (Player, Enemy, UI) communicate without direct references to each other.
+**Stop reading documentation and start seeing it work!** This sample shows:
 
-### Key Concepts Demonstrated:
+1. How Player heals without UI knowing about Player (**zero coupling**)
+2. How Enemy broadcasts damage without knowing who cares (**observer pattern**)
+3. How settings changes update everything automatically (**global events**)
 
-- **Untargeted Messages**: Global messages anyone can listen to (like game settings)
-- **Targeted Messages**: Messages sent to a specific component (like healing a player)
-- **Broadcast Messages**: Messages announced to all listeners (like damage events)
+**No prior messaging experience needed** - this sample walks you through everything.
+
+---
+
+## Why This Sample Matters
+
+### Before DxMessaging:
+
+```csharp
+public class Player {
+    [SerializeField] private UI ui;          // Coupling!
+    [SerializeField] private AudioManager audio; // More coupling!
+
+    void Heal(int amount) {
+        health += amount;
+        ui.UpdateHealth(health);     // Manual call
+        audio.PlayHealSound();        // Manual call
+    }
+}
+```
+
+#### Every new system = another SerializeField + another manual call.
+
+##### With DxMessaging:
+
+```csharp
+public class Player : MessageAwareComponent {
+    void Heal(int amount) {
+        health += amount;
+        new PlayerHealed(amount).EmitBroadcast(this);
+        // Done! UI, audio, analytics all react automatically.
+    }
+}
+```
+
+###### Zero coupling. Zero manual wiring. That's the power of messaging.
+
+---
+
+## Key Concepts (3 Message Types)
+
+### 1. Untargeted - "Everyone, listen up!"
+
+**Example:** Game settings changed
+
+- Like a stadium announcement - everyone hears it
+- No specific target
+- Perfect for: settings, pause, scene transitions
+
+### 2. Targeted - "Hey YOU, do this!"
+
+**Example:** Heal this specific player
+
+- Like mailing a letter to one address
+- Only the target receives it
+- Perfect for: commands, direct actions
+
+### 3. Broadcast - "I did something!"
+
+**Example:** Enemy took damage
+
+- Like ringing a bell - anyone nearby can hear
+- Source announces, observers react
+- Perfect for: events, notifications, analytics
 
 ---
 
@@ -28,25 +91,22 @@ Here's what each script does:
 
 ---
 
-## Quick Start Guide
+## Quick Start Guide (2 Minutes to Working Demo)
 
-### Method 1: Import from Package Manager (Recommended)
+### Import & Run (Fastest Way)
 
-1. **Open Package Manager**:
-   - Window → Package Manager
+#### Want to see it work immediately?
 
-1. **Find DxMessaging**:
-   - Look for "DxMessaging" in the package list
-   - Click on it to select
+1. **Open Package Manager**: Window → Package Manager
+2. **Find DxMessaging** in the package list
+3. **Scroll to Samples** section → Find "Mini Combat" → Click **Import**
+4. **Navigate to** Assets/Samples/DxMessaging/.../Mini Combat/
+5. **Open the scene**
+6. **Press Play** 🎮
 
-1. **Import the Sample**:
-   - In the Package Manager details view, scroll down to find the "Samples" section
-   - Find "Mini Combat" and click **Import**
-   - The sample files will be imported into your Assets/Samples folder
+**That's it!** Watch the Console logs as messages flow.
 
-1. **Open the Scene**:
-   - Navigate to Assets/Samples/DxMessaging/.../Mini Combat/
-   - Open the sample scene or create a new scene and follow Step 1 below
+**Pro tip:** Enable diagnostics in the Inspector (MessagingComponent → Enable Diagnostics) to see message traffic in real-time.
 
 ### Method 2: Manual Setup in Your Scene
 
@@ -87,13 +147,11 @@ Press Play! The Boot script will automatically:
 
 ### The Message Flow
 
-```text
-Boot.cs (sends messages)
-    ↓
-    ├─→ VideoSettingsChanged (Untargeted) → UIOverlay.cs (receives)
-    ├─→ Heal (Targeted to Player)         → Player.cs (receives)
-    └─→ TookDamage (Broadcast from Enemy) → UIOverlay.cs (receives)
-```
+#### Boot.cs sends messages:
+
+1. `VideoSettingsChanged` (Untargeted) → UIOverlay.cs receives
+2. `Heal` (Targeted to Player) → Player.cs receives
+3. `TookDamage` (Broadcast from Enemy) → UIOverlay.cs receives
 
 ### Understanding Message Types
 

package/Samples~/Mini Combat/Walkthrough.md

@@ -1,6 +1,28 @@
 # Mini Combat Walkthrough
 
-> **Deep Dive**: This walkthrough explains the implementation details and shows how all the sample scripts work together at runtime. Great for understanding the "why" behind the code!
+> **Deep Dive**: Ready to understand HOW it works? This walkthrough explains every line of code and shows the complete message flow.
+
+## Who This Is For
+
+- ✅ **You've imported and run the sample** - now you want to understand it
+- ✅ **You want to build your own** - need to see the patterns in action
+- ✅ **You're debugging something** - need to understand the flow
+
+**Haven't run the sample yet?** Go back to [the sample README](README.md) and press Play first. Come back when you've seen it work.
+
+---
+
+## What You'll Understand By The End
+
+After reading this walkthrough, you'll know:
+
+1. **Why each message type was chosen** - the reasoning behind Untargeted vs Targeted vs Broadcast
+2. **How the code flows** - step-by-step from Boot.cs through every script
+3. **Common patterns** - Observer, Broadcaster, Orchestrator, and more
+4. **Debugging strategies** - how to find and fix issues
+5. **How to extend it** - add your own messages and handlers
+
+**Estimated time:** 20-30 minutes for thorough understanding
 
 ---
 
@@ -85,30 +107,24 @@ Let's understand what each script does:
 
 Here's the full sequence that happens when you press Play:
 
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│ STEP 1: Boot starts and sends VideoSettingsChanged             │
-│         (Untargeted - anyone can listen)                        │
-└────────────┬────────────────────────────────────────────────────┘
-             │
-             ├──────────────► UIOverlay receives it
-             │                └─► Rebuilds its UI
-             │
-┌────────────▼────────────────────────────────────────────────────┐
-│ STEP 2: Boot sends Heal message to Player                       │
-│         (Targeted - only the Player Component receives it)      │
-└────────────┬────────────────────────────────────────────────────┘
-             │
-             ├──────────────► Player receives it
-             │                └─► Increases HP by heal amount
-             │
-┌────────────▼────────────────────────────────────────────────────┐
-│ STEP 3: Enemy broadcasts TookDamage                             │
-│         (Broadcast - all listeners receive it)                  │
-└────────────┬────────────────────────────────────────────────────┘
-             │
-             ├──────────────► UIOverlay receives it
-                              └─► Shows damage notification
+```mermaid
+sequenceDiagram
+    participant Boot
+    participant UIOverlay
+    participant Player
+    participant Enemy
+
+    Note over Boot: STEP 1: Boot starts
+    Boot->>UIOverlay: VideoSettingsChanged (Untargeted)
+    Note over UIOverlay: Rebuilds UI
+
+    Note over Boot: STEP 2: Boot sends Heal
+    Boot->>Player: Heal (Targeted)
+    Note over Player: Increases HP by heal amount
+
+    Note over Enemy: STEP 3: Enemy broadcasts
+    Enemy->>UIOverlay: TookDamage (Broadcast)
+    Note over UIOverlay: Shows damage notification
 ```
 
 ---

package/Samples~/UI Buttons + Inspector/DiagnosticsEnabler.cs

@@ -1,4 +1,5 @@
 using DxMessaging.Core;
+using DxMessaging.Core.MessageBus;
 using UnityEngine;
 
 public sealed class DiagnosticsEnabler : MonoBehaviour
@@ -10,8 +11,17 @@ public sealed class DiagnosticsEnabler : MonoBehaviour
     {
         if (enableOnStart)
         {
-            MessageHandler.MessageBus.DiagnosticsMode = true;
-            Debug.Log("DxMessaging global diagnostics enabled.");
+            if (MessageHandler.MessageBus is MessageBus concreteBus)
+            {
+                concreteBus.DiagnosticsMode = true;
+                Debug.Log("DxMessaging global diagnostics enabled.");
+            }
+            else
+            {
+                Debug.LogWarning(
+                    "Global diagnostics are unavailable because the active global bus is not the default DxMessaging implementation."
+                );
+            }
         }
     }
 }