Object Pooling (오브젝트 풀링)

Abstract

오브젝트 풀은 프레임워크의 범용 재사용 창고입니다. 엔티티 그룹과 UI 그룹이 내부에서 쓰는 바로 그 풀이고, 같은 것을 게임 코드도 직접 만들어 쓸 수 있습니다. 다만 대부분의 경우 엔티티나 UI 폼으로 만들면 풀링이 따라오므로, 직접 풀을 만드는 것은 그 둘에 맞지 않는 대상이 생겼을 때입니다.

직접 풀을 만들 만한 대상

•

적 머리 위에 따라다니는 월드 스페이스 HP 바 — 엔티티마다 하나씩 붙지만 그 자체는 엔티티가 아니다

•

데미지 숫자 팝업 — 초당 수십 개가 뜨고 1초 안에 사라진다

•

미니맵 아이콘, 조준선 마커처럼 수가 자주 변하는 UI 조각

직접 해 보기 — 데미지 숫자 풀

① 풀에 넣을 대상을 ObjectBase 로 감싼다. 풀은 GameObject 를 직접 모릅니다. "꺼낼 때 / 넣을 때 / 완전히 버릴 때 무엇을 할지"를 이 래퍼가 알려 줍니다.

using GameFramework;
using GameFramework.ObjectPool;
using UnityEngine;

namespace MyGame
{
    public class DamageTextObject : ObjectBase
    {
        public static DamageTextObject Create(GameObject instance)
        {
            DamageTextObject obj = ReferencePool.Acquire<DamageTextObject>();
            obj.Initialize(instance);        // Target 에 instance 가 들어간다
            return obj;
        }

        protected override void OnSpawn()
        {
            ((GameObject)Target).SetActive(true);
        }

        protected override void OnUnspawn()
        {
            ((GameObject)Target).SetActive(false);
        }

        // 풀이 이 객체를 완전히 버릴 때 (용량 초과·만료·종료)
        protected override void Release(bool isShutdown)
        {
            GameObject instance = (GameObject)Target;
            if (instance == null)
                return;

            Object.Destroy(instance);
        }
    }
}

복사

② 풀을 만든다 — 한 번만. Procedure 의 OnEnter 나 전용 컴포넌트의 Start 에서.

private const int PoolCapacity = 32;

ObjectPoolComponent objectPool = GameEntry.GetComponent<ObjectPoolComponent>();
mPool = objectPool.CreateSingleSpawnObjectPool<DamageTextObject>("DamageText", PoolCapacity);

복사

③ 꺼낸다 — 풀이 비어 있으면 null 이 오므로 그때만 새로 만들어 등록합니다.

DamageTextObject obj = mPool.Spawn();
if (obj == null)
{
    GameObject instance = Object.Instantiate(mPrefab, mRoot);
    obj = DamageTextObject.Create(instance);
    mPool.Register(obj, true);      // true = 등록과 동시에 "사용 중"
}

GameObject go = (GameObject)obj.Target;

복사

④ 돌려놓는다

mPool.Unspawn(go);     // Destroy 대신. OnUnspawn 이 불려 비활성화된다

복사

Single Spawn 과 Multi Spawn

	Single Spawn	Multi Spawn
한 객체를 동시에	한 곳에서만 쓴다	여러 곳에서 같이 쓴다 (참조 카운트)
맞는 대상	인스턴스 — HP 바, 데미지 숫자, 엔티티	공유 자원 — 로드한 에셋, 텍스처

GameObject 를 풀링한다면 거의 항상 Single Spawn 입니다.

ToyboxNightmare 에서는

ObjectPoolComponent 를 직접 부르지 않습니다. 하지만 플레이 중 Debugger 창의 Object Pool 탭을 열면 엔티티 그룹 5개(Player, Enemy, Projectile, Effect, Ally)와 UI 그룹의 인스턴스 풀이 돌고 있는 것을 볼 수 있습니다. HideEntity 로 회수한 적이 다음 ShowEntity 에서 다시 나오는 것이 이 풀 덕분입니다.

자주 걸리는 곳

•

ObjectBase 의 훅은 protected override 로 씁니다. 코어에서는 protected internal 이지만 게임 코드는 다른 어셈블리라 internal 을 붙이면 컴파일 에러(CS0507)입니다.

•

풀에서 다시 나온 인스턴스는 이전 상태 그대로입니다. 텍스트·색·위치·진행 중이던 트윈을 꺼낸 직후에 모두 다시 설정해야 합니다.

•

같은 이름·타입의 풀을 두 번 만들면 예외입니다. 재시작 흐름이 있다면 HasObjectPool<T>(name) 으로 확인하거나, 만든 쪽에서 DestroyObjectPool 로 정리합니다.

•

본문의 "Editor Integration" 절(ObjectPoolComponentInspector, CSV 내보내기)은 이 에디션에 없습니다. 런타임 Debugger 창을 쓰세요.

Object Pooling (오브젝트 풀링)

Relevant source files (관련 소스 파일)

•

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs

•

Scripts/Editor/Inspector/ReferencePoolComponentInspector.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

Overview (개요)

오브젝트 풀링(Object Pooling) 은 객체를 반복적으로 생성/삭제하는 대신 재사용하여 메모리 사용과 성능을 최적화하는 디자인 패턴입니다.

Unity 게임에서 오브젝트 풀링은 GC(가비지 컬렉션) 부하 감소, CPU 사용량 절감에 큰 효과가 있으며, 이를 위해 재사용 가능한 객체 풀을 유지합니다.

참고:

C# 참조형 객체를 위한 별도의 시스템은 Reference Pooling 문서를 확인하세요.

Overview and Architecture (개요 및 아키텍처)

Game Framework의 오브젝트 풀링 시스템은 객체 생성, 관리, 재사용을 위한 메커니즘을 제공합니다.

이는 효율적인 오브젝트 생명주기 관리를 위해 여러 컴포넌트로 구성됩니다.

Sources:

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 35-46

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs 38-42

Object Lifecycle (오브젝트 생명주기)

풀에 속한 객체는 특정 생명주기를 따릅니다. 이를 이해하는 것이 풀링 시스템 활용의 핵심입니다.

객체 상태 종류:

•

Created: 처음 생성되어 풀에 추가된 상태

•

Idle: 풀 안에서 대기 중인 상태 (재사용 가능)

•

In Use: 게임 내에서 활성화되어 사용 중인 상태

•

Released: 풀에서 제거된 상태 (풀 용량 초과 또는 만료 시점 도달 시)

Sources:

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 51-100

Key Features (핵심 기능)

Auto-Release Mechanism (자동 반환 메커니즘)

시스템은 주기적으로 미사용 객체를 검사하여 해제할 수 있습니다.

반환 기준은 다음과 같습니다:

•

Auto Release Interval: 검사 주기(초 단위)

•

Expire Time: 미사용 상태로 유지될 수 있는 시간

•

Priority: 공간 확보가 필요할 때 우선 제거할 객체의 우선순위

Sources:

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

Multi-Spawn Support (멀티 스폰 지원)

하나의 객체를 동시에 여러 번 스폰할 수 있도록 설정 가능합니다.

이는 동일 리소스가 여러 장소에 동시에 등장해야 하는 경우 유용합니다.

Sources:

Scripts/Editor/Inspector/ObjectPoolComponentInspector.cs 86-89

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs 63-79

Object Locking (객체 잠금)

객체를 잠금(lock) 상태로 설정하여 자동 반환 대상에서 제외할 수 있습니다.

이 기능은 항상 풀에 남아 있어야 하는 필수 객체 관리에 유용합니다.

Sources:

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

Configuring Object Pools (객체 풀 설정)

각 오브젝트 풀은 여러 매개변수로 설정할 수 있습니다:

Parameter	Description (설명)
Name	풀의 식별자
Type	관리되는 객체의 타입
Auto Release Interval	미사용 객체 검사 주기 (초 단위)
Capacity	풀에서 보관 가능한 최대 객체 수
Expire Time	미사용 객체가 해제되기까지의 시간
Priority	용량 도달 시 어떤 객체를 우선 해제할지 결정

Sources:

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

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

프레임워크는 런타임에서 오브젝트 풀을 디버깅/모니터링할 수 있는 기능을 제공합니다.

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

DebuggerComponent의 일부로 제공되며, 다음을 실시간 표시합니다:

•

풀의 개수

•

각 풀의 상세 정보 (이름, 타입, 용량 등)

•

풀 내 개별 객체 정보 (잠금 여부, 사용 상태, 우선순위, 마지막 사용 시각)

이 정보를 통해 풀 크기 문제, 잘못 재활용되는 객체 등을 파악할 수 있습니다.

Sources:

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

Editor Integration (에디터 통합)

ObjectPoolComponentInspector를 통해 에디터에서도 오브젝트 풀을 관리할 수 있습니다.

제공 기능:

•

풀 상세 정보 확인

•

객체 수동 반환

•

풀 데이터를 CSV로 내보내 분석

Sources:

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

Object Pool Information Display Example (정보 표시 예시)

Sources:

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

Integration with Game Framework (게임 프레임워크와의 통합)

오브젝트 풀링 시스템은 ObjectPoolComponent를 통해 Game Framework와 통합됩니다.

이를 통해 다른 시스템이 손쉽게 풀을 생성, 접근, 관리할 수 있으며, 전반적인 리소스 사용을 최적화합니다.

Sources:

Scripts/Runtime/Debugger/DebuggerComponent.ObjectPoolInformationWindow.cs 18-22

정리하면,

•

Object Pooling 문서는 Pooling Systems보다 더 세부적으로 GameObject 풀링 메커니즘을 다룬 문서입니다.

•

Reference Pooling은 별도로 다루므로, 여기서는 철저히 Unity 오브젝트 관리에 집중합니다.