com.wallstop-studios.dxmessaging 2.1.7 → 2.1.9

package/docs/reference/helpers.md.meta

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

package/docs/reference/quick-reference.md

@@ -1,269 +0,0 @@
-# Quick Reference (Cheat Sheet)
-
-Use this as a rapid guide to define/emit/listen and manage lifecycles.
-
-Do’s
-
-- Use attributes + `DxAutoConstructor` for clarity (or interfaces on structs for perf).
-- Bind struct messages to a variable before emitting.
-- Use GameObject/Component emit helpers (no manual `InstanceId`).
-- Register once; enable/disable with component state.
-- Prefer named handler methods over inline lambdas for reuse and clarity.
-- When using DI, inject `IMessageRegistrationBuilder` instead of newing `MessageHandler`s manually.
-
-## Don'ts
-
-- Don’t emit from temporaries; use a local variable (e.g., `var msg = new M(...); msg.Emit();`).
-- Don’t mix Component vs GameObject targeting if you expect matches (see targeting notes below).
-- Don’t register in Update; use `Awake` for staging + `OnEnable`/`OnDisable` for lifecycle.
-- Don’t forget base calls when inheriting from `MessageAwareComponent` — call `base.RegisterMessageHandlers()` and `base.OnEnable()`/`base.OnDisable()`.
-- Don’t hide Unity methods with `new` (e.g., `new void OnEnable()`); prefer `override` and call `base.*`.
-
-## Define messages
-
-```csharp
-using DxMessaging.Core.Attributes;
-
-[DxUntargetedMessage]
-[DxAutoConstructor]
-public readonly partial struct SceneLoaded { public readonly int buildIndex; }
-
-[DxTargetedMessage]
-[DxAutoConstructor]
-public readonly partial struct Heal { public readonly int amount; }
-
-[DxBroadcastMessage]
-[DxAutoConstructor]
-public readonly partial struct TookDamage { public readonly int amount; }
-```
-
-## Emit (Unity helpers)
-
-```csharp
-using DxMessaging.Core.Extensions;
-
-var scene = new SceneLoaded(1); scene.Emit();
-var heal  = new Heal(10);       heal.EmitGameObjectTargeted(gameObject);
-var hit   = new TookDamage(5);  hit.EmitComponentBroadcast(this);
-
-// String shorthands
-"Saved".Emit();                   // GlobalStringMessage
-"Hello".EmitAt(gameObject);       // StringMessage to GO (or .Emit(instanceId))
-"Hit".EmitFrom(gameObject);       // SourcedStringMessage from GO
-```
-
-## Register (Unity, via token)
-
-```csharp
-using DxMessaging.Core; // InstanceId
-// Untargeted
-_ = token.RegisterUntargeted<SceneLoaded>(OnSceneLoaded);
-void OnSceneLoaded(ref SceneLoaded m) { /* ... */ }
-
-// Targeted: to this component or gameObject
-_ = token.RegisterComponentTargeted<Heal>(this, OnHeal);
-_ = token.RegisterGameObjectTargeted<Heal>(gameObject, OnHeal);
-void OnHeal(ref Heal m) { /* ... */ }
-
-// Broadcast: from this component or gameObject
-_ = token.RegisterComponentBroadcast<TookDamage>(this, OnDamageFromMe);
-_ = token.RegisterGameObjectBroadcast<TookDamage>(gameObject, OnDamageFromMe);
-void OnDamageFromMe(ref TookDamage m) { /* ... */ }
-
-// Listen to all targets/sources
-_ = token.RegisterTargetedWithoutTargeting<Heal>(OnAnyHeal);
-void OnAnyHeal(ref InstanceId target, ref Heal m) { /* ... */ }
-
-_ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
-void OnAnyDamage(ref InstanceId src, ref TookDamage m) { /* ... */ }
-```
-
-## Register (DI / services)
-
-```csharp
-using DxMessaging.Core.MessageBus;
-
-public sealed class DamageSystem : IStartable, IDisposable
-{
-    private readonly MessageRegistrationLease lease;
-
-    public DamageSystem(IMessageRegistrationBuilder registrationBuilder)
-    {
-        lease = registrationBuilder.Build(new MessageRegistrationBuildOptions
-        {
-            Configure = token =>
-            {
-                _ = token.RegisterUntargeted<TookDamage>(OnDamage);
-            }
-        });
-    }
-
-    public void Start() => lease.Activate();
-
-    public void Dispose() => lease.Dispose();
-
-    private static void OnDamage(ref TookDamage message) { /* respond */ }
-}
-```
-
-Tip: Define `ZENJECT_PRESENT`, `VCONTAINER_PRESENT`, or `REFLEX_PRESENT` to enable the optional shims under [Runtime/Unity/Integrations](https://github.com/wallstop/DxMessaging/tree/master/Runtime/Unity/Integrations) that bind the builder automatically for those containers.
-
-## Interceptors and post‑processors
-
-```csharp
-using DxMessaging.Core;            // MessageHandler
-using DxMessaging.Core.MessageBus; // IMessageBus
-
-var bus = MessageHandler.MessageBus;
-_ = bus.RegisterBroadcastInterceptor<TookDamage>((ref InstanceId src, ref TookDamage m) =>
-{
-    if (m.amount <= 0) return false; // cancel
-    m = new TookDamage(Math.Min(m.amount, 999));
-    return true;
-});
-
-_ = token.RegisterUntargetedPostProcessor<SceneLoaded>((ref SceneLoaded m) => LogScene(m.buildIndex));
-```
-
-## Lifecycle
-
-```csharp
-void Awake()     { /* stage registrations */ }
-void OnEnable()  { token.Enable(); }
-void OnDisable() { token.Disable(); }
-```
-
-## Inheritance tip (MessageAwareComponent)
-
-- If you override `RegisterMessageHandlers`, start with `base.RegisterMessageHandlers()`.
-- If you override Unity lifecycle methods, call `base.OnEnable()` / `base.OnDisable()` (and `base.Awake()`/`base.OnDestroy()` if overridden).
-
-## Targeting notes (Component vs GameObject)
-
-- A targeted message matches if the emitted `InstanceId` equals the registered `InstanceId`.
-- Registering for a Component target listens for messages targeted at that specific Component.
-- Registering for a GameObject target listens for messages targeted at that GameObject.
-- Emitting to a GameObject will not reach Component‑targeted listeners (and vice‑versa). Use the matching helper.
-- Shorthands exist for strings too; be explicit about using a GameObject vs Component with `EmitAt`/`EmitFrom`.
-
-## See also
-
-- [Emit Shorthands](../advanced/emit-shorthands.md)
-- [Advanced](../guides/advanced.md)
-- [Targeting & Context](../concepts/targeting-and-context.md)
-- [Interceptors & Ordering](../concepts/interceptors-and-ordering.md)
-
-## Execution Order
-
-### Untargeted
-
-```text
-Interceptors → Global Accept-All → Handlers<T> → Post-Processors<T>
-```
-
-### Targeted
-
-```text
-Interceptors → Global Accept-All → Handlers<T> @ target
-    → Handlers<T> (All Targets) → Post-Processors<T> @ target
-    → Post-Processors<T> (All Targets)
-```
-
-### Broadcast
-
-```text
-Interceptors → Global Accept-All → Handlers<T> @ source
-    → Handlers<T> (All Sources) → Post-Processors<T> @ source
-    → Post-Processors<T> (All Sources)
-```
-
-> 📝 **Note: Priority Rules**
->
-> - Lower priority values run earlier
-> - Same priority preserves registration order
-> - Within a priority, fast (by-ref) handlers run before action handlers
-
-## API Quick Reference
-
-### Token: Untargeted
-
-```csharp
-// Register handler
-token.RegisterUntargeted<T>(Action<T> handler, int priority = 0)
-token.RegisterUntargeted<T>(FastHandler<T> handler, int priority = 0)
-
-// Post-processor
-token.RegisterUntargetedPostProcessor<T>(FastHandler<T> handler, int priority = 0)
-```
-
-### Token: Targeted (Specific)
-
-```csharp
-// Register for specific target
-token.RegisterGameObjectTargeted<T>(GameObject go, handler, int priority = 0)
-token.RegisterComponentTargeted<T>(Component c, handler, int priority = 0)
-token.RegisterTargeted<T>(InstanceId id, handler, int priority = 0)
-
-// Post-processor
-token.RegisterTargetedPostProcessor<T>(InstanceId id, FastHandler<T> handler, int priority = 0)
-```
-
-### Token: Targeted (All Targets)
-
-```csharp
-// Listen to messages for any target
-token.RegisterTargetedWithoutTargeting<T>(FastHandlerWithContext<T> handler, int priority = 0)
-
-// Post-processor
-token.RegisterTargetedWithoutTargetingPostProcessor<T>(FastHandlerWithContext<T> handler, int priority = 0)
-```
-
-### Token: Broadcast (Specific)
-
-```csharp
-// Register for specific source
-token.RegisterGameObjectBroadcast<T>(GameObject go, handler, int priority = 0)
-token.RegisterComponentBroadcast<T>(Component c, handler, int priority = 0)
-token.RegisterBroadcast<T>(InstanceId id, handler, int priority = 0)
-
-// Post-processor
-token.RegisterBroadcastPostProcessor<T>(InstanceId id, FastHandler<T> handler, int priority = 0)
-```
-
-### Token: Broadcast (All Sources)
-
-```csharp
-// Listen to broadcasts from any source
-token.RegisterBroadcastWithoutSource<T>(FastHandlerWithContext<T> handler, int priority = 0)
-
-// Post-processor
-token.RegisterBroadcastWithoutSourcePostProcessor<T>(FastHandlerWithContext<T> handler, int priority = 0)
-```
-
-### Token: Global Observer
-
-```csharp
-// Action-based
-token.RegisterGlobalAcceptAll(
-    Action<IUntargetedMessage> untargeted,
-    Action<InstanceId, ITargetedMessage> targeted,
-    Action<InstanceId, IBroadcastMessage> broadcast)
-
-// Fast handler-based
-token.RegisterGlobalAcceptAll(
-    FastHandler<IUntargetedMessage> untargeted,
-    FastHandlerWithContext<ITargetedMessage> targeted,
-    FastHandlerWithContext<IBroadcastMessage> broadcast)
-```
-
-### Bus: Interceptors
-
-```csharp
-// Type-specific interceptors (return false to cancel)
-bus.RegisterUntargetedInterceptor<T>(UntargetedInterceptor<T> interceptor, int priority = 0)
-bus.RegisterTargetedInterceptor<T>(TargetedInterceptor<T> interceptor, int priority = 0)
-bus.RegisterBroadcastInterceptor<T>(BroadcastInterceptor<T> interceptor, int priority = 0)
-
-// Bus-level global observer
-bus.RegisterGlobalAcceptAll(MessageHandler handler)
-```

package/docs/reference/quick-reference.md.meta

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

package/docs/reference/reference.md

@@ -1,365 +0,0 @@
-# API Reference (Practical)
-
-This reference provides a practical overview of the DxMessaging API for Unity developers.
-
----
-
-## Message Registration (Unity-Friendly)
-
-The `MessageRegistrationToken` is your primary interface for subscribing to messages in a managed, lifecycle-aware manner.
-
-### Token Lifecycle Methods
-
-```csharp
-// Enable/disable all registrations on this token
-token.Enable();
-token.Disable();
-
-// Remove all registrations
-token.UnregisterAll();
-
-// Remove a specific registration
-token.RemoveRegistration(handle);
-```
-
-### Untargeted Message Registration
-
-Register handlers for messages that have no specific target—system-wide events.
-
-```csharp
-// Standard handler (allocation-friendly for simple cases)
-MessageRegistrationHandle RegisterUntargeted<T>(
-    Action<T> handler,
-    int priority = 0
-)
-
-// Fast handler (zero-allocation, receives message by ref)
-MessageRegistrationHandle RegisterUntargeted<T>(
-    MessageHandler.FastHandler<T> handler,
-    int priority = 0
-)
-
-// Post-processor (runs after all handlers)
-MessageRegistrationHandle RegisterUntargetedPostProcessor<T>(
-    MessageHandler.FastHandler<T> handler,
-    int priority = 0
-)
-```
-
-### Targeted Message Registration
-
-Register handlers for messages directed at specific GameObjects, Components, or InstanceIds.
-
-#### Specific Target
-
-```csharp
-// GameObject target
-MessageRegistrationHandle RegisterGameObjectTargeted<T>(
-    GameObject target,
-    Action<T> handler,
-    int priority = 0
-)
-
-// Component target
-MessageRegistrationHandle RegisterComponentTargeted<T>(
-    Component target,
-    Action<T> handler,
-    int priority = 0
-)
-
-// InstanceId target (low-level)
-MessageRegistrationHandle RegisterTargeted<T>(
-    InstanceId target,
-    Action<T> handler,
-    int priority = 0
-)
-```
-
-#### All Targets
-
-```csharp
-// Receive all targeted messages regardless of target
-MessageRegistrationHandle RegisterTargetedWithoutTargeting<T>(
-    FastHandlerWithContext<T> handler,
-    int priority = 0
-)
-```
-
-#### Post-Processors
-
-```csharp
-// Post-process for specific target
-MessageRegistrationHandle RegisterTargetedPostProcessor<T>(
-    InstanceId target,
-    FastHandler<T> handler,
-    int priority = 0
-)
-
-// Post-process all targeted messages
-MessageRegistrationHandle RegisterTargetedWithoutTargetingPostProcessor<T>(
-    FastHandlerWithContext<T> handler,
-    int priority = 0
-)
-```
-
-### Broadcast Message Registration
-
-Register handlers for messages broadcast from specific sources.
-
-#### Specific Source
-
-```csharp
-// From specific GameObject
-MessageRegistrationHandle RegisterGameObjectBroadcast<T>(
-    GameObject source,
-    Action<T> handler,
-    int priority = 0
-)
-
-// From specific Component
-MessageRegistrationHandle RegisterComponentBroadcast<T>(
-    Component source,
-    Action<T> handler,
-    int priority = 0
-)
-
-// From specific InstanceId
-MessageRegistrationHandle RegisterBroadcast<T>(
-    InstanceId source,
-    Action<T> handler,
-    int priority = 0
-)
-```
-
-#### All Sources
-
-```csharp
-// Receive broadcasts from any source
-MessageRegistrationHandle RegisterBroadcastWithoutSource<T>(
-    FastHandlerWithContext<T> handler,
-    int priority = 0
-)
-```
-
-#### Post-Processors
-
-```csharp
-// Post-process for specific source
-MessageRegistrationHandle RegisterBroadcastPostProcessor<T>(
-    InstanceId source,
-    FastHandler<T> handler,
-    int priority = 0
-)
-
-// Post-process all broadcasts
-MessageRegistrationHandle RegisterBroadcastWithoutSourcePostProcessor<T>(
-    FastHandlerWithContext<T> handler,
-    int priority = 0
-)
-```
-
----
-
-## Emit Helpers
-
-The `DxMessaging.Core.Extensions.MessageExtensions` class provides convenient extension methods for emitting messages.
-
-### Untargeted Emission
-
-```csharp
-// Emit any message type as untargeted
-message.Emit();
-message.EmitUntargeted();
-```
-
-### Targeted Emission
-
-```csharp
-// Emit to specific target (by InstanceId)
-message.EmitTargeted(InstanceId target);
-
-// Emit to GameObject target
-message.EmitGameObjectTargeted(GameObject target);
-
-// Emit to Component target
-message.EmitComponentTargeted(Component target);
-```
-
-### Broadcast Emission
-
-```csharp
-// Broadcast from specific source (by InstanceId)
-message.EmitBroadcast(InstanceId source);
-
-// Broadcast from GameObject source
-message.EmitGameObjectBroadcast(GameObject source);
-
-// Broadcast from Component source
-message.EmitComponentBroadcast(Component source);
-```
-
-### String Message Conveniences
-
-```csharp
-// Quick string message emission
-"PlayerDied".Emit();
-"DamageDealt".Emit(targetInstanceId);
-```
-
----
-
-## Interceptors (Bus-Level)
-
-Interceptors allow you to intercept and potentially modify or cancel messages at the bus level before they reach handlers.
-
-```csharp
-// Intercept untargeted messages
-Action RegisterUntargetedInterceptor<T>(
-    UntargetedInterceptor<T> interceptor,
-    int priority = 0
-)
-
-// Intercept targeted messages
-Action RegisterTargetedInterceptor<T>(
-    TargetedInterceptor<T> interceptor,
-    int priority = 0
-)
-
-// Intercept broadcast messages
-Action RegisterBroadcastInterceptor<T>(
-    BroadcastInterceptor<T> interceptor,
-    int priority = 0
-)
-
-// Global observer for all messages
-Action RegisterGlobalAcceptAll(MessageHandler handler)
-```
-
----
-
-## Diagnostics
-
-DxMessaging provides diagnostic tools for debugging and monitoring message flow.
-
-### Global Settings
-
-```csharp
-// Enable/disable diagnostics globally
-IMessageBus.GlobalDiagnosticsMode = true;
-
-// Configure global message buffer size
-IMessageBus.GlobalMessageBufferSize = 1024;
-```
-
-### Per-Instance Settings
-
-```csharp
-// Per-bus diagnostics
-messageBus.DiagnosticsMode = true;
-
-// Per-token diagnostics
-token.DiagnosticMode = true;
-```
-
-### Registration Logging
-
-```csharp
-// Enable registration logging
-bus.Log.Enabled = true;
-
-// Get log output
-string logOutput = bus.Log.ToString();
-```
-
----
-
-## Key Types
-
-| Type                                     | Description                                                           |
-| ---------------------------------------- | --------------------------------------------------------------------- |
-| `DxMessaging.Core.InstanceId`            | Value type identity for GameObjects, Components, or custom owners     |
-| `DxMessaging.Core.MessageHandler`        | Per-owner callback runner that manages message dispatch               |
-| `DxMessaging.Core.MessageBus.MessageBus` | Instanced bus; global instance at `MessageHandler.MessageBus`         |
-| `DxMessaging.Core.Messages.*`            | Untargeted/Targeted/Broadcast interfaces and built-in string messages |
-
-> 💡 **Tip: String Messages**
->
-> For lightweight string-based messaging, see [String Messages](../advanced/string-messages.md).
-
----
-
-## Unity Bridge Types
-
-### MessagingComponent
-
-Base component for objects that emit messages.
-
-```csharp
-public class MessagingComponent : MonoBehaviour
-{
-    // When true, messages can be emitted even when component is disabled
-    public bool emitMessagesWhenDisabled;
-
-    // Create a registration token for a listener on this GameObject
-    public MessageRegistrationToken Create(MonoBehaviour listener);
-
-    // Toggle the message handler on/off
-    public void ToggleMessageHandler(bool enabled);
-}
-```
-
-### MessageAwareComponent
-
-Base component for objects that both emit and receive messages.
-
-```csharp
-public abstract class MessageAwareComponent : MessagingComponent
-{
-    // The registration token for this component
-    public MessageRegistrationToken Token { get; }
-
-    // When true, registrations are enabled/disabled with OnEnable/OnDisable
-    protected virtual bool MessageRegistrationTiedToEnableStatus { get; }
-
-    // When true, registers for string messages automatically
-    protected virtual bool RegisterForStringMessages { get; }
-
-    // Override to register your message handlers
-    protected virtual void RegisterMessageHandlers() { }
-}
-```
-
-> ⚠️ **Warning: Inheritance Tip**
->
-> If you override any lifecycle hooks (`Awake`, `OnDestroy`, `OnEnable`, `OnDisable`) or `RegisterMessageHandlers`, always call the base method:
->
-> ```csharp
-> protected override void RegisterMessageHandlers()
-> {
->     base.RegisterMessageHandlers();
->     // Your registrations here
-> }
->
-> protected override void OnEnable()
-> {
->     base.OnEnable();
->     // Your logic here
-> }
-> ```
->
-> Skipping base calls may prevent token setup and default string-message registrations.
-
----
-
-## Source Files
-
-For deeper exploration, browse the source code:
-
-| Component             | Source                                                                                                                      |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| Message Bus Interface | [IMessageBus.cs](https://github.com/wallstop/DxMessaging/blob/master/Runtime/Core/MessageBus/IMessageBus.cs)                |
-| Message Bus           | [MessageBus.cs](https://github.com/wallstop/DxMessaging/blob/master/Runtime/Core/MessageBus/MessageBus.cs)                  |
-| Message Handler       | [MessageHandler.cs](https://github.com/wallstop/DxMessaging/blob/master/Runtime/Core/MessageHandler.cs)                     |
-| Registration Token    | [MessageRegistrationToken.cs](https://github.com/wallstop/DxMessaging/blob/master/Runtime/Core/MessageRegistrationToken.cs) |
-| Emit Helpers          | [MessageExtensions.cs](https://github.com/wallstop/DxMessaging/blob/master/Runtime/Core/Extensions/MessageExtensions.cs)    |
-| Attributes            | [Attributes/](https://github.com/wallstop/DxMessaging/tree/master/Runtime/Core/Attributes)                                  |

package/docs/reference/reference.md.meta

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