# TravelRun 설계도

이 문서는 프로젝트를 다시 열었을 때 가장 먼저 보는 전체 설계도입니다. 세부 내용은 각 문서로 분리하고, 여기서는 어디를 보면 되는지와 현재 구조만 정리합니다.

## 읽는 순서

```text
README.md
-> Docs/blueprint.md
-> 필요한 세부 문서
```

세부 문서:

| 문서 | 확인할 내용 |
| --- | --- |
| [design.md](design.md) | 화면 구성, UX, 아트 방향 |
| [assets.md](assets.md) | 현재 이미지 에셋, 사용 위치, 교체 기준 |
| [gameplay.md](gameplay.md) | 조작, 장애물, 아이템, 클리어 조건 |
| [maps.md](maps.md) | 맵별 배경, 도착 지점, 패턴 방향 |
| [systems.md](systems.md) | 씬 흐름, 저장/로드, 면세점, 맵 해금 |
| [refactor-plan.md](refactor-plan.md) | 스크립트 책임 분리와 리팩터링 순서 |
| [feedback.md](feedback.md) | 날짜별 수정 기록과 다음 할 일 |

## 게임 핵심

TravelRun은 여행 테마 2D 러너입니다.

플레이어는 집에서 여행 영상을 보고 출발하며, 인천공항 튜토리얼을 지나 일본, 중국, 미국으로 이동합니다. 각 맵은 정해진 시간 안에 목적지까지 도착하는 구조입니다.

핵심 재미:

- 점프, 2단 점프, 슬라이드의 명확한 체험
- 클리어 가능한 패턴 기반 코스
- 마일리지 수집과 면세점 준비
- 국가별 배경, 장애물, 도착 지점 이미지
- 여행지 클리어와 다음 여행지 해금

## 전체 씬 흐름

```text
Intro
-> Opening Story
-> MapPreview
-> Main(Game)
-> Result
-> DutyFreeShop
-> MapPreview
```

역할:

| 씬 | 역할 |
| --- | --- |
| `Intro` | 세계지도 기반 타이틀, 시작/이어하기/설정 |
| `Opening Story` | 처음 시작 시 만화 컷신 |
| `MapPreview` | 다음 목적지와 목표 확인 |
| `Main` | 실제 러너 플레이 |
| `Result` | 클리어/실패 결과, 보상 |
| `DutyFreeShop` | 마일리지로 다음 스테이지 준비 |

## 현재 맵 구성

| 순서 | 맵 | 목적 |
| --- | --- | --- |
| 0 | Tutorial / Incheon | 조작과 아이템 학습 |
| 1 | Japan | 첫 일반 맵 |
| 2 | China | 지역 스킨과 난이도 확장 |
| 3 | America | 뉴욕/자유의 여신상 도착 |

자세한 맵별 자료는 [maps.md](maps.md)를 봅니다.

## 코스 설계 원칙

랜덤 배치가 아니라 검증된 패턴을 이어붙이는 방식으로 갑니다.

튜토리얼 코스와 일반 여행 맵 코스는 분리합니다.
튜토리얼은 조작 학습과 아이템 체험을 담당하고, 일본/중국/미국은 일반 반복 패턴과 맵별 난이도 차이를 담당합니다.

```text
기본 발판
-> 점프 장애물
-> 2단 점프 거리
-> 슬라이드 장애물
-> 강제 피격 체험
-> 아이템 체험
-> 도착 지점
```

이 방식은 플레이어가 왜 그 조작을 해야 하는지 실제로 체험하게 만듭니다.

## 현재 구조 정리 방향

현재 `GameFlowManager`, `GameManager`, `MapDatabase`, `PlatformSpawner`에 책임이 크게 모여 있습니다.
동작을 바꾸기보다 책임을 분리하는 방향으로 정리합니다.

우선순위:

1. 완료: `PlatformSpawner.TutorialStep`을 `CourseStep`으로 독립
2. 완료: 맵별 정의를 `Maps/Definitions`로 분리
3. 완료: 튜토리얼/일본/중국/미국 코스를 `CourseProfile`로 분리
4. 완료: `PlatformSpawner`의 fallback 코스를 `FallbackCourseProfile`로 이동
5. 진행: 결과 화면, 면세점, 디버그 메뉴를 화면 View 파일로 분리
6. 게임 HUD와 튜토리얼 안내창을 `GameManager`에서 분리

자세한 기준은 [refactor-plan.md](refactor-plan.md)를 봅니다.

## 문서 운영 규칙

- `README.md`는 짧은 입구로 유지합니다.
- 실제 전체 구조는 이 `blueprint.md`에 정리합니다.
- 구현 기록은 `feedback.md`에 날짜별로 남깁니다.
- 이미지 목록과 사용 여부는 `assets.md`에만 적습니다.
- 맵별 수치와 방향은 `maps.md`에만 적습니다.
- 시스템 구조는 `systems.md`에만 적습니다.

## 다음 작업 우선순위

1. 인천 튜토리얼 배경을 현재 화면비에 맞춘 새 16:9 배경 조각으로 다시 제작
2. Unity Play 모드에서 결과/면세점/맵 프리뷰 화면의 실제 배치 확인
3. `GameManager`의 HUD와 튜토리얼 안내창을 별도 스크립트로 분리
4. 일본, 중국, 미국 맵의 반복 패턴과 난이도 미세 조정
5. 인트로/오프닝/맵 프리뷰 화면도 같은 방식으로 View 파일 분리