# {프로젝트명} — Unity 셋업 가이드

> **버전**: v1
> **작성일**: {날짜}
> **담당**: 개발팀장
> **적용 범위**: 신규 PC에서 {프로젝트명} Unity 개발 환경 구축 + NerdNavis.Framework 연동

---

## 1. Unity 프로젝트 생성

### 1.1 Unity 버전

- **필수**: Unity 6000.0.x 이상 (Unity 6 LTS)
- Unity Hub에서 `6000.0.x` 버전 설치 확인
- 하위 버전 사용 시 개발팀장 확인 필수 (NerdNavis.Framework 호환성 보장 범위)

### 1.2 렌더 파이프라인 선택

| 선택지 | 권장 상황 |
|--------|----------|
| **URP (Universal Render Pipeline)** | 모바일 최적화, 셰이더 커스터마이즈 필요 시 (권장 기본값) |
| **Built-in** | 서드파티 셰이더·플러그인이 URP 미지원인 경우 |

결정 후 `개발/01_아키텍처_설계.md 섹션 1`에 기록.

### 1.3 프로젝트 경로 규칙

```
D:\NerdNavis\{프로젝트명}\        ← Unity 프로젝트 루트
D:\NerdNavis\NerdNavisAi\         ← 조직 레포 (별도)
D:\NerdNavis\NerdNavis.Framework\ ← Framework 레포 (로컬 개발용, 선택)
```

**경로 규칙**:
- 경로에 공백 금지 (Unity 빌드 도구 호환성)
- 한글 경로 금지 (Android/iOS 빌드 오류 원인)

---

## 2. NerdNavis.Framework 연동 (C+H1)

> **배포 방식**: C+H1 — UPM Git URL (원격 기본) + 로컬 file: 오버라이드 (개발용)
> **근거**: 03_배포방식_안건_v1.md — 목표 1·2·3 세 축 모두 최우위

### 2.1 기본 (원격 — 모든 PC)

`Packages/manifest.json` 에 다음 항목 추가:

```json
{
  "dependencies": {
    "com.nerdnavis.framework": "https://burning.i234.me/NerdNavis/NerdNavis.Framework.git#v0.x.y",
    "com.unity.addressables": "2.4.4",
    "com.unity.nuget.newtonsoft-json": "3.2.1",
    ...
  }
}
```

- `#v0.x.y` 부분을 실제 사용할 Framework 버전 태그로 교체 (예: `#v0.1.0`)
- **브랜치 추적(`#main`) 금지** — 재현성 보장을 위해 반드시 태그 또는 커밋 SHA 고정

### 2.2 개발용 (로컬 오버라이드 — Framework 동시 개발 시만)

Framework 코드를 동시에 수정해야 하는 경우 로컬 경로로 오버라이드:

```json
{
  "dependencies": {
    "com.nerdnavis.framework": "file:../../NerdNavis.Framework"
  }
}
```

> ⚠️ **로컬 오버라이드 커밋 금지**: 이 상태로 `manifest.json`을 커밋하면 다른 PC에서 빌드 실패.
> 로컬 개발 완료 후 반드시 원격 URL로 복원 후 커밋.

**`.gitignore`에 추가 권장**:
```
# 로컬 manifest 오버라이드 (있는 경우)
Packages/manifest.local.json
```

### 2.3 Git 인증 (사내 Gitea)

Windows Credential Manager에 인증 정보 등록 (최초 1회):
```
git credential-manager configure
# 또는 직접 입력 후 캐싱
git clone https://burning.i234.me/NerdNavis/NerdNavis.Framework.git
```

Package Manager가 자동으로 Windows Credential Manager를 사용하여 인증.

---

## 3. 프로젝트 설정

### 3.1 Player Settings

| 항목 | 값 |
|------|-----|
| **Company Name** | NerdNavis |
| **Product Name** | {프로젝트명} |
| **Bundle Identifier** | `com.nerdnavis.{프로젝트명소문자}` |
| **Scripting Backend** | IL2CPP |
| **API Compatibility Level** | .NET Standard 2.1 |
| **Managed Stripping Level** | Minimal (개발), High (릴리스) |

### 3.2 필수 패키지 (Package Manager)

| 패키지 | 버전 | 용도 |
|--------|------|------|
| `com.unity.addressables` | 2.x 최신 | 리소스 번들 |
| `com.unity.nuget.newtonsoft-json` | 3.x | JSON 직렬화 (DataTable) |
| `com.unity.render-pipelines.universal` | 17.x | URP (선택한 경우) |
| `com.unity.textmeshpro` | (번들 포함) | UI 텍스트 |

### 3.3 Quality Settings

- 모바일 타겟은 Quality Level을 "Medium" 이하로 시작 (실기기 테스트 후 조정)

---

## 4. Git 설정

### 4.1 .gitignore (Unity 표준)

프로젝트 루트에 `.gitignore` 생성:

```gitignore
# Unity 생성 폴더
[Ll]ibrary/
[Tt]emp/
[Oo]bj/
[Bb]uild/
[Bb]uilds/
[Ll]ogs/
[Mm]emoryCaptures/
[Rr]ecordings/

# Unity Asset Database
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Unity 자동 생성 파일
sysinfo.txt
*.apk
*.aab
*.unitypackage
*.app

# Visual Studio
.vs/
*.csproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb

# Rider
.idea/

# OS 메타
.DS_Store
Thumbs.db

# NerdNavis 로컬 설정
Packages/manifest.local.json
```

### 4.2 .gitattributes (LFS)

대용량 바이너리 파일 LFS 관리:

```gitattributes
# Unity
*.meta merge=unityyamlmerge eol=lf
*.unity merge=unityyamlmerge eol=lf
*.prefab merge=unityyamlmerge eol=lf
*.asset merge=unityyamlmerge eol=lf
*.mat merge=unityyamlmerge eol=lf
*.controller merge=unityyamlmerge eol=lf

# LFS — 바이너리 에셋
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.psd filter=lfs diff=lfs merge=lfs -text
*.wav filter=lfs diff=lfs merge=lfs -text
*.mp3 filter=lfs diff=lfs merge=lfs -text
*.ogg filter=lfs diff=lfs merge=lfs -text
*.fbx filter=lfs diff=lfs merge=lfs -text
*.anim filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text
*.xlsm filter=lfs diff=lfs merge=lfs -text
*.xlsx filter=lfs diff=lfs merge=lfs -text
```

**LFS 초기화** (최초 1회):
```bash
git lfs install
git lfs track "*.png" "*.jpg" "*.wav" "*.mp3" "*.fbx" "*.psd"
```

---

## 5. 기본 코드 구조

### 5.1 Bootstrap 씬 구성

```
00_Bootstrap.unity
└── [Bootstrap] (GameObject)
    ├── GameManager (MonoSingleton<GameManager>)
    ├── DataManager (MonoSingleton<DataManager>)
    ├── UIManager (MonoSingleton<UIManager>)
    └── ServiceLocatorBootstrap (MonoBehaviour)
        └── Awake()에서 ServiceLocator.Register<ISaveProvider>(...)
```

### 5.2 asmdef 4개 생성

각 디렉토리에 asmdef 파일 생성:

```
Assets/Scripts/{ProjectNamespace}/Core/{ProjectNamespace}.Core.asmdef
Assets/Scripts/{ProjectNamespace}/UI/{ProjectNamespace}.UI.asmdef
Assets/Scripts/{ProjectNamespace}/Data/{ProjectNamespace}.Data.asmdef
Assets/Scripts/{ProjectNamespace}/Editor/{ProjectNamespace}.Editor.asmdef
```

**Core asmdef 예시** (`{ProjectNamespace}.Core.asmdef`):
```json
{
    "name": "{ProjectNamespace}.Core",
    "references": [
        "NerdNavis.Framework.Runtime"
    ],
    "includePlatforms": [],
    "excludePlatforms": [],
    "allowUnsafeCode": false
}
```

**Editor asmdef 예시** (`{ProjectNamespace}.Editor.asmdef`):
```json
{
    "name": "{ProjectNamespace}.Editor",
    "references": [
        "{ProjectNamespace}.Core",
        "NerdNavis.Framework.Runtime",
        "NerdNavis.Framework.Editor"
    ],
    "includePlatforms": ["Editor"],
    "excludePlatforms": []
}
```

### 5.3 GameManager 기본 구현

```csharp
using NerdNavis.Core.Patterns;

namespace {ProjectNamespace}.Core
{
    public class GameManager : MonoSingleton<GameManager>
    {
        protected override void OnAwake()
        {
            Log.Info("GameManager", "초기화 시작");
            // 초기화 코드
        }
    }
}
```

---

## 6. 셋업 검증 (6항 — 전체 통과 필수)

> **Phase 2 완료 기준**: 아래 6항 모두 체크 완료.
> 하나라도 실패 시 원인 해결 후 재검증.

- [ ] **1. Framework 패키지 참조 확인** — Package Manager 창에서 `NerdNavis Framework` 표시됨
- [ ] **2. 컴파일 오류 없음** — 콘솔 에러 0건 (경고는 검토 후 판단)
- [ ] **3. Bootstrap 씬 Play → 콘솔 에러 없음** — Play 후 Console 확인
- [ ] **4. MonoSingleton 인스턴스 생성 테스트** — `GameManager.Instance != null` 확인
- [ ] **5. ServiceLocator Register/Resolve 테스트**
  ```csharp
  // 테스트 코드 (에디터 또는 Unity Test Runner)
  ServiceLocator.Register<ISaveProvider>(new JsonSaveProvider());
  var resolved = ServiceLocator.Resolve<ISaveProvider>();
  Debug.Assert(resolved != null);
  ```
- [ ] **6. Log.Info/Log.Warn 출력 테스트** — 콘솔에 로그 출력 확인

---

## 변경 이력

| 버전 | 일자 | 작성자 | 내용 |
|------|------|--------|------|
| v1 | {날짜} | 개발팀장 | 템플릿 초안. C+H1 배포 방식 + 셋업 검증 6항 정립 |
