@aqian0/dsh-unity 0.0.0-stage → 0.1.0

package/skills/manage-sprite-atlas/references/api.md

@@ -0,0 +1,382 @@
+# SpriteAtlas V2 API Reference
+
+Complete API documentation for Unity's SpriteAtlas V2 system.
+
+## Table of Contents
+
+- [SpriteAtlasAsset (Editor Authoring)](#spriteatlasasset-editor-authoring)
+- [SpriteAtlasImporter (Editor Settings)](#spriteatlasimporter-editor-settings)
+- [SpriteAtlasUtility (Editor Packing)](#spriteatlasutility-editor-packing)
+- [SpriteAtlas (Runtime)](#spriteatlas-runtime)
+- [SpriteAtlasManager (Runtime Loading)](#spriteatlasmanager-runtime-loading)
+- [Settings Structures](#settings-structures)
+
+## SpriteAtlasAsset (Editor Authoring)
+
+**Namespace:** `UnityEditor.U2D`
+**Location:** `SpriteAtlasAsset.bindings.cs`
+
+Primary API for adding/removing content from sprite atlases.
+
+### Constructor
+
+```csharp
+SpriteAtlasAsset atlasAsset = new SpriteAtlasAsset();
+```
+
+### Content Management
+
+```csharp
+// Add sprites or folders
+void Add(Object[] objects)
+
+// Remove packables
+void Remove(Object[] objects)
+
+// Remove by index
+void RemoveAt(int index)
+```
+
+### Persistence
+
+```csharp
+// Save to disk
+static void Save(SpriteAtlasAsset asset, string path)
+
+// Load from disk
+static SpriteAtlasAsset Load(string path)
+```
+
+### Variant Configuration
+
+```csharp
+// Mark as variant atlas
+void SetIsVariant(bool value)
+
+// Check if variant
+bool isVariant { get; }
+
+// Set master atlas (requires SpriteAtlas reference)
+void SetMasterAtlas(SpriteAtlas master)
+
+// Get master atlas
+SpriteAtlas GetMasterAtlas()
+```
+
+### Custom Packer
+
+```csharp
+// Set custom packing algorithm
+void SetScriptablePacker(Object packer)
+
+// Get current packer
+Object GetPacker()
+```
+
+### Deprecated Methods
+
+These methods are deprecated in V2. Use `SpriteAtlasImporter` instead:
+
+- `SetVariantScale()` → Use `SpriteAtlasImporter.variantScale`
+- `SetIncludeInBuild()` → Use `SpriteAtlasImporter.includeInBuild`
+- `IsIncludeInBuild()` → Use `SpriteAtlasImporter.includeInBuild`
+- `SetPlatformSettings()` → Use `SpriteAtlasImporter.SetPlatformSettings()`
+- `SetTextureSettings()` → Use `SpriteAtlasImporter.textureSettings`
+- `SetPackingSettings()` → Use `SpriteAtlasImporter.packingSettings`
+
+## SpriteAtlasImporter (Editor Settings)
+
+**Namespace:** `UnityEditor.U2D`
+**Location:** `SpriteAtlasImporter.bindings.cs`
+
+Primary API for configuring all sprite atlas settings.
+
+### Getting the Importer
+
+```csharp
+string path = "Assets/MyAtlas.spriteatlas";
+SpriteAtlasImporter importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+```
+
+### Basic Properties
+
+```csharp
+// Variant scale multiplier
+float variantScale { get; set; }
+
+// Include atlas in player build
+bool includeInBuild { get; set; }
+```
+
+### Texture Settings
+
+```csharp
+// Get/set texture settings (struct)
+SpriteAtlasTextureSettings textureSettings { get; set; }
+
+// Example:
+SpriteAtlasTextureSettings settings = importer.textureSettings;
+settings.filterMode = FilterMode.Bilinear;
+settings.generateMipMaps = false;
+settings.readable = false;
+settings.sRGB = true;
+importer.textureSettings = settings;
+```
+
+### Packing Settings
+
+```csharp
+// Get/set packing settings (struct)
+SpriteAtlasPackingSettings packingSettings { get; set; }
+
+// Example:
+SpriteAtlasPackingSettings settings = importer.packingSettings;
+settings.padding = 4;
+settings.enableRotation = false;
+settings.enableTightPacking = false;
+settings.enableAlphaDilation = true;
+importer.packingSettings = settings;
+```
+
+### Platform Settings
+
+```csharp
+// Get platform-specific settings
+TextureImporterPlatformSettings GetPlatformSettings(string platform)
+
+// Set platform-specific settings
+void SetPlatformSettings(TextureImporterPlatformSettings settings)
+
+// Example:
+TextureImporterPlatformSettings platformSettings = importer.GetPlatformSettings("Android");
+platformSettings.overridden = true;
+platformSettings.maxTextureSize = 2048;
+platformSettings.format = TextureImporterFormat.ASTC_6x6;
+platformSettings.compressionQuality = 50;
+importer.SetPlatformSettings(platformSettings);
+```
+
+Platform names: "Standalone", "Android", "iOS", "WebGL", etc.
+
+### Applying Changes
+
+```csharp
+// REQUIRED: Save and reimport after any changes
+void SaveAndReimport()
+```
+
+**Critical:** Always call `SaveAndReimport()` after modifying importer properties.
+
+## SpriteAtlasUtility (Editor Packing)
+
+**Namespace:** `UnityEditor.U2D`
+**Location:** `EditorSpritePacking.bindings.cs`
+
+Utilities for packing sprite atlases.
+
+### Packing Operations
+
+```csharp
+// Pack all atlases in project for target platform
+static void PackAllAtlases(BuildTarget target, bool canCancel)
+
+// Pack specific atlases
+static void PackAtlases(SpriteAtlas[] atlases, BuildTarget target, bool canCancel)
+
+// Clean up packing temporary data
+static void CleanupAtlasPacking()
+```
+
+### Usage
+
+```csharp
+using UnityEditor;
+using UnityEditor.U2D;
+
+BuildTarget target = EditorUserBuildSettings.activeBuildTarget;
+
+// Pack all
+SpriteAtlasUtility.PackAllAtlases(target, canCancel: true);
+SpriteAtlasUtility.CleanupAtlasPacking();
+
+// Pack specific
+SpriteAtlas[] atlases = new[] { atlas1, atlas2 };
+SpriteAtlasUtility.PackAtlases(atlases, target, canCancel: false);
+SpriteAtlasUtility.CleanupAtlasPacking();
+```
+
+**Important:** Always call `CleanupAtlasPacking()` after batch packing operations.
+
+## SpriteAtlas (Runtime)
+
+**Namespace:** `UnityEngine.U2D`
+**Location:** `Runtime/2D/SpriteAtlas/ScriptBindings/SpriteAtlas.bindings.cs`
+
+**RUNTIME ONLY** - Do not script against SpriteAtlas in editor code. Provides read-only access to packed sprites.
+
+### Properties
+
+```csharp
+// Total sprite count in atlas
+int spriteCount { get; }
+
+// Atlas tag identifier
+string tag { get; }
+
+// Check if atlas is variant
+bool isVariant { get; }
+```
+
+### Sprite Queries
+
+```csharp
+// Get sprite by name
+Sprite GetSprite(string name)
+
+// Get all sprites
+int GetSprites(Sprite[] sprites)
+
+// Get sprites matching name prefix
+int GetSprites(Sprite[] sprites, string namePrefix)
+
+// Check if sprite belongs to atlas
+bool CanBindTo(Sprite sprite)
+```
+
+### Usage
+
+```csharp
+using UnityEngine;
+using UnityEngine.U2D;
+
+SpriteAtlas atlas = Resources.Load<SpriteAtlas>("MyAtlas");
+
+// Get specific sprite
+Sprite sprite = atlas.GetSprite("SpriteName");
+
+// Get all sprites
+Sprite[] allSprites = new Sprite[atlas.spriteCount];
+int count = atlas.GetSprites(allSprites);
+
+// Get sprites with prefix
+Sprite[] enemySprites = new Sprite[atlas.spriteCount];
+int enemyCount = atlas.GetSprites(enemySprites, "Enemy_");
+
+// Validate sprite binding
+bool canBind = atlas.CanBindTo(sprite);
+```
+
+## SpriteAtlasManager (Runtime Loading)
+
+**Namespace:** `UnityEngine.U2D`
+**Location:** `Runtime/2D/SpriteAtlas/ScriptBindings/SpriteAtlas.bindings.cs`
+
+Manages atlas loading callbacks and runtime creation.
+
+### Events
+
+```csharp
+// Called when an atlas is requested (late binding)
+static event Action<string, Action<SpriteAtlas>> atlasRequested
+
+// Called when an atlas is registered
+static event Action<SpriteAtlas> atlasRegistered
+```
+
+### Late Binding Pattern
+
+```csharp
+using UnityEngine;
+using UnityEngine.U2D;
+
+public class AtlasLoader : MonoBehaviour
+{
+    void OnEnable()
+    {
+        SpriteAtlasManager.atlasRequested += OnAtlasRequested;
+        SpriteAtlasManager.atlasRegistered += OnAtlasRegistered;
+    }
+
+    void OnDisable()
+    {
+        SpriteAtlasManager.atlasRequested -= OnAtlasRequested;
+        SpriteAtlasManager.atlasRegistered -= OnAtlasRegistered;
+    }
+
+    void OnAtlasRequested(string tag, System.Action<SpriteAtlas> callback)
+    {
+        // Load atlas from Resources or AssetBundle
+        SpriteAtlas atlas = Resources.Load<SpriteAtlas>($"Atlases/{tag}");
+        callback(atlas);
+    }
+
+    void OnAtlasRegistered(SpriteAtlas atlas)
+    {
+        Debug.Log($"Atlas registered: {atlas.tag}");
+    }
+}
+```
+
+### Runtime Atlas Creation
+
+```csharp
+// Create atlas at runtime
+static SpriteAtlas CreateSpriteAtlas(string name,
+                                     SpriteAtlasRuntimeConfig config,
+                                     AtlasPage[] pages)
+```
+
+Advanced usage for dynamic atlas generation. See custom-packing.md for details.
+
+## Settings Structures
+
+### SpriteAtlasTextureSettings
+
+```csharp
+struct SpriteAtlasTextureSettings
+{
+    int maxTextureSize { get; }        // Read-only
+    int anisoLevel { get; set; }       // Anisotropic filtering level
+    FilterMode filterMode { get; set; } // Point, Bilinear, Trilinear
+    bool generateMipMaps { get; set; }  // Enable mipmap generation
+    bool readable { get; set; }         // CPU-readable texture
+    bool sRGB { get; set; }            // Use sRGB color space
+}
+```
+
+### SpriteAtlasPackingSettings
+
+```csharp
+struct SpriteAtlasPackingSettings
+{
+    int blockOffset { get; set; }        // Block offset for algorithm
+    int padding { get; set; }            // Padding between sprites (pixels)
+    bool enableRotation { get; set; }    // Allow sprite rotation
+    bool enableTightPacking { get; set; } // Pack around sprite meshes
+    bool enableAlphaDilation { get; set; } // Prevent bleeding artifacts
+}
+```
+
+### TextureImporterPlatformSettings
+
+Used for platform-specific configuration. See Unity's `TextureImporter` documentation for complete reference.
+
+Common fields:
+```csharp
+class TextureImporterPlatformSettings
+{
+    string name { get; set; }              // Platform name
+    bool overridden { get; set; }          // Override default settings
+    int maxTextureSize { get; set; }       // Max size (32-8192)
+    TextureImporterFormat format { get; set; } // Compression format
+    int compressionQuality { get; set; }   // Quality (0-100)
+}
+```
+
+Common platform names: "Standalone", "Android", "iOS", "WebGL"
+
+Common formats:
+- Android: `TextureImporterFormat.ASTC_6x6`, `TextureImporterFormat.ETC2_RGBA8`
+- iOS: `TextureImporterFormat.ASTC_6x6`, `TextureImporterFormat.PVRTC_RGBA4`
+- Desktop: `TextureImporterFormat.DXT5`, `TextureImporterFormat.BC7`
+- WebGL: `TextureImporterFormat.DXT5`

package/skills/manage-sprite-atlas/references/best-practices.md

@@ -0,0 +1,183 @@
+# SpriteAtlas V2 Best Practices
+
+Optimization tips, common pitfalls, and recommended patterns for SpriteAtlas V2.
+
+## Table of Contents
+
+- [V2 Architecture Rules (Critical)](#v2-architecture-rules-critical)
+- [Editor Code Best Practices](#editor-code-best-practices)
+  - [Always Use SpriteAtlasImporter for Configuration](#always-use-spriteatlasimporter-for-configuration)
+  - [Save SpriteAtlasAsset Properly](#save-spriteatlasasset-properly)
+  - [Clean Up After Batch Operations](#clean-up-after-batch-operations)
+  - [Handle Null Cases](#handle-null-cases)
+  - [Use Correct Platform Names](#use-correct-platform-names)
+- [Runtime Code Best Practices](#runtime-code-best-practices)
+  - [Register Callbacks Early](#register-callbacks-early)
+  - [Cache Loaded Atlases](#cache-loaded-atlases)
+  - [Handle Late Binding Properly](#handle-late-binding-properly)
+  - [Validate Sprite Binding](#validate-sprite-binding)
+  - [Query Sprites Efficiently](#query-sprites-efficiently)
+- [Performance Best Practices](#performance-best-practices)
+  - [Optimize Texture Settings](#optimize-texture-settings)
+  - [Enable Tight Packing](#enable-tight-packing)
+  - [Use Variants Wisely](#use-variants-wisely)
+  - [Batch Pack Operations](#batch-pack-operations)
+  - [Enable Alpha Dilation](#enable-alpha-dilation)
+  - [Set includeInBuild Appropriately](#set-includeinbuild-appropriately)
+- [Common Pitfalls](#common-pitfalls)
+  - [Don't Script SpriteAtlas in Editor](#dont-script-spriteatlas-in-editor)
+  - [Don't Use Deprecated SpriteAtlasAsset Methods](#dont-use-deprecated-spriteatlasasset-methods)
+  - [Don't Forget to Reimport](#dont-forget-to-reimport)
+  - [Don't Pack in Runtime Builds](#dont-pack-in-runtime-builds)
+  - [Don't Modify Importer Without Saving](#dont-modify-importer-without-saving)
+  - [Don't Confuse Authoring vs Runtime](#dont-confuse-authoring-vs-runtime)
+- [Migration from V1 to V2](#migration-from-v1-to-v2)
+  - [Replace Direct SpriteAtlas Scripting](#replace-direct-spriteatlas-scripting)
+  - [Update Settings Configuration](#update-settings-configuration)
+  - [Update Build Scripts](#update-build-scripts)
+- [Checklist](#checklist)
+  - [Before Creating an Atlas](#before-creating-an-atlas)
+  - [When Creating an Atlas](#when-creating-an-atlas)
+  - [When Packing Atlases](#when-packing-atlases)
+  - [Runtime Loading](#runtime-loading)
+
+## V2 Architecture Rules (Critical)
+
+1. **NEVER script against SpriteAtlas in editor code** - SpriteAtlas is runtime-only in V2
+2. **Use SpriteAtlasAsset for content authoring** - Add/remove sprites and folders
+3. **Use SpriteAtlasImporter for all settings** - Texture, packing, platform, and variant configuration
+4. **Follow the two-step pattern** - Create asset with SpriteAtlasAsset, configure with SpriteAtlasImporter
+5. **Always call SaveAndReimport()** - Required after modifying importer settings
+
+## Editor Code Best Practices
+
+### Always Use SpriteAtlasImporter for Configuration
+
+See [resources/editorconfiguration.cs](../resources/editorconfiguration.cs).
+
+### Save SpriteAtlasAsset Properly
+
+See [resources/savespriteatlasasset.cs](../resources/savespriteatlasasset.cs).
+
+### Clean Up After Batch Operations
+
+See [resources/cleanupbatchoperations.cs](../resources/cleanupbatchoperations.cs).
+
+### Handle Null Cases
+
+See [resources/handlenullcases.cs](../resources/handlenullcases.cs).
+
+### Use Correct Platform Names
+
+See [resources/platformnames.cs](../resources/platformnames.cs).
+
+## Runtime Code Best Practices
+
+### Register Callbacks Early
+
+See [resources/registercallbacks.cs](../resources/registercallbacks.cs).
+
+### Cache Loaded Atlases
+
+See [resources/cacheloadedatlases.cs](../resources/cacheloadedatlases.cs).
+
+### Handle Late Binding Properly
+
+See [resources/handlelatebinding.cs](../resources/handlelatebinding.cs).
+
+### Query Sprites Efficiently
+
+See [resources/queryspritesefficiently.cs](../resources/queryspritesefficiently.cs).
+
+## Performance Best Practices
+
+### Optimize Texture Settings
+
+See [resources/optimizetexturesettings.cs](../resources/optimizetexturesettings.cs).
+
+### Enable Tight Packing
+
+See [resources/enablespritepacking.cs](../resources/enablespritepacking.cs).
+
+### Use Variants Wisely
+
+See [resources/usevariantswisely.cs](../resources/usevariantswisely.cs).
+
+### Set includeInBuild Appropriately
+
+See [resources/setincludeinbuild.cs](../resources/setincludeinbuild.cs).
+
+## Common Pitfalls
+
+### Don't Script SpriteAtlas in Editor
+
+See [resources/dontscriptspriteatlasineditor.cs](../resources/dontscriptspriteatlasineditor.cs).
+
+### Don't Use Deprecated SpriteAtlasAsset Methods
+
+See [resources/deprecatedmethods.cs](../resources/deprecatedmethods.cs).
+
+### Don't Pack in Runtime Builds
+
+See [resources/dontpackinruntimebuilds.cs](../resources/dontpackinruntimebuilds.cs).
+
+### Don't Modify Importer Without Saving
+
+See [resources/dontmodifywithoutsaving.cs](../resources/dontmodifywithoutsaving.cs).
+
+### Don't Confuse Authoring vs Runtime
+
+See [resources/authoringvsruntime.cs](../resources/authoringvsruntime.cs).
+
+## Migration from V1 to V2
+
+If migrating from V1 code:
+
+### Replace Direct SpriteAtlas Scripting
+
+See [resources/migratev1tov2.cs](../resources/migratev1tov2.cs).
+
+### Update Settings Configuration
+
+See [resources/updatesettingsconfiguration.cs](../resources/updatesettingsconfiguration.cs).
+
+### Update Build Scripts
+
+See [resources/updatebuildscripts.cs](../resources/updatebuildscripts.cs).
+
+## Checklist
+
+### Before Creating an Atlas
+
+- [ ] Know what sprites to include
+- [ ] Determine target platforms and formats
+- [ ] Decide on texture quality settings
+- [ ] Plan for variants if needed
+
+### When Creating an Atlas
+
+- [ ] Create SpriteAtlasAsset
+- [ ] Add sprites or folders
+- [ ] Save to disk with SpriteAtlasAsset.Save()
+- [ ] Import with AssetDatabase.ImportAsset()
+- [ ] Get SpriteAtlasImporter
+- [ ] Configure texture settings
+- [ ] Configure packing settings
+- [ ] Configure platform settings
+- [ ] Set includeInBuild
+- [ ] Call SaveAndReimport()
+
+### When Packing Atlases
+
+- [ ] Use appropriate BuildTarget
+- [ ] Wrap in try/finally block
+- [ ] Call CleanupAtlasPacking() in finally
+- [ ] Validate packing results
+
+### Runtime Loading
+
+- [ ] Register callbacks early (Awake/OnEnable)
+- [ ] Unregister callbacks (OnDestroy/OnDisable)
+- [ ] Cache loaded atlases
+- [ ] Handle load failures gracefully
+- [ ] Use async loading when possible

package/skills/manage-sprite-atlas/references/common-errors.md

@@ -0,0 +1,123 @@
+# Common Errors and Invalid Patterns
+
+This document covers invalid V2 patterns, API corrections, and common mistakes to avoid.
+
+## Table of Contents
+
+- [Invalid V2 Patterns (Do Not Use)](#invalid-v2-patterns-do-not-use)
+- [Critical API Corrections](#critical-api-corrections)
+  - [❌ Format Casting in TextureImporterPlatformSettings](#-format-casting-in-textureimporterplatformsettings)
+  - [❌ SetMasterAtlasPath() - Method Does Not Exist](#-setmasteratlaspath---method-does-not-exist)
+  - [⚠ Platform-Specific Format Limitations](#-platform-specific-format-limitations)
+  - [⚠ PackAtlases() Requires Runtime SpriteAtlas[]](#-packatlases-requires-runtime-spriteatlas)
+  - [⚠ Always scope AssetDatabase.FindAssets to the folders you mean](#-always-scope-assetdatabasefindassets-to-the-folders-you-mean)
+  - [⚠ AssetImporter.GetAtPath() Takes Single Argument](#-assetimportergetatpath-takes-single-argument)
+
+## Invalid V2 Patterns (Do Not Use)
+
+```csharp
+// ❌ WRONG - V1 pattern (scripting SpriteAtlas in editor)
+SpriteAtlas atlas = new SpriteAtlas();
+atlas.Add(sprites);  // Invalid in V2
+atlas.SetTextureSettings(settings);  // Invalid in V2
+
+// ❌ WRONG - Deprecated/invalid SpriteAtlasAsset methods
+atlasAsset.SetTextureSettings(settings);  // Use importer instead
+atlasAsset.SetPackingSettings(settings);  // Use importer instead
+atlasAsset.SetIncludeInBuild(true);       // Use importer instead
+
+// ❌ WRONG - Creating variants from runtime SpriteAtlas
+SpriteAtlasAsset masterAsset = ...;
+atlasVariant.Add(masterAsset.GetPackables()); // GetPackables() doesn't exist on SpriteAtlasAsset!
+
+// ❌ WRONG - Incorrect packable handling in variants
+SpriteAtlasAsset variant = new SpriteAtlasAsset();
+variant.SetMasterAtlas(atlasPath); // WRONG: SetMasterAtlas expects a Runtime SpriteAtlas, not path or SpriteAtlasAsset!
+
+// ❌ WRONG - Format cast in TextureImporterPlatformSettings
+var settings = new TextureImporterPlatformSettings {
+    format = (int)TextureImporterFormat.ASTC_6x6  // ❌ Explicit cast causes compile error
+};
+
+// ❌ WRONG - Using deprecated/invalid method
+variant.SetMasterAtlasPath(path); // Method doesn't exist - use SetMasterAtlas() with runtime SpriteAtlas
+```
+
+## Critical API Corrections
+
+### ❌ Format Casting in TextureImporterPlatformSettings
+
+```csharp
+// ❌ WRONG - Explicit cast causes compile error
+var settings = new TextureImporterPlatformSettings {
+    format = (int)TextureImporterFormat.ASTC_6x6
+};
+
+// ✅ CORRECT - Direct enum assignment
+var settings = new TextureImporterPlatformSettings {
+    format = TextureImporterFormat.ASTC_6x6
+};
+```
+
+### ❌ SetMasterAtlasPath() - Method Does Not Exist
+
+```csharp
+// ❌ WRONG - Method doesn't exist
+variant.SetMasterAtlasPath(path);
+
+// ✅ CORRECT - Load runtime SpriteAtlas and pass to SetMasterAtlas()
+SpriteAtlas masterRuntime = AssetDatabase.LoadAssetAtPath<SpriteAtlas>(masterPath);
+variant.SetMasterAtlas(masterRuntime);
+```
+
+### ⚠ Platform-Specific Format Limitations
+
+- **PVRTC is NOT supported** in SpriteAtlas V2
+- Use **ASTC** for Android (`ASTC_6x6`, `ASTC_4x4`)
+- Use **ASTC or ETC2** for iOS (`ASTC_4x4`, `ETC2_RGBA8`)
+- Use **ETC2** for desktop (`ETC2_RGBA8`)
+
+### ⚠ PackAtlases() Requires Runtime SpriteAtlas[]
+
+```csharp
+// ❌ WRONG - Passing SpriteAtlasAsset[] causes compilation error
+SpriteAtlasUtility.PackAtlases(atlasAssets, ...);
+
+// ✅ CORRECT - Load runtime SpriteAtlases first
+SpriteAtlas[] atlases = AssetDatabase.FindAssets("t:SpriteAtlas", new[] { "Assets" })
+    .Select(g => AssetDatabase.LoadAssetAtPath<SpriteAtlas>(AssetDatabase.GUIDToAssetPath(g)))
+    .Where(a => a != null)
+    .ToArray();
+SpriteAtlasUtility.PackAtlases(atlases, EditorUserBuildSettings.activeBuildTarget, false);
+```
+
+### ⚠ Always scope AssetDatabase.FindAssets to the folders you mean
+
+```csharp
+// ❌ WRONG - does not compile. There is no SearchMode overload.
+string[] guids = AssetDatabase.FindAssets("t:SpriteAtlas", SearchMode.AllAssets);
+
+// ❌ RISKY - compiles, but searches the WHOLE project including read-only packages
+string[] guids = AssetDatabase.FindAssets("t:SpriteAtlas");
+
+// ✅ CORRECT - the second parameter is string[] searchInFolders
+string[] guids = AssetDatabase.FindAssets("t:SpriteAtlas", new[] { "Assets" });
+```
+
+`AssetDatabase.FindAssets` has exactly two overloads, `FindAssets(string filter)` and
+`FindAssets(string filter, string[] searchInFolders)`. Verified on Unity 6000.5.8f1.
+
+Scoping matters because an unscoped search reaches into `Packages/`, and those assets are usually
+read-only. Measured on a real project: an unscoped `t:Scene` search returned 20 scenes where the
+project itself has 1, and all 19 extras were package test fixtures. A batch operation that then
+writes to what it found will fail, or worse, target assets it must not modify.
+
+### ⚠ AssetImporter.GetAtPath() Takes Single Argument
+
+```csharp
+// ❌ WRONG - No such overload
+SpriteAtlasImporter importer = AssetImporter.GetAtPath(path, typeof(SpriteAtlasImporter));
+
+// ✅ CORRECT - Single argument, cast result
+SpriteAtlasImporter importer = AssetImporter.GetAtPath(path) as SpriteAtlasImporter;
+```