Abstract
"C# GameFramework" 섹션은 프레임워크의 엔진을 다룹니다. Unity 를 전혀 모르는 순수 C# 라이브러리로, 엔티티를 언제 만들고 언제 풀로 돌려보낼지, 이벤트를 어떤 순서로 배달할지 같은 규칙이 전부 여기에 있습니다. "Unity GameFramework" 섹션의 ~Component 들은 이 엔진에 Unity 의 손발(GameObject, 에셋 로딩, 오디오)을 달아 주는 얇은 껍데기입니다.
두 층의 관계
graph TD
G["게임 코드 (Assembly-CSharp)<br>ProcedureMain, Enemy, HUDForm ..."] --> U
U["Unity 래퍼 (UnityGameFramework.Runtime)<br>EntityComponent, UIComponent, EventComponent ..."] --> C
C["코어 (GameFramework)<br>EntityManager, UIManager, EventManager ...<br>UnityEngine 참조 없음"]Mermaid
복사
코어 (이 섹션) | Unity 래퍼 | |
어셈블리 | GameFramework | UnityGameFramework.Runtime |
대표 타입 | IEntityManager, IFsm<T>, ReferencePool | EntityComponent, FsmComponent, EntityLogic |
Unity 의존 | 없음 (UnityEngine 을 쓰면 컴파일 에러) | 있음 (MonoBehaviour) |
게임 코드가 직접 쓰나 | 일부만 — ReferencePool, IFsm<T>, FsmState<T>, GameEventArgs, ProcedureBase 의 인자 타입 | 대부분 여기를 통한다 |
이 섹션을 읽어야 하는 이유
게임을 만드는 데는 Unity 쪽 문서만으로 충분합니다. 이 섹션은 그다음 단계 — "왜 그렇게 동작하는가"가 궁금해졌을 때 읽습니다.
•
HideEntity 를 두 번 부르면 왜 예외인가 → Entity Manager
•
Fire 한 이벤트가 왜 다음 프레임에 도착하는가 → Event System
•
왜 OnInit 은 한 번이고 OnShow 는 매번인가 → Object Pooling
•
직접 프레임워크를 설계한다면 무엇을 참고할 것인가 → Module Management, Reference Pool, Task
ToyboxNightmare 가 코어를 직접 만지는 곳
using GameFramework; // ReferencePool, IReference
using GameFramework.Event; // GameEventArgs
using GameFramework.Fsm; // IFsm<T>, FsmState<T>
// Procedure 는 타입 이름만 빌려 온다
using ProcedureOwner = GameFramework.Fsm.IFsm<GameFramework.Procedure.IProcedureManager>;
C#
복사
이 세 네임스페이스가 전부입니다. 나머지 코어 타입은 Unity 래퍼 뒤에 가려져 있습니다.
이 에디션에서 다른 점
•
원작은 코어를 미리 빌드된 DLL(GameFramework.dll)로 배포했습니다. 이 에디션은 소스 그대로 패키지의 Runtime/Core/ 에 들어 있어, 브레이크포인트를 걸고 코어 안까지 따라 들어갈 수 있습니다.
•
본문의 "관련 소스 파일" 경로(GameFramework/Base/...)는 원작 저장소 기준입니다. 이 에디션에서는 Packages/com.yamyamcoding.gameframework/Runtime/Core/Base/... 입니다. 줄 번호는 어긋날 수 있습니다.
•
리소스 관리만은 사정이 다릅니다. 코어의 AssetBundle 기반 ResourceManager 소스는 패키지에 남아 있지만 실행 중에 생성되지 않습니다. Unity 래퍼가 Addressables 로 만든 자체 구현을 대신 끼워 넣기 때문입니다. 이 섹션의 Resource 문서 3개(…-Addressable)는 그 Addressables 구현을 기준으로 썼습니다.
안녕하세요! 
본 프로젝트는 EllanJiang이 제작한 Unity 게임 개발 전용 오픈소스 프레임워크인 GameFramework를 기반으로 구축되었어요.
본 프로젝트는 EllanJiang이 제작한 Unity 게임 개발 전용 오픈소스 프레임워크인 GameFramework를 기반으로 구축되었어요.GameFramework는 게임 개발 시 반복적으로 필요한 핵심 기능들을 재사용 가능하고 유지보수하기 쉽게 설계된 프레임워크입니다. 리소스 관리, 이벤트 시스템, UI 관리, 사운드, 네트워킹 등 게임 개발에 필수적인 다양한 기능 모듈을 이미 갖추고 있어, 개발자가 바퀴를 다시 발명할 필요 없이 게임의 핵심 로직에만 집중할 수 있게 도와줍니다.
본 프로젝트에서는 GameFramework의 강력한 기반 위에 프로젝트에 특화된 맞춤형 기능을 추가하고, 기존 시스템을 더욱 개선하여 안정적이면서도 확장 가능한 게임 아키텍처를 완성했습니다. 이를 통해 여러분은 견고한 구조 위에서 창의적인 게임 개발을 펼치실 수 있어요! 
개요 (Overview)
GameFramework는 게임 애플리케이션을 만들 때 공통적으로 필요한 기능을 모듈화해서 제공하는 종합 프레임워크입니다. 핵심 인프라를 매번 새로 만드는 대신, 재사용 가능한 컴포넌트와 시스템을 제공하여 개발자는 게임 고유의 로직에 집중할 수 있게 해줍니다.
관련 소스 파일 (Relevant source files)
•
GameFramework/Base/DataStruct/TypeNamePair.cs
•
GameFramework/Base/GameFrameworkEntry.cs
•
GameFramework/Base/GameFrameworkLinkedList.cs
•
GameFramework/Base/GameFrameworkLinkedListRange.cs
•
GameFramework/Base/GameFrameworkMultiDictionary.cs
•
GameFramework/Base/Version/Version.IVersionHelper.cs
•
GameFramework/Base/Version/Version.cs
목적과 범위 (Purpose and Scope)
이 문서는 GameFramework의 아키텍처, 핵심 컴포넌트, 그리고 컴포넌트 간 상호작용을 상위 수준에서 소개합니다. 각 시스템의 세부 내용으로 들어가기 전에 읽는 입문용 안내서입니다.
각 시스템의 자세한 내용은 해당 문서를 참고하세요:
•
코어 프레임워크 컴포넌트: Core Framework
•
리소스 관리 시스템: Resource Management
•
엔터티, UI, 사운드 시스템: Entity Framework
•
데이터 관리 시스템: Data Systems
•
네트워크 및 IO 시스템: Network and IO
출처(Sources):
GameFramework/Base/GameFrameworkEntry.cs 11–17
GameFramework/Base/Version/Version.cs 8–14
프레임워크 아키텍처 (Framework Architecture)
GameFramework는 중앙 집중식 모듈 관리 시스템을 중심으로 계층적·조직적으로 설계되었습니다. 각 주요 기능 영역은 공통 기반 클래스를 상속하는 모듈로 구현됩니다.
상위 수준 아키텍처 (High-Level Architecture)
(상위 구조 도식)
출처(Sources): GameFramework/Base/GameFrameworkEntry.cs 16–18
아키텍처는 대략 다음과 같은 레이어로 구성됩니다:
•
코어 프레임워크: 기반과 중앙 관리 제공
•
주요 시스템: 게임 기능을 담당하는 개별 특화 모듈
•
지원 시스템: 여러 주요 시스템이 공통으로 사용하는 유틸리티
모듈 관리 시스템 (Module Management System)
핵심은 모든 모듈의 진입점이자 중앙 관리자 역할을 하는 GameFrameworkEntry 클래스입니다. 이 클래스는 우선순위가 있는 모듈 목록을 유지하고, 모듈의 생명주기를 오케스트레이션합니다.
모듈 생명주기 (Module Lifecycle)
출처(Sources):
GameFramework/Base/GameFrameworkEntry.cs 25–46
GameFramework/Base/GameFrameworkEntry.cs 52–131
모듈 시스템의 주요 특징 (Key Features)
•
지연 초기화: GetModule<T>() 요청 시에만 모듈 생성
•
우선순위 정렬: 결정적 업데이트 순서를 위한 우선순위 기반 정렬
•
타입 안전성: 제네릭 메서드로 강타입 모듈 조회
•
자동 생성: 요청된 모듈이 없으면 자동으로 생성
출처(Sources): GameFramework/Base/GameFrameworkEntry.cs 52–131
메모리 관리 (Memory Management)
GameFramework는 성능 최적화와 GC 압박 감소를 위해 커스텀 자료구조와 메모리 관리 기법을 제공합니다.
레퍼런스 풀링 (Reference Pooling)
객체를 매번 생성·GC하지 않고 재사용할 수 있게 하는 시스템입니다.
출처(Sources): GameFramework/Base/GameFrameworkEntry.cs 44
커스텀 자료구조 (Custom Data Structures)
게임에 특화된 다음 자료구조를 제공합니다:
•
GameFrameworkLinkedList: 노드를 캐시/재사용하는 링크드 리스트
•
GameFrameworkLinkedListRange: 링크드 리스트의 구간 표현
•
GameFrameworkMultiDictionary: 하나의 키에 여러 값을 저장하는 딕셔너리
출처(Sources):
GameFramework/Base/GameFrameworkLinkedList.cs 19–452
GameFramework/Base/GameFrameworkLinkedListRange.cs 19–217
GameFramework/Base/GameFrameworkMultiDictionary.cs 19–283
버전 관리 (Version Management)
Version 클래스는 다음 정보를 제공합니다:
•
프레임워크 버전: GameFramework 자체 버전
•
게임 버전: IVersionHelper를 통해 제공되는 게임 버전
•
내부 게임 버전: 숫자 기반 내부 버전 코드(역시 IVersionHelper 경유)
출처(Sources):
GameFramework/Base/Version/Version.cs 13–70
GameFramework/Base/Version/Version.IVersionHelper.cs 15–33
리소스 관리 (Resource Management)
리소스 관리 시스템은 프레임워크에서 가장 중요한 컴포넌트 중 하나로, 의존성 처리와 비동기 작업을 포함한 에셋의 로드/언로드/업데이트를 담당합니다.
출처(Sources): 제공된 아키텍처 도식에 기반한 정보
엔터티와 UI 프레임워크 (Entity and UI Framework)
엔터티 및 UI의 생명주기 관리를 담당하는 포괄적인 시스템을 제공합니다.
출처(Sources): 제공된 아키텍처 도식에 기반한 정보
결론 (Conclusion)
GameFramework는 다음을 중시하는 견고한 게임 개발 기반을 제공합니다:
•
모듈성: 독립적으로 사용할 수 있는 자기완결적 시스템
•
성능: 최적화된 자료구조와 메모리 관리
•
확장성: 플랫폼 별 구현을 위한 헬퍼 인터페이스
•
조직화: 관심사 분리와 명확한 책임 구분
이들 컴포넌트가 어떻게 상호작용하는지 이해하면, 프레임워크를 활용해 견고하고 유지보수 쉬운 게임을 효과적으로 개발할 수 있습니다.