com.amanotes.magictilescore 0.4.2

package/Docs/Class-Hierarchy.md

@@ -0,0 +1,729 @@
+# MagicTilesCore - Complete Class Hierarchy
+
+**Package:** `com.amanotes.magictilescore`  
+**Version:** 0.4.0  
+**Generated:** 2026-01-22 (from source code analysis)
+
+---
+
+## Core Architecture
+
+### Game Layer (Your Implementation)
+```
+MonoBehaviour
+└── RhythmGame (abstract)
+    └── RhythmGameT<TSongNote, TMatchData> (generic base)
+        └── YourGame (e.g., MT3Game, DRGame, THGame)
+```
+
+**Role:** Main game controller - inherit this to create your game
+
+---
+
+## Framework Classes
+
+### 1. RhythmCore (Runtime/Rhythm/Core/)
+
+#### RhythmGame (abstract)
+**File:** `RhythmGameT.cs`  
+**Role:** Base game class - lifecycle, tile spawning, miss handling  
+**Key Methods:**
+- `CreateMatchData()` - Create scoring system
+- `CreateRhythmTile(note)` - Get tile from pool
+- `CheckMissedNote()` - Miss detection
+- `HandleMissedTile()` - Miss response
+- `DieNoteSequence()` - Death/revive flow
+
+#### RhythmTile (abstract)
+**File:** `RhythmTile.cs`  
+**Role:** Base tile visual component  
+**Key Members:**
+- `RhythmContext context` - Game context
+- `TileContext tileContext` - Tile data
+- `List<RhythmTileHandler> handlers` - Sub-components
+**Key Methods:**
+- `OnAttach()` - Setup when spawned
+- `OnDetach()` - Cleanup when despawned
+- `RefreshTileStatus()` - Update visuals based on status
+
+#### RhythmMatch
+**File:** `RhythmMatch.cs`  
+**Role:** Scoring system base class  
+**Key Methods:**
+- `Init(RhythmContext)` - Initialize
+- `CalculateScore(TileContext)` - Score calculation
+- `OnTileMissed(TileContext)` - Miss handling
+- `Reset()` - Clear score data
+
+#### RhythmBehaviour
+**File:** `RhythmBehaviour.cs`  
+**Role:** Base MonoBehaviour with context access  
+**Implements:** `IRhythmBehaviour`
+
+#### Key Interfaces
+- **IRhythmBehaviour** - Context-aware component interface
+- **IAudioPlayer** - Audio system interface
+- **IVisualWarp** - 3D transformation interface (for curved games)
+- **ITileProgress** - Long tile progress tracking interface
+
+---
+
+### 2. RhythmGame Layer (Runtime/Rhythm/Game/)
+
+#### RhythmContext (ScriptableObject)
+**Files:** `RhythmContext.cs` (+ 7 partial files)  
+**Role:** Central coordinator - connects all systems  
+**Key Members:**
+```csharp
+// Configuration
+RhythmConfig config
+ListSongNote songNotes
+RhythmMatch matchData
+
+// Systems
+RhythmStateMachine stateMachine
+VisualKnotLogic visualKnotLogic
+MTCTimeMachine timeMachine (internal via gameTime property)
+IVisualWarp visualWarp
+
+// Pooling
+IPrefabPool prefabPool
+PoolGroup tilePoolGroup
+PoolGroup vfxPoolGroup
+
+// Timing
+float gameTime        // Current game time
+float audioTime       // Audio playback time
+float visualSpeed     // Tile movement speed
+float audioSpeed      // Playback speed multiplier
+
+// State
+string GameState      // Current state (GAME_READY, GAME_START, etc.)
+bool IsPlaying        // Is game active
+bool IsRewinding      // Is rewinding
+```
+
+**Key Methods:**
+```csharp
+// Lifecycle
+Init() -> Prepare() -> Ready() -> StartGame()
+PauseGame() / ResumeGame()
+DieGame() -> RewindToNote() -> ReviveGame()
+StopGame() -> Shutdown()
+
+// State machine
+bool CanTransitionTo(string state)
+string GameState { get; set; }
+
+// Timing
+float GetDistanceAtTime(float time)
+float GetTimeAtDistance(float distance)
+float GetTimeDistanceToNote(SongNote note)
+
+// Warping (3D games)
+(Vector3 position, Quaternion rotation) GetWarped(float time, float lane)
+```
+
+**State Machine:** See mermaid state diagram in `RhythmCore-Customize-Guide.md`
+
+#### RhythmConfig (ScriptableObject)
+**File:** `RhythmConfig.cs`  
+**Role:** Configuration asset  
+**Key Fields:**
+```csharp
+// Timing
+float mp3Offset
+float touchLatency
+float deviceAudioLatency
+float gameDepartTime         // Start time offset
+float endingBufferTime       // End buffer
+float loopPrepareTime        // Loop preparation time
+float rewindingDuration      // Rewind animation time
+
+// Visual
+float visualSpeed            // Base tile speed
+float zUnitDistance          // Distance unit
+
+// Layout
+int nLanes                   // Number of lanes
+float laneWidth              // Width per lane
+
+// Pooling
+PoolGroup tilePoolGroup      // Tile prefabs
+PoolGroup vfxPoolGroup       // VFX prefabs
+
+// Behavior
+bool isAutoRewind            // Auto rewind on death
+List<string> excludeFromAutoPlay  // Types to skip in auto-play
+```
+
+#### TileContext (sealed class)
+**File:** `Game/Tile/TileContext.cs`  
+**Role:** Data bridge between note data and visual tile  
+**Key Members:**
+```csharp
+readonly int index
+readonly SongNote note
+readonly RhythmContext context
+readonly float slideLength
+readonly List<VisualKnot> knots  // Knots for this tile
+
+TileStatus Status          // None, Touching, End, Missed
+float progress             // 0-1 for long tiles
+float accuracy             // Hit accuracy
+RhythmTile view           // Visual component
+
+float FillingProgress      // Visual fill progress
+float GetKnotProgressAtTime(float time)  // Knot-based progress
+```
+
+**Methods:**
+```csharp
+TileContext AttachView()   // Spawn visual
+void RemoveView()          // Despawn visual
+```
+
+#### TileStatus (enum)
+```csharp
+None       // Not touched yet
+Touching   // Being touched
+End        // Touch completed
+Missed     // Missed/failed
+```
+
+---
+
+### 3. System Layer (Runtime/Rhythm/System/)
+
+#### MTCTimeMachine
+**Files:** `TimeMachine/MTCTimeMachine.cs` (+ 4 partial files)  
+**Role:** Time-based event system & distance conversion
+
+**Key Methods:**
+```csharp
+float currentTime { get; set; }  // Seek to time
+
+// Event system
+void Add(TimeNode node)          // Add time-triggered event
+void Add(TimeSpanNode node)      // Add duration-based event
+void Sort()                      // Sort events by time
+void PreExecuteActiveNodes()     // Execute active events
+
+// Cleanup
+void Reset()                     // Reset to time 0
+void ResetAndClear()            // Clear all events
+```
+
+**Sub-classes:**
+- `TimeNode` - Single time trigger
+- `TimeSpanNode` - Time range trigger
+- `TimeMarker` - Named time point
+- `ZLaneSpeed` - Lane-specific speed (MT3)
+
+**Usage:**
+```csharp
+// In RhythmContext
+context.gameTime  // Uses timeMachine.currentTime internally
+```
+
+#### VisualKnotLogic
+**File:** `VisualKnot/VisualKnotLogic.cs`  
+**Role:** Path waypoint management for 3D games
+
+**Key Classes:**
+```csharp
+class VisualKnot : TimeKnot
+{
+    float time          // Knot time
+    float lane          // Lane position
+    int noteIdx         // Note index
+    string type         // Knot type
+    
+    float zPos          // Z position
+    Vector3 warpedPosition   // 3D position after warp
+    Quaternion warpedRotation  // 3D rotation after warp
+    NoteBase note       // Associated note
+}
+
+class VisualKnotLogic : ListTimeKnots<VisualKnot>
+{
+    void CalculateWarpedPositions(RhythmContext)
+    Vector2 GetPositionAtTime(float time)
+    void ExtractKnotsByNoteIdx(List<VisualKnot>, int noteIdx)
+    (VisualKnot prev, VisualKnot next, float percent) InterpolateKnotForNote(float, int)
+}
+```
+
+**Usage:**
+```csharp
+// In RhythmContext
+context.visualKnotLogic.AddKnot(...)
+context.visualKnotLogic.CalculateWarpedPositions(context)
+var pos = context.visualKnotLogic.GetPositionAtTime(time)
+```
+
+#### ListTimeKnots<T> (abstract generic)
+**File:** `TimeKnot/ListTimeKnots.cs`  
+**Role:** Base class for time-sorted collections  
+**Used by:** `VisualKnotLogic`, `MetaLogic`
+
+**Key Methods:**
+```csharp
+(T prev, T next, float percent) InterpolateKnot(float time)
+T GetKnotAtIndex(int index)
+void Sort()
+void Clear()
+```
+
+#### RhythmStateMachine
+**Files:** `StateMachine/RhythmStateMachine.cs` (+ State.cs)  
+**Role:** State machine implementation
+
+**Key Methods:**
+```csharp
+void Add(string stateName, params string[] allowedNextStates)
+void SetStateCallbacks(string stateName, Action onEnter, Action onExit)
+bool Validate()                  // Validate transitions
+void Start(string stateName)     // Set initial state
+bool CanTransitionTo(string nextState)
+bool TransitionTo(string nextState)
+bool Reset(string initialState)
+```
+
+**Events:**
+```csharp
+Action<string, string> onStateChanged  // (prevState, newState)
+```
+
+**Usage:**
+```csharp
+// Setup (in RhythmContext.SetupStateMachine)
+stateMachine.Add(GAME_NONE, GAME_INITED);
+stateMachine.Add(GAME_INITED, GAME_SONG_LOADED);
+stateMachine.Add(GAME_SONG_LOADED, GAME_PREPARE);
+// ... etc
+
+// Transition
+context.GameState = GAME_START;  // Uses stateMachine internally
+```
+
+#### MetaLogic
+**File:** `Meta/MetaLogic.cs`  
+**Role:** Dynamic song-synchronized parameters
+
+**Key Classes:**
+```csharp
+class MetaInfo : TimeKnot
+{
+    float duration
+    string value
+    float endTime
+}
+
+class MetaLogic : ListTimeKnots<MetaInfo>
+{
+    string id
+    MetaInfo currentMeta
+    MetaInfo nextMeta
+    
+    void AddMetaInfo(float time, string value)
+    void Calculate(float? endTime)
+    bool Update(float time)  // Returns true if changed
+    string GetValueAtTime(float time)
+}
+```
+
+**Subclass Example:**
+```csharp
+class VisualSpeedMeta : MetaLogic
+{
+    class Info : MetaInfo
+    {
+        float speed  // Visual speed value
+    }
+}
+```
+
+**Usage:**
+```csharp
+// In RhythmContext
+context.gameMetas["mood"] = new MoodMeta("mood");
+context.gameMetas["speed"] = new VisualSpeedMeta("speed");
+
+// Update each frame
+foreach (var meta in context.gameMetas.Values)
+{
+    if (meta.Update(context.gameTime))
+    {
+        // Meta changed, react to it
+    }
+}
+```
+
+#### VisualSpeedMeta
+**File:** `Meta/VisualSpeedMeta.cs`  
+**Role:** Control visual speed over time  
+**Extends:** `MetaLogic`
+
+**Usage:**
+```csharp
+// In RhythmContext
+float visualSpeed => visualSpeedMeta.currentMeta?.speed ?? config.visualSpeed
+```
+
+---
+
+### 4. Input System (Runtime/Input/)
+
+**Files:** `Input/Base/` and `Input/Components/`
+
+#### IInputHandler (interface)
+**Role:** Input handler interface
+
+#### BaseTileInput (abstract)
+**Role:** Base tile input component  
+**Extends:** `MonoBehaviour, IInputHandler`
+
+#### Concrete Input Components
+All extend `BaseTileInput`:
+- **TouchInput** - Instant tap/touch
+- **HoldInput** - Continuous press/hold
+- **SwipeInput** - Directional swipe gestures
+- **DragInput** - Continuous drag
+
+**Enums:**
+```csharp
+enum InputPhase { Start, Progress, End }
+enum InputDirection { None, Up, Down, Left, Right }
+```
+
+---
+
+### 5. VisualWarp System (Runtime/Rhythm/System/VisualWarp/)
+
+#### IVisualWarp (interface)
+**File:** `IVisualWarp.cs`  
+**Role:** 3D perspective transformation for curved games  
+**Method:**
+```csharp
+(Vector3 position, Quaternion rotation) GetWarped(float time, float lane)
+```
+
+#### LinearVisualWarp
+**File:** `LinearVisualWarp.cs`  
+**Role:** Default linear warp (no transformation)  
+**Implements:** `IVisualWarp`
+
+**Custom implementations:**
+- `DRCurvedVisualWarp` (Dancing Road) - Creates curved 3D path illusion
+
+---
+
+### 6. MoodChange System (Runtime/MoodChange/)
+
+#### MoodChange
+**File:** `MoodChange.cs`  
+**Role:** Color/theme management  
+**Responds to:** Meta events with key="mood"
+
+#### AdjustHue
+**Files:** `AdjustHue.cs` (+ 5 component info files)  
+**Role:** Component-based hue adjustment  
+**Targets:** SpriteRenderer, Material, ParticleSystem, TrailRenderer
+
+---
+
+### 7. Helper Components (Runtime/Rhythm/Components/Helper/)
+
+- **CameraFollow** - Camera following behavior
+- **MeshSpriteSorter** - Mesh/sprite rendering order
+- **RecycleLayoutZ** - Z-axis recycling layout
+
+---
+
+### 8. Math Utilities (Runtime/Rhythm/Math/)
+
+#### Parabol
+**File:** `Parabol.cs`  
+**Role:** Parabolic arc calculation  
+**Usage:** Jump physics in HB3, TH3
+
+```csharp
+public static float Calculate(float h, float t)
+{
+    return 4f * h * t * (1f - t);
+}
+```
+
+---
+
+### 9. Preset Components (Runtime/Preset/)
+
+Pre-built components for common features:
+- **ScoreText** - Score display
+- **WowText** - Feedback text ("Perfect!", "Great!")
+- **StartHint** - Start game hint
+- **AudioSourcePlayer** - Audio player component
+- **ParticleSystemPlayer** - Particle player component
+- **AudioTimeText** - Audio time display
+- **RendererAlpha** - Renderer alpha control
+
+---
+
+## Constants & Events
+
+### GameEvent (static class)
+**File:** `System/Event/GameEvent.cs`  
+**Role:** State machine event constants
+
+```csharp
+public static class GameEvent
+{
+    // State constants
+    public const string GAME_NONE = "GAME_NONE";
+    public const string GAME_INITED = "GAME_INITED";
+    public const string GAME_SONG_LOADED = "GAME_SONG_LOADED";
+    public const string GAME_PREPARE = "GAME_PREPARE";
+    public const string GAME_READY = "GAME_READY";
+    public const string GAME_START = "GAME_START";
+    public const string GAME_PLAY = "GAME_PLAY";
+    public const string GAME_PAUSE = "GAME_PAUSE";
+    public const string GAME_DIE = "GAME_DIE";
+    public const string GAME_REWIND = "GAME_REWIND";
+    public const string GAME_REVIVE = "GAME_REVIVE";
+    public const string GAME_END = "GAME_END";
+    public const string GAME_END_ROUND = "GAME_END_ROUND";
+    public const string GAME_STOP = "GAME_STOP";
+    public const string GAME_SHUTDOWN = "GAME_SHUTDOWN";
+    
+    // State categories
+    public static class Category
+    {
+        public static readonly HashSet<string> Active = new()
+        {
+            GAME_PLAY, GAME_START, GAME_READY, GAME_REVIVE
+        };
+    }
+}
+```
+
+---
+
+## State Machine Flow (Source-Verified)
+
+**Implementation:** `RhythmStateMachine` class in `System/StateMachine/`  
+**Setup:** `RhythmGame.SetupStateMachine()` method  
+**Constants:** `GameEvent` static class
+
+### Complete State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> GAME_NONE
+    
+    GAME_NONE --> GAME_INITED : Init()
+    GAME_INITED --> GAME_SONG_LOADED : LoadSong()
+    GAME_INITED --> GAME_SHUTDOWN : [error]
+    
+    GAME_SONG_LOADED --> GAME_PREPARE : Prepare()
+    GAME_SONG_LOADED --> GAME_SHUTDOWN : [error]
+    
+    GAME_PREPARE --> GAME_READY : Ready()
+    GAME_PREPARE --> GAME_NOT_READY : [error]
+    GAME_PREPARE --> GAME_SHUTDOWN : [error]
+    
+    GAME_NOT_READY --> GAME_PREPARE : [retry]
+    GAME_NOT_READY --> GAME_SHUTDOWN : [abort]
+    
+    GAME_READY --> GAME_START : StartGame()
+    GAME_READY --> GAME_PREPARE : StopGame()
+    GAME_READY --> GAME_SHUTDOWN : [abort]
+    
+    GAME_START --> GAME_PLAY : [alias]
+    GAME_START --> GAME_PAUSE : PauseGame()
+    GAME_START --> GAME_DIE : DieGame()
+    GAME_START --> GAME_END : [complete]
+    GAME_START --> GAME_END_ROUND : [round complete]
+    GAME_START --> GAME_PREPARE : StopGame()
+    GAME_START --> GAME_SHUTDOWN : [error]
+    
+    GAME_PLAY --> GAME_PAUSE : PauseGame()
+    GAME_PLAY --> GAME_DIE : DieGame()
+    GAME_PLAY --> GAME_END : [complete]
+    GAME_PLAY --> GAME_END_ROUND : [round complete]
+    GAME_PLAY --> GAME_PREPARE : StopGame()
+    GAME_PLAY --> GAME_SHUTDOWN : [error]
+    
+    GAME_PAUSE --> GAME_PLAY : ResumeGame()
+    GAME_PAUSE --> GAME_PREPARE : StopGame()
+    GAME_PAUSE --> GAME_SHUTDOWN : [error]
+    
+    GAME_DIE --> GAME_REWIND : [auto-rewind]
+    GAME_DIE --> GAME_PREPARE : [no rewind]
+    GAME_DIE --> GAME_SHUTDOWN : [error]
+    
+    GAME_REWIND --> GAME_REVIVE : [complete]
+    GAME_REWIND --> GAME_SHUTDOWN : [error]
+    
+    GAME_REVIVE --> GAME_PLAY : ReviveGame()
+    
+    GAME_END --> GAME_PREPARE : [restart]
+    GAME_END --> GAME_SHUTDOWN : [exit]
+    
+    GAME_END_ROUND --> GAME_PREPARE : [endless loop]
+    GAME_END_ROUND --> GAME_SHUTDOWN : [exit]
+    
+    GAME_SHUTDOWN --> GAME_NONE
+    GAME_SHUTDOWN --> [*]
+```
+
+### State Categories
+
+**From GameEvent.Category:**
+```csharp
+PreGame:   GAME_NONE, GAME_INITED, GAME_SONG_LOADED, GAME_PREPARE
+Gameplay:  GAME_READY, GAME_START, GAME_PLAY, GAME_PAUSE, GAME_DIE,
+           GAME_REWIND, GAME_REVIVE, GAME_END, GAME_END_ROUND  
+Active:    All Gameplay + GAME_PREPARE
+```
+
+### State Machine Setup
+
+**In RhythmGame.SetupStateMachine():**
+```csharp
+var sm = context.stateMachine;
+
+// Initialization chain
+sm.Add(GAME_NONE, GAME_INITED);
+sm.Add(GAME_INITED, GAME_SONG_LOADED, GAME_SHUTDOWN);
+sm.Add(GAME_SONG_LOADED, GAME_PREPARE, GAME_SHUTDOWN);
+sm.Add(GAME_PREPARE, GAME_READY, GAME_NOT_READY, GAME_SHUTDOWN);
+sm.Add(GAME_READY, GAME_START, GAME_PREPARE, GAME_SHUTDOWN);
+
+// Active gameplay
+sm.Add(GAME_START, GAME_PLAY, GAME_PAUSE, GAME_DIE, GAME_END, 
+       GAME_END_ROUND, GAME_PREPARE, GAME_SHUTDOWN);
+sm.Add(GAME_PLAY, GAME_PAUSE, GAME_DIE, GAME_END, GAME_END_ROUND, 
+       GAME_PREPARE, GAME_SHUTDOWN);
+sm.Add(GAME_PAUSE, GAME_PLAY, GAME_PREPARE, GAME_SHUTDOWN);
+
+// Death & rewind (if enabled)
+sm.Add(GAME_DIE, GAME_REWIND, GAME_PREPARE, GAME_SHUTDOWN);
+sm.Add(GAME_REWIND, GAME_REVIVE, GAME_SHUTDOWN);
+sm.Add(GAME_REVIVE, GAME_PLAY, GAME_SHUTDOWN);
+
+// Ending
+sm.Add(GAME_END, GAME_PREPARE, GAME_SHUTDOWN);
+sm.Add(GAME_END_ROUND, GAME_PREPARE, GAME_SHUTDOWN);
+sm.Add(GAME_SHUTDOWN, GAME_NONE);
+
+// Validate
+sm.Validate();
+```
+
+---
+
+## Usage Patterns
+
+### Creating a Game
+```csharp
+using Amanotes.MagicTilesCore;
+using static Amanotes.MagicTilesCore.GameEvent;
+
+public class MyGame : RhythmGame
+{
+    protected override void Awake()
+    {
+        base.Awake();
+        context.OnGameStateChange += OnStateChange;
+    }
+    
+    public override RhythmMatch CreateMatchData()
+    {
+        return new MyMatchData().Init(context);
+    }
+    
+    protected void OnStateChange(string state)
+    {
+        if (state == GAME_START)
+        {
+            // Game started
+        }
+        else if (state == GAME_END)
+        {
+            // Game ended
+        }
+    }
+}
+```
+
+### Creating a Tile
+```csharp
+public class MyTile : RhythmTile
+{
+    public override void OnAttach()
+    {
+        // Setup when spawned
+        transform.position = GetPositionForNote(tileContext.note);
+    }
+    
+    public override void OnDetach()
+    {
+        // Cleanup when despawned
+    }
+    
+    public override void RefreshTileStatus()
+    {
+        base.RefreshTileStatus();
+        
+        // Update visuals based on tileContext.Status
+        switch (tileContext.Status)
+        {
+            case TileStatus.None: // Waiting for touch
+                break;
+            case TileStatus.Touching: // Being touched
+                break;
+            case TileStatus.End: // Touch completed
+                break;
+            case TileStatus.Missed: // Missed
+                break;
+        }
+    }
+}
+```
+
+### Using MetaLogic
+```csharp
+public class MoodMeta : MetaLogic
+{
+    public MoodMeta(string id) : base(id) { }
+    
+    public override bool Update(float time)
+    {
+        var changed = base.Update(time);
+        if (changed)
+        {
+            // Apply mood change
+            var moodValue = currentMeta.value;
+            ApplyMood(moodValue);
+        }
+        return changed;
+    }
+}
+
+// In game setup
+context.gameMetas["mood"] = new MoodMeta("mood");
+```
+
+---
+
+## Class Count Summary
+
+**Total C# Files:** 66  
+**Core Classes:** 9 (RhythmGame, RhythmTile, RhythmContext, RhythmConfig, RhythmMatch, etc.)  
+**System Classes:** 12 (MTCTimeMachine, VisualKnotLogic, MetaLogic, RhythmStateMachine, etc.)  
+**Input Classes:** 6 (IInputHandler, BaseTileInput, TouchInput, HoldInput, SwipeInput, DragInput)  
+**Helper Classes:** 12 (MoodChange, AdjustHue, CameraFollow, Parabol, etc.)  
+**Preset Components:** 7 (ScoreText, WowText, StartHint, etc.)
+
+**Verified:** All class names, file paths, and relationships confirmed from source