309 lines
8.0 KiB
Markdown
309 lines
8.0 KiB
Markdown
# {프로젝트명} — Unity 셋업 가이드
|
|
|
|
> **버전**: v1
|
|
> **작성일**: {날짜}
|
|
> **담당**: 개발팀장
|
|
> **적용 범위**: 신규 PC에서 {프로젝트명} Unity 개발 환경 구축 + BT.Framework 연동
|
|
|
|
---
|
|
|
|
## 1. Unity 프로젝트 생성
|
|
|
|
### 1.1 Unity 버전
|
|
|
|
- **필수**: Unity 6000.0.x 이상 (Unity 6 LTS)
|
|
- Unity Hub에서 `6000.0.x` 버전 설치 확인
|
|
- 하위 버전 사용 시 개발팀장 확인 필수 (BT.Framework 호환성 보장 범위)
|
|
|
|
### 1.2 렌더 파이프라인 선택
|
|
|
|
| 선택지 | 권장 상황 |
|
|
|--------|----------|
|
|
| **URP (Universal Render Pipeline)** | 모바일 최적화, 셰이더 커스터마이즈 필요 시 (권장 기본값) |
|
|
| **Built-in** | 서드파티 셰이더·플러그인이 URP 미지원인 경우 |
|
|
|
|
결정 후 `개발/01_아키텍처_설계.md 섹션 1`에 기록.
|
|
|
|
### 1.3 프로젝트 경로 규칙
|
|
|
|
```
|
|
D:\BurningTimes\{프로젝트명}\ ← Unity 프로젝트 루트
|
|
D:\BurningTimes\BurningTimesAi\ ← 조직 레포 (별도)
|
|
D:\BurningTimes\BT.Framework\ ← Framework 레포 (로컬 개발용, 선택)
|
|
```
|
|
|
|
**경로 규칙**:
|
|
- 경로에 공백 금지 (Unity 빌드 도구 호환성)
|
|
- 한글 경로 금지 (Android/iOS 빌드 오류 원인)
|
|
|
|
---
|
|
|
|
## 2. BT.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/BurningTimes/BT.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:../../BT.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/BurningTimes/BT.Framework.git
|
|
```
|
|
|
|
Package Manager가 자동으로 Windows Credential Manager를 사용하여 인증.
|
|
|
|
---
|
|
|
|
## 3. 프로젝트 설정
|
|
|
|
### 3.1 Player Settings
|
|
|
|
| 항목 | 값 |
|
|
|------|-----|
|
|
| **Company Name** | BurningTimes |
|
|
| **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
|
|
|
|
# BurningTimes 로컬 설정
|
|
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": [
|
|
"BT.Framework.Runtime"
|
|
],
|
|
"includePlatforms": [],
|
|
"excludePlatforms": [],
|
|
"allowUnsafeCode": false
|
|
}
|
|
```
|
|
|
|
**Editor asmdef 예시** (`{ProjectNamespace}.Editor.asmdef`):
|
|
```json
|
|
{
|
|
"name": "{ProjectNamespace}.Editor",
|
|
"references": [
|
|
"{ProjectNamespace}.Core",
|
|
"BT.Framework.Runtime",
|
|
"BT.Framework.Editor"
|
|
],
|
|
"includePlatforms": ["Editor"],
|
|
"excludePlatforms": []
|
|
}
|
|
```
|
|
|
|
### 5.3 GameManager 기본 구현
|
|
|
|
```csharp
|
|
using BurningTimes.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 창에서 `BurningTimes 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항 정립 |
|