Entity Framework

Abstract

플레이어가 보고 듣는 것은 셋 중 하나입니다 — 월드에 있는 것(Entity), 화면에 덮이는 것(UI), 귀로 들리는 것(Sound). 이 페이지는 그 세 매니저를 한꺼번에 소개합니다. 요점은 셋이 같은 틀로 만들어져 있어서 하나를 익히면 나머지는 이름만 바꿔 읽으면 된다는 것입니다.

세 매니저의 공통 틀

	Entity	UI	Sound
시작	ShowEntity	OpenUIForm	PlaySound
끝	HideEntity	CloseUIForm	StopSound (또는 재생이 끝나면 자동)
묶음 단위	엔티티 그룹	UI 그룹	사운드 그룹
그룹이 정하는 것	인스턴스 풀의 크기·수명	화면 층(depth), 가림·일시정지	동시 재생 수(에이전트 개수), 볼륨, 음소거
에셋 지정	Addressables 주소 (문자열)	Addressables 주소 (문자열)	Addressables 주소 (문자열)
결과 통지	비동기 → 이벤트	비동기 → 이벤트	비동기 → 이벤트
식별자	호출자가 정한 Id	반환되는 serialId	반환되는 serialId

ToyboxNightmare 의 구성

매니저	그룹	쓰는 곳
Entity	Player, Enemy, Projectile, Effect, Ally	캐릭터·적·투사체·피격 이펙트·소환수 전부
UI	Default	HUDForm, PauseMenuForm
Sound	Music(에이전트 1), Soundeffects(에이전트 8)	피격·사망 효과음 8종 (Soundeffects 그룹)

한 장면으로 보기 — 적이 플레이어를 때릴 때

// Entity: 피격 이펙트를 띄운다
entity.ShowEntity(effectId, typeof(HitEffect), "SlimeHit", "Effect", EffectData.Create(effectId, 1, hitPosition, rotation, lifetime));

// Sound: 피격음을 그 위치에서 낸다
sound.PlaySound("PlayerHurt", "Soundeffects", hitPosition);

// UI: 직접 부르지 않는다. 체력 변화 이벤트를 발행하면 HUD 가 듣고 스스로 갱신한다
events.Fire(this, PlayerHealthChangedEventArgs.Create(fromRatio, toRatio));

복사

세 줄의 모양이 거의 같고, 어느 것도 프리팹이나 오디오 클립을 직접 참조하지 않습니다.

그룹을 어떻게 나눌 것인가 — 확장할 때의 기준

•

엔티티 그룹은 "수명과 수량이 비슷한 것끼리". 초당 수십 개 뜨는 투사체와 한 판에 하나뿐인 보스를 같은 그룹에 두면 풀 설정을 어느 한쪽에 맞출 수 없습니다.

•

UI 그룹은 "화면의 층". 보통 Background / Default / Popup / System(로딩·오류) 정도로 시작합니다.

•

사운드 그룹은 "볼륨 슬라이더 하나". 옵션 화면에 배경음·효과음·음성 슬라이더가 따로 있다면 그룹도 셋입니다. 에이전트 수는 그 종류가 동시에 몇 개까지 겹쳐 들려야 하는지로 정합니다 — 배경음은 1(크로스페이드하려면 2), 효과음은 8~16.

본문을 읽을 때 주의할 점

•

"오브젝트 풀링"은 Entity 와 UI 에만 해당합니다. Sound 는 인스턴스 풀이 아니라 미리 만들어 둔 에이전트(AudioSource) 를 돌려 씁니다. 에이전트가 모두 재생 중이면 우선순위가 낮은 소리를 끊고 새 소리를 내거나, 새 소리가 무시됩니다.

•

"UI 깊이 관리"에서 그룹 depth 가 렌더링 순서를 정한다고 설명하지만, 이 에디션의 기본 그룹 헬퍼는 depth 를 적용하지 않습니다(SetDepth 가 빈 구현). 예제는 각 폼 Canvas 의 Sorting Order 로 순서를 줍니다.

•

"비동기 진행률 이벤트"는 이 에디션에서 발생하지 않습니다. 성공·실패 이벤트만 옵니다.

•

프리팹에 로직 스크립트를 붙이는 규칙이 Entity 와 UI 에서 정반대입니다. 엔티티 프리팹에는 붙이지 않고(런타임에 붙음), UI 폼 프리팹에는 반드시 붙입니다.

엔티티 프레임워크 (Entity Framework)

아키텍처 개요 (Architecture Overview)

엔티티 프레임워크는 세 가지 주요 하위 시스템(Entity, UI, Sound)에서 일관된 아키텍처 패턴을 따릅니다.

각 하위 시스템은 중앙 집중식 매니저를 가지고 있으며, 이 매니저는 요소를 논리적 그룹으로 조직하고, 리소스를 관리하며, 라이프사이클 이벤트를 제공합니다.

공통 설계 패턴 (Common Design Pattern)

엔티티 프레임워크의 세 매니저는 공통적으로 다음 설계 원칙을 따릅니다.

•

그룹 기반 조직: 요소들은 관리 효율성을 위해 이름이 있는 그룹으로 조직됩니다.

•

리소스 기반 인스턴스화: 요소들은 ResourceManager를 통해 애셋에서 로드됩니다.

•

오브젝트 풀링(Object Pooling): 효율적인 객체 재사용을 위해 오브젝트 풀을 활용합니다.

•

이벤트 기반 통신: 상태 변경에 대한 이벤트 기반 알림을 제공합니다.

•

헬퍼 인터페이스 패턴: 플랫폼별 구현은 헬퍼 인터페이스를 통해 지원됩니다.

엔티티 관리 시스템 (Entity Management System)

엔티티 관리 시스템은 게임 세계의 게임 오브젝트(Entity)를 생성, 조직, 제어하는 역할을 합니다.

엔티티(Entity)는 캐릭터, 소품, 이펙트, 상호작용 가능한 요소 등 게임 환경에 존재하는 모든 객체를 의미합니다.

엔티티 아키텍처 (Entity Architecture)

엔티티 그룹(Entity Group)

•

엔티티는 이름이 있는 그룹으로 조직됩니다.

•

각 그룹은 다음 기능을 가집니다:

◦

자체 오브젝트 풀을 유지

◦

자동 해제 간격, 용량, 만료 시간 설정

◦

그룹 내 엔티티 추적 및 관리

엔티티 라이프사이클 (Entity Lifecycle)

생성: ShowEntity 호출 (엔티티 ID, 애셋 이름, 그룹 이름 지정)

로딩: ResourceManager를 통해 리소스 로드

초기화: 엔티티 초기화 후 그룹에 추가

업데이트: 매 프레임 업데이트 호출

부착(옵션): 부모 엔티티에 부착 가능

숨김: HideEntity 호출

재활용: 엔티티 인스턴스를 오브젝트 풀로 반환

부모-자식 관계 (Parent-Child Relationship)

•

엔티티 간 계층 구조를 지원

◦

부모 엔티티에 부착(Attach)

◦

부모로부터 분리(Detach)

◦

계층 탐색 가능

•

복합 객체, 캐릭터 부착물 등 복잡한 구조 구현 가능

UI 관리 시스템 (UI Management System)

UI 관리 시스템은 UI 요소를 생성, 표시, 제어하는 프레임워크를 제공합니다.

UI Form 로딩, 표시, 상호작용 등을 관리합니다.

UI 아키텍처 (UI Architecture)

UI 그룹(UI Group)

•

UI Form은 그룹으로 조직되며, 그룹은 다음 기능을 가집니다:

◦

렌더링 순서를 결정하는 깊이(Depth) 값 설정

◦

UI Form 스택 유지

◦

활성/일시정지/가림 상태 제어

◦

동일 그룹 내 포커스 관리

UI Form 라이프사이클 (UI Form Lifecycle)

열기: OpenUIForm 호출 (애셋 이름, 그룹 이름)

로딩: ResourceManager를 통한 리소스 로드

인스턴스화: 인스턴스 생성 또는 풀에서 재사용

활성화: 그룹에서 활성 상태 전환

포커스 관리: 포커스, 가림, 일시정지 처리

닫기: CloseUIForm 호출

재활용: 인스턴스 오브젝트 풀 반환

UI 깊이(Depth) 관리

•

그룹 깊이 값에 따라 그룹 전체의 렌더링 순서 결정

•

그룹 내에서는 오픈 순서대로 UI Form 스택 구성

•

Refocus로 특정 Form을 맨 위로 가져올 수 있음

•

가려진 Form을 일시정지하여 성능 최적화

사운드 관리 시스템 (Sound Management System)

사운드 관리 시스템은 게임 내 오디오 로드, 재생, 제어를 담당합니다.

사운드 아키텍처 (Sound Architecture)

사운드 그룹(Sound Group)

•

그룹 단위로 볼륨, 음소거, 우선순위 제어

•

동시 재생을 위한 다수의 사운드 에이전트 보유

•

사운드 교체 정책 설정

•

음악, 효과음, 환경음 등 카테고리별 관리

사운드 라이프사이클 (Sound Lifecycle)

재생: PlaySound 호출 (애셋 이름, 그룹 이름)

로딩: ResourceManager를 통한 로드

에이전트 할당: 지정 그룹의 사운드 에이전트가 재생

제어: 일시정지, 재개, 정지 가능

해제: 사용이 끝난 사운드 리소스 해제

다른 시스템과의 통합 (Integration with Other Systems)

•

리소스 관리와의 통합

◦

EntityManager → 엔티티 프리팹 로드

◦

UIManager → UI Form 프리팹 로드

◦

SoundManager → 오디오 애셋 로드

◦

비동기 로딩, 의존성 관리, 리소스 업데이트 지원

•

오브젝트 풀과의 통합

◦

EntityManager, UIManager → 인스턴스 풀링 재사용

◦

성능 향상, GC 부담 감소

•

이벤트 시스템과의 통합

•

로딩 성공/실패 이벤트

•

라이프사이클 상태 변경 이벤트

•

비동기 진행률 이벤트

•

느슨한 결합(Loose Coupling) 구현

요약 (Summary)

엔티티 프레임워크는 엔티티, UI, 사운드를 세부적으로 관리하는 강력한 시스템이며,

다음과 같은 특징을 가집니다.

•

모든 시스템에 걸친 일관된 아키텍처

•

그룹 기반의 논리적 분리

•

효율적 메모리 사용을 위한 오브젝트 풀

•

이벤트 기반의 느슨한 결합 구조

•

엔티티의 부모-자식 관계 지원

•

UI 깊이 및 포커스 관리

•

사운드 볼륨 및 우선순위 제어