Entity Manager

Abstract

Entity Manager 는 엔티티의 장부입니다. "지금 Id 몇 번이 살아 있고, 어느 그룹에 속하며, 어떤 상태인가"를 기록하고, 그 기록에 따라 로직의 OnInit / OnShow / OnHide 를 정해진 순서로 딱 한 번씩 불러 줍니다. 게임 코드에서 겪는 엔티티 관련 예외는 거의 전부 이 장부와 어긋난 요청을 했을 때 납니다.

엔티티의 일생 — 상태와 콜백

stateDiagram-v2
    [*] --> Loading: ShowEntity
    Loading --> Inited: 에셋 도착 → OnInit (인스턴스가 새것일 때만)
    Inited --> Showed: OnShow
    Showed --> Hidden: HideEntity → OnHide
    Hidden --> Recycled: 다음 Update → OnRecycle
    Recycled --> [*]: 인스턴스는 풀로
    Loading --> [*]: 로드 중 HideEntity → 도착하면 바로 버림

Mermaid

복사

여기서 게임 코드가 알아야 할 것은 HideEntity 가 두 단계라는 점입니다. 호출 즉시 OnHide 가 불리고 장부에서 지워지지만(Hidden), 인스턴스가 풀로 돌아가는 것은 다음 프레임의 Update 입니다(Recycled). 그 사이 한 프레임 동안 GameObject 는 아직 그 자리에 있습니다.

자주 만나는 예외와 원인

메시지	원인	ToyboxNightmare 의 대응
Entity id '…' is already exist.	살아 있는 Id 로 또 ShowEntity. Id 는 호출자가 정해 넘기는 값이라 겹치지 않게 할 책임도 호출자에게 있다	EntitySerialId.Next() 로 매번 새 번호를 받는다
Can not find entity '…'.	이미 숨긴 엔티티를 또 HideEntity. 첫 호출에서 장부에서 지워졌기 때문이다	EntityLogicBase.SafeHide() — "이미 숨김 요청을 보냈나" 플래그로 한 번만 통과시킨다
Entity group '…' is not exist.	ShowEntity 에 넘긴 그룹 이름이 EntityComponent 에 등록돼 있지 않다 (오타)	그룹 이름을 EnemyTable.EntityGroup 같은 상수로 한곳에 둔다

이중 HideEntity 가 실제로 어떻게 생기는지 알아 두면 좋습니다. 적이 같은 프레임에 두 발의 총알을 맞아 사망 처리가 두 번 들어오거나, 수명 타이머와 충돌 판정이 동시에 투사체를 회수하려 할 때입니다. 드물지만 반드시 일어나는 경우라, 예제는 모든 회수를 SafeHide() 하나로 모았습니다.

부모-자식 — 붙이면 함께 사라진다

AttachEntity(child, parent) 로 붙인 자식은 부모가 숨겨질 때 먼저 자동으로 숨겨집니다. 무기를 캐릭터에 붙여 두면 캐릭터를 회수할 때 무기를 따로 챙기지 않아도 됩니다. 반대로 말하면, 부모를 숨긴 뒤 자식을 또 숨기려 하면 위의 Can not find entity 예외가 납니다.

// 무기 엔티티가 뜬 뒤(ShowEntitySuccess) 캐릭터의 손 본에 붙인다
entity.AttachEntity(weaponId, playerId, "RightHand");

복사

ToyboxNightmare 는 무기를 별도 엔티티로 만들지 않고 캐릭터 프리팹에 포함해 두어서 이 기능을 쓰지 않습니다. 장비 교체가 있는 게임이라면 가장 먼저 쓰게 될 기능입니다.

OnInit 과 OnShow 가 나뉜 이유

인스턴스가 풀에서 재사용되기 때문입니다. OnInit 은 GameObject 가 처음 만들어졌을 때 한 번, OnShow 는 스폰될 때마다 불립니다.

	OnInit 에 둘 것	OnShow 에 둘 것
성격	한 번 찾아 두면 변하지 않는 것	스폰마다 달라지는 것
예	GetComponentInChildren 으로 캐싱, 상태 객체 생성	체력·위치·타이머 리셋, FSM 생성, 애니메이터 초기화

"두 번째 스폰부터 체력이 0 인 채로 나온다" 같은 버그는 OnShow 에서 리셋할 것을 OnInit 이나 필드 초기값에 맡겼을 때 생깁니다.

본문을 읽을 때 주의할 점

•

본문의 entityManager.ShowEntity(...) 는 코어 API 입니다. 게임 코드는 GameEntry.GetComponent<EntityComponent>() 를 쓰고, 여기서는 로직 타입 인자가 하나 더 붙습니다 — ShowEntity(id, typeof(Enemy), "Zombunny", "Enemy", data).

•

"사용 가이드 → 초기화" 의 SetObjectPoolManager / SetResourceManager / AddEntityGroup 은 EntityComponent 가 Start 에서 대신 해 줍니다. 그룹은 인스펙터에서 등록합니다.

•

ShowEntityUpdate / ShowEntityDependencyAsset 이벤트는 이 에디션에서 발생하지 않습니다(리소스 계층이 진행률을 전달하지 않음).

•

엔티티를 치울 때는 반드시 HideEntity 를 거칩니다. Destroy 나 SetActive(false) 로 치우면 장부에는 살아 있는 것으로 남아 Id 가 영원히 점유되고 풀도 어긋납니다.

Entity Manager

개요 (Overview)

Entity Manager는 다음과 같은 기능을 수행하는 중앙 시스템입니다.

•

에셋에서 게임 엔티티 생성 및 표시

•

엔티티를 논리적 그룹으로 조직

•

엔티티 간 부모-자식 관계 관리

•

엔티티 생명주기 이벤트 처리

•

오브젝트 풀을 통한 엔티티 인스턴스 재활용

핵심 아키텍처

다른 GameFramework 시스템과 동일하게 모듈형 디자인 패턴을 따릅니다.

Entity Manager

EntityManager 클래스는 IEntityManager 인터페이스를 구현한 핵심 구성요소입니다.

역할:

•

mEntityInfos 딕셔너리로 활성 엔티티 추적 (원작 표기는 m_EntityInfos)

•

mEntityGroups 딕셔너리로 엔티티 그룹 관리

•

리소스 매니저와 협력하여 엔티티 로딩

•

엔티티 재활용 및 풀링 관리

•

부모-자식 관계 관리

•

생명주기 이벤트 브로드캐스트

엔티티 그룹 (Entity Groups)

엔티티 그룹은 관련 엔티티를 묶는 컨테이너입니다.

각 그룹은 고유한 인스턴스 풀을 가집니다.

속성:

•

Name: 그룹 식별자

•

EntityCount: 그룹 내 엔티티 개수

•

InstanceAutoReleaseInterval: 풀 자동 해제 주기

•

InstanceCapacity: 풀 최대 용량

•

InstanceExpireTime: 미사용 인스턴스 만료 시간

•

InstancePriority: 풀 해제 우선순위

•

Helper: 그룹 헬퍼 구현체

엔티티 정보 추적 (EntityInfo)

EntityManager는 EntityInfo 클래스를 통해 엔티티 상태를 내부적으로 추적합니다.

엔티티 생명주기

엔티티는 생성 → 표시 → 숨김 → 재활용 과정을 거칩니다.

엔티티 표시 (ShowEntity)

절차:

ShowEntity() 호출 (ID, 에셋 이름, 그룹 이름 지정)

풀에 인스턴스 존재 여부 확인

없으면 리소스 매니저로 에셋 로드

로드 성공 시 엔티티 초기화

해당 그룹에 추가

OnInit(), OnShow() 콜백 실행

ShowEntitySuccess 이벤트 발생

엔티티 숨김 (HideEntity)

절차:

HideEntity() 호출 (ID 또는 참조)

로딩 중이면 release-on-load 리스트에 추가

아니면 InternalHideEntity() 호출

OnHide() 콜백 실행

재활용 큐에 추가

HideEntityComplete 이벤트 발생

엔티티 재활용

업데이트 루프에서 재활용 큐 처리:

큐에서 엔티티 꺼내기

상태를 WillRecycle로 변경

OnRecycle() 콜백 실행

상태를 Recycled로 변경

인스턴스를 해당 그룹 풀에 반환

EntityInfo 해제

엔티티 계층 구조

부모-자식 관계를 지원합니다.

AttachEntity

•

자식 엔티티에 부모 참조 설정

•

부모의 자식 리스트에 추가

•

부모 OnAttached() 호출

•

자식 OnAttachTo() 호출

Query

•

GetParentEntity()

•

GetChildEntityCount()

•

GetChildEntity()

•

GetChildEntities()

DetachEntity

•

부모의 자식 리스트에서 제거

•

자식의 부모 참조 제거

•

부모 OnDetached() 호출

•

자식 OnDetachFrom() 호출

다른 시스템과의 통합

오브젝트 풀

•

각 엔티티 그룹은 전용 풀 보유

•

필요 시 풀에서 생성

•

숨길 때 풀에 반환

•

그룹별 파라미터 설정 가능

리소스 매니저

•

에셋 로딩 위임

•

로드 성공/실패 콜백 처리

이벤트 시스템

•

ShowEntitySuccess

•

ShowEntityFailure

•

ShowEntityUpdate

•

ShowEntityDependencyAsset

•

HideEntityComplete

다른 매니저와 비교

기능	Entity Manager	UI Manager	Sound Manager
그룹 개념	Entity Groups	UI Groups	Sound Groups
에셋 로딩	Resource Manager	Resource Manager	Resource Manager
인스턴스 풀	Entity Instances	UI Form Instances	Sound Agents
헬퍼 인터페이스	IEntityHelper	IUIFormHelper	ISoundHelper
그룹 헬퍼	IEntityGroupHelper	IUIGroupHelper	ISoundGroupHelper
부모-자식 지원	O	X	X
생명주기 이벤트	Show/Hide	Open/Close	Play/Stop

사용 가이드

초기화

entityManager.SetObjectPoolManager(objectPoolManager);
entityManager.SetResourceManager(resourceManager);
entityManager.SetEntityHelper(entityHelper);

entityManager.AddEntityGroup(groupName, autoReleaseInterval, capacity, expireTime, priority, groupHelper);

복사

엔티티 기본 조작

entityManager.ShowEntity(entityId, entityAssetName, entityGroupName);
entityManager.HideEntity(entityId);

bool exists = entityManager.HasEntity(entityId);
IEntity entity = entityManager.GetEntity(entityId);

복사

계층 조작

entityManager.AttachEntity(childEntityId, parentEntityId);
entityManager.DetachEntity(childEntityId);
IEntity parent = entityManager.GetParentEntity(childEntityId);
IEntity[] children = entityManager.GetChildEntities(parentEntityId);

복사