@aqian0/dsh-unity 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,190 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor;
+using UnityEditor.U2D;
+
+/// <summary>
+/// Demonstrates why you should NOT pack atlases during runtime builds.
+/// Packed atlases during build time are already optimized for the target platform.
+/// </summary>
+public static class DontPackInRuntimeBuildsDocumentation
+{
+    /// <summary>
+    /// ❌ WRONG: Attempting to pack atlases during a runtime build.
+    /// This is unnecessary and can cause issues because:
+    /// 1. Atlases should be packed at editor time (prebuild)
+    /// 2. Runtime builds don't have access to all source assets
+    /// 3. It slows down the build process significantly
+    /// </summary>
+    public static void Wrong_PackDuringRuntimeBuild()
+    {
+        // This is WRONG - do not pack during runtime build
+
+        // ❌ BAD: Calling PackAtlases in a build callback
+        // public class MyBuildProcessor : IPostprocessBuildWithReport
+        // {
+        //     public void OnPostprocessBuild(BuildTarget target, string path)
+        //     {
+        //         // Don't do this!
+        //         SpriteAtlasUtility.PackAtlases(atlases, BuildTarget.NoAPI);
+        //     }
+        // }
+
+        // ❌ BAD: Using SpriteAtlasUtility.PackAtlases in a runtime build
+        // This method is for editor preview only, not for build-time packing
+    }
+
+    /// <summary>
+    /// ❌ WRONG: Calling SaveAndReimport() during a build.
+    /// Modifying assets during build can cause unpredictable behavior.
+    /// </summary>
+    public static void Wrong_ModifyDuringBuild()
+    {
+        // This is WRONG - do not modify assets during build
+
+        // ❌ BAD: Saving asset database during build
+        // AssetDatabase.SaveAssets();
+        // AssetDatabase.ImportAsset(path);
+        // importer.SaveAndReimport(); // Don't do this in build!
+    }
+
+    /// <summary>
+    /// ✅ CORRECT: Pack atlases during prebuild, not runtime.
+    /// Use IPreprocessBuildWithReport to pack atlases before the build starts.
+    /// </summary>
+    public static void Correct_PackDuringPrebuild()
+    {
+        // ✅ CORRECT: Implement IPreprocessBuildWithReport for packing
+
+        /*
+        public class AtlasPacker : IPreprocessBuildWithReport
+        {
+            public int callbackOrder => 0;
+
+            public void OnPreprocessBuild(BuildTarget target, string path)
+            {
+                // Find and pack all atlases before build
+                string[] guids = AssetDatabase.FindAssets("t:SpriteAtlasAsset", new[] { "Assets" });
+                var atlases = new SpriteAtlasAsset[guids.Length];
+
+                for (int i = 0; i < guids.Length; i++)
+                {
+                    atlases[i] = AssetDatabase.LoadAssetAtPath<SpriteAtlasAsset>(
+                        AssetDatabase.GUIDToAssetPath(guids[i]));
+                }
+
+                // Pack is optional here - build-time packing happens automatically
+                // SpriteAtlasUtility.PackAtlases(atlases, BuildTarget.NoAPI);
+            }
+        }
+        */
+    }
+
+    /// <summary>
+    /// ✅ CORRECT: Use prebuild pipeline for atlas generation.
+    /// This is the recommended approach for all atlas operations.
+    /// </summary>
+    public static void Correct_UsePrebuildPipeline()
+    {
+        // ✅ Implement IPreprocessBuildWithReport for:
+        // - Atlas generation
+        // - Atlas configuration
+        // - Batch packing
+
+        /*
+        [InitializeOnLoad]
+        public class MyAtlasPreprocessor
+        {
+            static MyAtlasPreprocessor()
+            {
+                EditorApplication.wantsToQuit += () =>
+                {
+                    // Clean up any temporary assets before quit
+                    return true;
+                };
+            }
+        }
+
+        public class MyBuildProcessor : IPreprocessBuildWithReport
+        {
+            public int callbackOrder => 0;
+
+            public void OnPreprocessBuild(BuildTarget target, string path)
+            {
+                // Generate or update atlases here
+                // This runs BEFORE the build starts
+            }
+        }
+        */
+    }
+
+    /// <summary>
+    /// ✅ CORRECT: For runtime loading, use SpriteAtlasManager with late-binding.
+    /// Load atlases on-demand at runtime using Addressables or AssetBundles.
+    /// </summary>
+    public static void Correct_RuntimeLateBinding()
+    {
+        // ✅ Use SpriteAtlasManager for runtime atlas loading
+
+        /*
+        public class RuntimeAtlasLoader : MonoBehaviour
+        {
+            private void Awake()
+            {
+                // Register for late-binding
+                SpriteAtlasManager.atlasRegistrationNeeded += OnAtlasRegistrationNeeded;
+            }
+
+            private void OnAtlasRegistrationNeeded(Sprite sprite)
+            {
+                // Load the appropriate atlas using Addressables or AssetBundles
+                // This runs at runtime, not during build
+            }
+        }
+        */
+    }
+}
+
+/// <summary>
+/// Summary of when to pack atlases:
+///
+/// Editor Time (✅ DO):
+/// - IPreprocessBuildWithReport.OnPreprocessBuild()
+/// - Manual packing via SpriteAtlasUtility.PackAtlases() for preview
+///
+/// Build Time (❌ DON'T):
+/// - IPostprocessBuildWithReport.OnPostprocessBuild()
+/// - Any time during actual build process
+///
+/// Runtime (✅ DO):
+/// - Load atlases on-demand using SpriteAtlasManager
+/// - Use Addressables or AssetBundles for dynamic loading
+/// </summary>
+public static class PackingTimeline
+{
+    /// <summary>
+    /// Editor: Prebuild - Pack atlases here ✅
+    /// </summary>
+    public static void Pack_Editor_Prebuild()
+    {
+        // IPreprocessBuildWithReport.OnPreprocessBuild()
+        // This is the correct time to pack atlases
+    }
+
+    /// <summary>
+    /// Build: Build process - Do NOT pack here ❌
+    /// </summary>
+    public static void Pack_Build_Process()
+    {
+        // IPostprocessBuildWithReport.OnPostprocessBuild()
+        // Atlases are already packed at this point
+    }
+
+    /// <summary>
+    /// Runtime: Late-binding - Load atlases on-demand ✅
+    /// </summary>
+    public static void Pack_Runtime_LateBinding()
+    {
+        // SpriteAtlasManager.atlasRegistrationNeeded
+        // Load atlases as needed during gameplay
+    }
+}

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

@@ -0,0 +1,114 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEngine;
+using UnityEditor;
+using UnityEditor.U2D;
+using UnityEngine.U2D;
+
+/// <summary>
+/// Demonstrates what NOT to do when scripting SpriteAtlases in editor code.
+/// This file shows common mistakes and their consequences.
+/// </summary>
+public static class DontScriptSpriteAtlasInEditor
+{
+    /// <summary>
+    /// ❌ WRONG: Creating SpriteAtlas directly in editor code.
+    /// SpriteAtlas is a runtime-only type. This will fail at compile time or runtime.
+    /// </summary>
+    [System.Obsolete("This is incorrect - do not use")]
+    public static void Wrong_CreateSpriteAtlasDirectly()
+    {
+        // This is WRONG - SpriteAtlas cannot be constructed in editor code
+        // SpriteAtlas atlas = new SpriteAtlas(); // Compile error!
+    }
+
+    /// <summary>
+    /// ❌ WRONG: Using AssetDatabase.LoadAssetAtPath<SpriteAtlas>() in editor.
+    /// Use SpriteAtlasAsset for editor authoring, not SpriteAtlas.
+    /// </summary>
+    [System.Obsolete("This is incorrect - do not use")]
+    public static void Wrong_LoadSpriteAtlasInEditor()
+    {
+        // This is WRONG - SpriteAtlas is runtime-only
+        // SpriteAtlas atlas = AssetDatabase.LoadAssetAtPath<SpriteAtlas>("path/to/atlas.spriteatlas"); // Runtime error!
+    }
+
+    /// <summary>
+    /// ❌ WRONG: Modifying SpriteAtlas in editor scripts.
+    /// SpriteAtlas is read-only at runtime and cannot be created in editor.
+    /// </summary>
+    [System.Obsolete("This is incorrect - do not use")]
+    public static void Wrong_ModifySpriteAtlasInEditor()
+    {
+        // This is WRONG - cannot modify SpriteAtlas in editor
+        // atlas.Add(sprites); // Compile error!
+    }
+
+    /// <summary>
+    /// ❌ WRONG: Using deprecated SpriteAtlasAsset methods.
+    /// Use the two-step pattern with SpriteAtlasImporter instead.
+    /// </summary>
+    [System.Obsolete("This is incorrect - do not use")]
+    public static void Wrong_UseDeprecatedMethods()
+    {
+        // This is WRONG - deprecated methods should not be used
+        // SpriteAtlasAsset atlas = new SpriteAtlasAsset();
+        // atlas.SetBuildSettings(...); // Deprecated!
+    }
+
+    /// <summary>
+    /// ❌ WRONG: Modifying importer without calling SaveAndReimport().
+    /// Changes to SpriteAtlasImporter are not applied until you save and reimport.
+    /// </summary>
+    [System.Obsolete("This is incorrect - do not use")]
+    public static void Wrong_ModifyWithoutSaving()
+    {
+        // This is WRONG - changes won't be saved
+        // SpriteAtlasImporter importer = ...;
+        // importer.includeInBuild = true; // Not applied!
+        // No SaveAndReimport() called!
+    }
+
+    /// <summary>
+    /// ❌ WRONG: Confusing authoring vs runtime contexts.
+    /// SpriteAtlasAsset (editor) and SpriteAtlas (runtime) are different types.
+    /// </summary>
+    [System.Obsolete("This is incorrect - do not use")]
+    public static void Wrong_ConfuseAuthoringVsRuntime()
+    {
+        // This is WRONG - mixing contexts
+        // SpriteAtlasAsset asset = ...;
+        // SpriteAtlas runtime = asset; // Type mismatch!
+    }
+}
+
+/// <summary>
+/// CORRECT: The proper way to work with SpriteAtlases in editor code.
+/// </summary>
+public static class CorrectEditorPattern
+{
+    /// <summary>
+    /// Create and configure an atlas using the correct two-step V2 pattern.
+    /// </summary>
+    public static void CreateAndConfigureAtlas(string path, Object[] sprites)
+    {
+        // Step 1: Create with SpriteAtlasAsset (editor-only)
+        SpriteAtlasAsset asset = new SpriteAtlasAsset();
+        asset.Add(sprites);
+        SpriteAtlasAsset.Save(asset, path);
+
+        // Step 2: Import and configure via SpriteAtlasImporter
+        AssetDatabase.ImportAsset(path);
+
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+        if (importer != null)
+        {
+            importer.includeInBuild = true;
+            var packingSettings = importer.packingSettings;
+            packingSettings.enableTightPacking = true;
+            importer.packingSettings = packingSettings;
+
+            // CRITICAL: Save and reimport to apply changes
+            importer.SaveAndReimport();
+        }
+    }
+}

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

@@ -0,0 +1,95 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor;
+using UnityEditor.U2D;
+using UnityEngine;
+
+/// <summary>
+/// Demonstrates proper editor configuration for SpriteAtlas V2.
+/// Always use SpriteAtlasImporter for all settings in editor code.
+/// </summary>
+public static class EditorConfigurationExample
+{
+    /// <summary>
+    /// Configures an existing atlas asset with proper editor settings.
+    /// This is the correct pattern - create with SpriteAtlasAsset, then configure via SpriteAtlasImporter.
+    /// </summary>
+    public static void ConfigureSpriteAtlas(string atlasPath)
+    {
+        // Step 1: Ensure Sprite Packer is enabled
+        EditorSettings.spritePackerMode = SpritePackerMode.SpriteAtlasV2;
+
+        // Step 2: Get the importer for configuration
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+
+        if (importer == null)
+        {
+            Debug.LogError($"Could not get SpriteAtlasImporter for {atlasPath}");
+            return;
+        }
+
+        // Step 3: Configure texture settings via importer
+        var textureSettings = importer.textureSettings;
+        textureSettings.generateMipMaps = false;
+        textureSettings.filterMode = FilterMode.Bilinear;
+        importer.textureSettings = textureSettings;
+
+        // Step 4: Configure packing settings
+        var packingSettings = importer.packingSettings;
+        packingSettings.padding = 2;
+        packingSettings.enableRotation = true;
+        packingSettings.enableTightPacking = true;
+
+        // Step 5: Configure platform settings
+        var platformSettings = importer.GetPlatformSettings("DefaultTexturePlatform");;
+        platformSettings.maxTextureSize = 2048;
+        platformSettings.format = TextureImporterFormat.ASTC_6x6;
+        platformSettings.compressionQuality = 100;
+        importer.GetPlatformSettings("DefaultTexturePlatform");
+
+        // Step 6: Set build inclusion
+        importer.includeInBuild = true;
+
+        // Step 7: CRITICAL - Save and reimport to apply changes
+        importer.SaveAndReimport();
+
+        Debug.Log($"Configured atlas at {atlasPath}");
+    }
+
+    /// <summary>
+    /// Configures platform-specific settings for multiple platforms.
+    /// </summary>
+    public static void ConfigurePlatformSettings(string atlasPath)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+
+        // Mobile platform (Android/iOS)
+        importer.SetPlatformSettings(new TextureImporterPlatformSettings
+        {
+            name = "Android",
+            maxTextureSize = 1024,
+            format = TextureImporterFormat.ETC2_RGB4,
+            compressionQuality = 100
+        });
+
+        importer.SetPlatformSettings(new TextureImporterPlatformSettings
+        {
+            name = "iOS",
+            maxTextureSize = 1024,
+            format = TextureImporterFormat.ASTC_6x6,
+            compressionQuality = 100
+        });
+
+        // Desktop platform (Windows/Mac/Linux)
+        importer.SetPlatformSettings(new TextureImporterPlatformSettings
+        {
+            name = "Standalone",
+            maxTextureSize = 1024,
+            format = TextureImporterFormat.DXT5,
+            compressionQuality = 100
+        });
+
+
+        // Save and reimport
+        importer.SaveAndReimport();
+    }
+}

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

@@ -0,0 +1,172 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor;
+using UnityEditor.U2D;
+using UnityEngine;
+
+/// <summary>
+/// Demonstrates enabling and configuring Sprite Packer for SpriteAtlases.
+/// Proper packing configuration is essential for efficient atlas usage.
+/// </summary>
+public static class EnableSpritePackingExample
+{
+    /// <summary>
+    /// Enables Sprite Packer mode in Project Settings.
+    /// This must be done before creating atlases.
+    /// </summary>
+    public static void EnableSpritePacker()
+    {
+        EditorSettings.spritePackerMode = SpritePackerMode.SpriteAtlasV2;
+        Debug.Log("Sprite Packer V2 enabled");
+    }
+
+    /// <summary>
+    /// Configures packing settings for an atlas.
+    /// Tight packing reduces texture memory usage.
+    /// </summary>
+    public static void ConfigurePackingSettings(string atlasPath)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+        if (importer == null)
+            return;
+
+        // Enable tight packing for better space utilization
+        var packingSettings = importer.packingSettings;
+        packingSettings.enableTightPacking = true;
+        importer.packingSettings = packingSettings;
+
+        importer.SaveAndReimport();
+    }
+
+    /// <summary>
+    /// Configures packing settings with rotation enabled.
+    /// Rotation can significantly improve packing density for irregular sprites.
+    /// </summary>
+    public static void EnableRotationPacking(string atlasPath)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+        if (importer == null)
+            return;
+
+        var packingSettings = importer.packingSettings;
+        packingSettings.enableRotation = true;
+        importer.packingSettings = packingSettings;
+
+        importer.SaveAndReimport();
+    }
+
+    /// <summary>
+    /// Configures packing settings with padding.
+    /// Add padding to prevent texture bleeding between adjacent sprites.
+    /// </summary>
+    public static void ConfigurePackingWithPadding(string atlasPath, int paddingPixels)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+        if (importer == null)
+            return;
+
+        var packingSettings = importer.packingSettings;
+        packingSettings.padding = 2;
+        importer.packingSettings = packingSettings;
+
+        importer.SaveAndReimport();
+    }
+
+    /// <summary>
+    /// Configures packing settings for UI atlases.
+    /// UI sprites typically need consistent positioning without rotation.
+    /// </summary>
+    public static void ConfigureUIPacking(string atlasPath)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+        if (importer == null)
+            return;
+
+        // UI sprites usually shouldn't be rotated
+        var packingSettings = importer.packingSettings;
+        packingSettings.padding = 2;
+        packingSettings.enableTightPacking = false;
+        packingSettings.enableRotation = false;
+        packingSettings.enableAlphaDilation = false;
+        importer.packingSettings = packingSettings;
+
+        importer.SaveAndReimport();
+    }
+
+    /// <summary>
+    /// Configures packing settings for character/animation atlases.
+    /// Animation frames need consistent positioning across frames.
+    /// </summary>
+    public static void ConfigureAnimationPacking(string atlasPath)
+    {
+        SpriteAtlasImporter importer = AssetImporter.GetAtPath(atlasPath) as SpriteAtlasImporter;
+        if (importer == null)
+            return;
+
+        // UI sprites usually shouldn't be rotated
+        var packingSettings = importer.packingSettings;
+        packingSettings.padding = 2;
+        packingSettings.enableTightPacking = true;
+        packingSettings.enableRotation = false;
+        packingSettings.enableAlphaDilation = false;
+        importer.packingSettings = packingSettings;
+
+        importer.SaveAndReimport();
+    }
+}
+
+/// <summary>
+/// Editor window for batch configuring sprite packing settings.
+/// </summary>
+public class ConfigurePackingWindow : EditorWindow
+{
+    private string _atlasFolder = "Assets/Atlases";
+    private bool _tightPacking = true;
+    private bool _allowRotation = false;
+    private int _padding = 2;
+
+    [MenuItem("Tools/Configure Sprite Packing")]
+    public static void ShowWindow()
+    {
+        GetWindow<ConfigurePackingWindow>("Configure Packing");
+    }
+
+    private void OnGUI()
+    {
+        EditorGUILayout.LabelField("Batch Configure Packing", EditorStyles.boldLabel);
+
+        _atlasFolder = EditorGUILayout.TextField("Atlas Folder", _atlasFolder);
+        _tightPacking = EditorGUILayout.Toggle("Tight Packing", _tightPacking);
+        _allowRotation = EditorGUILayout.Toggle("Allow Rotation", _allowRotation);
+        _padding = EditorGUILayout.IntField("Padding (pixels)", _padding);
+
+        if (GUILayout.Button("Configure Atlases"))
+        {
+            BatchConfigure();
+        }
+    }
+
+    private void BatchConfigure()
+    {
+        string[] guids = AssetDatabase.FindAssets("t:SpriteAtlasAsset", new[] { _atlasFolder });
+
+        foreach (string guid in guids)
+        {
+            string path = AssetDatabase.GUIDToAssetPath(guid);
+            SpriteAtlasImporter importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+
+            if (importer != null)
+            {
+                var packingSettings = importer.packingSettings;
+                packingSettings.padding = _padding;
+                packingSettings.enableTightPacking = _tightPacking;
+                packingSettings.enableRotation = _allowRotation;
+                packingSettings.enableAlphaDilation = false;
+                importer.packingSettings = packingSettings;
+                importer.SaveAndReimport();
+            }
+        }
+
+        Debug.Log($"Configured packing for {guids.Length} atlases");
+        AssetDatabase.Refresh();
+    }
+}

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

@@ -0,0 +1,50 @@
+// [UNITY-SKILL:SPRITEATLAS]
+using UnityEditor.U2D;
+using UnityEngine;
+using Unity.Collections;
+
+/// <summary>
+/// Simple grid-based sprite packer that arranges sprites in a uniform grid pattern.
+/// Sprites are placed row by row from left to right, top to bottom.
+/// </summary>
+public class GridSpritePacker : ScriptablePacker
+{
+    /// <summary>Number of columns in the grid</summary>
+    public int columns = 4;
+
+    /// <summary>Size of each cell in pixels (assumed square)</summary>
+    public int cellSize = 256;
+
+    /// <summary>Padding between sprites in pixels</summary>
+    public int padding = 2;
+
+    /// <summary>
+    /// Packs sprites in a grid pattern.
+    /// Sprite at index i is placed at column (i % columns) and row (i / columns).
+    /// </summary>
+    public override bool Pack(SpriteAtlasPackingSettings config,
+                             SpriteAtlasTextureSettings setting,
+                             PackerData input)
+    {
+        NativeArray<SpriteData> sprites = input.spriteData;
+
+        for (int i = 0; i < sprites.Length; i++)
+        {
+            SpriteData sprite = sprites[i];
+
+            // Calculate grid position
+            int col = i % columns;
+            int row = i / columns;
+
+            // Set output position with padding
+            sprite.output.x = col * (cellSize + padding) + padding;
+            sprite.output.y = row * (cellSize + padding) + padding;
+            sprite.output.page = 0; // Single page
+            sprite.output.rot = PackTransform.None;
+
+            sprites[i] = sprite;
+        }
+
+        return true;
+    }
+}