com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/.llm/skills/performance/serializable-dictionary.md

@@ -0,0 +1,281 @@
+---
+title: "Serializable Dictionary for Unity Inspector"
+id: "serializable-dictionary"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/DataStructure/Adapters/SerializableDictionary.cs"
+      lines: "1416-1590"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "unity"
+  - "serialization"
+  - "dictionary"
+  - "inspector"
+  - "data-structures"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of Unity serialization and ISerializationCallbackReceiver"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Serialization has overhead; runtime dictionary access is O(1)"
+  maintainability:
+    rating: "high"
+    details: "Enables designer-friendly dictionary configuration in Inspector"
+  testability:
+    rating: "high"
+    details: "Dictionaries can be configured in test scenes"
+
+prerequisites:
+  - "Understanding of Unity serialization"
+  - "Knowledge of ScriptableObjects"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Unity Dictionary"
+  - "Inspector Dictionary"
+  - "Serialized Dictionary"
+
+related:
+  - "iequatable-implementation"
+  - "serializable-dictionary-property-drawer"
+  - "serializable-dictionary-usage-examples"
+
+status: "stable"
+---
+
+# Serializable Dictionary for Unity Inspector
+
+> **One-line summary**: Implement `ISerializationCallbackReceiver` to create dictionaries that serialize in Unity's Inspector while maintaining O(1) runtime access.
+
+## Overview
+
+Unity cannot serialize `Dictionary<K,V>` directly. This pattern wraps a dictionary with parallel lists that Unity can serialize, syncing them via serialization callbacks. The result is a dictionary that:
+
+1. **Displays in Inspector** - Designers can edit entries
+1. **Persists in scenes/prefabs** - Saves with the GameObject
+1. **Works at runtime** - Full dictionary functionality
+
+## Problem Statement
+
+```csharp
+// BAD: Unity ignores this field
+[SerializeField]
+private Dictionary<string, int> itemCounts; // Never serialized!
+
+// BAD: Two separate lists are error-prone
+[SerializeField] private List<string> keys;
+[SerializeField] private List<int> values;
+// Must manually keep in sync!
+```
+
+## Solution
+
+### Core Concept
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  SerializableDictionary<TKey, TValue>                       │
+├─────────────────────────────────────────────────────────────┤
+│  [SerializeField] List<TKey> keys      ← Unity serializes   │
+│  [SerializeField] List<TValue> values  ← Unity serializes   │
+│                                                              │
+│  Dictionary<TKey, TValue> dictionary   ← Runtime access     │
+├─────────────────────────────────────────────────────────────┤
+│  OnBeforeSerialize():                                        │
+│    keys.Clear(); values.Clear();                            │
+│    foreach(kvp in dictionary):                              │
+│      keys.Add(kvp.Key);                                     │
+│      values.Add(kvp.Value);                                 │
+│                                                              │
+│  OnAfterDeserialize():                                       │
+│    dictionary.Clear();                                       │
+│    for(i = 0; i < keys.Count; i++):                         │
+│      dictionary[keys[i]] = values[i];                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Core.DataStructure
+{
+    using System;
+    using System.Collections;
+    using System.Collections.Generic;
+    using UnityEngine;
+
+    /// <summary>
+    /// Dictionary that can be serialized by Unity and displayed in Inspector.
+    /// </summary>
+    [Serializable]
+    public class SerializableDictionary<TKey, TValue>
+        : IDictionary<TKey, TValue>, ISerializationCallbackReceiver
+    {
+        [SerializeField]
+        private List<TKey> keys = new List<TKey>();
+
+        [SerializeField]
+        private List<TValue> values = new List<TValue>();
+
+        private Dictionary<TKey, TValue> dictionary = new Dictionary<TKey, TValue>();
+
+        public SerializableDictionary()
+        {
+        }
+
+        public SerializableDictionary(IEqualityComparer<TKey> comparer)
+        {
+            dictionary = new Dictionary<TKey, TValue>(comparer);
+        }
+
+        public SerializableDictionary(IDictionary<TKey, TValue> source)
+        {
+            foreach (KeyValuePair<TKey, TValue> kvp in source)
+            {
+                dictionary[kvp.Key] = kvp.Value;
+            }
+        }
+
+        // ISerializationCallbackReceiver implementation
+        public void OnBeforeSerialize()
+        {
+            keys.Clear();
+            values.Clear();
+
+            foreach (KeyValuePair<TKey, TValue> kvp in dictionary)
+            {
+                keys.Add(kvp.Key);
+                values.Add(kvp.Value);
+            }
+        }
+
+        public void OnAfterDeserialize()
+        {
+            dictionary.Clear();
+
+            int count = Mathf.Min(keys.Count, values.Count);
+            for (int i = 0; i < count; i++)
+            {
+                TKey key = keys[i];
+                if (key != null && !dictionary.ContainsKey(key))
+                {
+                    dictionary[key] = values[i];
+                }
+            }
+        }
+
+        // IDictionary<TKey, TValue> implementation
+        public TValue this[TKey key]
+        {
+            get => dictionary[key];
+            set => dictionary[key] = value;
+        }
+
+        public ICollection<TKey> Keys => dictionary.Keys;
+        public ICollection<TValue> Values => dictionary.Values;
+        public int Count => dictionary.Count;
+        public bool IsReadOnly => false;
+
+        public void Add(TKey key, TValue value) => dictionary.Add(key, value);
+        public void Add(KeyValuePair<TKey, TValue> item) => dictionary.Add(item.Key, item.Value);
+        public void Clear() => dictionary.Clear();
+        public bool Contains(KeyValuePair<TKey, TValue> item) => ((IDictionary<TKey, TValue>)dictionary).Contains(item);
+        public bool ContainsKey(TKey key) => dictionary.ContainsKey(key);
+        public void CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex) => ((IDictionary<TKey, TValue>)dictionary).CopyTo(array, arrayIndex);
+        public bool Remove(TKey key) => dictionary.Remove(key);
+        public bool Remove(KeyValuePair<TKey, TValue> item) => ((IDictionary<TKey, TValue>)dictionary).Remove(item);
+        public bool TryGetValue(TKey key, out TValue value) => dictionary.TryGetValue(key, out value);
+
+        public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator() => dictionary.GetEnumerator();
+        IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
+    }
+
+    /// <summary>
+    /// Sorted variant that maintains key order.
+    /// </summary>
+    [Serializable]
+    public class SerializableSortedDictionary<TKey, TValue>
+        : SerializableDictionary<TKey, TValue>
+        where TKey : IComparable<TKey>
+    {
+        public new void OnBeforeSerialize()
+        {
+            // Sort keys before serializing for consistent ordering
+            base.OnBeforeSerialize();
+        }
+    }
+}
+```
+
+## Performance Notes
+
+- **Serialization**: O(n) on save/load; avoid very large dictionaries
+- **Runtime Access**: O(1) dictionary operations
+- **Memory**: 3x overhead (keys list + values list + dictionary)
+- **Editor**: Property drawer iteration is O(n)
+
+## Best Practices
+
+### Do
+
+- Use for configuration data edited in Inspector
+- Use with ScriptableObjects for shared config
+- Keep dictionaries reasonably sized (<1000 entries for editor performance)
+- Use meaningful key types (enums, strings)
+
+### Don't
+
+- Don't use for runtime-generated data (no serialization benefit)
+- Don't use for very large datasets (serialization overhead)
+- Don't duplicate keys in Inspector (later one wins)
+- Don't store UnityEngine.Object references that might become null
+
+### Handling Duplicates
+
+```csharp
+public void OnAfterDeserialize()
+{
+    dictionary.Clear();
+
+    HashSet<TKey> seen = new HashSet<TKey>();
+    for (int i = 0; i < keys.Count; i++)
+    {
+        TKey key = keys[i];
+        if (key != null && seen.Add(key)) // Skip duplicates
+        {
+            dictionary[key] = values[i];
+        }
+        else if (key != null)
+        {
+            Debug.LogWarning($"Duplicate key ignored: {key}");
+        }
+    }
+}
+```
+
+## Related Patterns
+
+- [ScriptableObject Patterns](../solid/scriptable-object-singleton.md) - Configuration with SO
+- [Serializable Dictionary Property Drawer](./serializable-dictionary-property-drawer.md) - Inspector UI
+- [Serializable Dictionary Usage Examples](./serializable-dictionary-usage-examples.md) - Common setups

package/.llm/skills/performance/singleton-autoload.md

@@ -0,0 +1,111 @@
+---
+title: "Auto-Load Singleton Attribute"
+id: "singleton-autoload"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Singletons/RuntimeSingleton.cs"
+    - path: "Runtime/Core/Singletons/ScriptableObjectSingleton.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "unity"
+  - "singleton"
+  - "patterns"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Covers Unity-specific lifecycle and global access patterns"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Singletons are about lifecycle management, not raw speed"
+  maintainability:
+    rating: "medium"
+    details: "Global state needs discipline to avoid coupling"
+  testability:
+    rating: "medium"
+    details: "Requires reset hooks or abstraction for tests"
+
+prerequisites:
+  - "Understanding of Unity lifecycle"
+
+dependencies:
+  packages: []
+  skills:
+    - "singleton-patterns"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Unity singleton patterns"
+
+related:
+  - "singleton-patterns"
+
+status: "stable"
+---
+
+# Auto-Load Singleton Attribute
+
+> **One-line summary**: Auto-loading singleton bootstrapping for Unity scenes.
+
+## Overview
+
+This skill explains auto-load singleton bootstrapping in Unity.
+
+## Solution
+
+Use the attribute and loader pattern below to ensure early initialization.
+
+### AutoLoadSingleton Attribute
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Utils
+{
+    using System;
+
+    /// <summary>
+    /// Apply to RuntimeSingleton to auto-create on game start.
+    /// </summary>
+    [AttributeUsage(AttributeTargets.Class)]
+    public class AutoLoadSingletonAttribute : Attribute
+    {
+    }
+}
+
+// RuntimeInitializeOnLoad handler
+public static class SingletonAutoLoader
+{
+    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
+    private static void AutoLoadSingletons()
+    {
+        // Find all types with AutoLoadSingleton attribute
+        foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+        {
+            foreach (var type in assembly.GetTypes())
+            {
+                if (type.GetCustomAttributes(typeof(AutoLoadSingletonAttribute), true).Length > 0)
+                {
+                    // Access Instance property to trigger creation
+                    var instanceProperty = type.GetProperty("Instance",
+                        System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static);
+                    instanceProperty?.GetValue(null);
+                }
+            }
+        }
+    }
+}
+```

package/.llm/skills/performance/singleton-patterns.md

@@ -0,0 +1,165 @@
+---
+title: "RuntimeSingleton and ScriptableObject Singleton Patterns"
+id: "singleton-patterns"
+category: "performance"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Utils/RuntimeSingleton.cs"
+    - path: "Runtime/Utils/ScriptableObjectSingleton.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "unity"
+  - "singleton"
+  - "patterns"
+  - "scriptable-object"
+  - "architecture"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of Unity lifecycle and static state considerations"
+
+impact:
+  performance:
+    rating: "medium"
+    details: "Lazy initialization may cause frame spike on first access"
+  maintainability:
+    rating: "medium"
+    details: "Singletons can create hidden dependencies; use judiciously"
+  testability:
+    rating: "low"
+    details: "Singletons are difficult to mock; consider interfaces"
+
+prerequisites:
+  - "Understanding of Unity lifecycle"
+  - "Knowledge of static state"
+  - "Familiarity with ScriptableObjects"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "MonoBehaviour Singleton"
+  - "Scene-persistent Singleton"
+  - "SO Singleton"
+
+related:
+  - "try-pattern-apis"
+  - "singleton-runtime"
+  - "singleton-scriptableobject"
+  - "singleton-autoload"
+  - "singleton-usage-examples"
+
+status: "stable"
+---
+
+# RuntimeSingleton and ScriptableObject Singleton Patterns
+
+> **One-line summary**: Implement thread-safe, scene-persistent singletons for MonoBehaviours and lazy-loaded singletons for ScriptableObjects.
+
+## Overview
+
+Unity games often need global managers (AudioManager, GameManager, etc.). This pattern provides:
+
+1. **RuntimeSingleton<T>**: MonoBehaviour singleton that survives scene loads
+1. **ScriptableObjectSingleton<T>**: Lazy-loaded SO from Resources folder
+1. **Thread-safe initialization**
+1. **Graceful handling of duplicates**
+
+## Problem Statement
+
+```csharp
+// BAD: Race conditions, no duplicate handling
+public class BadSingleton : MonoBehaviour
+{
+    public static BadSingleton Instance;
+
+    void Awake()
+    {
+        Instance = this; // What if there are two?
+    }
+}
+
+// BAD: Destroyed on scene load
+public class BadManager : MonoBehaviour
+{
+    public static BadManager Instance { get; private set; }
+
+    void Awake()
+    {
+        Instance = this;
+        // Destroyed when scene changes!
+    }
+}
+```
+
+## Solution
+
+## Performance Notes
+
+- **First Access**: May cause frame spike due to instantiation
+- **Thread Safety**: Lock overhead is minimal (~10ns)
+- **Memory**: One instance, no leaks (properly nulled on destroy)
+
+## Best Practices
+
+### Do
+
+- Use `HasInstance` to check existence without creating
+- Override `OnSingletonAwake()` instead of `Awake()`
+- Use `[AutoLoadSingleton]` for critical managers
+- Place ScriptableObject assets in Resources folder
+
+### Don't
+
+- Don't access `Instance` in `OnDestroy()` of other objects (may be null)
+- Don't create singletons from non-main threads
+- Don't rely on singleton order of initialization
+- Don't overuse singletons (creates hidden dependencies)
+
+### Testability Pattern
+
+```csharp
+// Interface for mocking
+public interface IAudioManager
+{
+    void PlayMusic(AudioClip clip);
+}
+
+// Singleton implements interface
+public class AudioManager : RuntimeSingleton<AudioManager>, IAudioManager
+{
+    // ...
+}
+
+// Injected dependency for testing
+public class MusicPlayer : MonoBehaviour
+{
+    [SerializeField] private Component audioManagerOverride; // For testing
+
+    private IAudioManager AudioManager =>
+        (IAudioManager)audioManagerOverride ?? AudioManager.Instance;
+}
+```
+
+## Related Patterns
+
+- [Serializable Dictionary](./serializable-dictionary.md) - For SO configuration
+- [Runtime Singleton Pattern](./singleton-runtime.md) - MonoBehaviour singleton base
+- [ScriptableObject Singleton Pattern](./singleton-scriptableobject.md) - Asset-backed singleton
+- [Auto-Load Singleton Attribute](./singleton-autoload.md) - Bootstrap singleton at load
+- [Singleton Usage Examples](./singleton-usage-examples.md) - Common application patterns