com.wallstop-studios.dxmessaging 2.0.0 → 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

@@ -147,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

@@ -107,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."
+                );
+            }
         }
     }
 }

package/Samples~/UI Buttons + Inspector/README.md.meta

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