Core Framework

Abstract

코어 프레임워크는 다른 모든 모듈이 올라서는 바닥입니다. 세 가지뿐입니다 — 모듈을 만들고 매 프레임 돌리는 GameFrameworkEntry, 작은 객체를 재활용하는 ReferencePool, 그리고 버전 정보. 게임 코드가 매일 만지는 것은 이 중 ReferencePool 하나입니다.

세 구성 요소와 게임 코드의 거리

구성 요소	하는 일	게임 코드에서
GameFrameworkEntry	모듈 생성·갱신·종료	직접 부르지 않는다. Unity 쪽 BaseComponent 가 대신 부른다
ReferencePool	C# 객체 재활용	자주 쓴다. 이벤트 인자, 엔티티 데이터
Version	프레임워크·게임 버전 문자열	가끔. 버전 표시, 서버 호환성 검사

한 프레임에 무슨 일이 일어나나

프레임워크 전체가 도는 것은 사실 이 한 줄 때문입니다.

// BaseComponent.cs (Unity 래퍼)
private void Update()
{
    GameFrameworkEntry.Update(Time.deltaTime, Time.unscaledDeltaTime);
}

복사

BaseComponent 가 붙은 GameObject 가 씬에 없으면 이벤트도, FSM 도, 엔티티도 전혀 움직이지 않습니다. 반대로 말하면 프레임워크의 심장은 MonoBehaviour 하나의 Update 이고, 나머지는 전부 평범한 C# 객체입니다. 그래서 코어를 Unity 없이 콘솔 프로그램에서 while 루프로 돌리는 것도 가능합니다(서버 로직 재사용, 단위 테스트).

게임 종료 시에는 GameFrameworkEntry.Shutdown() 이 모든 모듈을 역순으로 정리하고, 마지막에 ReferencePool.ClearAll() 로 풀을 비웁니다.

ToyboxNightmare 에서의 ReferencePool

// 꺼낼 때: new 대신
EnemyData data = ReferencePool.Acquire<EnemyData>();

// 돌려줄 때: 버리는 대신
ReferencePool.Release(data);     // 내부에서 data.Clear() 가 불린다

복사

자세한 규칙과 예제의 두 가지 사용 패턴은 Reference Pooling (레퍼런스 풀링) 에 정리했습니다.

확장 가능성 — 어디까지 열려 있나

•

새 모듈은 만들 수 없습니다. GameFrameworkModule 이 internal 입니다. GetModule<T>() 도 GameFramework. 네임스페이스의 인터페이스만 받습니다. 새 전역 시스템은 Unity 쪽에서 GameFrameworkComponent 를 상속해 만듭니다.

•

버전은 갈아 끼울 수 있습니다. Version.IVersionHelper 를 구현해 BaseComponent 의 Version Helper Type Name 에 지정하면 Version.GameVersion 이 내 게임의 버전을 돌려줍니다.

•

자료구조는 그대로 가져다 쓸 수 있습니다. GameFrameworkLinkedList<T> 는 노드를 재사용하는 연결 리스트라 삽입·삭제가 잦은 곳에서 가비지가 없고, GameFrameworkMultiDictionary<TKey, TValue> 는 "키 하나에 값 여러 개"가 필요할 때 Dictionary<TKey, List<TValue>> 대신 쓸 수 있습니다.

코어 프레임워크 (Core Framework)

주요 구성 요소

코어 프레임워크는 세 가지 주요 컴포넌트로 구성됩니다.

GameFrameworkEntry – 중앙 진입점이자 모듈 조정자

ReferencePool – 객체 풀링과 재사용을 위한 메모리 최적화 시스템

Version – 프레임워크 및 게임 버전을 추적하는 버전 관리 시스템

모듈 아키텍처

GameFrameworkEntry

GameFrameworkEntry 클래스는 프레임워크 전체의 중앙 허브 역할을 합니다.

이 클래스는 모든 프레임워크 모듈의 우선순위가 있는 연결 리스트를 유지하며 다음 기능을 제공합니다.

•

모듈 등록 및 검색 – 요청 시 자동으로 생성

•

모듈 업데이트 – 매 프레임 우선순위 순서대로 각 모듈의 Update 메서드 호출

•

모듈 종료 – 우선순위 역순으로 Shutdown 호출하여 정리

진입점은 리플렉션을 사용하여 인터페이스 요청을 구체 클래스 구현과 자동 매핑하여, 깔끔한 의존성 해결을 구현합니다.

모듈 검색 예시:

// 인터페이스를 통해 모듈을 가져오거나 생성
IResourceManager resourceManager = GameFrameworkEntry.GetModule<IResourceManager>();

복사

GetModule() 호출 시 과정:

T가 GameFramework 네임스페이스의 인터페이스인지 확인

인터페이스 이름에서 'I' 접두사를 제거하여 구체 클래스 이름 생성

리플렉션으로 모듈 인스턴스를 찾거나 생성

우선순위에 맞게 연결 리스트에 삽입

ReferencePool을 이용한 메모리 관리

ReferencePool은 효율적인 객체 풀링 시스템을 제공하여:

•

GC 부담 감소 (객체 재사용)

•

타입별 풀 관리

•

스레드 안전한 획득/반환

•

객체 사용 통계 추적

객체 풀에 들어가는 모든 객체는 IReference 인터페이스를 구현해야 하며, 이는 Clear() 메서드 하나를 정의하여 반환 시 객체 상태를 초기화합니다.

사용 패턴 예시:

MyEventArgs eventArgs = ReferencePool.Acquire<MyEventArgs>();
// 객체 사용 ...
ReferencePool.Release(eventArgs); // Clear() 자동 호출

복사

각 타입별 객체 풀은 ReferenceCollection을 가지고, 내부 큐에 미사용 인스턴스를 저장합니다. 큐가 비어있으면 새 객체를 생성합니다.

버전 시스템

Version 컴포넌트는 프레임워크와 게임 버전을 제공합니다.

•

GameFrameworkVersion – 프레임워크 버전(고정 문자열)

•

GameVersion – 게임 버전(헬퍼를 통해 제공)

•

InternalGameVersion – 호환성 검사를 위한 정수 버전

게임은 IVersionHelper 구현체를 제공하여 자체 버전 정보를 노출해야 합니다.

커스텀 데이터 구조

코어 프레임워크에는 다음과 같은 특수 데이터 구조가 포함되어 있습니다.

데이터 구조	목적	주요 기능
GameFrameworkLinkedList<T>	효율적인 연결 리스트	노드 캐싱으로 메모리 할당 감소
GameFrameworkLinkedListRange<T>	연결 리스트의 구간 표현	특정 구간 노드 열거 지원
GameFrameworkMultiDictionary<TKey,TValue>	키당 여러 값 저장	연결 리스트 구간 사용

이 자료구조들은 객체 풀, 이벤트 시스템, 리소스 관리 등 상위 시스템의 기반이 됩니다.

모듈 수명 주기

생성 및 초기화 – GetModule<T>() 호출 시 생성, 우선순위에 따라 정렬

업데이트 – 매 프레임 우선순위 순서대로 Update 호출

종료 – 게임 종료 시 역순으로 Shutdown 호출

이 순서는 의존성을 가진 모듈 간 올바른 초기화와 정리를 보장합니다.

모범 사례

모듈 구현

•

(프레임워크 내부 규칙) 모듈은 I이름 인터페이스 + GameFrameworkModule 을 상속한 같은 이름의 클래스 한 쌍으로 만든다

•

적절한 Priority 값 설정

•

Update와 Shutdown 메서드 구현

•

단, GameFrameworkModule 은 internal 이라 게임 코드에서는 새 모듈을 만들 수 없다. 새 전역 시스템은 Unity 쪽의 GameFrameworkComponent 를 상속해 만든다

메모리 관리

•

자주 생성/파괴되는 객체에 IReference 구현

•

사용 후 반드시 ReferencePool.Release() 호출

•

Clear()에서 상태 초기화

모듈 의존성

•

GameFrameworkEntry.GetModule<T>() 사용으로 올바른 생성 순서 확보