01. Framework Architecture

이 문서의 목표

Framework의 계층 구조와 의존 방향을 이해한다.

왜 필요한가

계층 구조를 모르고 코드를 작성하면 Framework -> Game 역참조, System 간 순환 의존 등 구조 붕괴가 발생한다.

언제 사용하는가

새 기능을 어느 계층에 넣을지 판단할 때마다 참조한다.

프로젝트에서 어떤 역할인가

Game (Entry | Features | Controllers | Adapters | Data)
  v 단방향만 허용
Framework (Core | Patterns | Systems | Integration | Common)
  v
Unity Engine / C# BCL / External

Game -> Framework 단방향만 허용, 역방향 금지
System <-> System 순환 금지, 시스템 조합은 Game/Integration Layer 담당
외부 라이브러리(VContainer, UniTask, FishNet 등)는 Integration 계층에서만 직접 호출

Runtime 최상위 5개 폴더

Runtime/
  Common/      범용 재사용 기능 (Utility, Collection, Math, Random, Id, Extensions)
  Core/        lifecycle, bootstrap, 진입점, framework 계약
  Integration/ 외부 라이브러리 adapter/wrapper
  Patterns/    재사용 가능한 설계 패턴
  Systems/     lifecycle, Tick, orchestration 런타임 시스템

새 최상위 폴더 생성 금지. Infrastructure/Utilities/Managers/Helpers/Shared/Base/Services/ 같은 이름 사용 금지.

실제 사용 예

새 기능이 "외부 라이브러리를 감싸기만 한다" -> Integration. 새 기능이 "매 프레임 상태를 갱신/조율한다" -> Systems. 새 기능이 "재사용 가능한 알고리즘/구조"다 -> Patterns.

Best Practice

기능을 추가하기 전 MCP_Index.md에서 동일 책임 기능이 있는지 먼저 확인한다.
Diagnostics는 다른 System에 의존하지 않는다 (단방향으로만 정보를 받는다).

자주 하는 실수

System이 다른 System을 직접 참조 (조합은 Game Layer 책임)
Gameplay 규칙을 System 내부에 구현

실습 과제

프로젝트의 Assets/_Framework/Runtime 하위 5개 폴더를 직접 열어 구조를 확인한다.
새로운 기능 하나(예: 인벤토리)를 넣는다면 어느 계층에 들어갈지 스스로 판단해본다.

이전 문서 / 다음 문서

이전: 00_Introduction.md 다음: 02_Project_Setup.md

Table of Contents