@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/manage-sprite-atlas/resources/queryspritesefficiently.cs

@@ -0,0 +1,222 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEngine;
+using UnityEngine.U2D;
+using System.Collections.Generic;
+using UnityEditor.U2D;
+
+/// <summary>
+/// Demonstrates efficient querying of sprites from SpriteAtlases.
+/// Avoids expensive operations and unnecessary allocations.
+/// </summary>
+public static class QuerySpritesEfficientlyExample
+{
+    /// <summary>
+    /// Gets all sprites from an atlas efficiently.
+    /// Uses the V2 GetPackables() method on runtime SpriteAtlas.
+    /// </summary>
+    public static Sprite[] GetSpritesFromAtlas(SpriteAtlas atlas)
+    {
+        if (atlas == null)
+        {
+            Debug.LogError("Cannot query: atlas is null");
+            return new Sprite[0];
+        }
+
+        // Use GetPackables() - this is the V2 way
+        Object[] packables = atlas.GetPackables();
+
+        // Filter to get only sprites
+        var sprites = new List<Sprite>();
+        for (int i = 0; i < packables.Length; i++)
+        {
+            if (packables[i] is Sprite sprite)
+            {
+                sprites.Add(sprite);
+            }
+        }
+
+        return sprites.ToArray();
+    }
+
+    /// <summary>
+    /// Gets a sprite by name from an atlas efficiently.
+    /// Avoids iterating through all sprites on each call by caching the results.
+    /// </summary>
+    public static Sprite GetSpriteFromAtlas(SpriteAtlas atlas, string spriteName)
+    {
+        if (atlas == null)
+        {
+            Debug.LogError("Cannot query: atlas is null");
+            return null;
+        }
+
+        if (string.IsNullOrEmpty(spriteName))
+        {
+            Debug.LogWarning("Cannot query: sprite name is null or empty");
+            return null;
+        }
+
+        // Get all sprites once
+        Sprite[] sprites = GetSpritesFromAtlas(atlas);
+
+        // Find matching sprite
+        for (int i = 0; i < sprites.Length; i++)
+        {
+            if (sprites[i].name == spriteName)
+            {
+                return sprites[i];
+            }
+        }
+
+        Debug.LogWarning($"Sprite '{spriteName}' not found in atlas: {atlas.name}");
+        return null;
+    }
+
+    /// <summary>
+    /// Queries multiple sprites by name from an atlas.
+    /// More efficient than calling GetSpriteFromAtlas multiple times
+    /// when you need to query many sprites at once.
+    /// </summary>
+    public static Sprite[] GetSpritesFromAtlas(SpriteAtlas atlas, string[] spriteNames)
+    {
+        if (atlas == null || spriteNames == null || spriteNames.Length == 0)
+            return new Sprite[0];
+
+        // Get all sprites once
+        Sprite[] allSprites = GetSpritesFromAtlas(atlas);
+
+        // Create lookup dictionary for efficient searching
+        var spriteLookup = new Dictionary<string, Sprite>();
+        for (int i = 0; i < allSprites.Length; i++)
+        {
+            spriteLookup[allSprites[i].name] = allSprites[i];
+        }
+
+        // Query requested sprites
+        var result = new List<Sprite>(spriteNames.Length);
+        for (int i = 0; i < spriteNames.Length; i++)
+        {
+            if (spriteLookup.TryGetValue(spriteNames[i], out Sprite foundSprite))
+            {
+                result.Add(foundSprite);
+            }
+            else
+            {
+                Debug.LogWarning($"Sprite '{spriteNames[i]}' not found in atlas: {atlas.name}");
+            }
+        }
+
+        return result.ToArray();
+    }
+
+    /// <summary>
+    /// Checks if an atlas contains a specific sprite by name.
+    /// </summary>
+    public static bool ContainsSprite(SpriteAtlas atlas, string spriteName)
+    {
+        if (atlas == null || string.IsNullOrEmpty(spriteName))
+            return false;
+
+        Sprite[] sprites = GetSpritesFromAtlas(atlas);
+
+        for (int i = 0; i < sprites.Length; i++)
+        {
+            if (sprites[i].name == spriteName)
+                return true;
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Gets the count of sprites in an atlas without loading all sprites.
+    /// </summary>
+    public static int GetSpriteCount(SpriteAtlas atlas)
+    {
+        if (atlas == null)
+            return 0;
+
+        Object[] packables = atlas.GetPackables();
+        int count = 0;
+
+        for (int i = 0; i < packables.Length; i++)
+        {
+            if (packables[i] is Sprite)
+                count++;
+        }
+
+        return count;
+    }
+}
+
+/// <summary>
+/// Component that demonstrates efficient sprite querying.
+/// Caches queries for repeated access.
+/// </summary>
+public class EfficientSpriteQuery : MonoBehaviour
+{
+    [SerializeField] private SpriteAtlas _atlas;
+
+    private Dictionary<string, Sprite> _spriteCache;
+    private bool _cacheInitialized = false;
+
+    /// <summary>
+    /// Initializes the cache with all sprites from the atlas.
+    /// Call this once at startup for efficient repeated queries.
+    /// </summary>
+    public void InitializeCache()
+    {
+        if (_atlas == null)
+            return;
+
+        Sprite[] sprites = QuerySpritesEfficientlyExample.GetSpritesFromAtlas(_atlas);
+
+        _spriteCache = new Dictionary<string, Sprite>(sprites.Length);
+        for (int i = 0; i < sprites.Length; i++)
+        {
+            _spriteCache[sprites[i].name] = sprites[i];
+        }
+
+        _cacheInitialized = true;
+        Debug.Log($"Cached {sprites.Length} sprites from atlas: {_atlas.name}");
+    }
+
+    /// <summary>
+    /// Gets a sprite by name using the cached lookup.
+    /// Much faster than querying the atlas directly for each call.
+    /// </summary>
+    public Sprite GetCachedSprite(string name)
+    {
+        if (!_cacheInitialized)
+        {
+            InitializeCache();
+        }
+
+        if (_spriteCache.TryGetValue(name, out Sprite sprite))
+        {
+            return sprite;
+        }
+
+        Debug.LogWarning($"Sprite '{name}' not found in cached atlas");
+        return null;
+    }
+
+    /// <summary>
+    /// Gets a sprite by name, with optional cache initialization.
+    /// </summary>
+    public Sprite GetSprite(string name, bool initializeIfNeeded = true)
+    {
+        if (!_cacheInitialized && initializeIfNeeded)
+        {
+            InitializeCache();
+        }
+
+        if (_spriteCache != null && _spriteCache.TryGetValue(name, out Sprite sprite))
+        {
+            return sprite;
+        }
+
+        // Fallback to direct query if cache not available
+        return QuerySpritesEfficientlyExample.GetSpriteFromAtlas(_atlas, name);
+    }
+}

package/skills/manage-sprite-atlas/resources/registercallbacks.cs

@@ -0,0 +1,152 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEngine;
+using UnityEngine.U2D;
+
+/// <summary>
+/// Demonstrates registering SpriteAtlasManager callbacks early in the lifecycle.
+/// Always register callbacks in Awake() or OnEnable(), not in Start().
+/// </summary>
+public class RegisterCallbacksExample : MonoBehaviour
+{
+    /// <summary>
+    /// Registers atlas loading callbacks when the component awakens.
+    /// This is the correct place - before any sprites might need atlases.
+    /// </summary>
+    private void Awake()
+    {
+        RegisterAtlasCallbacks();
+    }
+
+    /// <summary>
+    /// Registers SpriteAtlasManager callbacks for dynamic atlas loading.
+    /// Called during Awake() to ensure callbacks are ready before any sprite access.
+    /// </summary>
+    private void RegisterAtlasCallbacks()
+    {
+        // Register for atlas load events
+        SpriteAtlasManager.atlasRequested += RequestLateBindingAtlas;
+        SpriteAtlasManager.atlasRegistered += AtlasRegistered;
+
+        Debug.Log("SpriteAtlas callbacks registered");
+    }
+
+    /// <summary>
+    /// Unregisters callbacks when the component is destroyed.
+    /// Always unregister to prevent memory leaks and errors.
+    /// </summary>
+    private void OnDestroy()
+    {
+        SpriteAtlasManager.atlasRequested -= RequestLateBindingAtlas;
+        SpriteAtlasManager.atlasRegistered -= AtlasRegistered;
+
+        Debug.Log("SpriteAtlas callbacks unregistered");
+    }
+
+    /// <summary>
+    /// Callback invoked when a sprite needs its atlas but it's not loaded yet.
+    /// This is where you implement the late-binding logic.
+    /// </summary>
+    void RequestLateBindingAtlas(string tag, System.Action<SpriteAtlas> action)
+    {
+        // Determine which atlas should contain this sprite
+        string atlasName = GetAtlasNameForSprite(tag);
+
+        if (string.IsNullOrEmpty(atlasName))
+        {
+            Debug.LogWarning($"Could not determine atlas for sprite: {tag}");
+            return;
+        }
+
+        // Load the atlas asynchronously
+        LoadAtlasAsync(atlasName);
+    }
+
+    /// <summary>
+    /// Gets the atlas name for a given sprite.
+    /// This is project-specific logic - adjust based on your naming conventions.
+    /// </summary>
+    private string GetAtlasNameForSprite(string tag)
+    {
+        // Pattern 1: Use sprite name prefix
+        if (tag.StartsWith("btn_"))
+            return "UI_Buttons";
+        else if (tag.StartsWith("icon_"))
+            return "UI_Icons";
+        else if (tag.StartsWith("char_"))
+            return "Characters";
+        return "Default";
+    }
+
+    /// <summary>
+    /// Loads an atlas asynchronously.
+    /// In a real implementation, this would use Addressables or AssetBundle loading.
+    /// </summary>
+    private void LoadAtlasAsync(string atlasName)
+    {
+        // Example using Resources.Load (not recommended for production)
+        // SpriteAtlas atlas = Resources.Load<SpriteAtlas>(atlasName);
+
+        // For production with Addressables:
+        /*
+        var handle = Addressables.LoadAssetAsync<SpriteAtlas>(atlasName);
+        handle.Completed += op =>
+        {
+            if (op.Status == AsyncOperationStatus.Succeeded)
+            {
+                Debug.Log($"Late-bound atlas loaded: {atlasName}");
+            }
+            else
+            {
+                Debug.LogError($"Failed to load late-bound atlas: {atlasName}");
+            }
+        };
+        */
+
+        Debug.Log($"Loading late-bound atlas: {atlasName}");
+    }
+
+    void AtlasRegistered(SpriteAtlas spriteAtlas)
+    {
+        Debug.LogFormat("Registered {0}.", spriteAtlas.name);
+    }
+
+    /// <summary>
+    /// Forces loading of a specific atlas (for manual control).
+    /// </summary>
+    public void ForceLoadAtlas(string atlasName)
+    {
+        LoadAtlasAsync(atlasName);
+    }
+}
+
+/// <summary>
+/// Alternative pattern using OnEnable/OnDisable instead of Awake/OnDestroy.
+/// Use this if the component can be enabled/disabled dynamically.
+/// </summary>
+public class RegisterCallbacksWithEnable : MonoBehaviour
+{
+    private void OnEnable()
+    {
+        RegisterAtlasCallbacks();
+    }
+
+    private void OnDisable()
+    {
+        UnregisterAtlasCallbacks();
+    }
+
+    private void RegisterAtlasCallbacks()
+    {
+        SpriteAtlasManager.atlasRequested += RequestLateBindingAtlas;
+        SpriteAtlasManager.atlasRegistered += OnAtlasLoaded;
+    }
+
+    private void UnregisterAtlasCallbacks()
+    {
+        SpriteAtlasManager.atlasRequested -= RequestLateBindingAtlas;
+        SpriteAtlasManager.atlasRegistered -= OnAtlasLoaded;
+    }
+
+    private void OnAtlasLoaded(SpriteAtlas atlas) { }
+    private void RequestLateBindingAtlas(string tag, System.Action<SpriteAtlas> action) { }
+}

package/skills/manage-sprite-atlas/resources/runtimeatlasloader.cs

@@ -0,0 +1,15 @@
+using UnityEngine;
+using UnityEngine.U2D;
+
+public class AtlasLoader : MonoBehaviour
+{
+    void OnEnable() => SpriteAtlasManager.atlasRequested += OnAtlasRequested;
+    void OnDisable() => SpriteAtlasManager.atlasRequested -= OnAtlasRequested;
+
+    void OnAtlasRequested(string tag, System.Action<SpriteAtlas> callback)
+    {
+        // Load from Resources or AssetBundle (NOT AssetDatabase!)
+        SpriteAtlas atlas = Resources.Load<SpriteAtlas>($"Atlases/{tag}");
+        callback(atlas);
+    }
+}

package/skills/manage-sprite-atlas/resources/runtimespriteaccess.cs

@@ -0,0 +1,19 @@
+using UnityEngine;
+using UnityEngine.U2D;
+
+// Query sprites *after* atlas is loaded via SpriteAtlasManager
+public static class SpriteQueryHelper
+{
+    public static Sprite GetSpriteByName(SpriteAtlas atlas, string name)
+    {
+        // atlas.GetSprite(name) is safe in runtime context
+        return atlas.GetSprite(name);
+    }
+
+    public static Sprite[] GetSpritesByPrefix(SpriteAtlas atlas, string prefix)
+    {
+        Sprite[] sprites = new Sprite[atlas.spriteCount];
+        int count = atlas.GetSprites(sprites);
+        return System.Array.FindAll(sprites, s => s.name.StartsWith(prefix));
+    }
+}

package/skills/manage-sprite-atlas/resources/savespriteatlasasset.cs

@@ -0,0 +1,107 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor;
+using UnityEditor.U2D;
+using UnityEngine;
+using UnityEngine.U2D;
+
+/// <summary>
+/// Demonstrates proper saving of SpriteAtlasAsset.
+/// Always use SpriteAtlasAsset.Save() followed by AssetDatabase.ImportAsset().
+/// </summary>
+public static class SaveSpriteAtlasAssetExample
+{
+    /// <summary>
+    /// Creates and saves a new sprite atlas asset properly.
+    /// Follows the two-step V2 pattern: Create → Save → Import → Configure.
+    /// </summary>
+    public static void CreateAndSaveAtlas(string path, Object[] sprites)
+    {
+        // Step 1: Create the atlas asset in memory
+        SpriteAtlasAsset atlasAsset = new SpriteAtlasAsset();
+
+        // Step 2: Add sprites to the atlas
+        if (sprites != null && sprites.Length > 0)
+        {
+            atlasAsset.Add(sprites);
+        }
+
+        // Step 3: Save the asset to disk
+        SpriteAtlasAsset.Save(atlasAsset, path);
+
+        // Step 4: Import the asset into Unity's asset database
+        AssetDatabase.ImportAsset(path);
+
+        Debug.Log($"Created and saved atlas at {path}");
+    }
+
+    /// <summary>
+    /// Creates an atlas with automatic folder-based organization.
+    /// </summary>
+    public static void CreateAtlasFromFolder(string folderPath, string outputPath)
+    {
+        // Find all sprites in the folder
+        string[] guids = AssetDatabase.FindAssets("t:Sprite", new[] { folderPath });
+
+        Object[] sprites = new Object[guids.Length];
+        for (int i = 0; i < guids.Length; i++)
+        {
+            string assetPath = AssetDatabase.GUIDToAssetPath(guids[i]);
+            sprites[i] = AssetDatabase.LoadAssetAtPath<Sprite>(assetPath);
+        }
+
+        // Create and save the atlas
+        CreateAndSaveAtlas(outputPath, sprites);
+
+        // Configure via importer (two-step V2 pattern)
+        ConfigureViaImporter(outputPath);
+    }
+
+    /// <summary>
+    /// Configures an atlas after saving using SpriteAtlasImporter.
+    /// This is the correct two-step approach for V2.
+    /// </summary>
+    private static void ConfigureViaImporter(string atlasPath)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+
+        if (importer != null)
+        {
+            // Configure settings
+            importer.includeInBuild = true;
+            var packingSettings = importer.packingSettings;
+            packingSettings.enableTightPacking = true;
+            packingSettings.enableAlphaDilation = false;
+            importer.packingSettings = packingSettings;
+
+            // CRITICAL: Save and reimport to apply changes
+            importer.SaveAndReimport();
+        }
+    }
+
+    /// <summary>
+    /// Updates an existing atlas by adding more sprites.
+    /// </summary>
+    public static void AddSpritesToExistingAtlas(string atlasPath, Object[] newSprites)
+    {
+        // Load the existing atlas
+        SpriteAtlasAsset atlasAsset = AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>(atlasPath);
+
+        if (atlasAsset == null)
+        {
+            Debug.LogError($"Could not load atlas at {atlasPath}");
+            return;
+        }
+
+        // Add new sprites
+        if (newSprites != null && newSprites.Length > 0)
+        {
+            atlasAsset.Add(newSprites);
+        }
+
+        // Save changes
+        SpriteAtlasAsset.Save(atlasAsset, atlasPath);
+        AssetDatabase.ImportAsset(atlasPath);
+
+        Debug.Log($"Added {newSprites.Length} sprites to atlas at {atlasPath}");
+    }
+}

package/skills/manage-sprite-atlas/resources/scriptablepacker.cs

@@ -0,0 +1,81 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor.U2D;
+using UnityEngine;
+using Unity.Collections;
+
+/// <summary>
+/// Base class for implementing custom sprite packing algorithms.
+/// Extend this class to create specialized packing strategies beyond Unity's default algorithms.
+/// </summary>
+public class CustomSpritePacker : ScriptablePacker
+{
+    /// <summary>
+    /// Required: Implement packing logic.
+    /// This method is called during atlas building to determine sprite positions.
+    /// </summary>
+    /// <param name="config">Packing configuration settings</param>
+    /// <param name="setting">Texture settings for the atlas</param>
+    /// <param name="input">Input data containing sprites, textures, and vertex data</param>
+    /// <returns>True if packing succeeded, false otherwise</returns>
+    public override bool Pack(SpriteAtlasPackingSettings config,
+                             SpriteAtlasTextureSettings setting,
+                             PackerData input)
+    {
+        // Access input data
+        NativeArray<SpriteData> sprites = input.spriteData;
+        NativeArray<TextureData> textures = input.textureData;
+        NativeArray<Color32> colors = input.colorData;
+        NativeArray<int> indices = input.indexData;
+        NativeArray<Vector2> vertices = input.vertexData;
+
+        // Implement packing algorithm
+        for (int i = 0; i < sprites.Length; i++)
+        {
+            SpriteData sprite = sprites[i];
+
+            // Set output position and page
+            sprite.output.x = CalculateX(i);
+            sprite.output.y = CalculateY(i);
+            sprite.output.page = CalculatePage(i);
+            sprite.output.rot = PackTransform.None;
+
+            sprites[i] = sprite;
+        }
+
+        return true; // Return true if packing succeeded
+    }
+
+    /// <summary>
+    /// Optional: Implement fitting without texture creation.
+    /// This method is used to determine if sprites fit within the atlas bounds.
+    /// </summary>
+    protected override bool Fit(SpriteAtlasPackingSettings config,
+                               SpriteAtlasTextureSettings setting,
+                               PackerData input)
+    {
+        // Implement fit algorithm (optional)
+        return false;
+    }
+
+    #region Helper Methods
+
+    private int CalculateX(int index)
+    {
+        // Custom X position calculation
+        return index * 100;
+    }
+
+    private int CalculateY(int index)
+    {
+        // Custom Y position calculation
+        return (index / 10) * 100;
+    }
+
+    private int CalculatePage(int index)
+    {
+        // Page assignment logic
+        return index / 64;
+    }
+
+    #endregion
+}