@aqian0/dsh-unity 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,147 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEngine;
+using UnityEngine.U2D;
+
+/// <summary>
+/// Demonstrates proper handling of late-binding for SpriteAtlases.
+/// Late-binding allows atlases to be loaded on-demand when sprites are first accessed.
+/// </summary>
+public class HandleLateBinding : MonoBehaviour
+{
+    /// <summary>Prefix used for atlas resources</summary>
+    [SerializeField] private string _atlasResourcePrefix = "Atlases/";
+
+    /// <summary>Whether to automatically load atlases</summary>
+    [SerializeField] private bool _autoLoad = true;
+
+    private void Awake()
+    {
+        if (_autoLoad)
+        {
+            RegisterLateBinding();
+        }
+    }
+
+    private void OnDestroy()
+    {
+        UnregisterLateBinding();
+    }
+
+    /// <summary>
+    /// Registers for late-binding via SpriteAtlasManager.
+    /// When a sprite needs an atlas, the registration callback will be invoked.
+    /// </summary>
+    public void RegisterLateBinding()
+    {
+        SpriteAtlasManager.atlasRequested += RequestLateBindingAtlas;
+        SpriteAtlasManager.atlasRegistered += AtlasRegistered;
+        Debug.Log("Late-binding registered");
+    }
+
+    /// <summary>
+    /// Unregisters late-binding callbacks.
+    /// Call this when the component is destroyed or no longer needs late-binding.
+    /// </summary>
+    public void UnregisterLateBinding()
+    {
+        SpriteAtlasManager.atlasRequested -= RequestLateBindingAtlas;
+        SpriteAtlasManager.atlasRegistered -= AtlasRegistered;
+        Debug.Log("Late-binding 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>
+/// Example of using late-binding in a scene with multiple objects.
+/// Each object can request its atlas to be loaded.
+/// </summary>
+public class LateBindingConsumer : MonoBehaviour
+{
+    [SerializeField] private Sprite _spriteToDisplay;
+
+    private void Start()
+    {
+        // Accessing the sprite will trigger late-binding if needed
+        SpriteRenderer renderer = GetComponent<SpriteRenderer>();
+        if (renderer != null && _spriteToDisplay != null)
+        {
+            renderer.sprite = _spriteToDisplay;
+            Debug.Log($"Set sprite: {_spriteToDisplay.name}");
+        }
+    }
+}

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

@@ -0,0 +1,141 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor;
+using UnityEditor.U2D;
+using UnityEngine;
+using UnityEngine.U2D;
+
+/// <summary>
+/// Demonstrates proper null handling when working with SpriteAtlases.
+/// Always check for null before accessing assets and importers.
+/// </summary>
+public static class HandleNullCasesExample
+{
+    /// <summary>
+    /// Safely loads a sprite atlas asset with null checking.
+    /// </summary>
+    public static SpriteAtlasAsset LoadSpriteAtlasSafely(string path)
+    {
+        // Check if path is valid
+        if (string.IsNullOrEmpty(path))
+        {
+            Debug.LogError("Atlas path is null or empty");
+            return null;
+        }
+
+        // Load the asset with null check
+        SpriteAtlasAsset atlasAsset = AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>(path);
+
+        if (atlasAsset == null)
+        {
+            Debug.LogWarning($"Could not load SpriteAtlasAsset at {path}. It may not exist yet or is invalid.");
+            return null;
+        }
+
+        return atlasAsset;
+    }
+
+    /// <summary>
+    /// Safely gets the SpriteAtlasImporter with null checking.
+    /// </summary>
+    public static SpriteAtlasImporter GetSpriteAtlasImporterSafely(string path)
+    {
+        if (string.IsNullOrEmpty(path))
+        {
+            Debug.LogError("Atlas path is null or empty");
+            return null;
+        }
+
+        // Get importer with null check
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+
+        if (importer == null)
+        {
+            Debug.LogWarning($"Could not get SpriteAtlasImporter for {path}. Is this a valid atlas file?");
+            return null;
+        }
+
+        return importer;
+    }
+
+    /// <summary>
+    /// Safely adds sprites to an atlas with null checking.
+    /// </summary>
+    public static bool AddSpritesToAtlasSafely(SpriteAtlasAsset atlas, Object[] sprites)
+    {
+        // Check all inputs
+        if (atlas == null)
+        {
+            Debug.LogError("Cannot add sprites: atlas is null");
+            return false;
+        }
+
+        if (sprites == null || sprites.Length == 0)
+        {
+            Debug.LogWarning("No sprites provided to add to atlas");
+            return true; // Not an error, just nothing to do
+        }
+
+        // Add sprites
+        atlas.Add(sprites);
+        return true;
+    }
+
+    /// <summary>
+    /// Safely configures an atlas with comprehensive null checking.
+    /// </summary>
+    public static bool ConfigureAtlasSafely(string path)
+    {
+        // Check path
+        if (string.IsNullOrEmpty(path))
+        {
+            Debug.LogError("Cannot configure atlas: path is null or empty");
+            return false;
+        }
+
+        // Load asset
+        SpriteAtlasAsset atlas = LoadSpriteAtlasSafely(path);
+        if (atlas == null)
+        {
+            return false;
+        }
+
+        // Get importer
+        SpriteAtlasImporter importer = GetSpriteAtlasImporterSafely(path);
+        if (importer == null)
+        {
+            return false;
+        }
+
+        // Configure settings
+        try
+        {
+            importer.includeInBuild = true;
+            var packingSettings = importer.packingSettings;
+            packingSettings.enableTightPacking = true;
+            importer.packingSettings = packingSettings;
+            importer.SaveAndReimport();
+            return true;
+        }
+        catch (System.Exception ex)
+        {
+            Debug.LogError($"Failed to configure atlas: {ex.Message}");
+            return false;
+        }
+    }
+
+    /// <summary>
+    /// Safely gets sprites from an atlas with null checking.
+    /// </summary>
+    public static Object[] GetAtlasSpritesSafely(SpriteAtlas atlas)
+    {
+        if (atlas == null)
+        {
+            Debug.LogError("Cannot get sprites: atlas is null");
+            return new Object[0];
+        }
+
+        // Use GetPackables() - this is the V2 way
+        Object[] packables = atlas.GetPackables();
+        return packables ?? new Object[0];
+    }
+}

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

@@ -0,0 +1,335 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor;
+using UnityEditor.U2D;
+using UnityEngine;
+
+/// <summary>
+/// Migration guide from SpriteAtlas V1 to V2.
+/// This file shows the key differences and how to update existing code.
+/// </summary>
+public static class MigrateV1ToV2Documentation
+{
+    /// <summary>
+    /// V1 Pattern: Direct SpriteAtlas scripting (NO LONGER WORKS)
+    ///
+    /// ❌ OLD V1 CODE:
+    /// var atlas = ScriptableObject.CreateInstance<SpriteAtlas>();
+    /// atlas.Add(sprites);
+    /// AssetDatabase.AddObjectToAsset(atlas, path);
+    /// EditorUtility.SetDirty(atlas);
+    ///
+    /// ✅ NEW V2 CODE:
+    /// SpriteAtlasAsset asset = new SpriteAtlasAsset();
+    /// asset.Add(sprites);
+    /// SpriteAtlasAsset.Save(asset, path);
+    /// AssetDatabase.ImportAsset(path);
+    /// </summary>
+    public static void Migration_1_CreateAtlas()
+    {
+        // ===== MIGRATION 1: Creating an Atlas =====
+
+        // ❌ OLD (V1 - Broken):
+        /*
+        var atlas = ScriptableObject.CreateInstance<SpriteAtlas>();
+        atlas.Add(sprites);
+        AssetDatabase.AddObjectToAsset(atlas, path);
+        EditorUtility.SetDirty(atlas);
+        */
+
+        // ✅ NEW (V2):
+        SpriteAtlasAsset asset = new SpriteAtlasAsset();
+        asset.Add(new Object[0]); // Add sprites
+        SpriteAtlasAsset.Save(asset, "Assets/MyAtlas.spriteatlasv2");
+        AssetDatabase.ImportAsset("Assets/MyAtlas.spriteatlasv2");
+    }
+
+    /// <summary>
+    /// V1 Pattern: Direct configuration (NO LONGER WORKS)
+    ///
+    /// ❌ OLD V1 CODE:
+    /// var importer = (SpriteAtlasImporter)AssetImporter.GetAtPath(path);
+    /// importer.SetBuildSettings(settings);
+    ///
+    /// ✅ NEW V2 CODE:
+    /// var importer = (SpriteAtlasImporter)AssetImporter.GetAtPath(path);
+    /// importer.packingSettings = settings;
+    /// importer.SaveAndReimport();
+    /// </summary>
+    public static void Migration_2_ConfigureAtlas()
+    {
+        // ===== MIGRATION 2: Configuring an Atlas =====
+
+        // ❌ OLD (V1 - Deprecated):
+        /*
+        var importer = (SpriteAtlasImporter)AssetImporter.GetAtPath(path);
+        importer.SetBuildSettings(settings); // Method removed!
+        */
+
+        // ✅ NEW (V2):
+        SpriteAtlasImporter importer = null; // Get from AssetImporter
+        // importer.packingSettings = settings;
+        // importer.SaveAndReimport();
+    }
+
+    /// <summary>
+    /// V1 Pattern: Loading in editor (NO LONGER WORKS)
+    ///
+    /// ❌ OLD V1 CODE:
+    /// var atlas = AssetDatabase.LoadAssetAtPath<SpriteAtlas>(path);
+    ///
+    /// ✅ NEW V2 CODE:
+    /// var asset = AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>(path);
+    /// </summary>
+    public static void Migration_3_LoadInEditor()
+    {
+        // ===== MIGRATION 3: Loading Atlases in Editor =====
+
+        // ❌ OLD (V1 - Broken):
+        /*
+        var atlas = AssetDatabase.LoadAssetAtPath<SpriteAtlas>(path); // Returns null!
+        */
+
+        // ✅ NEW (V2):
+        SpriteAtlasAsset asset = AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>("Assets/MyAtlas.spriteatlasv2");
+    }
+
+    /// <summary>
+    /// V1 Pattern: Runtime loading (CHANGED SIGNIFICANTLY)
+    ///
+    /// ❌ OLD V1 CODE:
+    /// var atlas = Resources.Load<SpriteAtlas>("Atlases/MyAtlas");
+    ///
+    /// ✅ NEW V2 CODE:
+    /// SpriteAtlasManager.atlasRegistrationNeeded += OnRegistrationNeeded;
+    /// // Or use Addressables for dynamic loading
+    /// </summary>
+    public static void Migration_4_RuntimeLoading()
+    {
+        // ===== MIGRATION 4: Runtime Loading =====
+
+        // ❌ OLD (V1 - Not recommended):
+        /*
+        var atlas = Resources.Load<SpriteAtlas>("Atlases/MyAtlas");
+        */
+
+        // ✅ NEW (V2 - Recommended):
+        // Use SpriteAtlasManager with late-binding
+        /*
+        public class MyLoader : MonoBehaviour
+        {
+            private void Awake()
+            {
+                SpriteAtlasManager.atlasRegistrationNeeded += OnRegistrationNeeded;
+            }
+
+            private void OnRegistrationNeeded(Sprite sprite)
+            {
+                // Load atlas via Addressables or AssetBundles
+            }
+        }
+        */
+    }
+
+    /// <summary>
+    /// V1 Pattern: Manual packing (CHANGED)
+    ///
+    /// ❌ OLD V1 CODE:
+    /// SpriteAtlasUtility.PackAtlases(atlases, BuildTarget.StandaloneWindows64);
+    ///
+    /// ✅ NEW V2 CODE:
+    /// Use IPreprocessBuildWithReport for automatic packing during build
+    /// </summary>
+    public static void Migration_5_Packing()
+    {
+        // ===== MIGRATION 5: Packing Atlases =====
+
+        // ❌ OLD (V1 - Manual):
+        /*
+        SpriteAtlasUtility.PackAtlases(atlases, BuildTarget.StandaloneWindows64);
+        */
+
+        // ✅ NEW (V2 - Automatic via Prebuild):
+        /*
+        public class MyPreprocessor : IPreprocessBuildWithReport
+        {
+            public void OnPreprocessBuild(BuildTarget target, string path)
+            {
+                // Atlases are automatically packed during build
+                // Use this for generation/configuration, not manual packing
+            }
+        }
+        */
+    }
+
+    /// <summary>
+    /// Complete migration checklist:
+    ///
+    /// [ ] Replace SpriteAtlas creation with SpriteAtlasAsset
+    /// [ ] Use SpriteAtlasImporter for all configuration
+    /// [ ] Call SaveAndReimport() after every modification
+    /// [ ] Use SpriteAtlasManager for runtime loading
+    /// [ ] Implement IPreprocessBuildWithReport for automatic generation
+    /// [ ] Use .spriteatlasv2 file extension (not .spriteatlas)
+    /// </summary>
+    public static void Migration_Checklist()
+    {
+        /*
+        MIGRATION CHECKLIST:
+        ====================
+
+        1. Asset Creation
+           - OLD: ScriptableObject.CreateInstance<SpriteAtlas>()
+           - NEW: new SpriteAtlasAsset()
+
+        2. Saving Assets
+           - OLD: AssetDatabase.AddObjectToAsset(), EditorUtility.SetDirty()
+           - NEW: SpriteAtlasAsset.Save(), AssetDatabase.ImportAsset()
+
+        3. Configuration
+           - OLD: importer.SetBuildSettings()
+           - NEW: importer.packingSettings, importer.platformSettings
+
+        4. Saving Changes
+           - OLD: EditorUtility.SetDirty()
+           - NEW: importer.SaveAndReimport()
+
+        5. Loading in Editor
+           - OLD: AssetDatabase.LoadAssetAtPath<SpriteAtlas>()
+           - NEW: AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>()
+
+        6. Runtime Loading
+           - OLD: Resources.Load<SpriteAtlas>()
+           - NEW: SpriteAtlasManager + Addressables/AssetBundles
+
+        7. File Extension
+           - OLD: .spriteatlas
+           - NEW: .spriteatlasv2
+        */
+    }
+}
+
+/// <summary>
+/// Example: Complete V1 to V2 migration for a build script.
+/// </summary>
+public static class BuildScriptMigrationExample
+{
+    /// <summary>
+    /// ❌ OLD V1 Build Script (BROKEN):
+    /// This script will NOT work with SpriteAtlas V2.
+    /// </summary>
+    [System.Obsolete("This is the old V1 pattern - do not use")]
+    public static void Old_V1_BuildScript()
+    {
+        // ❌ BROKEN: This is the old V1 way
+        /*
+        [MenuItem("Tools/Build Game")]
+        public static void BuildGame()
+        {
+            // Create atlas (V1 - Broken)
+            var atlas = ScriptableObject.CreateInstance<SpriteAtlas>();
+            atlas.Add(AssetDatabase.LoadAllAssetsAtPath("Assets/Sprites"));
+
+            // Save atlas (V1 - Broken)
+            AssetDatabase.AddObjectToAsset(atlas, "Assets/MyAtlas.spriteatlas");
+            EditorUtility.SetDirty(atlas);
+
+            // Configure (V1 - Broken)
+            var importer = (SpriteAtlasImporter)AssetImporter.GetAtPath("Assets/MyAtlas.spriteatlas");
+            importer.SetBuildSettings(new SpriteAtlasPackingSettings()); // Method removed!
+
+            // Build
+            BuildPipeline.BuildPlayer(...);
+        }
+        */
+    }
+
+    /// <summary>
+    /// ✅ NEW V2 Build Script (WORKING):
+    /// This script works with SpriteAtlas V2.
+    /// </summary>
+    public static void New_V2_BuildScript()
+    {
+        // ✅ WORKING: This is the new V2 way
+
+        /*
+        [MenuItem("Tools/Build Game")]
+        public static void BuildGame()
+        {
+            // Step 1: Generate/update atlases (V2)
+            string[] guids = AssetDatabase.FindAssets("t:SpriteAtlasAsset", new[] { "Assets" });
+            foreach (string guid in guids)
+            {
+                string path = AssetDatabase.GUIDToAssetPath(guid);
+                var asset = AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>(path);
+
+                // Add sprites if needed
+                // asset.Add(sprites);
+
+                // Save and import
+                SpriteAtlasAsset.Save(asset, path);
+                AssetDatabase.ImportAsset(path);
+
+                // Configure via importer (V2)
+                var importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+                importer.includeInBuild = true;
+                importer.packingSettings.tightPacking = true;
+                importer.SaveAndReimport();
+            }
+
+            // Step 2: Build the game
+            BuildPipeline.BuildPlayer(...);
+        }
+        */
+
+        Debug.Log("Use V2 pattern instead of V1");
+    }
+
+    /// <summary>
+    /// ✅ NEW V2 Prebuild Processor (RECOMMENDED):
+    /// This is the recommended approach - automatic atlas generation during build.
+    /// </summary>
+    public static void New_V2_PreprocessBuild()
+    {
+        // ✅ RECOMMENDED: Use prebuild processor for automatic generation
+
+        /*
+        public class AtlasPreprocessor : IPreprocessBuildWithReport
+        {
+            public int callbackOrder => 0;
+
+            public void OnPreprocessBuild(BuildTarget target, string path)
+            {
+                // Automatically generate or update atlases before build
+                GenerateAtlases();
+            }
+
+            private void GenerateAtlases()
+            {
+                // Find sprites by folder, naming convention, or label
+                string[] guids = AssetDatabase.FindAssets("t:Sprite", new[] { "Assets/Sprites" });
+
+                // Create atlas asset
+                var asset = new SpriteAtlasAsset();
+                var sprites = new Object[guids.Length];
+                for (int i = 0; i < guids.Length; i++)
+                {
+                    sprites[i] = AssetDatabase.LoadAssetAtPath<Sprite>(
+                        AssetDatabase.GUIDToAssetPath(guids[i]));
+                }
+                asset.Add(sprites);
+
+                // Save and import
+                string path = "Assets/Atlases/GameSprites.spriteatlasv2";
+                SpriteAtlasAsset.Save(asset, path);
+                AssetDatabase.ImportAsset(path);
+
+                // Configure via importer
+                var importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+                importer.includeInBuild = true;
+                importer.packingSettings.tightPacking = true;
+                importer.SaveAndReimport();
+            }
+        }
+        */
+    }
+}

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

@@ -0,0 +1,80 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor.U2D;
+using UnityEngine;
+using Unity.Collections;
+
+/// <summary>
+/// Distributes sprites across multiple atlas pages with automatic page management.
+/// Handles both row wrapping within a page and page overflow.
+/// </summary>
+public class MultiPagePacker : ScriptablePacker
+{
+    /// <summary>Maximum number of sprites per page</summary>
+    public int maxSpritesPerPage = 64;
+
+    /// <summary>Width of each atlas page in pixels</summary>
+    public int pageWidth = 2048;
+
+    /// <summary>Padding between sprites in pixels</summary>
+    public int padding = 4;
+
+    /// <summary>
+    /// Packs sprites across multiple pages.
+    /// Automatically creates new pages when the current page is full or a row wraps.
+    /// </summary>
+    public override bool Pack(SpriteAtlasPackingSettings config,
+                             SpriteAtlasTextureSettings setting,
+                             PackerData input)
+    {
+        NativeArray<SpriteData> sprites = input.spriteData;
+        NativeArray<TextureData> textures = input.textureData;
+
+        int currentPage = 0;
+        int spritesInPage = 0;
+        int currentX = padding;
+        int currentY = padding;
+        int maxHeightInRow = 0;
+
+        for (int i = 0; i < sprites.Length; i++)
+        {
+            SpriteData sprite = sprites[i];
+            TextureData texture = textures[sprite.texIndex];
+
+            int spriteWidth = sprite.rect.width;
+            int spriteHeight = sprite.rect.height;
+
+            // Check if we need a new page
+            if (spritesInPage >= maxSpritesPerPage)
+            {
+                currentPage++;
+                spritesInPage = 0;
+                currentX = padding;
+                currentY = padding;
+                maxHeightInRow = 0;
+            }
+
+            // Check if we need a new row
+            if (currentX + spriteWidth + padding > pageWidth)
+            {
+                currentX = padding;
+                currentY += maxHeightInRow + padding;
+                maxHeightInRow = 0;
+            }
+
+            // Set output
+            sprite.output.x = currentX;
+            sprite.output.y = currentY;
+            sprite.output.page = currentPage;
+            sprite.output.rot = PackTransform.None;
+
+            // Update position for next sprite
+            currentX += spriteWidth + padding;
+            maxHeightInRow = Mathf.Max(maxHeightInRow, spriteHeight);
+            spritesInPage++;
+
+            sprites[i] = sprite;
+        }
+
+        return true;
+    }
+}