com.wallstop-studios.unity-helpers 2.0.0-rc81.9 → 2.0.1

package/Docs/UTILITY_COMPONENTS.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: ac9f163079562e14dbaaf3910614449c
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Docs/VISUAL_COMPONENTS.md

@@ -0,0 +1,337 @@
+# Visual Components Guide
+
+## TL;DR — Why Use These
+
+- **AnimatedSpriteLayer**: Data structure for packaging sprite animation frames with per-frame offsets and transparency
+- **LayeredImage**: UI Toolkit element that composites multiple sprite animation layers into a single animated image
+- **EnhancedImage**: Extended Unity UI Image with HDR color support and shape masking
+
+These components solve the problem of creating complex, multi-layer sprite animations without pre-rendering every combination into massive sprite sheets.
+
+---
+
+## AnimatedSpriteLayer
+
+**What it is:** An immutable data structure (struct) that packages a sprite animation sequence with per-frame position offsets and layer-wide alpha transparency.
+
+**Why it exists:** When building complex sprite animations (like a character with equipment, effects, or layered body parts), you need a standardized way to represent each layer with its timing, positioning, and transparency. This struct is the building block for the LayeredImage composition system.
+
+**Problem it solves:**
+
+- Eliminates manually syncing sprite frames, offsets, and alpha values across multiple systems
+- Provides type-safe storage for animation layer data
+- Automatically converts world-space offsets to pixel-space for rendering
+- Validates texture readability at construction time (catches import setting errors early)
+
+### When to Use
+
+✅ **Use when:**
+
+- Building `LayeredImage` compositions
+- Creating character animations with separate layers for body parts
+- Combining sprite effects (glow, shadow, outline) with base sprites
+- You need frame-by-frame position adjustments (bobbing, recoil, etc.)
+- Working with sprite-based animations that need dynamic layering
+
+❌ **Don't use when:**
+
+- You only have a single sprite sequence (just use `Animator`)
+- Sprites don't need per-frame offsets (just use sprite arrays)
+- You're working with UI Toolkit animations (use USS transitions)
+- Performance is critical and you can pre-render combinations
+
+### Basic Usage
+
+```csharp
+using WallstopStudios.UnityHelpers.Visuals;
+using UnityEngine;
+
+// Create a layer from sprite sequence
+Sprite[] walkCycleFrames = LoadWalkCycleSprites(); // Must have Read/Write enabled!
+
+// Optional: per-frame offsets in world space (e.g., for bobbing motion)
+Vector2[] walkBobOffsets = new[]
+{
+    new Vector2(0, 0.1f),   // Frame 0: slight up
+    new Vector2(0, 0),      // Frame 1: neutral
+    new Vector2(0, 0.1f),   // Frame 2: slight up
+    new Vector2(0, 0)       // Frame 3: neutral
+};
+
+AnimatedSpriteLayer bodyLayer = new AnimatedSpriteLayer(
+    sprites: walkCycleFrames,
+    worldSpaceOffsets: walkBobOffsets,
+    alpha: 1f  // Fully opaque
+);
+
+// Create equipment layer (same frame count, different sprites)
+Sprite[] helmetFrames = LoadHelmetSprites();
+AnimatedSpriteLayer helmetLayer = new AnimatedSpriteLayer(
+    sprites: helmetFrames,
+    worldSpaceOffsets: null, // No offsets
+    alpha: 0.9f  // Slightly transparent
+);
+
+// Combine in LayeredImage (see below)
+```
+
+### Editor-Only: Creating from AnimationClip
+
+In editor code, you can create layers directly from AnimationClips:
+
+```csharp
+#if UNITY_EDITOR
+using UnityEditor;
+
+AnimationClip walkClip = AssetDatabase.LoadAssetAtPath<AnimationClip>("Assets/Animations/Walk.anim");
+AnimatedSpriteLayer layer = new AnimatedSpriteLayer(
+    clip: walkClip,
+    worldSpaceOffsets: null,
+    alpha: 1f
+);
+#endif
+```
+
+### Important Notes
+
+**Texture Readability:**
+All sprites must have **Read/Write Enabled** in their texture import settings. The constructor validates this and logs errors for non-readable textures.
+
+To fix:
+
+1. Select the texture asset
+2. In Inspector, check "Read/Write Enabled"
+3. Click Apply
+
+**Frame Rate:**
+Default frame rate is 12 fps (stored in `AnimatedSpriteLayer.FrameRate` constant). This matches classic sprite animation timing.
+
+**Offset Conversion:**
+World-space offsets are automatically converted to pixel-space using sprite pixels-per-unit. This ensures offsets scale correctly with sprite resolution.
+
+---
+
+## LayeredImage
+
+**What it is:** A UI Toolkit `VisualElement` that composites multiple `AnimatedSpriteLayer` instances into a single animated image with alpha blending, automatic cropping, and frame timing.
+
+**Why it exists:** Creating character customization systems (body + equipment), visual effects (base + glow), or any multi-layer sprite animation traditionally requires pre-rendering every combination into massive sprite sheets. LayeredImage composes layers dynamically at runtime.
+
+**Problem it solves:**
+
+- **Sprite sheet explosion**: Instead of 10 bodies × 20 helmets × 15 armors = 3,000 pre-rendered sprites, you have 10 + 20 + 15 = 45 source sprites
+- **Memory efficiency**: Only active layers are loaded, not every possible combination
+- **Runtime flexibility**: Change equipment/effects without new assets
+- **Automatic composition**: Handles alpha blending, pivot alignment, and cropping
+
+### When to Use
+
+✅ **Use when:**
+
+- Character customization systems (swap equipment, clothing, accessories)
+- Visual effects that layer over base sprites (shields, auras, damage flashes)
+- Procedural sprite generation from components
+- UI that needs animated, multi-layer sprites
+- You want to avoid combinatorial explosion of pre-rendered sprites
+
+❌ **Don't use when:**
+
+- Single-layer animations (use Unity's `Image` or `Animator`)
+- 3D models (use skinned mesh renderers)
+- Performance is absolutely critical and you can afford pre-rendered sheets
+- Sprites don't share the same frame count/timing
+- Working in UGUI (use `EnhancedImage` for UGUI, though it doesn't support layering)
+
+### Basic Usage
+
+```csharp
+using WallstopStudios.UnityHelpers.Visuals.UIToolkit;
+using UnityEngine.UIElements;
+
+// Create layers (see AnimatedSpriteLayer section above)
+AnimatedSpriteLayer[] layers = new[]
+{
+    bodyLayer,    // Base character
+    armorLayer,   // Equipment layer 1
+    helmetLayer,  // Equipment layer 2
+    glowLayer     // Effect layer
+};
+
+// Create LayeredImage
+LayeredImage characterImage = new LayeredImage(
+    inputSpriteLayers: layers,
+    backgroundColor: null,  // Transparent background (or use Color for solid background)
+    fps: 12f,               // Animation speed
+    updatesSelf: true,      // Automatically advances frames (uses Unity editor ticks or coroutines)
+    pixelCutoff: 0.01f      // Alpha threshold for cropping transparent pixels
+);
+
+// Add to UI Toolkit hierarchy
+rootVisualElement.Add(characterImage);
+```
+
+### Manual Frame Control
+
+If you need precise control over frame advancement:
+
+```csharp
+LayeredImage manualImage = new LayeredImage(
+    inputSpriteLayers: layers,
+    backgroundColor: null,
+    fps: 12f,
+    updatesSelf: false,  // Disable automatic updates
+    pixelCutoff: 0.01f
+);
+
+// In your update loop
+void Update()
+{
+    manualImage.Update(force: false); // Advances frame based on elapsed time
+}
+
+// Or force immediate frame advance
+manualImage.Update(force: true);
+```
+
+### Changing Animation Speed
+
+```csharp
+// Set frames per second at runtime
+characterImage.Fps = 24f; // Speed up animation
+characterImage.Fps = 6f;  // Slow down animation
+```
+
+### How Compositing Works
+
+LayeredImage performs these steps each frame:
+
+1. **Allocates canvas**: Creates a texture large enough to hold all layers with their offsets
+2. **Alpha blending**: Layers are composited back-to-front with alpha blending
+3. **Pivot alignment**: Each sprite's pivot point is respected during positioning
+4. **Offset application**: Per-frame pixel offsets are applied
+5. **Cropping**: Transparent borders are trimmed (configurable via `pixelCutoff`)
+6. **Rendering**: Final composited texture is displayed
+
+**Performance optimization:**
+
+- Uses parallel processing for large sprites (2048+ pixels total)
+- Employs array pooling to minimize GC allocations
+- Caches composited frames when possible
+
+### Pixel Cutoff Parameter
+
+Controls how aggressive transparent pixel cropping is:
+
+```csharp
+// More aggressive cropping (removes near-transparent pixels)
+layeredImage.pixelCutoff = 0.05f;
+
+// Less aggressive (keeps more semi-transparent pixels)
+layeredImage.pixelCutoff = 0.001f;
+
+// No cropping (includes fully transparent border)
+layeredImage.pixelCutoff = 0f;
+```
+
+Higher values = smaller final image, but may clip soft edges (glows, shadows).
+
+### Important Notes
+
+**Frame Synchronization:**
+All layers must have the same number of frames. Mixing 4-frame and 8-frame animations will cause visual glitches.
+
+**Performance Considerations:**
+
+- Compositing happens every frame for animated images
+- Large sprite resolutions (1024×1024+) will impact performance
+- Consider pre-rendering if targeting low-end devices
+- Parallel processing threshold is 2048 pixels (width × height)
+
+**Editor vs Runtime:**
+
+- In Editor: Uses Unity's editor update ticks for animation
+- In Runtime: Uses coroutines for frame timing
+- Both honor `updatesSelf` setting
+
+---
+
+## EnhancedImage (UGUI)
+
+**What it is:** An extended version of Unity's UI `Image` component with HDR color support and texture-based shape masking.
+
+**Why it exists:** Unity's standard `Image` component doesn't support:
+
+- HDR colors (for bloom/glow effects)
+- Complex shape masks (beyond sprite masks)
+- Shader-based shape rendering
+
+**See full documentation:** [Editor Tools Guide - EnhancedImage](EDITOR_TOOLS_GUIDE.md#enhancedimage-editor)
+
+**Quick example:**
+
+```csharp
+using WallstopStudios.UnityHelpers.Visuals.UGUI;
+
+EnhancedImage image = GetComponent<EnhancedImage>();
+
+// HDR color for bloom
+image.HdrColor = new Color(2f, 0.5f, 0.1f, 1f); // RGB values > 1 for bloom
+
+// Shape mask
+image.shapeMask = myMaskTexture; // Black areas are transparent
+```
+
+---
+
+## Best Practices
+
+### AnimatedSpriteLayer
+
+- **Always enable Read/Write** on source textures (build will fail otherwise)
+- **Keep frame counts consistent** across layers for the same animation
+- **Use world-space offsets** for consistent motion across different sprite resolutions
+- **Cache layer instances** when using the same animation repeatedly (they're immutable)
+
+### LayeredImage
+
+- **Layer order matters**: Layers are rendered front-to-back in array order
+- **Optimize sprite sizes**: Trim transparent borders before importing (use Sprite Editor's "Tight" mode)
+- **Profile on target hardware**: Mobile devices may struggle with 512×512+ composites at 60fps
+- **Use manual updates** when syncing with non-UI systems (like gameplay state)
+- **Pre-render** if combinations are limited and performance is critical
+
+### EnhancedImage
+
+- **Don't mix with Image**: EnhancedImage replaces Unity's Image, don't use both
+- **Material cleanup** is automatic but test in edit mode transitions
+- **HDR requires post-processing**: Ensure Bloom is enabled in your camera's post-processing
+
+---
+
+## Related Documentation
+
+- [Editor Tools Guide](EDITOR_TOOLS_GUIDE.md) - EnhancedImage editor integration
+- [Samples](Samples~/) - Example projects for each component
+- [Math & Extensions](MATH_AND_EXTENSIONS.md) - Color utilities used internally
+
+---
+
+## FAQ
+
+**Q: Can I mix different frame counts in LayeredImage?**
+A: No, all layers must have the same frame count. Pad shorter animations with duplicate frames if needed.
+
+**Q: Why are my layers not aligned correctly?**
+A: Check that sprite pivots are set correctly (usually center). LayeredImage respects sprite pivot points.
+
+**Q: Can I change layers at runtime?**
+A: Currently no, LayeredImage is immutable after construction. Create a new instance with updated layers.
+
+**Q: Performance impact vs pre-rendered sprites?**
+A: Compositing costs ~1-3ms per image on modern hardware. Pre-rendered is faster but uses more memory/storage.
+
+**Q: Does this work with Unity's Animator?**
+A: No, LayeredImage is independent. It's designed for UI Toolkit programmatic control.
+
+**Q: Can I export the composited result?**
+A: Not directly, but you could capture the rendered texture using `Texture2D.ReadPixels` in a render texture setup.

package/Docs/VISUAL_COMPONENTS.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: a5cbb14084a437b44a2dbf6d21d895f2
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: