Table of Contents

Getting Started

Framework v1.0.0 을 신규 프로젝트에 적용하는 순서입니다.

1. 프로젝트 생성

Unity 6 프로젝트를 생성합니다(URP/BiRP 무관). Framework 는 Unity.RenderPipelines.Core.Runtime 만 참조하므로 특정 파이프라인에 종속되지 않습니다.

2. Package 설치

Framework 가 의존하는 패키지를 먼저 설치합니다:

  • VContainer, MessagePipe, MessagePipe.VContainer
  • UniTask, UniTask.Addressables
  • Unity Addressables, Unity Localization
  • Unity Input System
  • Unity Cinemachine
  • TextMeshPro
  • UnityScreenNavigator, uPalette (UI)
  • MemoryPack, Newtonsoft.Json
  • (선택) FishNet — 멀티플레이어 사용 시에만, FRAMEWORK_MULTIPLAYER 심볼과 함께

_Framework 폴더(Runtime/Editor/Samples)를 프로젝트에 복사합니다.

3. RootScope 생성

Assets/Resources/RootScope.prefab 이 이미 준비되어 있습니다(RootScope 컴포넌트 + VContainer LifetimeScope). 별도 씬 배치가 필요 없습니다 — RootBootstrap.Initialize() 가 [RuntimeInitializeOnLoadMethod(BeforeSceneLoad)] 로 Play 진입/빌드 실행 시 자동으로 Resources 에서 로드하고 DontDestroyOnLoad 로 유지합니다.

커스터마이즈가 필요하면 RootScope.prefab 을 열어 Configure() 흐름(Assets/_Framework/Runtime/Core/Bootstrap/RootScope.cs)을 확인하세요. 게임 전용 System 은 RootScope.Configure() 끝부분에 등록을 추가합니다.

4. Initialize

별도 초기화 코드가 필요 없습니다. Play 진입 시 자동으로:

  1. RootBootstrap.Initialize() → RootScope 인스턴스화 (Resources 로드 + DontDestroyOnLoad)
  2. VContainer ContainerBuilder.Build() → 전체 System DI 등록 완료
  3. RegisterBuildCallback → TickSystem/AudioSystem/TimeSystem/Diagnostics/Stat 초기 연결
  4. (Editor/Development Build 전용) RuntimeStartupValidator.Validate() 실행, 실패 시 Diagnostics 에 경고 기록

Tools > Framework > Runtime Startup Report 에서 초기화 결과를 확인할 수 있습니다.

5. Asset 사용

[Inject] private IAssetSystem _asset;

var result = await _asset.LoadAsync<GameObject>("Enemy/Goblin");
if (result.IsSuccess) Instantiate(result.Value);

Addressable Group/Key 를 먼저 구성해야 합니다. Samples/Asset/AssetSystemSample.cs 참고.

6. Scene 사용

[Inject] private ISceneSystem _scene;
await _scene.LoadAsync("Stage01");

Samples/Scene/SceneSystemSample.cs 참고.

7. Save 사용

[Inject] private ISaveSystem _save;
await _save.SaveAsync("slot1", myData);
var loaded = await _save.LoadAsync<MyData>("slot1");

Samples/Save/SaveSystemSample.cs 참고.

8. UI 사용

[Inject] private INavigationService _nav;
await _nav.PushAsync("MainMenu");

Samples/UI/UISystemSample.cs 참고. UnityScreenNavigator/uPalette 실제 화면 바인딩은 프로젝트에서 구성합니다.

9. Diagnostics 사용

Editor/Development Build 에서 자동 활성화됩니다:

  • F1 — Runtime Inspector 토글
  • F2 — Command Console 토글
  • Tools > Framework > Diagnostics — Diagnostics Workspace
  • Tools > Framework > Test Report — 테스트 현황
  • Tools > Framework > Runtime Startup Report — 초기화 결과

Samples/Diagnostics/DiagnosticsSample.cs 참고.

10. Build

Release 빌드에서는 Diagnostics/RuntimeStartupValidator 등 #if UNITY_EDITOR || DEVELOPMENT_BUILD 코드가 자동 제거됩니다. 빌드 전 Documentation/ReleaseChecklist.md 를 확인하세요.

순서 요약

프로젝트 생성 → Package 설치 → (RootScope 는 이미 준비됨, 별도 생성 불필요)
    → Initialize(자동) → Asset 사용 → Scene 사용 → Save 사용
    → UI 사용 → Diagnostics 사용 → Build

더 알아보기

Edit this page