Build TravelRun intro and tutorial flow

2026-07-06 16:15:20 +09:00
parent af26dd4311
commit 2ba3882f1b
153 changed files with 13625 additions and 2086 deletions
@@ -1,3 +1,5 @@
+using System.Collections;
+using System.Collections.Generic;
 using UnityEngine;
 using UnityEngine.SceneManagement;
 using TMPro;
@@ -40,7 +42,7 @@ public class GameManager : MonoBehaviour {
    private string tutorialTitle = ""; // 튜토리얼 안내 제목
    private string tutorialMessage = ""; // 튜토리얼 안내 문구
    private Image[] lifeIcons; // 왼쪽 HUD의 목숨 도장 표시
-    private GameObject tutorialGuideObject; // 화면 하단 이미지 튜토리얼 패널
+    private GameObject tutorialGuideObject; // 화면 상단 이미지 튜토리얼 패널
    private Image tutorialMainImage; // 점프/슬라이드 대표 이미지
    private TextMeshProUGUI tutorialMultiplierText; // 2단 점프 x2 표시
    private TextMeshProUGUI tutorialTitleText; // 튜토리얼 제목
@@ -54,16 +56,28 @@ public class GameManager : MonoBehaviour {
    private float stageElapsedTime = 0f; // 현재 맵 진행 시간
    private float stageDistance = 0f; // 현재 맵 진행 거리
    private bool stageCompleted = false; // 결과 화면이 이미 처리되었는지 여부
+    private Coroutine tutorialGuidePauseRoutine; // 안내를 보여주는 동안 잠깐 멈추는 코루틴
+    private bool tutorialGuidePauseActive = false; // 안내 일시정지 중인지 여부
+    private float tutorialGuidePreviousTimeScale = 1f; // 안내 일시정지 전 시간 배율
+    private int tutorialGuideVersion = 0; // 오래된 자동 숨김 요청을 무시하기 위한 버전
+    private FinishGate activeFinishGate; // 목표 지점에 나타나는 맵별 클리어 게이트
+    private bool finishGateSpawned = false; // 현재 맵에서 도착 게이트를 이미 만들었는지 여부

    public int maxLife = 3; // 시작 목숨
    public int initialMileage = 500; // 첫 시작시 지급할 초기 마일리지
    public bool grantInitialMileage = true; // 초기 마일리지 지급 여부
    public bool saveMileageImmediately = true; // 스테이지 정산 전까지는 획득 즉시 누적한다.
-    public bool playTutorialGuideSequence = false; // 시작 시 입력/아이템 안내를 시간 기준으로 보여준다.
+    public bool playTutorialGuideSequence = false; // 코스 데이터가 없을 때만 시간 기준 안내를 보여준다.
+    public bool pauseGameplayForTutorialGuide = true; // 안내가 뜨는 동안 게임을 잠깐 멈춘다.
+    public float tutorialGuidePauseDuration = 2f; // 안내를 보여주고 자동으로 숨길 시간
    public float itemInvincibleDuration = 2.2f; // 라멘 아이템 무적 지속 시간
    public float itemSpeedBoostAmount = 0.35f; // 운동화 아이템 즉시 속도 보정량
    public float mileageBonusDuration = 7f; // 마일리지 카드 보너스 지속 시간
    public int mileageBonusMultiplier = 2; // 마일리지 카드 획득 배율
+    public float finishGateSpawnX = 20f; // 도착 게이트가 처음 나타나는 x 위치
+    public float finishGatePlayerX = -6f; // 게이트가 클리어 판정을 내릴 플레이어 기준 x 위치
+    public float finishGateGroundY = -2.42f; // 도착 게이트가 바닥에 붙는 y 위치
+    public float finishGateFallbackDistance = 18f; // 게이트 트리거를 놓쳤을 때의 안전 클리어 거리

    private const string TotalMileageKey = "UniRun.TotalMileage";
    private const string InitialMileageGrantedKey = "UniRun.InitialMileageGranted";
@@ -86,6 +100,10 @@ public class GameManager : MonoBehaviour {
    private float itemInvincibleEndTime = 0f; // 라멘 무적 종료 시각
    private float mileageBonusEndTime = 0f; // 마일리지 카드 보너스 종료 시각

+    public bool IsTutorialGuidePaused {
+        get { return tutorialGuidePauseActive; }
+    }
+
    // 게임 시작과 동시에 싱글톤을 구성
    void Awake() {
        // 싱글톤 변수 instance가 비어있는가?
@@ -120,7 +138,6 @@ public class GameManager : MonoBehaviour {
        }

        BuildRuntimeHUD();
-        StartTutorialGuideSequence();
        BeginMap(GameFlowManager.Instance != null
            ? GameFlowManager.Instance.CurrentMap
            : MapDatabase.GetMap(MapId.TutorialIncheon));
@@ -153,11 +170,15 @@ public class GameManager : MonoBehaviour {
            gameSpeed = Mathf.Min(gameSpeed, maxGameSpeed);

            stageDistance += 10f * gameSpeed * Time.deltaTime;
+            UpdateFinishGate();

            if(currentMapDefinition != null && currentMapDefinition.targetDistance > 0f && stageDistance >= currentMapDefinition.targetDistance)
            {
-                CompleteStage(true);
-                return;
+                if(!ShouldUseFinishGate() || stageDistance >= currentMapDefinition.targetDistance + finishGateFallbackDistance)
+                {
+                    CompleteStage(true);
+                    return;
+                }
            }

            if(currentMapDefinition != null && currentMapDefinition.timeLimit > 0f && stageElapsedTime >= currentMapDefinition.timeLimit)
@@ -171,9 +192,13 @@ public class GameManager : MonoBehaviour {
    }

    public void BeginMap(MapDefinition mapDefinition) {
+        StopTutorialGuidePause(true);
+        Time.timeScale = 1f;
+
        currentMapDefinition = mapDefinition != null
            ? mapDefinition
            : MapDatabase.GetMap(MapId.TutorialIncheon);
+        BackgroundLoop.ApplyResourceBackground(currentMapDefinition.backgroundResourcePath);

        score = 0;
        stageMileage = 0;
@@ -185,10 +210,12 @@ public class GameManager : MonoBehaviour {
        stageElapsedTime = 0f;
        stageDistance = 0f;
        stageCompleted = false;
+        finishGateSpawned = false;
        isGameover = false;
        tutorialGuideSequenceComplete = false;
        currentTutorialGuideSequenceIndex = -1;
        SetTutorialGuide(TutorialGuideType.None, "", "");
+        RemoveActiveFinishGate();

        if(gameoverUI != null)
        {
@@ -201,6 +228,7 @@ public class GameManager : MonoBehaviour {
            platformSpawner.ApplyMap(currentMapDefinition);
        }

+        StartTutorialGuideSequence();
        UpdateScoreUI();
    }

@@ -220,15 +248,99 @@ public class GameManager : MonoBehaviour {
    }

    public void SetTutorialGuide(TutorialGuideType guideType, string title, string message) {
+        tutorialGuideVersion++;
        tutorialGuideType = guideType;
        tutorialTitle = title;
        tutorialMessage = message;
+
+        if(!HasTutorialGuideContent(guideType, title, message))
+        {
+            StopTutorialGuidePause(true);
+            UpdateScoreUI();
+            return;
+        }
+
        UpdateScoreUI();
+        TryPauseForTutorialGuide(tutorialGuideVersion);
+    }
+
+    private bool HasTutorialGuideContent(TutorialGuideType guideType, string title, string message) {
+        return guideType != TutorialGuideType.None
+            || !string.IsNullOrEmpty(title)
+            || !string.IsNullOrEmpty(message);
+    }
+
+    private void TryPauseForTutorialGuide(int guideVersion) {
+        if(!pauseGameplayForTutorialGuide
+            || tutorialGuidePauseDuration <= 0f
+            || isGameover
+            || !GameFlowManager.IsGameplayActive)
+        {
+            return;
+        }
+
+        if(!tutorialGuidePauseActive)
+        {
+            tutorialGuidePreviousTimeScale = Time.timeScale;
+            tutorialGuidePauseActive = true;
+        }
+
+        Time.timeScale = 0f;
+
+        if(tutorialGuidePauseRoutine != null)
+        {
+            StopCoroutine(tutorialGuidePauseRoutine);
+        }
+
+        tutorialGuidePauseRoutine = StartCoroutine(HideTutorialGuideAfterPause(guideVersion));
+    }
+
+    private IEnumerator HideTutorialGuideAfterPause(int guideVersion) {
+        yield return new WaitForSecondsRealtime(tutorialGuidePauseDuration);
+
+        tutorialGuidePauseRoutine = null;
+
+        if(guideVersion == tutorialGuideVersion)
+        {
+            tutorialGuideVersion++;
+            tutorialGuideType = TutorialGuideType.None;
+            tutorialTitle = "";
+            tutorialMessage = "";
+            UpdateScoreUI();
+        }
+
+        RestoreTutorialGuideTimeScale();
+    }
+
+    private void StopTutorialGuidePause(bool restoreTimeScale) {
+        if(tutorialGuidePauseRoutine != null)
+        {
+            StopCoroutine(tutorialGuidePauseRoutine);
+            tutorialGuidePauseRoutine = null;
+        }
+
+        if(restoreTimeScale)
+        {
+            RestoreTutorialGuideTimeScale();
+        }
+    }
+
+    private void RestoreTutorialGuideTimeScale() {
+        if(!tutorialGuidePauseActive)
+        {
+            return;
+        }
+
+        Time.timeScale = Mathf.Approximately(tutorialGuidePreviousTimeScale, 0f)
+            ? 1f
+            : tutorialGuidePreviousTimeScale;
+        tutorialGuidePauseActive = false;
    }

    private void StartTutorialGuideSequence() {
-        if(!playTutorialGuideSequence)
+        if(!ShouldUseTimeBasedTutorialGuide())
        {
+            tutorialGuideSequenceComplete = true;
            return;
        }

@@ -239,7 +351,7 @@ public class GameManager : MonoBehaviour {
    }

    private void UpdateTutorialGuideSequence() {
-        if(!playTutorialGuideSequence || tutorialGuideSequenceComplete)
+        if(!ShouldUseTimeBasedTutorialGuide() || tutorialGuideSequenceComplete)
        {
            return;
        }
@@ -256,6 +368,33 @@ public class GameManager : MonoBehaviour {
        ApplyTutorialGuideSequenceStep(guideIndex);
    }

+    private bool ShouldUseTimeBasedTutorialGuide() {
+        return playTutorialGuideSequence && !HasCourseDrivenTutorialGuide();
+    }
+
+    private bool HasCourseDrivenTutorialGuide() {
+        if(currentMapDefinition == null
+            || currentMapDefinition.openingSteps == null
+            || currentMapDefinition.openingSteps.Length == 0)
+        {
+            return false;
+        }
+
+        for(int i = 0; i < currentMapDefinition.openingSteps.Length; i++)
+        {
+            PlatformSpawner.TutorialStep step = currentMapDefinition.openingSteps[i];
+            if(step != null
+                && (step.guideType != TutorialGuideType.None
+                    || !string.IsNullOrEmpty(step.title)
+                    || !string.IsNullOrEmpty(step.message)))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
    private int GetTutorialGuideSequenceIndex(float elapsedTime) {
        if(elapsedTime < TutorialJumpGuideDuration)
        {
@@ -359,23 +498,38 @@ public class GameManager : MonoBehaviour {
            case TutorialItemType.HealthSushi:
                currentLife = Mathf.Min(maxLife, currentLife + 1);
                AddScore(3);
-                SetTutorialGuide(TutorialGuideType.Items, "초밥", "방금 잃은 목숨을 1 회복합니다.");
+                if(ShouldShowItemEffectGuide())
+                {
+                    SetTutorialGuide(TutorialGuideType.Items, "초밥", "방금 잃은 목숨을 1 회복합니다.");
+                }
                break;
            case TutorialItemType.InvincibleRamen:
                itemInvincibleEndTime = Time.time + itemInvincibleDuration;
-                SetTutorialGuide(TutorialGuideType.Items, "라멘", "짧은 시간 동안 다음 충돌 피해를 받지 않습니다.");
+                if(ShouldShowItemEffectGuide())
+                {
+                    SetTutorialGuide(TutorialGuideType.Items, "라멘", "짧은 시간 동안 다음 충돌 피해를 받지 않습니다.");
+                }
                break;
            case TutorialItemType.Shield:
                shieldCharges = Mathf.Max(shieldCharges, 1);
-                SetTutorialGuide(TutorialGuideType.Items, "방어막", "다음 충돌 1회를 방어막이 대신 막습니다.");
+                if(ShouldShowItemEffectGuide())
+                {
+                    SetTutorialGuide(TutorialGuideType.Items, "방어막", "다음 충돌 1회를 방어막이 대신 막습니다.");
+                }
                break;
            case TutorialItemType.SpeedShoes:
                gameSpeed = Mathf.Min(maxGameSpeed, gameSpeed + itemSpeedBoostAmount);
-                SetTutorialGuide(TutorialGuideType.Items, "운동화", "속도를 즉시 회복해 늦어진 일정을 따라잡습니다.");
+                if(ShouldShowItemEffectGuide())
+                {
+                    SetTutorialGuide(TutorialGuideType.Items, "운동화", "속도를 즉시 회복해 늦어진 일정을 따라잡습니다.");
+                }
                break;
            case TutorialItemType.MileageCard:
                mileageBonusEndTime = Time.time + mileageBonusDuration;
-                SetTutorialGuide(TutorialGuideType.Items, "마일리지 카드", "잠시 동안 먹는 마일리지가 두 배로 들어옵니다.");
+                if(ShouldShowItemEffectGuide())
+                {
+                    SetTutorialGuide(TutorialGuideType.Items, "마일리지 카드", "잠시 동안 먹는 마일리지가 두 배로 들어옵니다.");
+                }
                break;
        }

@@ -390,14 +544,23 @@ public class GameManager : MonoBehaviour {

        if(IsItemInvincibleActive())
        {
-            SetTutorialGuide(TutorialGuideType.Items, "라멘", "무적 중이라 이번 충돌은 피해 없이 지나갑니다.");
+            if(ShouldShowItemEffectGuide())
+            {
+                SetTutorialGuide(TutorialGuideType.Items, "라멘", "무적 중이라 이번 충돌은 피해 없이 지나갑니다.");
+            }
+
+            SpawnItemBlockFeedback(TutorialItemType.InvincibleRamen);
            return true;
        }

        if(shieldCharges > 0)
        {
            shieldCharges--;
-            SetTutorialGuide(TutorialGuideType.Items, "방어막", "방어막이 충돌 피해를 한 번 막았습니다.");
+            SpawnItemBlockFeedback(TutorialItemType.Shield);
+            if(ShouldShowItemEffectGuide())
+            {
+                SetTutorialGuide(TutorialGuideType.Items, "방어막", "방어막이 충돌 피해를 한 번 막았습니다.");
+            }
            UpdateScoreUI();
            return true;
        }
@@ -405,6 +568,20 @@ public class GameManager : MonoBehaviour {
        return false;
    }

+    private void SpawnItemBlockFeedback(TutorialItemType itemType) {
+        GameObject playerObject = GameObject.FindGameObjectWithTag("Player");
+        if(playerObject == null)
+        {
+            return;
+        }
+
+        ItemFeedbackEffect.Spawn(playerObject.transform.position, null, itemType, true);
+    }
+
+    private bool ShouldShowItemEffectGuide() {
+        return currentMapDefinition == null || !currentMapDefinition.isTutorial;
+    }
+
    private bool IsItemInvincibleActive() {
        return Time.time < itemInvincibleEndTime;
    }
@@ -425,12 +602,24 @@ public class GameManager : MonoBehaviour {
        CompleteStage(false);
    }

+    public void CompleteCurrentStageFromFinishGate() {
+        if(currentMapDefinition != null && currentMapDefinition.targetDistance > 0f)
+        {
+            stageDistance = Mathf.Max(stageDistance, currentMapDefinition.targetDistance);
+        }
+
+        CompleteStage(true);
+    }
+
    private void CompleteStage(bool cleared) {
        if(stageCompleted)
        {
            return;
        }

+        StopTutorialGuidePause(true);
+        RemoveActiveFinishGate();
+
        stageCompleted = true;
        isGameover = true;

@@ -444,6 +633,40 @@ public class GameManager : MonoBehaviour {
        }
    }

+    private void UpdateFinishGate() {
+        if(!ShouldUseFinishGate() || finishGateSpawned || stageCompleted)
+        {
+            return;
+        }
+
+        float spawnLeadDistance = Mathf.Max(0f, finishGateSpawnX - finishGatePlayerX);
+        float spawnDistance = Mathf.Max(0f, currentMapDefinition.targetDistance - spawnLeadDistance);
+        if(stageDistance < spawnDistance)
+        {
+            return;
+        }
+
+        GameObject gateObject = new GameObject("Finish Gate - " + currentMapDefinition.displayName);
+        gateObject.transform.position = new Vector3(finishGateSpawnX, finishGateGroundY, 0f);
+        activeFinishGate = gateObject.AddComponent<FinishGate>();
+        activeFinishGate.Setup(currentMapDefinition.finishGateStyle);
+        finishGateSpawned = true;
+    }
+
+    private bool ShouldUseFinishGate() {
+        return currentMapDefinition != null
+            && currentMapDefinition.finishGateStyle != FinishGateStyle.None
+            && currentMapDefinition.targetDistance > 0f;
+    }
+
+    private void RemoveActiveFinishGate() {
+        if(activeFinishGate != null)
+        {
+            Destroy(activeFinishGate.gameObject);
+            activeFinishGate = null;
+        }
+    }
+
    private void SyncTotalMileageToFlow() {
        if(GameFlowManager.Instance != null)
        {
@@ -518,6 +741,8 @@ public class GameManager : MonoBehaviour {

        bool showItemRow = tutorialGuideType == TutorialGuideType.Items;
        Sprite mainSprite = GetTutorialMainSprite(tutorialGuideType);
+        bool showFullText = !showItemRow && mainSprite == null;
+        UpdateTutorialTextLayout(showItemRow, showFullText);

        if(tutorialMainImage != null)
        {
@@ -542,6 +767,40 @@ public class GameManager : MonoBehaviour {
        }
    }

+    private void UpdateTutorialTextLayout(bool showItemRow, bool showFullText) {
+        Vector2 textPosition = new Vector2(66f, -8f);
+        Vector2 textSize = new Vector2(268f, 17f);
+        Vector2 bodyPosition = new Vector2(66f, -26f);
+        Vector2 bodySize = new Vector2(268f, 31f);
+
+        if(showItemRow)
+        {
+            textPosition = new Vector2(154f, -8f);
+            textSize = new Vector2(178f, 17f);
+            bodyPosition = new Vector2(154f, -26f);
+            bodySize = new Vector2(178f, 31f);
+        }
+        else if(showFullText)
+        {
+            textPosition = new Vector2(16f, -8f);
+            textSize = new Vector2(316f, 17f);
+            bodyPosition = new Vector2(16f, -26f);
+            bodySize = new Vector2(316f, 31f);
+        }
+
+        if(tutorialTitleText != null)
+        {
+            tutorialTitleText.rectTransform.anchoredPosition = textPosition;
+            tutorialTitleText.rectTransform.sizeDelta = textSize;
+        }
+
+        if(tutorialBodyText != null)
+        {
+            tutorialBodyText.rectTransform.anchoredPosition = bodyPosition;
+            tutorialBodyText.rectTransform.sizeDelta = bodySize;
+        }
+    }
+
    private Color GetActiveLifeIconColor(Image lifeIcon) {
        if(lifeIcon != null && lifeIcon.sprite == null)
        {
@@ -726,22 +985,22 @@ public class GameManager : MonoBehaviour {
        tutorialGuideObject.transform.SetParent(canvasTransform, false);

        RectTransform guideRect = tutorialGuideObject.GetComponent<RectTransform>();
-        guideRect.anchorMin = new Vector2(0.5f, 0f);
-        guideRect.anchorMax = new Vector2(0.5f, 0f);
-        guideRect.pivot = new Vector2(0.5f, 0f);
-        guideRect.anchoredPosition = new Vector2(18f, 12f);
-        guideRect.sizeDelta = new Vector2(372f, 72f);
+        guideRect.anchorMin = new Vector2(0.5f, 1f);
+        guideRect.anchorMax = new Vector2(0.5f, 1f);
+        guideRect.pivot = new Vector2(0.5f, 1f);
+        guideRect.anchoredPosition = new Vector2(0f, -12f);
+        guideRect.sizeDelta = new Vector2(348f, 66f);

        Image guideBackground = tutorialGuideObject.GetComponent<Image>();
-        guideBackground.color = new Color(0.035f, 0.055f, 0.07f, 0.76f);
+        guideBackground.color = new Color(0.035f, 0.055f, 0.07f, 0.82f);
        guideBackground.raycastTarget = false;

        tutorialFontAsset = CreateKoreanTutorialFontAsset();

        CreateTutorialMainImage(tutorialGuideObject.transform);
        CreateTutorialItemRow(tutorialGuideObject.transform);
-        tutorialTitleText = CreateTutorialText(tutorialGuideObject.transform, "Tutorial Title", new Vector2(70f, -9f), new Vector2(286f, 18f), 12f, FontStyles.Bold);
-        tutorialBodyText = CreateTutorialText(tutorialGuideObject.transform, "Tutorial Body", new Vector2(70f, -28f), new Vector2(286f, 34f), 9f, FontStyles.Normal);
+        tutorialTitleText = CreateTutorialText(tutorialGuideObject.transform, "Tutorial Title", new Vector2(66f, -8f), new Vector2(268f, 17f), 11.5f, FontStyles.Bold);
+        tutorialBodyText = CreateTutorialText(tutorialGuideObject.transform, "Tutorial Body", new Vector2(66f, -26f), new Vector2(268f, 31f), 8.5f, FontStyles.Normal);
        tutorialGuideObject.SetActive(false);
    }

@@ -936,4 +1195,413 @@ public class GameManager : MonoBehaviour {
        return null;
 #endif
    }
+
+    private class CourseMinimapView {
+        private struct MarkerInfo {
+            public string label;
+            public string kind;
+            public Color color;
+        }
+
+        private const float RootWidth = 452f;
+        private const float RootHeight = 72f;
+        private const float CourseWidth = 386f;
+        private const float CourseAreaHeight = 36f;
+        private const float CourseAreaY = -9f;
+        private const float GroundY = -22f;
+        private const float CeilingY = 3f;
+        private const float PlatformHeight = 6f;
+        private const float PlatformDistanceWidth = 7.4f;
+        private const float CourseDistancePerInterval = 10f;
+        private const int MaxCourseObjectCount = 96;
+
+        private readonly List<GameObject> markerObjects = new List<GameObject>();
+        private RectTransform rootRect;
+        private RectTransform progressFillRect;
+        private RectTransform playerMarkerRect;
+        private TextMeshProUGUI routeText;
+        private TextMeshProUGUI progressText;
+        private TMP_FontAsset fontAsset;
+        private bool hasActiveMap = false;
+        private MapId activeMapId;
+        private float activeTargetDistance = -1f;
+
+        public void Build(Transform canvasTransform, TMP_FontAsset minimapFont) {
+            fontAsset = minimapFont;
+
+            GameObject rootObject = new GameObject("Course Minimap", typeof(RectTransform), typeof(CanvasRenderer), typeof(Image));
+            rootObject.transform.SetParent(canvasTransform, false);
+
+            rootRect = rootObject.GetComponent<RectTransform>();
+            rootRect.anchorMin = new Vector2(0.5f, 0f);
+            rootRect.anchorMax = new Vector2(0.5f, 0f);
+            rootRect.pivot = new Vector2(0.5f, 0f);
+            rootRect.anchoredPosition = new Vector2(0f, 9f);
+            rootRect.sizeDelta = new Vector2(RootWidth, RootHeight);
+
+            Image background = rootObject.GetComponent<Image>();
+            background.color = new Color(0.025f, 0.045f, 0.055f, 0.78f);
+            background.raycastTarget = false;
+
+            routeText = CreateText(rootObject.transform, "Route Label", new Vector2(-207f, 24f), new Vector2(270f, 14f), 8.4f, TextAlignmentOptions.Left);
+            progressText = CreateText(rootObject.transform, "Route Progress", new Vector2(174f, 24f), new Vector2(94f, 14f), 8.4f, TextAlignmentOptions.Right);
+
+            CreateBlock(rootObject.transform, "Course Drawing Area", new Vector2(0f, CourseAreaY), new Vector2(CourseWidth + 18f, CourseAreaHeight), new Color(0.04f, 0.08f, 0.095f, 0.78f));
+
+            GameObject progressObject = new GameObject("Track Progress", typeof(RectTransform), typeof(CanvasRenderer), typeof(Image));
+            progressObject.transform.SetParent(rootObject.transform, false);
+
+            progressFillRect = progressObject.GetComponent<RectTransform>();
+            progressFillRect.anchorMin = new Vector2(0.5f, 0.5f);
+            progressFillRect.anchorMax = new Vector2(0.5f, 0.5f);
+            progressFillRect.pivot = new Vector2(0f, 0.5f);
+            progressFillRect.anchoredPosition = new Vector2(-CourseWidth * 0.5f, CourseAreaY);
+            progressFillRect.sizeDelta = new Vector2(0f, CourseAreaHeight);
+
+            Image progressImage = progressObject.GetComponent<Image>();
+            progressImage.color = new Color(0.18f, 0.55f, 0.68f, 0.28f);
+            progressImage.raycastTarget = false;
+
+            Image playerMarker = CreateBlock(rootObject.transform, "Player Marker", new Vector2(GetCourseX(0f), GroundY + 14f), new Vector2(7f, 24f), new Color(1f, 0.78f, 0.21f, 1f));
+            playerMarkerRect = playerMarker.rectTransform;
+        }
+
+        public void Refresh(MapDefinition mapDefinition, float stageDistance) {
+            if(rootRect == null)
+            {
+                return;
+            }
+
+            if(mapDefinition == null)
+            {
+                rootRect.gameObject.SetActive(false);
+                return;
+            }
+
+            rootRect.gameObject.SetActive(true);
+
+            float targetDistance = Mathf.Max(1f, mapDefinition.targetDistance);
+            bool mapChanged = !hasActiveMap
+                || activeMapId != mapDefinition.mapId
+                || !Mathf.Approximately(activeTargetDistance, targetDistance);
+
+            if(mapChanged)
+            {
+                hasActiveMap = true;
+                activeMapId = mapDefinition.mapId;
+                activeTargetDistance = targetDistance;
+                RebuildMarkers(mapDefinition, targetDistance);
+
+                if(routeText != null)
+                {
+                    routeText.text = !string.IsNullOrEmpty(mapDefinition.routeName)
+                        ? mapDefinition.routeName
+                        : mapDefinition.displayName;
+                }
+            }
+
+            float progress = Mathf.Clamp01(stageDistance / targetDistance);
+            if(progressFillRect != null)
+            {
+                progressFillRect.sizeDelta = new Vector2(CourseWidth * progress, CourseAreaHeight);
+            }
+
+            if(playerMarkerRect != null)
+            {
+                playerMarkerRect.anchoredPosition = new Vector2(GetCourseX(progress), GroundY + 14f);
+                playerMarkerRect.SetAsLastSibling();
+            }
+
+            if(progressText != null)
+            {
+                progressText.text = Mathf.FloorToInt(stageDistance) + "/" + Mathf.FloorToInt(targetDistance) + "m";
+            }
+        }
+
+        private void RebuildMarkers(MapDefinition mapDefinition, float targetDistance) {
+            ClearMarkers();
+
+            float cursor = 0f;
+            AddStepMarkers(mapDefinition.openingSteps, ref cursor, targetDistance);
+
+            PlatformSpawner.TutorialStep[] loopSteps = mapDefinition.loopSteps;
+            int loopGuard = 0;
+            while(cursor < targetDistance
+                && loopSteps != null
+                && loopSteps.Length > 0
+                && markerObjects.Count < MaxCourseObjectCount
+                && loopGuard < 300)
+            {
+                AddStepMarkers(loopSteps, ref cursor, targetDistance);
+                loopGuard++;
+            }
+        }
+
+        private void AddStepMarkers(PlatformSpawner.TutorialStep[] steps, ref float cursor, float targetDistance) {
+            if(steps == null)
+            {
+                return;
+            }
+
+            for(int i = 0; i < steps.Length; i++)
+            {
+                PlatformSpawner.TutorialStep step = steps[i];
+                float stepDistance = GetStepDistance(step);
+
+                if(markerObjects.Count < MaxCourseObjectCount)
+                {
+                    float centerDistance = cursor + (stepDistance * 0.5f);
+                    float centerProgress = Mathf.Clamp01(centerDistance / targetDistance);
+                    float platformWidth = Mathf.Max(8f, CourseWidth * (PlatformDistanceWidth / targetDistance));
+                    CreatePlatformPiece(centerProgress, platformWidth, GetPlatformColor(step));
+
+                    if(TryGetMarkerInfo(step, out MarkerInfo markerInfo))
+                    {
+                        CreateCourseFeature(centerProgress, markerInfo);
+                    }
+                }
+
+                cursor += stepDistance;
+                if(cursor >= targetDistance && markerObjects.Count >= MaxCourseObjectCount)
+                {
+                    return;
+                }
+            }
+        }
+
+        private float GetStepDistance(PlatformSpawner.TutorialStep step) {
+            if(step == null)
+            {
+                return CourseDistancePerInterval;
+            }
+
+            return Mathf.Max(0.3f, step.spawnInterval) * CourseDistancePerInterval;
+        }
+
+        private bool TryGetMarkerInfo(PlatformSpawner.TutorialStep step, out MarkerInfo markerInfo) {
+            markerInfo = new MarkerInfo();
+
+            if(step == null)
+            {
+                return false;
+            }
+
+            if(step.itemPattern != Platform.ItemPattern.None)
+            {
+                markerInfo.label = GetItemMarkerLabel(step.itemPattern);
+                markerInfo.color = new Color(0.38f, 0.93f, 0.57f, 0.98f);
+                markerInfo.kind = "Item";
+                return true;
+            }
+
+            if(step.coursePlatformType == PlatformSpawner.CoursePlatformType.ForceHit
+                || step.platformPattern == Platform.PlatformPattern.ForceHit)
+            {
+                markerInfo.label = "!";
+                markerInfo.color = new Color(1f, 0.34f, 0.28f, 0.98f);
+                markerInfo.kind = "ForceHit";
+                return true;
+            }
+
+            if(step.guideType == TutorialGuideType.DoubleJump || step.spawnInterval >= 1.4f)
+            {
+                markerInfo.label = "2";
+                markerInfo.color = new Color(0.40f, 0.89f, 1f, 0.98f);
+                markerInfo.kind = "DoubleJump";
+                return true;
+            }
+
+            if(step.coursePlatformType == PlatformSpawner.CoursePlatformType.Slide
+                || step.platformPattern == Platform.PlatformPattern.Slide)
+            {
+                markerInfo.label = "S";
+                markerInfo.color = new Color(0.47f, 0.63f, 1f, 0.98f);
+                markerInfo.kind = "Slide";
+                return true;
+            }
+
+            if(step.coursePlatformType == PlatformSpawner.CoursePlatformType.Jump
+                || step.platformPattern == Platform.PlatformPattern.LowLeft
+                || step.platformPattern == Platform.PlatformPattern.LowMid
+                || step.platformPattern == Platform.PlatformPattern.LowRight)
+            {
+                markerInfo.label = "J";
+                markerInfo.color = new Color(1f, 0.83f, 0.28f, 0.98f);
+                markerInfo.kind = "Jump";
+                return true;
+            }
+
+            return false;
+        }
+
+        private string GetItemMarkerLabel(Platform.ItemPattern itemPattern) {
+            switch(itemPattern)
+            {
+                case Platform.ItemPattern.HealthSushi:
+                    return "+";
+                case Platform.ItemPattern.InvincibleRamen:
+                    return "R";
+                case Platform.ItemPattern.Shield:
+                    return "G";
+                case Platform.ItemPattern.SpeedShoes:
+                    return "V";
+                case Platform.ItemPattern.MileageCard:
+                    return "M";
+                default:
+                    return "I";
+            }
+        }
+
+        private void CreatePlatformPiece(float progress, float width, Color color) {
+            Image platformImage = CreateBlock(rootRect, "Course Platform", new Vector2(GetCourseX(progress), GroundY), new Vector2(width, PlatformHeight), color);
+            markerObjects.Add(platformImage.gameObject);
+        }
+
+        private Color GetPlatformColor(PlatformSpawner.TutorialStep step) {
+            if(step != null && step.spawnInterval >= 1.4f)
+            {
+                return new Color(0.28f, 0.50f, 0.57f, 0.96f);
+            }
+
+            return new Color(0.33f, 0.63f, 0.70f, 0.96f);
+        }
+
+        private void CreateCourseFeature(float progress, MarkerInfo markerInfo) {
+            if(markerInfo.kind == "Slide")
+            {
+                CreateSlideFeature(progress, markerInfo);
+                return;
+            }
+
+            if(markerInfo.kind == "ForceHit")
+            {
+                CreateJumpFeature(progress, markerInfo);
+                CreateSlideFeature(progress, markerInfo);
+                return;
+            }
+
+            if(markerInfo.kind == "Item")
+            {
+                CreateItemFeature(progress, markerInfo);
+                return;
+            }
+
+            if(markerInfo.kind == "DoubleJump")
+            {
+                CreateDoubleJumpFeature(progress, markerInfo);
+                return;
+            }
+
+            CreateJumpFeature(progress, markerInfo);
+        }
+
+        private void CreateJumpFeature(float progress, MarkerInfo markerInfo) {
+            float x = GetCourseX(progress);
+            Image obstacle = CreateBlock(rootRect, "Jump Obstacle", new Vector2(x, GroundY + 8f), new Vector2(10f, 12f), markerInfo.color);
+            markerObjects.Add(obstacle.gameObject);
+            CreateTinyLabel(markerInfo.label, new Vector2(x, GroundY + 8f), new Color(0.02f, 0.04f, 0.05f, 0.95f));
+        }
+
+        private void CreateSlideFeature(float progress, MarkerInfo markerInfo) {
+            float x = GetCourseX(progress);
+            Image ceiling = CreateBlock(rootRect, "Slide Ceiling", new Vector2(x, CeilingY), new Vector2(32f, 6f), new Color(0.56f, 0.70f, 0.98f, 0.95f));
+            markerObjects.Add(ceiling.gameObject);
+            Image hanging = CreateBlock(rootRect, "Slide Hanging Obstacle", new Vector2(x, CeilingY - 8f), new Vector2(18f, 10f), markerInfo.color);
+            markerObjects.Add(hanging.gameObject);
+            CreateTinyLabel(markerInfo.label, new Vector2(x, CeilingY - 8f), new Color(0.02f, 0.04f, 0.05f, 0.95f));
+        }
+
+        private void CreateItemFeature(float progress, MarkerInfo markerInfo) {
+            float x = GetCourseX(progress);
+            GameObject markerObject = new GameObject("Course Marker " + markerInfo.label, typeof(RectTransform), typeof(CanvasRenderer), typeof(Image));
+            markerObject.transform.SetParent(rootRect, false);
+
+            RectTransform markerRect = markerObject.GetComponent<RectTransform>();
+            markerRect.anchorMin = new Vector2(0.5f, 0.5f);
+            markerRect.anchorMax = new Vector2(0.5f, 0.5f);
+            markerRect.pivot = new Vector2(0.5f, 0.5f);
+            markerRect.anchoredPosition = new Vector2(x, GroundY + 15f);
+            markerRect.sizeDelta = new Vector2(11f, 11f);
+
+            Image markerImage = markerObject.GetComponent<Image>();
+            markerImage.color = markerInfo.color;
+            markerImage.raycastTarget = false;
+
+            TextMeshProUGUI markerText = CreateText(markerObject.transform, "Label", Vector2.zero, new Vector2(11f, 11f), 6.4f, TextAlignmentOptions.Center);
+            markerText.color = new Color(0.02f, 0.04f, 0.05f, 0.95f);
+            markerText.fontStyle = FontStyles.Bold;
+            markerText.text = markerInfo.label;
+
+            markerObjects.Add(markerObject);
+        }
+
+        private void CreateDoubleJumpFeature(float progress, MarkerInfo markerInfo) {
+            float x = GetCourseX(progress);
+            Image gapMarker = CreateBlock(rootRect, "Double Jump Gap", new Vector2(x, GroundY + 14f), new Vector2(24f, 3f), markerInfo.color);
+            markerObjects.Add(gapMarker.gameObject);
+            CreateTinyLabel(markerInfo.label, new Vector2(x, GroundY + 21f), markerInfo.color);
+        }
+
+        private void CreateTinyLabel(string label, Vector2 anchoredPosition, Color color) {
+            TextMeshProUGUI markerText = CreateText(rootRect, "Course Label " + label, anchoredPosition, new Vector2(14f, 11f), 6.4f, TextAlignmentOptions.Center);
+            markerText.color = color;
+            markerText.fontStyle = FontStyles.Bold;
+            markerText.text = label;
+            markerObjects.Add(markerText.gameObject);
+        }
+
+        private TextMeshProUGUI CreateText(Transform parent, string objectName, Vector2 anchoredPosition, Vector2 sizeDelta, float fontSize, TextAlignmentOptions alignment) {
+            GameObject textObject = new GameObject(objectName, typeof(RectTransform), typeof(CanvasRenderer));
+            textObject.transform.SetParent(parent, false);
+
+            RectTransform textRect = textObject.GetComponent<RectTransform>();
+            textRect.anchorMin = new Vector2(0.5f, 0.5f);
+            textRect.anchorMax = new Vector2(0.5f, 0.5f);
+            textRect.pivot = new Vector2(0.5f, 0.5f);
+            textRect.anchoredPosition = anchoredPosition;
+            textRect.sizeDelta = sizeDelta;
+
+            TextMeshProUGUI text = textObject.AddComponent<TextMeshProUGUI>();
+            text.font = fontAsset;
+            text.alignment = alignment;
+            text.fontSize = fontSize;
+            text.color = new Color(0.88f, 0.96f, 1f, 0.92f);
+            text.raycastTarget = false;
+            text.textWrappingMode = TextWrappingModes.NoWrap;
+            return text;
+        }
+
+        private Image CreateBlock(Transform parent, string objectName, Vector2 anchoredPosition, Vector2 sizeDelta, Color color) {
+            GameObject blockObject = new GameObject(objectName, typeof(RectTransform), typeof(CanvasRenderer), typeof(Image));
+            blockObject.transform.SetParent(parent, false);
+
+            RectTransform blockRect = blockObject.GetComponent<RectTransform>();
+            blockRect.anchorMin = new Vector2(0.5f, 0.5f);
+            blockRect.anchorMax = new Vector2(0.5f, 0.5f);
+            blockRect.pivot = new Vector2(0.5f, 0.5f);
+            blockRect.anchoredPosition = anchoredPosition;
+            blockRect.sizeDelta = sizeDelta;
+
+            Image image = blockObject.GetComponent<Image>();
+            image.color = color;
+            image.raycastTarget = false;
+            return image;
+        }
+
+        private float GetCourseX(float progress) {
+            return (-CourseWidth * 0.5f) + (CourseWidth * Mathf.Clamp01(progress));
+        }
+
+        private void ClearMarkers() {
+            for(int i = 0; i < markerObjects.Count; i++)
+            {
+                if(markerObjects[i] != null)
+                {
+                    Object.Destroy(markerObjects[i]);
+                }
+            }
+
+            markerObjects.Clear();
+        }
+    }
 }