165 lines
6.7 KiB
Markdown
165 lines
6.7 KiB
Markdown
# {프로젝트명} — 아키텍처 설계
|
|
|
|
> **버전**: v1
|
|
> **작성일**: {날짜}
|
|
> **담당**: 개발팀장
|
|
> **적용 범위**: {프로젝트명} Unity 클라이언트
|
|
|
|
---
|
|
|
|
## 1. 프로젝트 기본 정보
|
|
|
|
| 항목 | 값 | 비고 |
|
|
|------|-----|------|
|
|
| **Unity 버전** | 6000.0.x 이상 (Unity 6 LTS) | 하위 버전 사용 시 팀장 확인 필수 |
|
|
| **타겟 플랫폼** | Android(주), iOS, Windows(Editor) | {장르}에 따라 조정 |
|
|
| **Scripting Backend** | IL2CPP | Android/iOS 공통 |
|
|
| **API 호환성** | .NET Standard 2.1 | |
|
|
| **BT.Framework 버전** | `com.nerdnavis.framework v0.x.y` | `관리/Unity_셋업_가이드.md` 참조 |
|
|
| **렌더 파이프라인** | URP (기본) / Built-in (선택) | 착수 시 확정 |
|
|
|
|
---
|
|
|
|
## 2. 어셈블리(asmdef) 구성
|
|
|
|
> ⚠️ **Assembly-CSharp 단일 어셈블리 금지** (수상한잡화점 교훈: asmdef 미적용으로 컴파일 시간 증가·의존성 관리 불가 문제 발생)
|
|
|
|
| asmdef | 경로 | 의존 |
|
|
|--------|------|------|
|
|
| `{ProjectNamespace}.Core` | `Assets/Scripts/{ProjectNamespace}/Core/` | BT.Framework.Runtime |
|
|
| `{ProjectNamespace}.UI` | `Assets/Scripts/{ProjectNamespace}/UI/` | .Core |
|
|
| `{ProjectNamespace}.Data` | `Assets/Scripts/{ProjectNamespace}/Data/` | .Core |
|
|
| `{ProjectNamespace}.Server` | `Assets/Scripts/{ProjectNamespace}/Server/` | .Core |
|
|
| `{ProjectNamespace}.Editor` | `Assets/Scripts/{ProjectNamespace}/Editor/` | .Core, BT.Framework.Editor (Editor only) |
|
|
| `ThirdParty/` | `Assets/ThirdParty/` | 서드파티별 격리 |
|
|
|
|
**규칙**:
|
|
- 각 asmdef는 자신의 역할 외 다른 도메인 코드를 포함하지 않는다
|
|
- 순환 참조 금지 (Core ← UI ← Data ← Server 단방향)
|
|
- 에디터 전용 코드는 반드시 `.Editor` asmdef로 분리
|
|
|
|
---
|
|
|
|
## 3. Assets 폴더 구조
|
|
|
|
```
|
|
Assets/
|
|
├── Scripts/
|
|
│ └── {ProjectNamespace}/
|
|
│ ├── Core/ ← 게임 매니저, 부트스트랩, 공통 모델
|
|
│ ├── UI/ ← UI View, Panel, HUD
|
|
│ ├── Data/ ← DataTable 서브클래스, DataLoader
|
|
│ ├── Server/ ← 서버 통신 레이어 (INetworkService 구현)
|
|
│ └── Editor/ ← 에디터 전용 도구
|
|
├── Addressable/
|
|
│ ├── Ingame/ ← 인게임 리소스 그룹
|
|
│ ├── UI/ ← UI 리소스 그룹
|
|
│ └── Audio/ ← 오디오 그룹
|
|
├── Scenes/
|
|
│ ├── 00_Bootstrap.unity
|
|
│ └── ...
|
|
├── Prefabs/
|
|
├── Art/
|
|
│ ├── Sprites/
|
|
│ ├── Effects/
|
|
│ └── Characters/
|
|
├── Audio/
|
|
│ ├── BGM/
|
|
│ └── SFX/
|
|
├── ThirdParty/ ← 서드파티 패키지 격리
|
|
└── Editor/ ← 프로젝트 에디터 도구 (asmdef 없는 구역)
|
|
```
|
|
|
|
**주의**: `Resources/` 폴더는 최소 사용. 동적 로딩은 Addressables로 대체한다.
|
|
|
|
---
|
|
|
|
## 4. 네임스페이스 체계
|
|
|
|
> ⚠️ **전역 네임스페이스(global) 사용 금지** (수상한잡화점 교훈: 클래스명 충돌 위험, 장기 리팩토링 부담)
|
|
|
|
```
|
|
{ProjectNamespace} ← 루트 (공용 인터페이스, 공용 enum)
|
|
│
|
|
├── {ProjectNamespace}.Core ← 게임 매니저, 부트스트랩, 공통 도메인
|
|
├── {ProjectNamespace}.UI ← UI View, Panel
|
|
├── {ProjectNamespace}.Data ← DataTable 구현체, DataLoader
|
|
├── {ProjectNamespace}.Server ← 서버 통신, Request/Response 래퍼
|
|
└── {ProjectNamespace}.Editor ← 에디터 도구 (런타임 제외)
|
|
```
|
|
|
|
**BurningTimes 네임스페이스와 분리 원칙**:
|
|
- `BurningTimes.*` = 프레임워크 영역 (수정 불가)
|
|
- `{ProjectNamespace}.*` = 프로젝트 전용 영역
|
|
- 두 영역의 혼합 사용 금지
|
|
|
|
---
|
|
|
|
## 5. 매니저/시스템 목록
|
|
|
|
| 클래스 | 역할 | 라이프사이클 | Framework 의존 |
|
|
|--------|------|-------------|---------------|
|
|
| `GameManager` | 게임 전체 상태 관리, 씬 전환 총괄 | `MonoSingleton<T>` (Persistent) | ✅ |
|
|
| `DataManager` | DataTable 로딩·캐시 관리 | `MonoSingleton<T>` (Persistent) | ✅ |
|
|
| `UIManager` | UI View 스택·전환 관리 | `MonoSingleton<T>` (Persistent) | ✅ |
|
|
| `AudioManager` | BGM/SFX 재생 | `BurningTimes.Audio` 위임 | ✅ |
|
|
| `ServerManager` | 서버 통신 추상화 | `ServiceLocator` | ✅ |
|
|
| `SaveManager` | 세이브/로드 | `ServiceLocator` + `BurningTimes.Save` | ✅ |
|
|
| `{Game}Manager` | 핵심 게임 로직 매니저 ({장르} 특화) | `MonoSingleton<T>` or `ServiceLocator` | 상황별 |
|
|
|
|
**라이프사이클 선택 기준**:
|
|
- `MonoSingleton<T>`: Update/OnDestroy 훅이 필요하거나 씬 생명주기와 동기화가 필요한 서비스
|
|
- `ServiceLocator`: 순수 C# 서비스, 인터페이스 바인딩·테스트 대체가 필요한 서비스
|
|
|
|
---
|
|
|
|
## 6. 씬 구성
|
|
|
|
| 씬명 | 역할 | 로드 방식 |
|
|
|------|------|----------|
|
|
| `00_Bootstrap` | 앱 진입점, 초기화(Manager 셋업, DataTable 로딩) | Single (시작점) |
|
|
| `01_Title` | 타이틀·로그인 화면 | Single |
|
|
| `02_Main` | 메인 로비 | Single |
|
|
| `03_Ingame` | 인게임(핵심 게임 루프) | Single or Additive |
|
|
| `9x_Tool_*` | 개발용 도구 씬 (배포 빌드 씬 리스트 제외 필수) | Single |
|
|
|
|
**규칙**:
|
|
- 배포 빌드에서 `9x_Tool_*` 씬은 Build Settings 씬 목록에서 **반드시 제외**
|
|
- 씬 전환은 `GameManager`를 통해서만 수행 (직접 `SceneManager.LoadScene` 금지)
|
|
|
|
---
|
|
|
|
## 7. 서드파티 의존성
|
|
|
|
| 패키지 | 버전 | 용도 | 라이선스 |
|
|
|--------|------|------|----------|
|
|
| `com.unity.addressables` | 2.x | 리소스 번들 관리 | Unity |
|
|
| `com.unity.nuget.newtonsoft-json` | 3.x | JSON 직렬화 | MIT |
|
|
| `com.unity.render-pipelines.universal` | 17.x | URP 렌더링 | Unity |
|
|
| `com.unity.textmeshpro` | (번들) | UI 텍스트 | Unity |
|
|
| `(AntiCheatToolkit)` | 최신 | 메모리 변조 방어 | 구매 |
|
|
| `{추가 서드파티}` | `{버전}` | `{용도}` | `{라이선스}` |
|
|
|
|
**서드파티 추가 규칙**:
|
|
- 신규 서드파티 추가 시 `공유/` 채널에 라이선스·용도·대안 검토 결과를 기록 (P15)
|
|
- `ThirdParty/` 폴더에 격리하여 프로젝트 코드와 물리적으로 분리
|
|
|
|
---
|
|
|
|
## 8. 열린 결정 항목
|
|
|
|
| 항목 | 선택지 | 현재 상태 |
|
|
|------|--------|----------|
|
|
| 렌더 파이프라인 | URP / Built-in | 미결 |
|
|
| 백엔드 서비스 | PlayFab / GameSparks / 자체 서버 | 미결 |
|
|
| DI 추가 도구 | ServiceLocator(Framework 내장) / VContainer | 미결 |
|
|
| 비동기 패턴 | async/await + CoroutineRunner / UniTask | 미결 |
|
|
|
|
---
|
|
|
|
## 변경 이력
|
|
|
|
| 버전 | 일자 | 작성자 | 내용 |
|
|
|------|------|--------|------|
|
|
| v1 | {날짜} | 개발팀장 | 템플릿 초안 |
|