com.amanotes.magictilescore 0.4.2

package/Docs/Input-System-Guide.md

@@ -0,0 +1,419 @@
+# Input System Guide
+
+## 🎯 System Overview
+
+The RhythmEngine Input System provides **unified input handling** for rhythm game tiles with support for touch, hold, and swipe gestures. It features automatic input handler detection, world position calculation, and direction-based gesture recognition.
+
+## 🏗️ Core Architecture
+
+### Input Data Structure
+```csharp
+public readonly struct InputData
+{
+    public readonly InputPhase phase;      // Start, Progress, End, Miss
+    public readonly Vector3 worldPosition; // 3D world coordinates
+    public readonly Vector3 deltaPosition; // Movement delta
+    public readonly byte direction;        // 8-directional (0-7)
+}
+```
+
+### Input Phases
+```csharp
+public enum InputPhase : byte 
+{ 
+    None,      // No input
+    Start,     // Input began (touch down)
+    Progress,  // Input continuing (drag/hold)
+    End,       // Input finished (touch up)
+    Miss       // Input validation failed
+}
+```
+
+## 🎮 Input Components
+
+### BaseTileInput (Abstract Base)
+```csharp
+public abstract class BaseTileInput : MonoBehaviour
+```
+**Features:**
+- **Automatic handler detection** - Finds `IInputHandler` components
+- **Collider validation** - Ensures input hits correct target
+- **World position calculation** - Converts screen to 3D coordinates
+- **Performance optimized** - Aggressive inlining for hot paths
+
+**Key Methods:**
+```csharp
+protected bool ValidateInput(PointerEventData eventData)    // Collision validation
+protected Vector3 GetWorldPos(PointerEventData eventData)   // Screen to world conversion
+public void SetTargetCollider(Collider collider)           // Runtime collider assignment
+```
+
+### TouchInput (Instant Tap)
+```csharp
+public sealed class TouchInput : BaseTileInput, IPointerDownHandler
+```
+**Usage:** Short tiles, instant actions, tap-to-hit mechanics
+
+**Behavior:**
+- Triggers on `OnPointerDown` only
+- Calls both `OnInputBegin` and `OnInputEnd` immediately
+- Perfect for short tiles that don't require hold duration
+
+**Example:**
+```csharp
+public class ShortTile : MonoBehaviour, IInputHandler
+{
+    public void OnInputBegin(InputData inputData)
+    {
+        // Handle tap start
+        Debug.Log($"Tile tapped at {inputData.worldPosition}");
+    }
+    
+    public void OnInputUpdate(InputData inputData) { /* Not called for TouchInput */ }
+    
+    public void OnInputEnd(InputData inputData)
+    {
+        // Handle tap completion
+        MarkTileComplete();
+    }
+}
+```
+
+### HoldInput (Continuous Press)
+```csharp
+public sealed class HoldInput : BaseTileInput, IPointerDownHandler, IPointerUpHandler, IPointerMoveHandler
+```
+**Usage:** Long tiles, hold mechanics, progress tracking
+
+**Behavior:**
+- `OnPointerDown` → `OnInputBegin` + starts hold coroutine
+- Continuous `OnInputUpdate` calls during hold
+- `OnPointerMove` → Updates world position
+- `OnPointerUp` → `OnInputEnd` + stops hold coroutine
+
+**Features:**
+- **Pointer ID tracking** - Handles multi-touch correctly
+- **World position updates** - Tracks finger movement in 3D space
+- **Hold validation** - Prevents multiple simultaneous holds
+- **Debug visualization** - Optional world position visualizer
+
+**Example:**
+```csharp
+public class LongTile : MonoBehaviour, IInputHandler, ITileProgress
+{
+    private float holdStartTime;
+    private bool isHolding;
+    
+    public void OnInputBegin(InputData inputData)
+    {
+        holdStartTime = Time.time;
+        isHolding = true;
+        Debug.Log("Hold started");
+    }
+    
+    public void OnInputUpdate(InputData inputData)
+    {
+        if (!isHolding) return;
+        
+        float holdDuration = Time.time - holdStartTime;
+        float progress = holdDuration / requiredHoldTime;
+        UpdateProgress(Mathf.Clamp01(progress));
+    }
+    
+    public void OnInputEnd(InputData inputData)
+    {
+        isHolding = false;
+        Debug.Log("Hold ended");
+    }
+}
+```
+
+### SwipeInput (Directional Gestures)
+```csharp
+public sealed class SwipeInput : BaseTileInput, IPointerDownHandler, IPointerUpHandler, IPointerMoveHandler
+```
+**Usage:** Swipe tiles, directional mechanics, gesture recognition
+
+**Behavior:**
+- Tracks swipe direction using `DirectionUtil`
+- Calculates delta movement and direction
+- Validates minimum swipe distance
+- Supports 8-directional recognition (N, NE, E, SE, S, SW, W, NW)
+
+**Configuration:**
+```csharp
+[SerializeField] private float minSwipeDistance = 0.5f;    // Minimum distance for valid swipe
+[SerializeField] private float swipeTimeLimit = 2f;       // Maximum time for swipe completion
+```
+
+**Example:**
+```csharp
+public class SwipeTile : MonoBehaviour, IInputHandler
+{
+    [SerializeField] private SwipeDirection requiredDirection;
+    
+    public void OnInputBegin(InputData inputData)
+    {
+        // Swipe started
+        ShowSwipeIndicator();
+    }
+    
+    public void OnInputUpdate(InputData inputData)
+    {
+        // Track swipe progress
+        if (inputData.HasDelta())
+        {
+            UpdateSwipeVisualization(inputData.deltaPosition);
+        }
+    }
+    
+    public void OnInputEnd(InputData inputData)
+    {
+        // Validate swipe direction
+        if (inputData.IsValidDirection())
+        {
+            var swipedDirection = (SwipeDirection)inputData.direction;
+            if (swipedDirection == requiredDirection)
+            {
+                CompleteSwipe();
+            }
+            else
+            {
+                FailSwipe();
+            }
+        }
+    }
+}
+```
+
+## 🧭 Direction System
+
+### DirectionUtil (8-Directional Recognition)
+```csharp
+public static class DirectionUtil
+```
+**Features:**
+- **8-direction mapping** - N(0), NE(1), E(2), SE(3), S(4), SW(5), W(6), NW(7)
+- **Angle-based calculation** - Converts Vector3 delta to direction byte
+- **Name mapping** - Human-readable direction names
+
+**Usage:**
+```csharp
+Vector3 swipeDelta = endPos - startPos;
+byte direction = DirectionUtil.GetDirection(swipeDelta);
+string dirName = DirectionUtil.GetDirectionName(direction);
+
+// Example: swipeDelta = (1, 0, 1) → direction = 1 (NE) → dirName = "NorthEast"
+```
+
+**Direction Mapping:**
+```
+     N(0)
+NW(7) ↑ NE(1)
+W(6)← + →E(2)
+SW(5) ↓ SE(3)
+     S(4)
+```
+
+## 🔌 Integration Patterns
+
+### IInputHandler Interface
+```csharp
+public interface IInputHandler
+{
+    void OnInputBegin(InputData inputData);   // Input started
+    void OnInputUpdate(InputData inputData);  // Input progressing (hold/swipe only)
+    void OnInputEnd(InputData inputData);     // Input completed
+}
+```
+
+### Automatic Handler Detection
+```csharp
+// BaseTileInput automatically finds IInputHandler on the same GameObject
+private void FindInputHandler()
+{
+    var handlers = GetComponents<MonoBehaviour>();
+    for (int i = 0; i < handlers.Length; i++)
+    {
+        if (handlers[i] is IInputHandler)
+        {
+            handler = handlers[i];
+            break;
+        }
+    }
+}
+```
+
+### Manual Handler Assignment
+```csharp
+// Override automatic detection
+touchInput.handler = customInputHandler;
+```
+
+## 🎵 Rhythm Game Integration
+
+### Tile Setup Pattern
+```csharp
+public class MyTile : RhythmTile, IInputHandler
+{
+    [SerializeField] private TouchInput touchInput;
+    [SerializeField] private HoldInput holdInput;
+    [SerializeField] private SwipeInput swipeInput;
+    
+    public void OnAttach(TileContext tile)
+    {
+        // Configure input based on tile type
+        switch (tile.note.type)
+        {
+            case "short":
+                touchInput.enabled = true;
+                holdInput.enabled = false;
+                swipeInput.enabled = false;
+                break;
+                
+            case "long":
+                touchInput.enabled = false;
+                holdInput.enabled = true;
+                swipeInput.enabled = false;
+                break;
+                
+            case "swipe":
+                touchInput.enabled = false;
+                holdInput.enabled = false;
+                swipeInput.enabled = true;
+                break;
+        }
+        
+        // Set target collider for all inputs
+        var collider = GetComponent<Collider>();
+        touchInput.SetTargetCollider(collider);
+        holdInput.SetTargetCollider(collider);
+        swipeInput.SetTargetCollider(collider);
+    }
+    
+    public void OnInputBegin(InputData inputData)
+    {
+        // Unified input handling
+        context.BeginTileTouch(tileContext.index);
+        
+        // Log input for debugging
+        RhythmContext.LogInput($"Tile {tileContext.index} input began at {inputData.worldPosition}");
+    }
+    
+    public void OnInputUpdate(InputData inputData)
+    {
+        // Handle continuous input (hold/swipe)
+        if (tileContext.Status == TileStatus.Touching)
+        {
+            UpdateTileProgress(inputData);
+        }
+    }
+    
+    public void OnInputEnd(InputData inputData)
+    {
+        // Complete tile interaction
+        if (tileContext.Status == TileStatus.Touching)
+        {
+            context.EndTileTouch(tileContext.index);
+        }
+    }
+}
+```
+
+### Multi-Input Tiles
+```csharp
+public class HybridTile : MonoBehaviour, IInputHandler
+{
+    [SerializeField] private TouchInput quickTap;
+    [SerializeField] private HoldInput longHold;
+    
+    private float inputStartTime;
+    private bool isQuickTap;
+    
+    public void OnInputBegin(InputData inputData)
+    {
+        inputStartTime = Time.time;
+        isQuickTap = false;
+        
+        // Start timer to determine input type
+        StartCoroutine(DetermineInputType());
+    }
+    
+    public void OnInputUpdate(InputData inputData)
+    {
+        // This is definitely a hold
+        isQuickTap = false;
+        HandleHoldProgress(inputData);
+    }
+    
+    public void OnInputEnd(InputData inputData)
+    {
+        float inputDuration = Time.time - inputStartTime;
+        
+        if (inputDuration < 0.2f && isQuickTap)
+        {
+            HandleQuickTap();
+        }
+        else
+        {
+            HandleHoldComplete();
+        }
+    }
+    
+    private IEnumerator DetermineInputType()
+    {
+        yield return new WaitForSeconds(0.1f);
+        isQuickTap = true; // If we reach here without OnInputUpdate, it's a quick tap
+    }
+}
+```
+
+## 🚀 Performance Optimization
+
+### Aggressive Inlining
+```csharp
+[MethodImpl(MethodImplOptions.AggressiveInlining)]
+protected bool ValidateInput(PointerEventData eventData)
+{
+    var hitGO = eventData?.pointerEnter?.gameObject;
+    if (hitGO == null) return false;
+    return hitGO == targetCollider.gameObject || hitGO == gameObject;
+}
+```
+
+### Efficient Direction Calculation
+```csharp
+// DirectionUtil uses optimized angle calculation
+public static byte GetDirection(Vector3 delta)
+{
+    if (delta.sqrMagnitude < 0.001f) return 255; // Invalid
+    
+    float angle = Mathf.Atan2(delta.z, delta.x) * Mathf.Rad2Deg;
+    if (angle < 0) angle += 360f;
+    
+    return (byte)Mathf.RoundToInt(angle / 45f) % 8;
+}
+```
+
+### Memory-Efficient InputData
+```csharp
+// InputData is a readonly struct - no heap allocations
+public readonly struct InputData
+{
+    // All fields are readonly and value types
+    // Passed by value, no GC pressure
+}
+```
+
+## 🎯 Key Benefits
+
+1. **Unified Interface**: Single `IInputHandler` for all input types
+2. **Automatic Detection**: No manual wiring required
+3. **Performance Optimized**: Aggressive inlining and struct-based data
+4. **Multi-Touch Safe**: Proper pointer ID tracking
+5. **Direction Aware**: Built-in 8-directional gesture recognition
+6. **Rhythm Game Ready**: Designed for tile-based gameplay
+7. **Extensible**: Easy to add new input types
+8. **Debug Friendly**: Built-in logging and visualization support
+
+The Input System provides a **solid foundation** for rhythm game interactions while maintaining **high performance** and **ease of use**.

package/Docs/Input-System-Guide.md.meta

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