Travel_Run/Docs/systems.md

# Systems

게임의 주요 시스템 구조를 정리합니다.

## Scene Flow

`GameFlowManager`가 전체 흐름을 관리합니다.
결과 화면, 면세점, 디버그 메뉴의 UI 생성 코드는 `Flow/Screens` partial 파일로 분리했습니다.

```text
Intro
-> Opening Story
-> MapPreview
-> Main
-> Result
-> DutyFreeShop
-> MapPreview
```

## Save / Load

관련 파일:

- `Assets/Scripts/Flow/GameSaveData.cs`
- `Assets/Scripts/Flow/GameSaveManager.cs`

저장하는 것:

- 현재 맵 인덱스
- 해금된 맵 인덱스
- 총 마일리지
- 면세점 구매 아이템 수량
- 가방 슬롯 수와 장착 슬롯 상태
- 영양제 구매 수
- 스테이지별 마일리지 카드/영양제 1회 구매 제한 상태

## Map Data

관련 파일:

- `Assets/Scripts/Maps/MapId.cs`
- `Assets/Scripts/Maps/MapDefinition.cs`
- `Assets/Scripts/Maps/MapDatabase.cs`
- `Assets/Scripts/Maps/Definitions/*.cs`
- `Assets/Scripts/Course/*.cs`

역할:

- 맵 이름
- 배경
- 발판 스킨
- 도착 지점
- 목표 거리
- 제한 시간
- 보상
- 다음 맵
- 코스 패턴

`MapDefinition`은 `CourseProfile`을 우선 참조합니다.
맵 생성 코드는 `Maps/Definitions/*Map.cs`로 분리했고, 각 맵은 `Course/Profiles/*CourseProfile.cs`를 연결합니다.
`openingSteps`, `loopSteps`는 이전 구조와의 호환용 fallback으로 남겨 둡니다.

목표 구조:

```text
MapDatabase
-> TutorialIncheonMap.Create()
-> JapanMap.Create()
-> ChinaMap.Create()
-> AmericaMap.Create()

MapDefinition
-> CourseProfile

PlatformSpawner
-> CourseProfile opening/loop 실행
```

## Gameplay Runtime

관련 파일:

- `Assets/Scripts/GameManager.cs`
- `Assets/Scripts/PlayerController.cs`
- `Assets/Scripts/PlatformSpawner.cs`
- `Assets/Scripts/Platform.cs`
- `Assets/Scripts/ItemPickup.cs`
- `Assets/Scripts/ItemFeedbackEffect.cs`
- `Assets/Scripts/MileagePickup.cs`
- `Assets/Scripts/FinishGate.cs`

역할:

- 게임 속도 증가
- 거리/시간 계산
- 목숨/피격/무적
- 아이템 효과
- 발판/장애물/아이템 스폰
- 아이템 획득/방어 성공 이펙트
- 도착 지점 통과 시 클리어

현재 `GameManager`는 플레이 진행과 UI를 함께 담당합니다.
리팩터링 후에는 아래처럼 책임을 나눕니다.

| 책임 | 목표 스크립트 |
| --- | --- |
| 플레이 세션 총괄 | `GameManager` |
| 거리/시간/클리어 판정 | `StageProgressTracker` |
| 도착 게이트 생성/정리 | `FinishGateController` |
| 목숨/피격/무적 | `DamageController` |
| 아이템 효과 | `ItemEffectController` |
| 왼쪽/오른쪽 HUD | `GameplayHudView` |
| 튜토리얼 안내창 | `TutorialGuideView` |
| 튜토리얼 단계 제어 | `TutorialGuideController` |

## Flow UI

현재 상태:

- `GameFlowManager` 안에 인트로, 오프닝 스토리, 맵 프리뷰 UI 생성 코드가 남아 있음
- 공통 UI 오브젝트 생성과 에셋 로딩도 같은 파일에 있음
- 결과 화면, 면세점, 디버그 메뉴 UI 생성 코드는 `Assets/Scripts/Flow/Screens`로 먼저 이동함
- 구매/저장/장착 로직은 안정성을 위해 아직 본체에 남아 있음
- 맵 프리뷰는 인트로 세계지도 리소스와 비행기 경로 모션을 재사용해 다음 여행지 이동을 보여주며, 왼쪽 설명 패널은 표시하지 않음

목표 구조:

| 책임 | 목표 스크립트 |
| --- | --- |
| 흐름 제어 | `GameFlowManager` |
| 현재 화면 상태와 공통 데이터 | `FlowScreenContext` |
| 인트로 화면 | `IntroScreenView` |
| 오프닝 스토리 | `OpeningStoryScreenView` |
| 결과 화면 | `ResultScreenView` |
| 면세점 화면 | `DutyFreeShopView` |
| 맵 프리뷰 | `MapPreviewScreenView` |
| 디버그 메뉴 | `DebugMenuView` |
| 공통 UI 생성 | `FlowUiFactory` |
| UI 에셋 로딩 | `FlowAssetLoader` |

디버그 메뉴는 현재 `Esc`로 열며, 인트로/현재 맵 시작/출국 실패/출국 성공/면세점/지도 화면으로 바로 이동합니다.
일본, 중국, 미국은 각각 게임시작과 출국성공 프리뷰 버튼을 따로 제공합니다.
리팩터링 후에도 개발 빌드 전용 기능으로 유지합니다.

## DutyFreeShop

현재 상태:

- 화면 흐름은 있음
- 코드 오버레이 화면은 면세점 내부 배경과 상품 카드형 UI로 표시함
- 판매 아이템은 도시락, 영양제, 마일리지 카드, 가방 업그레이드
- 도시락과 마일리지 카드는 가방 슬롯에 장착해서 다음 스테이지에서 사용
- 영양제는 장착 아이템이 아니라 누적 구매형 최대 HP 증가 아이템
- 가방 업그레이드는 활성 슬롯을 최대 3칸까지 늘림
- 구매 데이터와 장착 슬롯은 저장/로드됨

구매 제한:

1. 가방 칸보다 많은 장착형 아이템은 살 수 없음
2. 도시락은 현재 최대 목숨 수보다 많이 살 수 없음
3. 보유 마일리지가 부족하면 살 수 없음
4. 영양제와 마일리지 카드는 한 스테이지당 1개만 살 수 있음

다음 방향:

1. Unity Play 모드에서 구매/장착/소모 흐름 확인
2. 면세점 UI에서 부족/슬롯 가득/1회 완료 상태가 잘 읽히는지 확인
3. 필요하면 구매 피드백 효과 추가

## Stage Backgrounds

현재 맵별 런타임 배경:

- 튜토리얼/인천: `StageBackgrounds/Incheon/Stage_Incheon_DarkLower_Segment_*`
- 일본: `Map_Japan_Fukuoka`
- 중국: `Map_China_Beijing`
- 미국: `Map_America_NewYork`

`BackgroundLoop`는 단일 `backgroundResourcePath`와 여러 장의 `backgroundResourcePaths`를 모두 처리합니다.
여러 배경 조각이 들어오면 왼쪽/오른쪽 배경 오브젝트에 순서대로 스프라이트를 배정하고, 루프될 때 다음 조각으로 넘깁니다.
인천 배경은 현재 임시 캔버스 보정본이 적용되어 있으므로 최종 16:9 원화로 다시 교체할 예정입니다.

## Finish Gate

`FinishGate`는 맵별 도착 지점 이미지를 `Resources`에서 불러옵니다.

현재 도착 지점:

- 튜토리얼: 출국 게이트
- 일본: 토리이
- 중국: 패방
- 미국: 자유의 여신상/뉴욕 도착지

플레이어가 도착 지점 트리거를 통과하면 클리어 처리합니다.
도착 게이트가 생성될 때는 `PlatformSpawner`가 빈 착지 발판을 같은 위치에 함께 깔아, 게이트가 배경 위에 떠 보이지 않게 합니다.
도착 게이트 뒤로는 새 발판, 장애물, 아이템 코스가 더 생성되지 않도록 스폰을 중지합니다.

## Minimap

하단 미니맵은 현재 삭제했습니다.

이유:

- 현재 튜토리얼/코스 설계에는 화면 하단 미니맵보다 실제 발판과 도착 지점 가독성이 중요합니다.
- 이후 필요하면 별도 작은 진행 바 형태로 다시 설계합니다.