com.wallstop-studios.dxmessaging 2.1.7 → 2.1.8

package/docs/examples/end-to-end-scene-transitions.md

@@ -1,130 +0,0 @@
-# End‑to‑End Example: Scene Transitions + Overlay Pause
-
-Short intro
-
-An end‑to‑end pattern showing scene‑scoped buses, a global overlay that persists across scenes, and pausing emissions/listeners safely.
-
-Scenario
-
-- Each scene has its own local MessageBus for scene‑scoped flows.
-- A global overlay persists across scenes and listens to global notifications.
-- During pause, some systems should stop processing (Disable tokens), but others still emit (emit while disabled).
-
-Setup
-
-```csharp
-using DxMessaging.Core;
-using DxMessaging.Core.MessageBus;
-using UnityEngine;
-
-public static class SceneBus
-{
-    public static MessageBus Current { get; private set; } = new MessageBus();
-    public static void NewScene() => Current = new MessageBus();
-}
-```
-
-Messages
-
-```csharp
-using DxMessaging.Core.Attributes;
-
-[DxUntargetedMessage][DxAutoConstructor]
-public readonly partial struct SceneLoaded { public readonly int buildIndex; }
-
-[DxUntargetedMessage][DxAutoConstructor]
-public readonly partial struct Paused { }
-
-[DxUntargetedMessage][DxAutoConstructor]
-public readonly partial struct Resumed { }
-```
-
-Global overlay (persists across scenes)
-
-```csharp
-using DxMessaging.Unity;
-using DxMessaging.Core.Messages;
-using UnityEngine;
-
-public sealed class GlobalOverlay : MessageAwareComponent
-{
-    protected override void RegisterMessageHandlers()
-    {
-        base.RegisterMessageHandlers();
-        DontDestroyOnLoad(gameObject);
-        _ = Token.RegisterUntargeted<SceneLoaded>(OnSceneLoaded);
-        _ = Token.RegisterUntargeted<Paused>(m => ShowPause());
-        _ = Token.RegisterUntargeted<Resumed>(m => HidePause());
-    }
-
-    private void OnSceneLoaded(ref SceneLoaded m) => RebuildUIForScene(m.buildIndex);
-}
-```
-
-Scene systems (use local bus)
-
-```csharp
-using DxMessaging.Core;
-using DxMessaging.Core.MessageBus;
-using DxMessaging.Core.Messages;
-
-public sealed class SceneDriver
-{
-    public void OnSceneStart(int buildIndex)
-    {
-        // Switch to a fresh bus per scene
-        SceneBus.NewScene();
-
-        // Broadcast globally (untargeted) so overlay updates
-        var info = new SceneLoaded(buildIndex);
-        info.Emit();
-
-        // For scene‑local flows, pass the local bus to tokens
-        // var token = MessageRegistrationToken.Create(handler, SceneBus.Current);
-    }
-}
-```
-
-Pausing
-
-```csharp
-using DxMessaging.Unity;
-using UnityEngine;
-
-public sealed class PauseController : MonoBehaviour
-{
-    public MessagingComponent[] systemsToPause; // listeners to disable during pause
-
-    public void Pause()
-    {
-        foreach (var mc in systemsToPause)
-        {
-            mc.ToggleMessageHandler(false); // disable listeners
-        }
-
-        var p = new Paused(); p.Emit(); // overlay still listening globally
-    }
-
-    public void Resume()
-    {
-        var r = new Resumed(); r.Emit();
-        foreach (var mc in systemsToPause)
-        {
-            mc.ToggleMessageHandler(true);
-        }
-    }
-}
-```
-
-Emitting while disabled
-
-```csharp
-// For specific emitters that must keep sending even if disabled:
-messaging.emitMessagesWhenDisabled = true;
-```
-
-Notes
-
-- Use global untargeted messages to communicate scene transitions to global overlays.
-- Keep scene‑specific flows isolated on a per‑scene bus (pass to tokens for registrations and emit to it).
-- Toggle listeners off to pause, and opt into emission while disabled for emitters that must remain active.

package/docs/examples/end-to-end-scene-transitions.md.meta

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

package/docs/examples/end-to-end.md

@@ -1,139 +0,0 @@
-# End‑to‑End Example: Combat + UI + Settings
-
-Short intro
-
-A small scenario tying together Untargeted, Targeted, and Broadcast messages with Unity integration, ordering, interceptors, and diagnostics.
-
-Scenario
-
-- Global: settings change (Untargeted)
-- Targeted: heal a specific player (Targeted)
-- Broadcast: enemies report damage taken (Broadcast)
-- UI listens globally to update overlays
-- Analytics listens across all sources/targets
-
-Messages
-
-```csharp
-using DxMessaging.Core.Attributes;
-
-[DxUntargetedMessage][DxAutoConstructor]
-public readonly partial struct VideoSettingsChanged { public readonly int width; public readonly int height; }
-
-[DxTargetedMessage][DxAutoConstructor]
-public readonly partial struct Heal { public readonly int amount; }
-
-[DxBroadcastMessage][DxAutoConstructor]
-public readonly partial struct TookDamage { public readonly int amount; }
-```
-
-Unity: Player component (targeted)
-
-```csharp
-using DxMessaging.Unity;
-using DxMessaging.Core.Messages;
-
-public sealed class Player : MessageAwareComponent
-{
-    private int _hp;
-
-    protected override void RegisterMessageHandlers()
-    {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterComponentTargeted<Heal>(this, OnHeal);
-    }
-
-    private void OnHeal(ref Heal m) => _hp += m.amount;
-}
-```
-
-Unity: Enemy component (broadcast)
-
-```csharp
-using DxMessaging.Unity;
-using DxMessaging.Core.Extensions;
-using DxMessaging.Core.Messages;
-
-[RequireComponent(typeof(MessagingComponent))]
-public sealed class Enemy : UnityEngine.MonoBehaviour
-{
-    public void ApplyDamage(int amount)
-    {
-        var took = new TookDamage(amount);
-        took.EmitGameObjectBroadcast(gameObject);
-    }
-}
-```
-
-UI overlay (global + all‑sources)
-
-```csharp
-using DxMessaging.Unity;
-using DxMessaging.Core;
-using DxMessaging.Core.Messages;
-using UnityEngine;
-
-public sealed class UIOverlay : MessageAwareComponent
-{
-    protected override void RegisterMessageHandlers()
-    {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterUntargeted<VideoSettingsChanged>(OnSettings);
-        _ = Token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
-    }
-
-    private void OnSettings(ref VideoSettingsChanged m) => RebuildUI(m.width, m.height);
-    private void OnAnyDamage(ref InstanceId src, ref TookDamage m) => ShowFloatingText(src, $"-{m.amount}");
-}
-```
-
-Interceptors and post‑processing (ordering)
-
-```csharp
-using DxMessaging.Core;            // MessageHandler
-using DxMessaging.Core.MessageBus; // IMessageBus
-
-var bus = MessageHandler.MessageBus;
-
-// Normalize negatives to zero and clamp max
-_ = bus.RegisterTargetedInterceptor<Heal>((ref InstanceId tgt, ref Heal m) =>
-{
-    var amount = UnityEngine.Mathf.Clamp(m.amount, 0, 999);
-    if (amount == 0) return false; // cancel zero heals
-    m = new Heal(amount);
-    return true;
-}, priority: 0);
-
-// Log after handlers
-_ = token.RegisterBroadcastWithoutSourcePostProcessor<TookDamage>((InstanceId src, TookDamage m) =>
-{
-    Analytics.Log("Damage", new { src, m.amount });
-});
-```
-
-Settings menu (untargeted)
-
-```csharp
-using DxMessaging.Core.Extensions;
-
-public sealed class SettingsMenu
-{
-    public void Apply(int width, int height)
-    {
-        var changed = new VideoSettingsChanged(width, height);
-        changed.Emit();
-    }
-}
-```
-
-Diagnostics (Editor)
-
-- On any GameObject with a MessagingComponent:
-  - Enable Global Diagnostics to record emissions.
-  - Inspect Global Buffer for recent messages (type + context). Matching listeners are highlighted.
-  - Inspect Local Buffer per listener and paginated Registrations with priorities and contexts.
-
-Notes
-
-- Use component vs gameObject context consistently for targeted/broadcast messages (see [Targeting & Context](../concepts/targeting-and-context.md)).
-- For tests/subsystems, use a local MessageBus and pass it to the token factory.

package/docs/examples/end-to-end.md.meta

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

package/docs/examples.meta

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

package/docs/getting-started/getting-started.md

@@ -1,203 +0,0 @@
-# Getting Started with DxMessaging
-
-[Back to Index](index.md) | [Visual Guide](visual-guide.md) | [Quick Start](quick-start.md) | [FAQ](../reference/faq.md)
-
----
-
-This guide covers the basics of DxMessaging. By the end, you'll understand what DxMessaging is, when it might be useful, and how to use it in your Unity projects.
-
-## Your Goal
-
-By the end of this guide, you will:
-
-- Understand the three message types and when to use each
-- Write your first message handler in Unity
-- Know when to use DxMessaging vs. traditional events
-- Avoid common beginner mistakes
-
-## Table of Contents
-
-- [What is DxMessaging?](#what-is-dxmessaging)
-- [Quick Start](#quick-start)
-- [Message Types](#message-types)
-- [Common Patterns](#common-patterns)
-- [Troubleshooting](#troubleshooting)
-- [Next Steps](#next-steps)
-- [Quick Reference](#quick-reference)
-
-## What is DxMessaging?
-
-**Picture this:** You're building a Unity game. Your player takes damage. Now you need to:
-
-- Update the health bar UI
-- Play a damage sound
-- Show a damage number popup
-- Track damage for analytics
-- Check if an achievement unlocked
-- Maybe trigger a tutorial tip
-
-**One approach:** The Player script needs references to all 6 systems. Or they all need references to the Player. This can create tight coupling.
-
-**With DxMessaging:** The Player emits one message: `TookDamage(25)`. Interested systems receive it through subscriptions. This approach decouples systems and handles cleanup automatically.
-
----
-
-**Technical summary:** DxMessaging is a type-safe messaging system that provides an alternative to C# events, UnityEvents, and global event buses.
-
-**Think of it as:** An alternative event system designed for larger projects.
-
-### What you get
-
-- **Decoupled systems** - no manual subscribe/unsubscribe, leak prevention built-in
-- **Predictable execution** - priority-based ordering, see exactly what runs when
-- **Actually debuggable** - Inspector shows message history with timestamps
-- **Designed to scale** - works for prototypes and larger codebases
-
-## Quick Start
-
-1. Define messages
-
-```csharp
-using DxMessaging.Core.Attributes;
-
-[DxTargetedMessage]
-[DxAutoConstructor]
-public readonly partial struct Heal
-{
-    public readonly int amount;
-}
-
-[DxBroadcastMessage]
-[DxAutoConstructor]
-public readonly partial struct TookDamage
-{
-    public readonly int amount;
-}
-```
-
-1. Listen in a component
-
-```csharp
-using DxMessaging.Core;
-using DxMessaging.Core.Extensions;
-using DxMessaging.Unity;
-
-public class GameUI : MessageAwareComponent
-{
-    // Assume this references a Player GameObject
-    public UnityEngine.GameObject playerGO;
-
-    protected override void RegisterMessageHandlers()
-    {
-        base.RegisterMessageHandlers();
-
-        _ = Token.RegisterGameObjectTargeted<Heal>(playerGO, OnPlayerHealed);
-        _ = Token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
-    }
-
-    private void OnPlayerHealed(ref Heal m) => UpdateHealthBar(m.amount);
-    private void OnAnyDamage(InstanceId source, TookDamage m) => ShowDamageEffect(source);
-}
-```
-
-1. Send a message
-
-```csharp
-var heal = new Heal(10);
-heal.EmitGameObjectTargeted(playerGameObject);
-```
-
-## Message Types
-
-### New to messaging? Use this decision tree
-
-```text
-Is it a global announcement? (pause, settings, scene load)
-  -> Use UNTARGETED
-
-Are you commanding a specific entity? (heal Player, open Chest #3)
-  -> Use TARGETED
-
-Is an entity announcing something happened? (Enemy died, Chest opened)
-  -> Use BROADCAST
-```
-
-#### Examples
-
-```csharp
-// Untargeted: "Everyone, the game paused!"
-[DxUntargetedMessage]
-public struct GamePaused { }
-
-// Targeted: "Player, heal yourself by 50!"
-[DxTargetedMessage]
-public struct Heal { public int amount; }
-
-// Broadcast: "I (Enemy #3) just died!"
-[DxBroadcastMessage]
-public struct EnemyDied { public string enemyName; }
-```
-
-**Need more detail?** See the [Visual Guide](visual-guide.md) for additional explanations, or [Message Types](../concepts/message-types.md) for technical details.
-
-## Common Patterns
-
-### Example use cases
-
-- **UI reacting to gameplay** - Health bar updates when player takes damage (without UI knowing about Player)
-- **Achievement systems** - Track ALL kills across ALL enemies with ONE listener
-- **Cross-system coordination** - Scene transitions coordinate audio, save system, and UI automatically
-- **Input handling** - Decouple input system from player controller
-- **Analytics** - Track all events without polluting gameplay code
-
-**Want code examples?** See [Patterns](../guides/patterns.md) for example patterns and [Listening Patterns](../concepts/listening-patterns.md) for additional techniques.
-
-## Troubleshooting
-
-### "My handler isn't being called"
-
-Checklist:
-
-1. Did you call `base.RegisterMessageHandlers()` first?
-1. Is your component enabled in the scene?
-1. Are you emitting to the right target? (Check GameObject vs Component)
-1. Check the Inspector - does the registration show up?
-
-### "My message is firing twice"
-
-- Check if you accidentally registered the same handler multiple times
-- Make sure you're calling `base.RegisterMessageHandlers()` only once
-
-### "I get a compile error on `[DxAutoConstructor]`"
-
-- Did you mark the struct as `partial`? (required for code generation)
-- Example: `public readonly partial struct MyMessage`
-
-### "Which message type should I use"
-
-- See the decision tree in [Message Types](#message-types) above
-- When in doubt, start with `Broadcast` - it's the most flexible
-
-**Still stuck?** See [Troubleshooting](../reference/troubleshooting.md) for the complete guide or [FAQ](../reference/faq.md) for common questions.
-
-## Next Steps
-
-- [Mental Model](../concepts/mental-model.md) - Understand the philosophy behind DxMessaging
-- [Visual Guide](visual-guide.md)
-- [Quick Reference](../reference/quick-reference.md)
-- [Diagnostics](../guides/diagnostics.md)
-- [Interceptors and Ordering](../concepts/interceptors-and-ordering.md)
-
-## Quick Reference
-
-```csharp
-// Listen
-_ = Token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
-_ = Token.RegisterGameObjectTargeted<Heal>(playerGO, OnPlayerHealed);
-
-// Emit (broadcasts always require a source)
-var damage = new TookDamage(25);
-damage.EmitGameObjectBroadcast(enemyGO);  // enemyGO is the source
-var heal = new Heal(10);
-heal.EmitGameObjectTargeted(playerGO);
-```

package/docs/getting-started/getting-started.md.meta

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