com.amanotes.magictilescore 0.4.2

package/Docs/Knot-System-Guide.md

@@ -0,0 +1,309 @@
+# Knot System Guide
+
+## Overview
+
+The **Knot System** provides efficient time-based lookup and interpolation by caching expensive calculations once. Used internally by MetaLogic, VisualSpeedMeta, and VisualKnotLogic.
+
+**Key Concept**: Knot = Cached control point at a specific time
+
+## Core Classes
+
+### TimeKnot
+
+```csharp
+// From: ListTimeKnots.cs
+public abstract class TimeKnot
+{
+    public int knotIdx;   // Index in sorted list
+    public float time;    // Time in seconds
+}
+```
+
+### ListTimeKnots<T>
+
+```csharp
+// From: ListTimeKnots.cs
+public class ListTimeKnots<T> where T : TimeKnot
+{
+    public readonly List<T> _knots = new();
+    
+    public (T prevKnot, T nextKnot, float percent) InterpolateKnot(float time)
+    {
+        int idx = _knots.Count > 32 ? BinarySearch(time) : LinearSearch(time);
+        // Returns: previous knot, next knot, interpolation percent (0-1)
+    }
+    
+    protected void Sort()
+    {
+        _knots.Sort((a, b) => a.time.CompareTo(b.time));
+        for (int i = 0; i < _knots.Count; i++)
+        {
+            _knots[i].knotIdx = i;
+        }
+    }
+}
+```
+
+**Performance**:
+- ≤32 knots: Linear search O(n)
+- \>32 knots: Binary search O(log n)
+
+## MetaInfo (Meta System)
+
+```csharp
+// From: MetaLogic.cs
+public class MetaInfo : TimeKnot
+{
+    public float duration;    // Duration until next meta
+    public string rawValue;   // Original value
+    public string value;      // Parsed value
+}
+
+public class MetaLogic : ListTimeKnots<MetaInfo>
+{
+    public string GetValueAtTime(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot(time);
+        var active = prev ?? next;
+        return active?.value;
+    }
+}
+```
+
+## VisualSpeedMeta (Speed System)
+
+```csharp
+// From: VisualSpeedMeta.cs
+public class VisualSpeedMeta : MetaLogic
+{
+    public class Info : MetaInfo
+    {
+        public float speed;      // Speed value
+        public float distance;   // Accumulated distance (cached)
+    }
+    
+    public float GetSpeedAtTime(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot<Info>(time);
+        return (prev ?? next).speed;
+    }
+    
+    public float GetDistanceAtTime(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot<Info>(time);
+        if (prev == null) return 0f;
+        if (next == null) return prev.distance + (time - prev.time) * prev.speed;
+        return Mathf.Lerp(prev.distance, next.distance, percent);
+    }
+}
+```
+
+## VisualKnot (Position System)
+
+```csharp
+// From: VisualKnotLogic.cs
+public class VisualKnot : TimeKnot
+{
+    public float lane;
+    public int noteIdx;
+    public int controlIdx;     // -1 for note, >=0 for control point
+    public string type;        // "jump", "slide", "land", etc.
+    
+    // ⭐ PRE-CALCULATED DATA (calculated once, used many times)
+    public float zPos;                       // From context.config.GetZ(time)
+    public Vector3 warpedPosition;            // With visual speed & warp applied
+    public Quaternion warpedRotation;         // With visual warp applied
+    
+    public NoteBase note;
+}
+
+public class VisualKnotLogic : ListTimeKnots<VisualKnot>
+{
+    // ⭐ CRITICAL: Pre-calculates ALL positions once
+    public void CalculateWarpedPositions(RhythmContext context)
+    {
+        for (var i = 0; i < _knots.Count; i++)
+        {
+            var knot = _knots[i];
+            knot.zPos = context.config.GetZ(knot.time);
+            var (warpedPos, warpedRot) = context.GetWarped(knot.time, knot.lane);
+            knot.warpedPosition = warpedPos;
+            knot.warpedRotation = warpedRot;
+        }
+    }
+    
+    public Vector2 GetPositionAtTime(float time)
+    {
+        var (prevKnot, nextKnot, percent) = InterpolateKnot(time);
+        // Interpolates between cached warpedPosition
+        return Vector2.Lerp(prevPos, nextPos, percent);
+    }
+}
+```
+
+### Object Pooling
+
+```csharp
+// From: VisualKnotLogic.cs
+private static ObjectPool<VisualKnot> _knotPool = new ObjectPool<VisualKnot>(
+    createFunc: () => new VisualKnot(),
+    defaultCapacity: 500,
+    maxSize: 2000
+);
+
+public static VisualKnot GetKnotFromPool() => _knotPool.Get();
+public static void ReleaseKnotToPool(VisualKnot knot) => _knotPool.Release(knot);
+```
+
+## Template Examples
+
+### Dancing Road (DR3)
+
+```csharp
+// From: DRGame.Knot.cs
+public override void InjectKnots(List<VisualKnot> knots, SongNote note, bool isVisible)
+{
+    if (!isVisible) return;
+    
+    if (IsValidLane(note.lane) && !IsFakeNote(note))
+    {
+        knots.Add(CreateKnot(note, -1));  // Note knot
+        
+        for (var i = 0; i < note.controls.Count; i++)
+        {
+            knots.Add(CreateKnot(note, i));  // Control point knots
+        }
+    }
+    
+    if (note.type == "push")
+    {
+        InjectKnot_TilePush(knots, note);
+    }
+}
+
+private VisualKnot CreateKnot(SongNote note, int controlIdx)
+{
+    var knot = VisualKnotLogic.GetKnotFromPool();
+    knot.time = controlIdx < 0 ? note.time : note.controls[controlIdx].time;
+    knot.lane = controlIdx < 0 ? note.lane : note.controls[controlIdx].lane;
+    knot.noteIdx = note.index;
+    knot.controlIdx = controlIdx;
+    knot.type = GetKnotType(note, controlIdx);
+    knot.note = note;
+    return knot;
+}
+```
+
+### TilesHop (TH3)
+
+```csharp
+// From: THGame.Knots.cs
+private void InjectKnot_Circular(List<VisualKnot> knots, SongNote note)
+{
+    var lane = note.lane < 3 ? 1 : 5;
+    
+    // First jump
+    var knot1 = VisualKnotLogic.GetKnotFromPool();
+    knot1.time = note.time;
+    knot1.lane = lane;
+    knot1.type = "jump";
+    knot1.noteIdx = note.index;
+    knots.Add(knot1);
+    
+    // Second jump
+    var knot2 = VisualKnotLogic.GetKnotFromPool();
+    knot2.time = note.time + config.circular.timeDistance;
+    knot2.lane = lane;
+    knot2.type = "jump";
+    knot2.noteIdx = note.index;
+    knots.Add(knot2);
+}
+```
+
+## Performance Benefits
+
+**Without Knot System** (every frame):
+```csharp
+// ❌ EXPENSIVE - 60+ times per second
+float z = context.config.GetZ(time);
+var (pos, rot) = context.GetWarped(time, lane);
+```
+
+**With Knot System** (once at start):
+```csharp
+// ✅ FAST - calculate once, cache forever
+knot.zPos = context.config.GetZ(knot.time);
+knot.warpedPosition = context.GetWarped(knot.time, knot.lane);
+
+// Then every frame - just interpolate
+Vector3.Lerp(prevKnot.warpedPosition, nextKnot.warpedPosition, percent);
+```
+
+## System Hierarchy
+
+```mermaid
+classDiagram
+    TimeKnot <|-- MetaInfo
+    TimeKnot <|-- VisualKnot
+    ListTimeKnots~T~ <|-- MetaLogic
+    ListTimeKnots~T~ <|-- VisualKnotLogic
+    MetaLogic <|-- VisualSpeedMeta
+    
+    class TimeKnot {
+        +int knotIdx
+        +float time
+    }
+    
+    class ListTimeKnots~T~ {
+        +List~T~ _knots
+        +InterpolateKnot(time)
+    }
+    
+    class MetaInfo {
+        +float duration
+        +string value
+    }
+    
+    class VisualKnot {
+        +float lane
+        +int noteIdx
+        +float zPos
+        +Vector3 warpedPosition
+        +Quaternion warpedRotation
+    }
+    
+    class MetaLogic {
+        +string id
+        +GetValueAtTime(time)
+    }
+    
+    class VisualSpeedMeta {
+        +GetSpeedAtTime(time)
+        +GetDistanceAtTime(time)
+    }
+    
+    class VisualKnotLogic {
+        +CalculateWarpedPositions()
+        +GetPositionAtTime(time)
+    }
+```
+
+## Summary
+
+The Knot System provides:
+
+- ✅ **Efficient lookup**: O(log n) binary search for >32 knots
+- ✅ **Cached calculations**: Pre-compute expensive operations once
+- ✅ **Smooth interpolation**: Linear interpolation between cached points
+- ✅ **Memory efficient**: Object pooling for VisualKnots
+
+**Used internally by**:
+- `MetaLogic` - Game parameter changes
+- `VisualSpeedMeta` - Speed and distance calculations
+- `VisualKnotLogic` - Position and rotation caching
+
+---
+
+**See Also**:
+- [Meta-System-Guide.md](Meta-System-Guide.md) - Meta system details
+- [RhythmCore-Architecture.md](RhythmCore-Architecture.md) - Overall architecture

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

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

package/Docs/Meta-System-Guide.md

@@ -0,0 +1,249 @@
+# Meta System Guide
+
+## Overview
+
+The **Meta System** manages game parameter changes over time using the Knot System for efficient lookup. Meta data comes from song notes and controls speed, visual effects, and gameplay mechanics.
+
+**Key Concept**: Meta = Time-stamped game parameter (speed, color, effect, etc.)
+
+## Core Classes
+
+### MetaInfo
+
+```csharp
+// From: MetaLogic.cs
+public class MetaInfo : TimeKnot
+{
+    public float duration;    // Duration until next meta
+    public string rawValue;   // Original value from song
+    public string value;      // Parsed value
+    public float endTime => time + duration;
+}
+```
+
+### MetaLogic
+
+```csharp
+// From: MetaLogic.cs
+public class MetaLogic : ListTimeKnots<MetaInfo>
+{
+    public string id { get; }                    // Meta ID (e.g., "speed", "color")
+    public MetaInfo currentMeta { get; protected set; }  // Active meta now
+    public MetaInfo nextMeta { get; protected set; }     // Next meta change
+    
+    public void AddMetaInfo(float time, string value)
+    {
+        if (_knots.Count == 0 && time > 0)
+        {
+            base.AddKnot(CreateMetaInfo(0f, value));  // Add first knot at t=0
+        }
+        base.AddKnot(CreateMetaInfo(time, value));
+    }
+    
+    public virtual bool Update(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot(time);
+        var activeNode = prev ?? next;
+        currentMeta = activeNode;
+        nextMeta = next;
+        return hasChanged;
+    }
+    
+    public string GetValueAtTime(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot(time);
+        var active = prev ?? next;
+        return active?.value;
+    }
+}
+```
+
+## VisualSpeedMeta
+
+Built-in meta for controlling visual speed and calculating accumulated distance:
+
+```csharp
+// From: VisualSpeedMeta.cs
+public class VisualSpeedMeta : MetaLogic
+{
+    public class Info : MetaInfo
+    {
+        public float speed;      // Speed value
+        public float distance;   // Accumulated distance
+    }
+    
+    public float GetSpeedAtTime(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot<Info>(time);
+        var active = prev ?? next;
+        return active.speed;
+    }
+    
+    public float GetDistanceAtTime(float time)
+    {
+        var (prev, next, percent) = InterpolateKnot<Info>(time);
+        if (prev == null) return 0f;
+        if (next == null) return prev.distance + (time - prev.time) * prev.speed;
+        return Mathf.Lerp(prev.distance, next.distance, percent);
+    }
+    
+    void CalculateDistance()
+    {
+        var prev = (Info)_knots[0];
+        prev.distance = 0f;
+        for (var i = 1; i < _knots.Count; i++)
+        {
+            var cur = (Info)_knots[i];
+            cur.distance = prev.distance + prev.duration * prev.speed;
+            prev = cur;
+        }
+    }
+}
+```
+
+## How It Works
+
+### 1. Song Data Contains Meta
+
+```json
+{
+  "notes": [
+    {"time": 0, "lane": 1, "type": "short"},
+    {
+      "time": 4, 
+      "lane": 1, 
+      "type": "meta", 
+      "metas": [
+        {"key": "speed", "value": "6"},
+        {"key": "bgColor", "value": "red"}
+      ]
+    }
+  ]
+}
+```
+
+### 2. RhythmContext Processes Meta
+
+```csharp
+// From: RhythmContext.Runtime.cs
+private void ProcessNoteMetas(List<NoteMeta> metas, float time)
+{
+    foreach (var meta in metas)
+    {
+        GetOrCreateMetaLogic(meta.key).AddMetaInfo(time, meta.value);
+    }
+}
+
+private MetaLogic GetOrCreateMetaLogic(string key)
+{
+    if (gameMetas.TryGetValue(key, out var logic)) return logic;
+    
+    // Create new MetaLogic or use custom creator
+    logic = customMetaCreators.TryGetValue(key, out var creator) 
+        ? creator() 
+        : new MetaLogic(key);
+    
+    gameMetas[key] = logic;
+    return logic;
+}
+```
+
+### 3. Update During Gameplay
+
+```csharp
+// Every frame, RhythmContext updates all meta:
+foreach (var meta in gameMetas.Values)
+{
+    bool changed = meta.Update(currentTime);
+    if (changed)
+    {
+        // Dispatch META_CHANGED event
+        Dispatch(GameEvent.META_CHANGED, meta.id, meta.currentMeta.value);
+    }
+}
+```
+
+## Custom Meta Types
+
+### Creating Custom Meta
+
+```csharp
+public class CustomMeta : MetaLogic
+{
+    public CustomMeta() : base("customId") { }
+    
+    protected override MetaInfo CreateMetaInfo(float time, string value)
+    {
+        // Parse and validate value
+        return new MetaInfo(time, processedValue);
+    }
+}
+```
+
+### Registering Custom Meta
+
+```csharp
+// From: RhythmContext.Runtime.cs - registration
+public void RegisterMetaCreator<T>(string key) where T: MetaLogic, new()
+{
+    customMetaCreators[key] = () => new T();
+}
+
+// Usage:
+context.RegisterMetaCreator<CustomMeta>("customId");
+```
+
+## System Hierarchy
+
+```mermaid
+classDiagram
+    TimeKnot <|-- MetaInfo
+    ListTimeKnots~MetaInfo~ <|-- MetaLogic
+    MetaLogic <|-- VisualSpeedMeta
+    MetaLogic <|-- CustomMeta
+    
+    class TimeKnot {
+        +int knotIdx
+        +float time
+    }
+    
+    class MetaInfo {
+        +float duration
+        +string rawValue
+        +string value
+        +float endTime
+    }
+    
+    class MetaLogic {
+        +string id
+        +MetaInfo currentMeta
+        +MetaInfo nextMeta
+        +AddMetaInfo(time, value)
+        +Update(time) bool
+        +GetValueAtTime(time) string
+    }
+    
+    class VisualSpeedMeta {
+        +GetSpeedAtTime(time) float
+        +GetDistanceAtTime(time) float
+    }
+```
+
+## Summary
+
+The Meta System provides:
+
+- ✅ **Time-based parameters**: Control game parameters at specific times
+- ✅ **Efficient lookup**: Uses Knot System (O(log n) for >32 knots)
+- ✅ **Automatic processing**: RhythmContext handles meta from song data
+- ✅ **Extensible**: Create custom meta types for any game parameter
+- ✅ **Event-driven**: META_CHANGED event when values change
+
+**Built-in Meta**:
+- `VisualSpeedMeta` - Controls visual speed and distance calculations
+
+---
+
+**See Also**:
+- [Knot-System-Guide.md](Knot-System-Guide.md) - Knot system internals
+- [RhythmCore-Architecture.md](RhythmCore-Architecture.md) - Overall architecture

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

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

package/Docs/New-Game-Checklist.md

@@ -0,0 +1,102 @@
+# RhythmCore New Game Template - Essential Steps
+
+## 🚀 **ESSENTIAL CORE SETUP** (Must Do First)
+
+### 1. Create Core Classes (30 minutes)
+- [ ] **Main Game Class** extending `RhythmGameT<TConfig, TMatch>`
+- [ ] **Game Config Class** extending `RhythmConfig` with `[CreateAssetMenu]`
+- [ ] **Match Data Class** extending `RhythmMatch` (optional but recommended)
+- [ ] **Base Tile Class** extending `RhythmTile`
+
+### 2. Create Essential Assets (15 minutes)
+- [ ] **RhythmContext ScriptableObject** - Central coordinator
+- [ ] **GameConfig ScriptableObject** - Game settings
+- [ ] **ListSongNote ScriptableObject** - Song data container
+- [ ] **Link assets**: Context → Config, Context → SongNotes
+
+### 3. Setup Scene & Pool (20 minutes)
+- [ ] **Create main scene** with game object + your main game script
+- [ ] **Assign RhythmContext** to game object
+- [ ] **Configure tile pool** in GameConfig with tile prefabs
+- [ ] **Test basic setup** - should compile and run without errors
+
+## 🎮 **GAMEPLAY IMPLEMENTATION** (After Core Setup)
+
+### 4. Implement Tile Behavior (45 minutes)
+- [ ] **Override `OnAttach()`** - position tile, setup visuals
+- [ ] **Override `RefreshTileStatus()`** - handle None/Touching/End/Missed states  
+- [ ] **Add `Update()`** - position tiles based on `context.GetDistanceAtTime()`
+- [ ] **Add input handling** - TouchInput, HoldInput, or SwipeInput components
+
+### 5. Configure Game Logic (30 minutes)
+- [ ] **Override `GetMissedThreshold()`** in main game class
+- [ ] **Override `CalculateScore()`** in match data class
+- [ ] **Setup tile pool entries** - id matches SongNote.type, assign prefabs
+- [ ] **Test with sample song data** - create basic notes and verify gameplay
+
+### 6. Add Essential UI (20 minutes)
+- [ ] **Score display** using `RhythmBehaviour` + `OnGameScoreChange` event
+- [ ] **Basic game controls** (play/pause/restart)
+- [ ] **Audio setup** - AudioSource component or custom IAudioPlayer
+
+## 🔧 **ADVANCED FEATURES** (Optional)
+
+### Visual Polish
+- [ ] **Particle effects** for tile hits/misses
+- [ ] **Smooth animations** for tile state changes
+- [ ] **Background elements** and theme system
+- [ ] **Screen size adaptation** using `ISizeListener`
+
+### Gameplay Features  
+- [ ] **Long note support** with progress tracking
+- [ ] **Special tile types** (swipe, drag, multi-tap)
+- [ ] **Combo system** and accuracy calculation
+- [ ] **Death/rewind system** with `GetDeathTiming()`
+
+### Performance & Polish
+- [ ] **Object pooling optimization** 
+- [ ] **Audio latency compensation**
+- [ ] **Memory usage profiling**
+- [ ] **Multi-platform testing**
+
+## ⚡ **QUICK START TEMPLATE**
+
+```csharp
+// 1. YourGame.cs
+public class YourGame : RhythmGameT<YourGameConfig, YourMatchData> 
+{
+    protected override void Start() { base.Start(); }
+    public override float GetMissedThreshold() => 0.5f;
+}
+
+// 2. YourGameConfig.cs  
+[CreateAssetMenu] public class YourGameConfig : RhythmConfig 
+{
+    public float laneWidth = 2f;
+    public Vector3 GetLanePosition(int lane) => new Vector3((lane-1) * laneWidth, 0, 0);
+}
+
+// 3. YourMatchData.cs
+public class YourMatchData : RhythmMatch 
+{
+    public override void CalculateScore(TileContext tile) 
+    {
+        if (tile.Status == TileStatus.Touching) AddScore(100);
+    }
+}
+
+// 4. YourTile.cs
+public class YourTile : RhythmTile 
+{
+    public override void OnAttach() { UpdatePosition(); }
+    void Update() { if (tileContext != null) UpdatePosition(); }
+    void UpdatePosition() 
+    {
+        var pos = ((YourGameConfig)context.config).GetLanePosition(tileContext.note.lane);
+        pos.z = context.GetDistanceAtTime(tileContext.note.time);
+        transform.localPosition = pos;
+    }
+}
+```
+
+**Total Setup Time: ~2 hours for basic working game**

package/Docs/New-Game-Checklist.md.meta

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