nccgs 2.1.1 → 3.0.0-rc.2

package/unity-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/unity-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/unity-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/unity-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;
+    }
+}

package/unity-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}");
+        }
+    }
+}