com.amanotes.magictilescore 0.4.2

package/Docs/RhythmCore-Customize-Guide.md

@@ -0,0 +1,391 @@
+# Custom Game Implementation Guide
+
+**Package:** `com.amanotes.magictilescore`  
+**Version:** 0.4.0
+
+---
+
+# PART 1: Quick Start
+
+Create a rhythm game with **3 classes**:
+
+```
+YourGame/
+├── YourGameConfig.cs    # Game settings
+├── YourGame.cs          # Game controller
+└── YourTile.cs          # Tile visual + input
+```
+
+---
+
+## Step 1: Game Config
+
+`YourGameConfig.cs`
+
+```csharp
+using Amanotes.MagicTilesCore;
+using UnityEngine;
+
+[CreateAssetMenu(menuName = "YourGame/Config")]
+public class YourGameConfig : RhythmConfig
+{
+    // Add custom settings here if needed
+}
+```
+
+`RhythmConfig` provides everything you need.
+
+---
+
+## Step 2: Game Controller
+
+`YourGame.cs`
+
+```csharp
+using Amanotes.MagicTilesCore;
+
+public class YourGame : RhythmGame
+{
+    // Framework handles everything
+}
+```
+
+---
+
+## Step 3: Tile Visual + Input
+
+`YourTile.cs`
+
+```csharp
+using Amanotes.MagicTilesCore;
+using UnityEngine;
+
+public class YourTile : RhythmTile
+{
+    [SerializeField] private TouchInput touchInput;
+    [SerializeField] private SpriteRenderer sprite;
+    
+    public override void OnAttach()
+    {
+        // Position tile (framework handles 2D/3D automatically)
+        var (pos, rot) = context.GetWarped(
+            tileContext.note.time,
+            tileContext.note.lane
+        );
+        transform.localPosition = pos;
+        transform.localRotation = rot;
+        
+        // Setup input
+        touchInput.onTouchDown += OnTouched;
+        sprite.color = Color.white;
+    }
+    
+    public override void OnDetach()
+    {
+        touchInput.onTouchDown -= OnTouched;
+    }
+    
+    private void OnTouched()
+    {
+        if (tileContext.Status != TileStatus.None) return;
+        
+        tileContext.Status = TileStatus.Touching;
+        sprite.color = Color.green;
+    }
+}
+```
+
+**Key Concept:** `context.GetWarped()` positions tiles for both 2D and 3D games!
+
+---
+
+### Step 4: Unity Setup
+
+#### 4.1: Create Assets
+
+**Create Config:**
+- Right-click → Create → YourGame/Config
+- Set: Visual Speed: `5.0`, N Lanes: `4`
+- Tile Pool Group → Add Entry:
+  - ID: `"Tile"`
+  - Prefab: (your tile prefab)
+  - Pool Size: `20`
+
+**Create Context:**
+- Right-click → Create → Rhythm/Context
+- Assign: Config (your config asset), Song Notes (your song data)
+
+#### 4.2: Scene Setup
+
+**Hierarchy:**
+```
+YourGameScene
+├── YourGame (GameObject)
+├── MainCamera
+└── Canvas
+```
+
+**YourGame GameObject:**
+- Add `YourGame.cs` component
+- Add `PrefabPool` component
+- Create child: Empty Transform named "TileParent"
+- Assign: Context, Pool, Tile Parent
+
+#### 4.3: Create Tile Prefab
+
+- Create GameObject with: `YourTile.cs`, `TouchInput`, `SpriteRenderer`
+- Save as prefab
+- Assign to Config's Tile Pool Group
+
+---
+
+## ✅ Done!
+
+Press Play! Working rhythm game.
+
+**What happens:**
+- Tiles spawn automatically
+- Player touches → tile turns green
+- Framework handles timing, pooling, lifecycle
+
+---
+
+# PART 2: Understanding & Customizing
+
+## What You Inherited
+
+**RhythmConfig Provides:**
+
+```csharp
+// Timing
+float visualSpeed;         // Tile movement speed
+float mp3Offset;           // Audio sync
+float gameDepartTime;      // Start delay
+
+// Layout
+int nLanes;                // Number of lanes
+float laneW;               // Lane width
+float zUnitDistance;       // Distance per second
+
+// Pooling
+PoolGroup tilePoolGroup;   // Tile pool settings
+PoolGroup vfxPoolGroup;    // VFX pool settings
+
+// Behavior
+bool isAutoRewind;         // Auto-rewind on death
+```
+
+**RhythmGame Provides:**
+
+```csharp
+// Components
+public RhythmContext context;
+public PrefabPool pool;
+public Transform tileParent;
+
+// Override if needed
+virtual RhythmMatch CreateMatchData();
+virtual RhythmTile CreateRhythmTile(SongNote note);
+virtual void HandleMissedTile(TileContext tile);
+virtual float GetMissedThreshold();
+```
+
+**RhythmTile Provides:**
+
+```csharp
+// Properties (set when OnAttach called)
+public RhythmContext context;
+public TileContext tileContext;
+
+// Override methods
+public abstract void OnAttach();     // Tile spawns
+public virtual void OnDetach();      // Tile despawns
+public virtual void RefreshTileStatus();  // Status changes
+```
+
+**TileContext Has:**
+
+```csharp
+readonly SongNote note;          // time, lane, type
+readonly List<VisualKnot> knots; // Cached warped positions/rotations
+                                 // Roughly matches note.time + note.controls[i].time
+TileStatus Status;               // None, Touching, End, Missed
+float accuracy;                  // 0-1 hit accuracy
+float FillingProgress;           // 0-1 for long tiles
+```
+
+---
+
+## Custom Tile Feedback
+
+```csharp
+// YourTile.cs
+public override void RefreshTileStatus()
+{
+    switch (tileContext.Status)
+    {
+        case TileStatus.None:
+            sprite.color = Color.white;
+            break;
+        case TileStatus.Touching:
+            sprite.color = Color.green;
+            break;
+        case TileStatus.End:
+            sprite.color = Color.blue;
+            break;
+        case TileStatus.Missed:
+            sprite.color = Color.red;
+            break;
+    }
+}
+```
+
+---
+
+## Custom Scoring Logic
+
+```csharp
+using Amanotes.MagicTilesCore;
+
+public class YourMatchData : RhythmMatch
+{
+    public int combo;
+    public int perfectCount;
+    
+    public override RhythmMatch Init(RhythmContext context)
+    {
+        base.Init(context);
+        combo = 0;
+        perfectCount = 0;
+        return this;
+    }
+    
+    public override void CalculateScore(TileContext tile)
+    {
+        if (tile.accuracy >= 0.9f)  // Perfect!
+        {
+            perfectCount++;
+            combo++;
+            AddScore(100 * combo);
+        }
+        else
+        {
+            combo = 0;
+        }
+    }
+}
+```
+
+**Use in game:**
+
+```csharp
+public override RhythmMatch CreateMatchData()
+{
+    return new YourMatchData().Init(context);
+}
+```
+
+---
+
+## Implement Long Tiles (Hold/Slide)
+
+```csharp
+public class YourLongTile : RhythmTile, ITileProgress
+{
+    [SerializeField] private HoldInput holdInput;
+    [SerializeField] private Transform progressBar;
+    
+    public override void OnAttach()
+    {
+        var (pos, rot) = context.GetWarped(
+            tileContext.note.time,
+            tileContext.note.lane
+        );
+        transform.localPosition = pos;
+        transform.localRotation = rot;
+        
+        holdInput.onHoldStart += () => 
+        {
+            tileContext.Status = TileStatus.Touching;
+        };
+        
+        holdInput.onHoldEnd += () => 
+        {
+            tileContext.Status = TileStatus.End;
+        };
+    }
+    
+    public void RefreshTileProgress()
+    {
+        // Called automatically during hold
+        float progress = tileContext.FillingProgress;
+        progressBar.localScale = new Vector3(1f, progress, 1f);
+    }
+}
+```
+
+---
+
+## Game Flow
+
+**How It Works:**
+
+```
+1. Framework spawns tile → OnAttach() called
+2. Player touches → Status = Touching
+3. Framework detects status change → RefreshTileStatus() called
+4. Tile despawns → OnDetach() called
+5. Tile returned to pool
+```
+
+**Lifecycle:**
+
+```
+Awake() → Init() → Prepare() → StartGame() → [Playing] → EndGame()
+```
+
+**Game States:**
+
+```csharp
+GAME_NONE          // Not initialized
+GAME_INITED        // Ready
+GAME_PREPARE       // Loading
+GAME_PLAY          // Playing
+GAME_PAUSE         // Paused
+GAME_DIE           // Failed
+GAME_END           // Finished
+```
+
+**Add callbacks:**
+
+```csharp
+protected override void SetupStateCallbacks()
+{
+    base.SetupStateCallbacks();
+    
+    context.stateMachine.SetStateCallbacks(GAME_START,
+        onEnter: () => Debug.Log("Started!"),
+        onExit: null
+    );
+}
+```
+
+---
+
+## Critical APIs
+
+**Tile Positioning:**
+
+```csharp
+// ALWAYS use this!
+var (pos, rot) = context.GetWarped(time, lane);
+transform.localPosition = pos;
+transform.localRotation = rot;
+```
+
+Handles both 2D linear and 3D curved paths automatically.
+
+---
+
+**Last Updated:** 2026-01-23  
+**Source:** MagicTilesCore v0.4.0

package/Docs/RhythmCore-Customize-Guide.md.meta

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