8.0 KiB

Raw Blame History

{프로젝트명} — 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 에 다음 항목 추가:

{
  "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 코드를 동시에 수정해야 하는 경우 로컬 경로로 오버라이드:

{
  "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 생성:

# 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 관리:

# 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회):

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):

{
    "name": "{ProjectNamespace}.Core",
    "references": [
        "BT.Framework.Runtime"
    ],
    "includePlatforms": [],
    "excludePlatforms": [],
    "allowUnsafeCode": false
}

Editor asmdef 예시 ({ProjectNamespace}.Editor.asmdef):

{
    "name": "{ProjectNamespace}.Editor",
    "references": [
        "{ProjectNamespace}.Core",
        "BT.Framework.Runtime",
        "BT.Framework.Editor"
    ],
    "includePlatforms": ["Editor"],
    "excludePlatforms": []
}

5.3 GameManager 기본 구현

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 테스트

// 테스트 코드 (에디터 또는 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항 정립

8.0 KiB Raw Blame History