Uniy_run/README.md

# Uni-Run

`Uni-Run`은 마우스 입력만으로 조작하는 2D 스피드 러너 게임 프로젝트입니다.

현재 프로젝트는 자동으로 오른쪽을 향해 달리는 기본 러너 구조를 가지고 있으며, 점프, 충돌, 발판 스폰, 점수, 게임 오버 흐름을 학습하기 좋은 공부용 게임입니다. 앞으로는 이 기본 구조를 바탕으로 여행 콘셉트, 제한 시간, 마일리지, 면세점, 기념품 수집, 패턴 기반 맵 생성이 결합된 러너 게임으로 발전시키는 것을 목표로 합니다.

## 게임 콘셉트

플레이어는 한국에서 튜토리얼을 진행하며 인천공항으로 향하고, 이후 비행기를 타고 일본, 중국, 미국 등 여러 여행지를 방문합니다.

각 여행지는 여러 도시 스테이지로 구성되며, 플레이어는 정해진 여행 일정 안에 목적지까지 도착해야 합니다. 빠르게 도착하고, 마일리지를 많이 모으고, 기념품을 수집하는 것이 핵심 목표입니다.

## 기본 게임 흐름

```text
한국 튜토리얼
-> 인천공항 도착
-> 비행기 이동 연출
-> 여행 국가 진입
-> 도시 스테이지 3개 진행
-> 기념품 획득
-> 면세점에서 마일리지 사용
-> 다음 여행지 해금
```

초기 월드 구성은 다음과 같습니다.

| 국가 | 스테이지 |
| --- | --- |
| 일본 | 후쿠오카, 오사카, 도쿄 |
| 중국 | 베이징, 사천, 홍콩 |
| 미국 | LA, 올랜도, 뉴욕 |

처음 구현 범위는 `한국 튜토리얼 + 일본 월드 3스테이지`를 기준으로 잡습니다.

## 조작

조작은 마우스 두 버튼으로 단순하게 유지합니다.

| 입력 | 기능 |
| --- | --- |
| 마우스 왼쪽 클릭 | 점프 |
| 마우스 오른쪽 클릭 유지 | 슬라이딩 |

슬라이딩은 중간에 해금하지 않고 튜토리얼부터 사용합니다. 초반부터 점프와 슬라이딩을 함께 익히게 하여, 후반 난이도 상승이 새로운 조작 때문이 아니라 플레이어의 반응과 숙련도 문제로 느껴지게 합니다.

튜토리얼에서 익히는 기본 패턴은 다음과 같습니다.

- 낮은 장애물은 점프로 피한다.
- 높은 장애물은 슬라이딩으로 피한다.
- 점프 후 슬라이딩을 연속으로 사용한다.
- 슬라이딩 후 점프를 연속으로 사용한다.

## 스테이지 목표

스테이지는 단순히 오래 살아남는 방식이 아니라, 정해진 여행 일정 안에 목적지까지 도착하는 방식입니다.

```text
목표 거리 도달 + 제한 시간 내 도착 = 클리어
제한 시간 초과 = 실패
목숨 0 = 실패
일찍 도착 = 추가 점수
```

예시 목표는 다음과 같습니다.

| 스테이지 | 목표 예시 |
| --- | --- |
| 한국 튜토리얼 | 인천공항 체크인 시간 맞추기 |
| 후쿠오카 | 라멘 투어 예약 시간 맞추기 |
| 오사카 | 도톤보리 일정 시간 맞추기 |
| 도쿄 | 다음 비행기 또는 열차 시간 맞추기 |

장애물에 부딪히면 속도가 줄어들기 때문에, 실수는 목숨 손실뿐 아니라 도착 시간 손해로 이어집니다.

## 목숨과 속도 시스템

기본 목숨은 `3개`입니다.

게임이 진행될수록 속도는 조금씩 빨라집니다. 장애물에 부딪히면 목숨이 줄고, 현재 속도가 감소합니다. 이후 잠깐의 무적 시간을 주어 연속 충돌로 목숨이 한 번에 사라지는 상황을 막습니다.

```text
충돌
-> 목숨 -1
-> 속도 감소
-> 짧은 무적 시간
-> 다시 진행
```

목숨은 점수 보너스가 아니라 생존 자원입니다. 따라서 남은 목숨 보너스는 넣지 않습니다. 목숨을 잘 지키면 속도 감소가 적어지고, 결과적으로 더 빨리 도착할 수 있으므로 간접적으로 점수에 영향을 줍니다.

## 점수 구조

점수는 생존보다 빠른 도착과 수집 중심으로 계산합니다.

| 항목 | 점수 반영 |
| --- | --- |
| 스테이지 클리어 | 기본 점수 |
| 빠른 도착 | 시간 보너스 |
| 마일리지 수집 | 점수 및 재화 |
| 모든 마일리지 수집 | 퍼펙트 수집 보너스 |
| 남은 목숨 | 점수 반영 없음 |
| 아이템 사용 | 점수 반영 없음 |

아이템은 직접 점수를 주는 것이 아니라, 더 빠르게 도착하거나 더 많은 마일리지를 먹을 수 있게 도와주는 간접 요소로 둡니다.

최고점은 다음 조건을 함께 만족해야 가능하도록 설계합니다.

```text
빠른 도착
+ 모든 마일리지 수집
+ 최적의 면세점 아이템 준비
+ 충돌 최소화
+ 반복 플레이를 통한 루트 숙지
```

## 마일리지와 면세점

마일리지는 스테이지 중 수집하는 재화입니다. 스테이지 클리어 후 면세점에서 다음 스테이지를 준비하는 데 사용합니다.

면세점은 플레이어가 다음 스테이지를 어떻게 버틸지 결정하는 준비 공간입니다.

| 상품 | 효과 |
| --- | --- |
| 도시락 | 다음 스테이지 중 목숨 회복용. 구매 즉시 이전 스테이지에서 깎인 체력을 회복하지 않음 |
| 운동화 | 충돌 시 속도 감소량 완화 |
| 가방 | 아이템 저장칸 증가. 기본 1칸, 최대 3칸 |
| 여행 보험 또는 방어막 | 충돌 1회 방어 |
| 교통패스 | 마일리지 획득량 증가 |

도시락은 구매 즉시 체력을 회복하지 않습니다. 예를 들어 이전 스테이지를 목숨 1개로 클리어했다면, 면세점에서 도시락을 사도 바로 목숨이 2개가 되지 않습니다. 대신 도시락은 다음 스테이지 중 회복 보험처럼 사용됩니다.

가방은 전략성을 높이는 핵심 아이템입니다.

| 가방 등급 | 저장칸 |
| --- | --- |
| 기본 가방 | 1칸 |
| 고급 가방 | 2칸 |
| 특급 가방 | 3칸 |

면세점 상품은 진행도에 따라 해금됩니다.

```text
1단계: 기본 아이템 2~3개
2단계: 추가 아이템 + 일부 고급 아이템
3단계: 전체 아이템 + 고급/특급 아이템
```

이 해금 구조는 일본, 중국, 미국 월드에 동일하게 적용합니다.

## 지역 아이템

아이템 효과는 공통으로 유지하되, 이름과 외형은 지역 특산물과 음식에 맞춥니다.

| 효과 | 일본 | 중국 | 미국 |
| --- | --- | --- | --- |
| 목숨 회복 | 초밥 도시락 | 딤섬 도시락 | 버거 세트 |
| 무적 | 라멘 | 마라탕 | 에너지드링크 |
| 방어막 | 오마모리 | 옥 펜던트 | 여행 보험 카드 |
| 마일리지 증가 | 교통패스 | 고속철 패스 | 시티패스 |

이 방식은 시스템을 재사용하면서도, 여행지마다 다른 분위기와 수집 재미를 줄 수 있습니다.

## 기념품 시스템

스테이지 완료 보상은 기념품으로 합니다. 기념품은 소비하지 않고 수집됩니다.

기념품 보관 방식은 집 냉장고에 마그넷을 붙이는 형태가 잘 어울립니다. 플레이어는 여행지를 클리어할수록 냉장고나 여행 앨범에 기념품을 채워나갑니다.

예시 기념품은 다음과 같습니다.

| 스테이지 | 기본 기념품 | 추가 기념품 |
| --- | --- | --- |
| 한국 튜토리얼 | 인천공항 탑승권 | 첫 여행 도장 |
| 후쿠오카 | 라멘 마그넷 | 포장마차 사진 |
| 오사카 | 타코야키 키링 | 도톤보리 배지 |
| 도쿄 | 도쿄타워 마그넷 | 전철 패스 기념권 |

기념품은 점수와 분리된 수집 요소입니다. 점수는 빠른 도착과 마일리지 수집에서 나오고, 기념품은 클리어와 도전 과제의 완료 증표 역할을 합니다.

## 맵 생성 방향

현재 구조처럼 장애물과 발판을 개별 랜덤으로 배치하면, 클리어 불가능한 구간이 생기거나 맵이 단순하게 느껴질 수 있습니다.

따라서 맵 생성은 개별 오브젝트 랜덤이 아니라, 사람이 직접 검증한 패턴 묶음을 랜덤으로 조합하는 방식으로 개선합니다.

```text
기존 방식:
장애물 개별 랜덤 생성

개선 방식:
검증된 패턴 선택
-> 패턴 안의 장애물, 마일리지, 아이템 배치
-> 기존 오브젝트 풀링으로 실제 오브젝트 재사용
```

예시 패턴은 다음과 같습니다.

| 패턴 | 요구 조작 |
| --- | --- |
| Safe | 쉬는 구간 |
| Jump | 점프 |
| Slide | 슬라이딩 |
| JumpSlide | 점프 후 슬라이딩 |
| SlideJump | 슬라이딩 후 점프 |
| CoinRoute | 마일리지 수집 루트 |
| ItemRoute | 아이템 획득 루트 |
| Expert | 빠른 반응 요구 |

어려운 패턴 연속은 허용합니다. 갈수록 도전 욕구가 생기도록 후반부에는 빠른 속도와 짧은 반응 시간을 요구할 수 있습니다.

다만 물리적으로 불가능한 배치는 금지합니다.

- 장애물 사이에는 최소 반응 거리가 필요하다.
- 점프 착지 직후 바로 슬라이딩 장애물을 배치하지 않는다. 단, 충분한 간격이 있으면 가능하다.
- 슬라이딩 직후 바로 점프 장애물을 배치하지 않는다. 단, 충분한 간격이 있으면 가능하다.
- 회복 및 아이템 패턴은 의도적으로 배치한다.
- 모든 패턴은 실제 플레이로 클리어 가능한지 검증한다.

## 난이도 방향

플레이어는 시간이 지날수록 패턴에 적응하므로, 후반부는 아슬하게 깰 수 있도록 설계합니다.

```text
초반: 조작 학습
중반: 점프/슬라이딩 조합
후반: 빠른 속도 + 짧은 반응 시간
최종: 패턴 숙지 + 반응 속도 모두 필요
```

속도가 빨라진다고 해서 장애물 간격을 무조건 넓히지 않습니다. 이 게임의 재미는 반응 속도와 패턴 숙지에서 나오므로, 후반부는 어렵지만 가능한 조합을 연속으로 배치해 도전 욕구를 만듭니다.

## 현재 구현 상태

현재까지 반영된 주요 작업은 다음과 같습니다.

- 게임 속도 증가 시스템 기초 추가
- `ScrollingObject`가 `GameManager.gameSpeed`를 반영하도록 변경
- 오른쪽 클릭 슬라이딩 기초 구조 추가
- 플레이어 콜라이더를 `CapsuleCollider2D` 기반으로 변경
- 슬라이딩용 `JJ_Slide` 스프라이트 시트 추가

## 다음 개발 우선순위

1. 목숨 3개 시스템 추가
2. 장애물 충돌 시 즉사 대신 목숨 감소 처리
3. 충돌 시 현재 속도 감소 처리
4. 충돌 후 짧은 무적 시간 추가
5. 슬라이딩 충돌 판정과 애니메이션 연결 확인
6. 높은 장애물 추가
7. 목표 거리와 제한 시간 기반 스테이지 클리어 구조 추가
8. 패턴 기반 맵 생성 구조 설계
9. 마일리지와 면세점 기초 구현
10. 기념품 수집 화면 기획 및 구현

## 최종 목표

`Uni-Run`의 최종 목표는 마우스 두 버튼만으로 조작하는 여행 테마 2D 스피드 러너 게임입니다.

플레이어는 점프와 슬라이딩으로 장애물을 피하고, 마일리지를 모아 면세점에서 다음 스테이지를 준비하며, 각 도시를 클리어해 기념품을 수집합니다. 맵은 랜덤처럼 보이지만 실제로는 클리어 가능한 패턴들로 구성되어, 운보다 반응 속도와 반복 학습, 준비 전략이 중요한 게임이 되는 것을 목표로 합니다.