Module Management

Abstract

모듈 관리는 "전역 시스템 스무 개를 어떤 순서로 만들고, 돌리고, 끄는가"에 대한 답입니다. 프레임워크는 이것을 연결 리스트 하나와 우선순위 숫자 하나로 풉니다. 게임 코드가 직접 만질 일은 없지만, 모듈이 갱신되는 순서를 알아야 "이벤트가 왜 다음 프레임에 오는가" 같은 동작이 이해됩니다.

실제 갱신 순서 (이 에디션의 코드 기준)

매 프레임 GameFrameworkEntry.Update() 는 우선순위가 높은 것부터 차례로 부릅니다.

순서	모듈	Priority	이 순서인 이유
1	Event	7	지난 프레임에 쌓인 이벤트를 가장 먼저 배달한다. 뒤의 모듈들이 최신 상태로 움직인다
2	ObjectPool	6	만료된 인스턴스를 정리해 둔다
3	Download	5
4	FileSystem	4
5	Scene	2
6	Fsm	1	상태 전이를 엔티티 갱신보다 먼저 처리한다
7	Entity, UI, Sound, DataTable, Config, Localization, Setting, DataNode, Network, WebRequest	0	같은 우선순위끼리는 먼저 만들어진 순서
8	Debugger	-1	다른 모듈이 다 돈 뒤의 상태를 본다
9	Procedure	-2	게임 흐름 판단은 맨 마지막 — 이 프레임의 결과를 모두 본 뒤 결정한다

종료는 정확히 이 역순입니다.

이 순서가 게임 코드에 미치는 영향

•

Fire 한 이벤트는 다음 프레임 맨 앞에서 배달됩니다. 엔티티의 OnUpdate 안에서 Fire 하면, Event 모듈은 이번 프레임에 이미 돌았으므로 다음 프레임 1번 순서에서 처리됩니다. 즉시 처리가 필요하면 FireNow 를 씁니다.

•

FSM 상태의 OnUpdate 가 엔티티의 OnUpdate 보다 먼저 불립니다. ToyboxNightmare 의 적은 FSM 상태(EnemyChaseState 등)에서 이동을 결정하고 엔티티 쪽에서 나머지를 처리하는데, 같은 프레임 안에서 "상태 판단 → 엔티티 갱신" 순서가 보장되는 것은 Priority 1 > 0 이기 때문입니다.

•

Procedure 는 마지막에 돕니다. ProcedureMain.OnUpdate 에서 "플레이어가 죽었나"를 확인할 때는 이번 프레임의 전투 결과가 모두 반영된 뒤입니다.

모듈은 언제 만들어지나

GetModule<IEntityManager>() 가 처음 불리는 순간 리플렉션으로 GameFramework.Entity.EntityManager 를 찾아 생성합니다. 실제로는 Unity 쪽 각 ~Component 의 Awake 가 자기 모듈을 요청하므로, GameFramework.prefab 에 붙어 있는 컴포넌트의 모듈만 만들어집니다. 프리팹에서 Network 오브젝트를 지우면 네트워크 모듈은 생성조차 되지 않습니다.

본문을 읽을 때 주의할 점

•

게임 코드는 새 모듈을 만들 수 없습니다. GameFrameworkModule 은 internal abstract 이고, GetModule<T>() 는 GameFramework. 로 시작하는 네임스페이스의 인터페이스만 받습니다. 확장은 Unity 쪽 GameFrameworkComponent 로 합니다(GameEntry와 컴포넌트 관리).

•

게임 코드에서 GameFrameworkEntry.GetModule<T>() 를 직접 부를 일도 없습니다. GameEntry.GetComponent<EntityComponent>() 처럼 Unity 컴포넌트를 통합니다. 본문의 "베스트 프랙티스"는 프레임워크 내부 코드를 쓸 때의 이야기입니다.

•

본문 끝의 모듈 요약 표에는 EventManager, ProcedureManager, SceneManager, FileSystemManager, DebuggerManager 가 빠져 있습니다. 위 순서 표가 전체 목록입니다.

•

표의 ResourceManager(원작 Priority 3)는 이 에디션에서 모듈로 생성되지 않습니다. Addressables 구현체가 ResourceComponent 안에서 일반 객체로 만들어져 다른 모듈에 주입됩니다.

모듈 관리 (Module Management)

목적과 범위 (Purpose and Scope)

이 문서는 GameFramework에서 모든 주요 서브시스템을 조직화·초기화·업데이트·종료하는 기반인 모듈 관리 시스템을 설명합니다. 모듈 관리 시스템은 시스템 수명주기를 일관되게 다루는 방법을 제공하고, 프레임워크 능력을 위한 명확한 아키텍처를 구성합니다.

모듈 시스템과 함께 동작하는 객체 참조 풀링에 대한 정보는 Reference Pool을 참조하세요.

개요 (Overview)

모듈 관리 시스템은 두 가지 핵심 구성요소 GameFrameworkEntry와 GameFrameworkModule을 중심으로 합니다. 이 시스템은 모든 프레임워크 서브시스템의 자동 생성, 우선순위 기반 업데이트, 질서 있는 종료를 가능하게 하면서, 시스템 간의 약한 결합(loose coupling) 을 유지합니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 16–132

모듈 아키텍처 (Module Architecture)

이 모듈 시스템은 단순하지만 효과적인 아키텍처 패턴을 구현합니다:

•

모든 프레임워크 기능은 특화 모듈에 캡슐화됩니다.

•

각 모듈은 추상 기본 클래스 GameFrameworkModule을 상속합니다.

•

모듈은 정적 클래스 GameFrameworkEntry를 통해 자동으로 생성·관리됩니다.

•

게임 코드는 인터페이스를 통해 모듈과 상호작용하여 약한 결합을 촉진합니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 16–132

모듈 조회 시스템 (Module Retrieval System)

모듈 조회 시스템은 게임 코드가 GetModule<T>() 메서드를 사용해 인터페이스를 통해 어떤 모듈이든 접근할 수 있게 해줍니다. 요청된 모듈이 존재하지 않으면 자동으로 생성되어, 모듈은 필요할 때만 초기화됩니다.

모듈 조회의 핵심 특성:

•

모듈은 인터페이스(예: IResourceManager) 로 조회해야 합니다.

•

구체 구현 클래스는 프레임워크가 자동으로 결정합니다.

•

모듈 인스턴스는 지연 생성(최초 요청 시) 됩니다.

•

모듈은 약한 결합을 위해 인터페이스 타입으로 반환됩니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 55–76, 84–95

모듈 생성 과정 (Module Creation Process)

모듈이 처음 요청되면 프레임워크는 다음을 수행합니다:

리플렉션으로 모듈 인스턴스를 생성합니다.

모듈의 우선순위에 따라 모듈 목록에서 삽입 위치를 결정합니다.

모듈을 적절한 위치에 삽입합니다.

생성된 모듈을 호출자에게 반환합니다.

이를 통해 모듈은 요청 시점에 생성되고, 업데이트를 위해 올바른 순서로 정렬됩니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 102–131

모듈 수명주기 관리 (Module Lifecycle Management)

모듈 업데이트 순서 (Module Update Sequence)

모듈 시스템은 GameFrameworkEntry.Update() 를 통해 중앙집중식 업데이트 처리를 제공합니다. 이 메서드는:

•

모든 모듈을 우선순위 순서로 순회하고,

•

각 모듈의 Update()를 호출하면서 경과 시간 값을 전달하며,

•

모듈이 필요한 주기적 작업을 수행할 수 있게 합니다.

즉, 우선순위가 높은 모듈이 낮은 모듈보다 먼저 항상 업데이트됩니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 25–31

모듈 종료 순서 (Module Shutdown Sequence)

애플리케이션 종료 시 프레임워크는 GameFrameworkEntry.Shutdown() 을 통해 체계적인 정리를 보장합니다:

•

모든 모듈을 우선순위의 역순(마지막부터 처음) 으로 순회하고,

•

각 모듈의 Shutdown()을 호출합니다.

•

모든 종료가 완료되면 모듈 목록을 비우고,

•

(예: 레퍼런스 풀 정리 등) 추가 정리 작업을 수행합니다.

이로써 낮은 우선순위 모듈이 그에 의존할 수 있는 높은 우선순위 모듈보다 먼저 종료됩니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 36–47

모듈 우선순위 (Module Prioritization)

모듈은 우선순위로 정렬된 연결 리스트에 보관되며, 우선순위가 높은 모듈이 목록의 앞쪽에 위치합니다. 이 정렬은 다음에 영향을 줍니다:

•

업데이트 순서: 높은 우선순위 모듈이 먼저 업데이트

•

종료 순서: 낮은 우선순위 모듈이 먼저 종료

새 모듈이 생성되면, 그 모듈의 Priority 속성에 따라 올바른 위치에 삽입됩니다.

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 110–128

구현 세부사항 (Implementation Details)

모듈 관리 시스템은 다음 자료구조와 패턴을 사용합니다:

•

GameFrameworkLinkedList: 모듈 인스턴스를 우선순위 순서로 저장하기 위한 특수 연결 리스트

•

모듈 인터페이스 네이밍 규칙: 인터페이스는 "I[ModuleName]", 구현 클래스는 "[ModuleName]"

◦

예: IResourceManager → ResourceManager

•

리플렉션 기반 인스턴스화: 요청된 인터페이스 타입에서 구현 클래스 이름을 유도해 자동 생성

예시:

// Interface name: IResourceManager
// Derived module name: ResourceManager
string moduleName = Utility.Text.Format("{0}.{1}", interfaceType.Namespace, interfaceType.Name.Substring(1));
Type moduleType = Type.GetType(moduleName);

복사

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 18, 68–75

모듈 사용 베스트 프랙티스 (Best Practices for Module Usage)

•

항상 GameFrameworkEntry.GetModule<T>() 를 사용해 인터페이스로 모듈에 접근하세요.

•

씬 사이에서 모듈 인스턴스를 캐싱하지 마세요(상태 문제 방지).

•

우선순위를 정할 때 모듈 간 의존성을 고려하세요.

•

모듈은 시작 시점이 아니라, 최초 요청 시 인스턴스화된다는 점을 기억하세요.

모듈 요약 (Module Summary)

Module	Interface	Purpose
ResourceManager	IResourceManager	게임 에셋의 로드/언로드/업데이트 처리
EntityManager	IEntityManager	게임 엔터티와 그 수명주기 관리
UIManager	IUIManager	UI 폼, 그룹, 레이어 제어
SoundManager	ISoundManager	오디오 재생 및 설정 관리
ConfigManager	IConfigManager	게임 설정 데이터 관리
DataTableManager	IDataTableManager	구조화된 게임 데이터 처리
LocalizationManager	ILocalizationManager	언어별 리소스 제공
NetworkManager	INetworkManager	네트워크 통신 관리
DownloadManager	IDownloadManager	파일 다운로드 처리
WebRequestManager	IWebRequestManager	웹 요청 관리
ObjectPoolManager	IObjectPoolManager	성능을 위한 오브젝트 풀 제공
FsmManager	IFsmManager	유한 상태 기계(FSM) 관리
SettingManager	ISettingManager	지속 사용자 설정 관리
DataNodeManager	IDataNodeManager	계층적 데이터 구조 관리

출처(Sources):

GameFramework/Base/GameFrameworkEntry.cs 16–132

Module Management

Abstract

모듈 관리 (Module Management)

관련 소스 파일 (Relevant source files)

목적과 범위 (Purpose and Scope)

개요 (Overview)

모듈 아키텍처 (Module Architecture)

모듈 조회 시스템 (Module Retrieval System)

모듈 생성 과정 (Module Creation Process)

모듈 수명주기 관리 (Module Lifecycle Management)

모듈 업데이트 순서 (Module Update Sequence)

모듈 종료 순서 (Module Shutdown Sequence)

모듈 우선순위 (Module Prioritization)

구현 세부사항 (Implementation Details)

모듈 사용 베스트 프랙티스 (Best Practices for Module Usage)

모듈 요약 (Module Summary)