Pooling System

Abstract

풀링은 "만들고 버리는 대신 돌려 쓴다"는 한 가지 아이디어입니다. 프레임워크에는 풀이 세 겹으로 들어 있고, 그중 게임 코드가 직접 만질 일이 있는 것은 사실상 하나(레퍼런스 풀)입니다. 나머지는 엔티티와 UI 를 쓰면 저절로 돕니다.

세 겹의 풀 — 무엇이 무엇을 재사용하나

풀	재사용하는 것	게임 코드가 하는 일	ToyboxNightmare
엔티티 그룹 / UI 그룹 (내부적으로 오브젝트 풀)	프리팹 인스턴스(GameObject)	ShowEntity / HideEntity 만 부른다. 풀은 보이지 않는다	적·투사체·이펙트 전부
오브젝트 풀 (ObjectPoolComponent)	엔티티도 UI 폼도 아닌 것 — 월드 HP 바, 데미지 숫자 등	풀을 직접 만들고 Spawn / Unspawn	직접 쓰지 않음
레퍼런스 풀 (ReferencePool)	순수 C# 객체 — 이벤트 인자, 엔티티 데이터	Acquire / Release	이벤트 인자 7종, 엔티티 데이터 7종

고르는 기준

•

게임 월드에 나타났다 사라지는 것 → 엔티티로 만든다. 풀링은 따라온다.

•

화면에 뜨는 창 → UI 폼으로 만든다. 마찬가지.

•

위 둘에 안 맞는데 자주 생기는 GameObject → 오브젝트 풀.

•

new 로 자주 만드는 작은 클래스 → 레퍼런스 풀.

풀 크기는 어디서 정하나

엔티티 그룹의 풀 설정은 GameFramework.prefab 의 Entity 오브젝트에 있습니다. 예제의 값입니다.

그룹	Instance Capacity	들어가는 것
Player	4	선택 화면의 Girl / Boy, 플레이 중인 캐릭터
Enemy	64	적 5종 (스폰 테이블의 동시 생존 상한 합계는 13)
Projectile	64	슬라임·악취 투사체
Effect	32	피격 이펙트
Ally	2	소환된 아군 (Sheep / Dog)

Capacity 는 "풀에 보관해 둘 최대 수"이지 스폰 상한이 아닙니다. 넘쳐도 스폰은 되고, 넘친 만큼은 회수될 때 보관되지 않고 파괴될 뿐입니다. Expire Time(예제 60초) 동안 다시 쓰이지 않은 인스턴스는 Auto Release Interval(60초)마다 도는 검사에서 정리됩니다.

본문을 읽을 때 주의할 점

•

본문은 오브젝트 풀을 "Unity GameObject 전용"이라고 설명하지만, 정확히는 ObjectBase 로 감싼 임의의 객체를 다룹니다. 원작은 로드한 에셋 자체도 이 풀로 관리했습니다. GameObject 풀링은 가장 흔한 용도일 뿐입니다.

•

"Editor Integration" 절(인스펙터에서 통계 보기, CSV 내보내기, 수동 해제)은 이 에디션에 없습니다. 에디터 확장이 빠져 있습니다. 같은 정보는 런타임 Debugger 창의 Object Pool / Reference Pool 탭에서 봅니다.

Pooling Systems (풀링 시스템)

Relevant source files (관련 소스 파일)

•

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs

•

Scripts/Editor/Inspector/ReferencePoolComponentInspector.cs

•

Scripts/Editor/Inspector/ReferencePoolComponentInspector.cs.meta

•

Scripts/Runtime/Debugger/DebuggerActiveWindowType.cs

•

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs

•

Scripts/Runtime/Debugger/DebuggerComponent.ReferencePoolInformationWindow.cs

•

Scripts/Runtime/Debugger/DebuggerComponent.ReferencePoolInformationWindow.cs.meta

•

Scripts/Runtime/Debugger/DebuggerComponent.RuntimeMemoryInformationWindow.cs

•

Scripts/Runtime/Debugger/DebuggerComponent.RuntimeMemorySummaryWindow.cs

•

Scripts/Runtime/Debugger/DebuggerComponent.cs

•

Scripts/Runtime/ReferencePool.meta

•

Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs

•

Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs.meta

•

Scripts/Runtime/ReferencePool/ReferenceStrictCheckType.cs

•

Scripts/Runtime/ReferencePool/ReferenceStrictCheckType.cs.meta

Overview (개요)

Unity Game Framework는 게임 내 메모리 사용 최적화 및 GC(Garbage Collection) 부하 감소를 위해 두 가지 풀링 시스템을 제공합니다.

•

Object Pool System (오브젝트 풀 시스템): Unity GameObject 전용 풀링

•

Reference Pool System (레퍼런스 풀 시스템): C# 객체 전용 풀링

이 두 시스템은 객체를 재사용함으로써 성능을 개선하며, 반복적인 생성/파괴로 인한 오버헤드를 줄입니다.

일반적인 리소스 관리에 대해서는 Resource Management System 참고

Sources:

Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs

Scripts/Runtime/ObjectPool/ObjectPoolComponent.cs (파일 목록에는 없지만 추론됨)

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs

Scripts/Runtime/Debugger/DebuggerComponent.ReferencePoolInformationWindow.cs

Object Pool System (오브젝트 풀 시스템)

오브젝트 풀 시스템은 Unity GameObject를 관리합니다.

객체를 매번 Instantiate/Destroy 하지 않고 재사용할 수 있도록 하여, 특히 투사체, 이펙트, UI 요소 등 자주 생성/파괴되는 오브젝트에 유리합니다.

Architecture and Components (아키텍처 및 컴포넌트)

Sources:

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 41-45

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 75-82

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 83-90

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs 46-58

Key Features (핵심 기능)

•

Single/Multi-Spawn 지원:

하나의 인스턴스만 동시에 활성화되는 단일 스폰 모드와 여러 개를 동시에 활성화할 수 있는 멀티 스폰 모드 지원

•

자동 반환(Auto-Release):

지정한 시간 후 객체를 풀로 자동 반환

•

우선순위(Prioritization):

풀 공간이 부족할 때 우선순위가 높은 객체는 더 오래 유지됨

•

객체 추적(Object Tracking):

각 객체의 상태와 마지막 사용 시점 등 상세 정보 추적

Using the Object Pool (사용 방법)

•

주로 Prefab 인스턴스, 자주 생성/삭제되는 Unity 오브젝트 관리에 사용

•

반환된 오브젝트는 비활성화 상태로 유지되며, 필요할 때 즉시 재활성화 가능

Reference Pool System (레퍼런스 풀 시스템)

레퍼런스 풀 시스템은 C# 객체를 관리하여 GC 부하를 줄이는 것에 초점이 맞춰져 있습니다.

특히 이벤트 파라미터, 커맨드 인자, 임시 데이터 구조체 등 짧은 생명주기 객체에 유용합니다.

Architecture and Components (아키텍처 및 컴포넌트)

Sources:

Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs 16-72

Scripts/Runtime/ReferencePool/ReferenceStrictCheckType.cs 13-34

Scripts/Editor/Inspector/ReferencePoolComponentInspector.cs 48-58

Scripts/Runtime/Debugger/DebuggerComponent.ReferencePoolInformationWindow.cs 33-41

Strict Checking (엄격 검사)

레퍼런스 풀은 객체가 올바르게 획득/반환되는지 검사할 수 있는 기능을 제공합니다.

•

활성화 시, 객체의 올바른 획득/반환 여부를 검증

•

메모리 누수나 잘못된 사용 패턴을 탐지 가능

•

개발 시점(에디터/디버그 빌드 등)에서만 활성화 가능

ReferenceStrictCheckType 옵션:

•

AlwaysEnable: 항상 활성화

•

OnlyEnableWhenDevelopment: 개발 빌드에서만 활성화

•

OnlyEnableInEditor: 에디터에서만 활성화

•

AlwaysDisable: 비활성화

Sources:

Scripts/Runtime/ReferencePool/ReferencePoolComponent.cs 51-69

Scripts/Runtime/ReferencePool/ReferenceStrictCheckType.cs 13-34

Using the Reference Pool (사용 방법)

•

풀링 대상 클래스는 IReference 인터페이스를 구현하고 public 기본 생성자를 가져야 함

•

객체 획득: ReferencePool.Acquire<T>()

•

객체 반환: ReferencePool.Release(reference) (제네릭이 아니며 IReference 를 받는다)

•

엄격 검사는 성능에 영향을 줄 수 있으므로 보통 개발/테스트 시에만 사용

Debugging and Monitoring (디버깅 및 모니터링)

두 풀링 시스템 모두 디버거 컴포넌트를 통해 모니터링이 가능합니다.

Object Pool Information Window (오브젝트 풀 정보 창)

표시 내용:

•

전체 오브젝트 풀 개수

•

각 풀의 상세 정보: 이름, 타입, 용량

•

현재 사용량

•

자동 반환 간격

•

우선순위 설정

•

객체 상태 정보

Sources:

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs 30-92

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 25-136

Reference Pool Information Window (레퍼런스 풀 정보 창)

표시 내용:

•

엄격 검사 활성 여부

•

전체 레퍼런스 풀 개수

•

각 타입별 통계:

◦

사용 중/미사용 객체 수

◦

획득/반환 횟수

◦

추가/제거 횟수

•

클래스 이름 표기를 전체 이름 / 단순 이름으로 전환 가능

Sources:

Scripts/Runtime/Debugger/DebuggerComponent.ReferencePoolInformationWindow.cs 30-86

Scripts/Editor/Inspector/ReferencePoolComponentInspector.cs 29-128

Editor Integration (에디터 통합)

프레임워크는 에디터에서 다음 기능을 제공합니다:

•

풀 통계 모니터링 (Play Mode 중 확인 가능)

•

CSV로 데이터 내보내기

•

인스펙터에서 직접 미사용 객체 해제

Sources:

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 20-138

Scripts/Editor/Inspector/ReferencePoolComponentInspector.cs 19-152

Best Practices (모범 사례)

•

Object Pool:

투사체, 이펙트, UI 등 자주 생성/삭제되는 Unity GameObject 관리에 사용

•

Reference Pool:

이벤트 파라미터, 명령 인자, 임시 데이터 등 짧은 수명의 C# 객체 관리에 사용

•

자동 반환 설정:

메모리 사용과 성능 균형을 맞출 수 있도록 적절히 지정

•

적절한 용량 설정:

동시에 필요할 것으로 예상되는 최대 수량보다 약간 큰 값으로 풀 크기 설정

•

개발 중 엄격 검사 활성화:

개발 단계에서는 Reference Pool의 Strict Checking을 켜서 문제를 조기에 발견,

릴리즈 빌드에서는 성능을 위해 비활성화