com.wallstop-studios.dxmessaging 2.1.6 → 2.1.8

package/docs/guides/migration-guide.md

@@ -1,513 +0,0 @@
-# Migration Guide: Adopting DxMessaging Incrementally
-
-This guide helps you introduce DxMessaging into an existing Unity project **gradually and pragmatically**. You don't need to rewrite everything at once.
-
-## Philosophy: Start Small, Prove Value
-
-### Don't do this
-
-- L Rip out all C# events and rewrite everything
-- L Force the whole team to learn it before trying it
-- L Commit to full adoption before seeing benefits
-
-#### Do this instead
-
--  Pick ONE system to migrate (low risk, high visibility)
--  Let old and new approaches coexist
--  Expand usage as team comfort grows
--  Evaluate after each migration step
-
-## Phase 0: Install and Experiment (1-2 hours)
-
-### Goal: Get comfortable without touching production code
-
-1. **Install DxMessaging** via Package Manager
-1. **Read the [Visual Guide](../getting-started/visual-guide.md)** (5 minutes)
-1. **Import the Mini Combat sample** from Package Manager
-1. **Create a throwaway test scene** and try:
-
-   ```csharp
-   [DxUntargetedMessage]
-   [DxAutoConstructor]
-   public readonly partial struct TestMessage { public readonly int value; }
-
-   public class TestListener : MessageAwareComponent {
-       protected override void RegisterMessageHandlers() {
-           base.RegisterMessageHandlers();
-           _ = Token.RegisterUntargeted<TestMessage>(OnTest);
-       }
-       void OnTest(ref TestMessage m) => Debug.Log($"Got {m.value}");
-   }
-
-   // In another script:
-   var msg = new TestMessage(42);
-   msg.Emit();
-   ```
-
-**Success criteria:** You understand the basic flow and have no build errors.
-
-## Phase 1: Add to a New Feature (1 week)
-
-### Goal: Prove value without refactoring existing code
-
-#### Best candidates for first adoption
-
--  **New UI system** - Add a new settings menu that reacts to game state
--  **Achievement/analytics system** - Listen to existing events without coupling
--  **New game mode** - Implement it with DxMessaging from scratch
-
-### Example: Adding an Achievement System
-
-```csharp
-// 1. Define messages for interesting events (don't touch existing code yet)
-[DxBroadcastMessage]
-[DxAutoConstructor]
-public readonly partial struct EnemyKilled {
-    public readonly string enemyType;
-    public readonly int playerLevel;
-}
-
-// 2. Make your NEW achievement system listen
-public class AchievementSystem : MessageAwareComponent {
-    protected override void RegisterMessageHandlers() {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterBroadcastWithoutSource<EnemyKilled>(OnEnemyKilled);
-    }
-
-    void OnEnemyKilled(InstanceId source, EnemyKilled msg) {
-        // Track kills, unlock achievements
-        if (msg.enemyType == "Boss") UnlockAchievement("BossSlayer");
-    }
-}
-
-// 3. Bridge from existing code (minimal change)
-public class Enemy : MonoBehaviour {
-    public event Action OnDied; // OLD - keep for now
-
-    void Die() {
-        OnDied?.Invoke(); // OLD code still works
-
-        // NEW: Emit DxMessage too
-        var msg = new EnemyKilled(enemyType, PlayerStats.Level);
-        msg.EmitGameObjectBroadcast(gameObject);
-    }
-}
-```
-
-#### Why this works
-
--  Old code still works (zero risk)
--  New system is decoupled
--  Team sees immediate value (achievements without wiring)
--  Easy to roll back if needed
-
-## Phase 2: Migrate High-Pain Areas (2-4 weeks)
-
-### Goal: Replace the systems causing the most problems
-
-#### High-value migration targets
-
-1. **UI that references too many systems** - Replace with message listeners
-1. **Global static event buses** - Convert to DxMessaging
-1. **Memory-leak prone event chains** - Eliminate manual unsubscribe
-
-### Strategy: Parallel Paths During Transition
-
-#### Step 1: Add DxMessages alongside existing events
-
-```csharp
-// Old event (keep for now)
-public event Action<int> OnHealthChanged;
-
-// New message
-[DxBroadcastMessage]
-[DxAutoConstructor]
-public readonly partial struct HealthChanged { public readonly int newHealth; }
-
-void TakeDamage(int amount) {
-    health -= amount;
-
-    // Fire both during migration
-    OnHealthChanged?.Invoke(health);  // OLD
-    var msg = new HealthChanged(health);
-    msg.EmitGameObjectBroadcast(gameObject);  // NEW
-}
-```
-
-#### Step 2: Migrate listeners one-by-one
-
-```csharp
-// OLD listener (comment out when ready)
-// void Awake() { player.OnHealthChanged += UpdateBar; }
-// void OnDestroy() { player.OnHealthChanged -= UpdateBar; }
-
-// NEW listener
-public class HealthBar : MessageAwareComponent {
-    [SerializeField] private GameObject playerObject;
-
-    protected override void RegisterMessageHandlers() {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterGameObjectBroadcast<HealthChanged>(playerObject, OnHealthChanged);
-    }
-
-    void OnHealthChanged(ref HealthChanged msg) => UpdateBar(msg.newHealth);
-}
-```
-
-#### Step 3: Remove old events once all listeners migrated
-
-```csharp
-// Delete after confirming no one uses it:
-// public event Action<int> OnHealthChanged; L
-
-void TakeDamage(int amount) {
-    health -= amount;
-    var msg = new HealthChanged(health);
-    msg.EmitGameObjectBroadcast(gameObject);  // Only this now
-}
-```
-
-### Migration Checklist Template
-
-Use this for each system you migrate:
-
-```text
-System: _________________
-
-[ ] Identified all listeners to migrate
-[ ] Defined DxMessages for all events
-[ ] Added DxMessage emissions (parallel with old events)
-[ ] Migrated listeners one-by-one
-[ ] Tested thoroughly
-[ ] Removed old event declarations
-[ ] Updated documentation/comments
-```
-
-## Phase 3: Adopt for All New Code (Ongoing)
-
-### Goal: Make DxMessaging the default for new features
-
-#### Team guidelines
-
--  All new cross-system communication uses DxMessaging
--  Old code migrates opportunistically (when touched)
--  Code reviews check for messaging best practices
-
-##### Example team policy
-
-```text
-When to use DxMessaging (for new code):
-- Any UI listening to game state � DxMessaging
-- Any analytics/logging � DxMessaging
-- Any cross-scene communication � DxMessaging
-- Any event with 2+ listeners � DxMessaging
-
-When to use direct references/events:
-- Simple UI button � method call (use UnityEvents)
-- Single listener, same GameObject � direct reference
-- Private implementation details � keep internal
-```
-
-## Coexistence Patterns
-
-### Pattern 1: Event-to-Message Bridge
-
-```csharp
-public class LegacyBridge : MonoBehaviour {
-    [SerializeField] private LegacySystem legacySystem;
-
-    void Awake() {
-        // Old system fires event, we convert to message
-        legacySystem.OnSomethingHappened += (args) => {
-            var msg = new SomethingHappened(args);
-            msg.Emit();
-        };
-    }
-}
-```
-
-### Pattern 2: Message-to-Event Bridge
-
-```csharp
-public class ModernBridge : MessageAwareComponent {
-    public event Action<int> LegacyEvent; // For old code that needs events
-
-    protected override void RegisterMessageHandlers() {
-        base.RegisterMessageHandlers();
-        _ = Token.RegisterUntargeted<NewMessage>(OnMessage);
-    }
-
-    void OnMessage(ref NewMessage msg) {
-        LegacyEvent?.Invoke(msg.value); // Fire old event
-    }
-}
-```
-
-### Pattern 3: Gradual GameObject Migration
-
-```csharp
-// Phase 1: Keep old inspector references, emit messages
-public class Player : MonoBehaviour {
-    [SerializeField] private HealthBar healthBar; // OLD - will remove later
-
-    void TakeDamage(int amount) {
-        health -= amount;
-        healthBar.UpdateHealth(health); // OLD direct call
-        var msg = new HealthChanged(health);
-        msg.EmitGameObjectBroadcast(gameObject); // NEW message
-    }
-}
-
-// Phase 2: Remove direct references
-public class Player : MonoBehaviour {
-    // [SerializeField] private HealthBar healthBar; � DELETED
-
-    void TakeDamage(int amount) {
-        health -= amount;
-        var msg = new HealthChanged(health);
-        msg.EmitGameObjectBroadcast(gameObject); // Only this
-    }
-}
-```
-
-## What to Migrate First vs. Last
-
-### Migrate FIRST (High Value, Low Risk)
-
-1. **New systems** - No refactor needed, immediate win
-1. **Analytics/logging** - Decoupled observers, zero disruption
-1. **UI that needs to listen to many systems** - Eliminate reference spaghetti
-1. **Global event buses** - Direct replacement, clear improvement
-
-### Migrate LATER (Lower Priority)
-
-1. **Stable, working code** - If it ain't broke, don't rush
-1. **Performance-critical paths** - Validate overhead first
-1. **Code that rarely changes** - Low ROI for migration
-1. **Third-party integrations** - Keep adapters simple
-
-### DON'T Migrate (Keep As-Is)
-
-1. **Simple button onClick � method** - UnityEvents are fine
-1. **Private implementation details** - Internal events are okay
-1. **Single-listener, same-GameObject** - Direct references are clearer
-1. **Legacy systems about to be deleted** - Why bother?
-
-## Common Migration Pitfalls
-
-### L Pitfall 1: Boiling the Ocean
-
-**Problem:** "Let's rewrite the entire codebase!"
-
-**Solution:** Migrate incrementally. Set a rule: "One system per sprint" or "New features only."
-
-### L Pitfall 2: No Rollback Plan
-
-**Problem:** Full commit before proving value.
-
-**Solution:** Keep old code commented for 1-2 sprints:
-
-```csharp
-// OLD (keep until 2024-02-01)
-// player.OnHealthChanged += UpdateBar;
-
-// NEW
-_ = Token.RegisterBroadcast<HealthChanged>(...);
-```
-
-### L Pitfall 3: Mixing Message Types Incorrectly
-
-**Problem:** Using Untargeted for everything because it's "simpler."
-
-**Solution:** Follow message type guidelines:
-
-- Global state? Untargeted
-- Command to one? Targeted
-- Event from one? Broadcast
-
-### L Pitfall 4: Over-Messaging
-
-**Problem:** Converting every method call to a message.
-
-**Solution:** Keep simple things simple:
-
-```csharp
-// L OVERKILL - Just call the method!
-var msg = new CloseDoorMessage(doorId);
-msg.Emit();
-
-// BETTER - Direct reference is fine
-door.Close();
-```
-
-### L Pitfall 5: Not Training the Team
-
-**Problem:** Team doesn't understand when/how to use it.
-
-#### Solution
-
-- Schedule a 30-minute walkthrough
-- Share the [Visual Guide](../getting-started/visual-guide.md)
-- Pair program on first migrations
-- Document team conventions in your wiki
-
-## Success Metrics
-
-Track these to validate migration is worthwhile:
-
-### Quantitative
-
-- Lines of event subscribe/unsubscribe code removed
-- Number of SerializedField references eliminated
-- Memory leaks fixed (profiler)
-
-#### Qualitative
-
-- Time to add new observers (before/after)
-- Ease of debugging message flow
-- Team satisfaction (survey)
-
-##### Example
-
-> "Before: Adding achievement tracking required touching 12 files.
-> After: Added achievement system with zero changes to existing code."
-
-## Timeline Examples
-
-### Small Project (10k lines)
-
-- **Week 1:** Experiment + add to one new feature
-- **Week 2-3:** Migrate high-pain UI systems
-- **Week 4+:** New code uses DxMessaging
-
-### Medium Project (50k lines)
-
-- **Month 1:** Pilot with 2-3 systems
-- **Month 2-4:** Gradual migration of problem areas
-- **Month 5+:** Standard practice for new code
-
-### Large Project (100k+ lines)
-
-- **Quarter 1:** Pilot + evangelize
-- **Quarter 2-3:** Migrate critical systems
-- **Quarter 4+:** Opportunistic refactors
-
-## Getting Team Buy-In
-
-### For Managers
-
-- "Reduces memory leaks and hard-to-debug issues"
-- "Faster feature development (decoupled systems)"
-- "Easier onboarding (clear message contracts)"
-
-### For Developers
-
-- "No more manual unsubscribe hell"
-- "Built-in debugging (Inspector shows message history)"
-- "Add features without touching existing code"
-
-### For QA
-
-- "Easier to reproduce bugs (message logs)"
-- "Fewer null reference errors"
-- "Clear system boundaries"
-
-## FAQ: Migration Edition
-
-### "Do we need to migrate everything?"
-
-**No!** DxMessaging coexists happily with C# events, UnityEvents, and direct references. Migrate what benefits, leave what works.
-
-### "What if we decide it's not for us?"
-
-Keep old events during migration. If you hate it, delete the DxMessaging parts and uncomment the old code.
-
-### "How do we handle prefabs with Inspector references?"
-
-Phase them out gradually:
-
-1. Keep references during transition
-1. Emit messages alongside old calls
-1. Migrate listeners
-1. Remove references in next refactor pass
-
-### Adopt the DI Registration Builder
-
-Once the bus/provider abstractions are in place, wire listeners through the registration builder instead of hand-rolling handler lifecycles. Benefits:
-
-- Container-managed lifetimes (`IDisposable`, `IInitializable`, `IStartable`, etc.) automatically enable/disable registrations.
-- Centralises diagnostics toggles and message bus selection.
-- Keeps MonoBehaviours and pure C# services on the same path.
-
-```csharp
-public sealed class InventoryService : IStartable, IDisposable
-{
-    private readonly MessageRegistrationLease lease;
-
-    public InventoryService(IMessageRegistrationBuilder registrationBuilder)
-    {
-        lease = registrationBuilder.Build(new MessageRegistrationBuildOptions
-        {
-            Configure = token =>
-            {
-                _ = token.RegisterUntargeted<InventoryChanged>(OnInventoryChanged);
-            }
-        });
-    }
-
-    public void Start()
-    {
-        lease.Activate();
-    }
-
-    public void Dispose()
-    {
-        lease.Dispose();
-    }
-
-    private static void OnInventoryChanged(ref InventoryChanged message)
-    {
-        // respond to updates
-    }
-}
-```
-
-- **Unity scene code:** Call `MessagingComponent.CreateRegistrationBuilder()` during dependency injection and share the lease across helper services or pooled objects.
-- **Container shims:** Define `ZENJECT_PRESENT`, `VCONTAINER_PRESENT`, or `REFLEX_PRESENT` to enable the built-in installers/extensions that register the builder automatically when those frameworks are present.
-- **Tests:** Prefer the builder to create isolated tokens tied to the test fixture lifecycle.
-
-### "Should we migrate tests?"
-
-Yes! Tests benefit from isolated message buses:
-
-```csharp
-var testBus = new MessageBus();
-var token = MessageRegistrationToken.Create(handler, testBus);
-// Test in isolation
-```
-
-### "What about mobile performance?"
-
-Enable diagnostics only in Editor:
-
-```csharp
-#if UNITY_EDITOR
-IMessageBus.GlobalDiagnosticsMode = true;
-#endif
-```
-
-Profile early, measure impact.
-
-## Next Steps
-
-1. **Try Phase 0** - Install and experiment (today)
-1. **Pick one system** - Choose a low-risk, high-value target (this week)
-1. **Timebox it** - Give yourself 2 weeks to evaluate
-1. **Measure results** - Did it make life better?
-1. **Expand or abort** - Based on evidence, not hope
-
-**Remember:** Migration is a journey, not a destination. Go at your own pace.
-
----
-
-**Questions?** See [FAQ](../reference/faq.md) | **Need patterns?** See [Common Patterns](patterns.md)

package/docs/guides/migration-guide.md.meta

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