# {프로젝트명} — 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) ├── DataManager (MonoSingleton) ├── UIManager (MonoSingleton) └── ServiceLocatorBootstrap (MonoBehaviour) └── Awake()에서 ServiceLocator.Register(...) ``` ### 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 { 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(new JsonSaveProvider()); var resolved = ServiceLocator.Resolve(); Debug.Assert(resolved != null); ``` - [ ] **6. Log.Info/Log.Warn 출력 테스트** — 콘솔에 로그 출력 확인 --- ## 변경 이력 | 버전 | 일자 | 작성자 | 내용 | |------|------|--------|------| | v1 | {날짜} | 개발팀장 | 템플릿 초안. C+H1 배포 방식 + 셋업 검증 6항 정립 |