03. 캐릭터 선택 — 첫 엔티티와 첫 이벤트

// Assets/GameMain/Utility/EntitySerialId.cs namespace ToyBoxNightmare { /// <summary> /// 엔티티 고유 ID 전역 생성기. /// 모든 엔티티(플레이어, 적, 투사체 등)가 이걸 통해 ID를 받는다. /// /// 리셋 API 가 없다. 프로시저를 재진입해 새 판을 시작해도 번호는 이어서 나간다. /// </summary> public static class EntitySerialId { /// <summary>마지막으로 발급한 ID. 아직 아무것도 발급하지 않았으면 0 이고, 첫 발급은 1 이다.</summary> private static int mLastIssuedId = 0; /// <summary>다음 ID 를 발급한다.</summary> public static int Next() { // int 범위를 넘기면 음수로 돌아 이미 살아 있는 엔티티와 ID 가 충돌한다. // 도달하려면 21억 번 스폰해야 하므로 에디터/개발 빌드에서만 확인한다. GameAssert.IsTrue( mLastIssuedId < int.MaxValue, "EntitySerialId 가 int 범위를 넘었다. 발급 ID 가 음수로 돌아 엔티티 ID 가 충돌한다."); return ++mLastIssuedId; } } }

// Assets/GameMain/Utility/GameAssert.cs using System.Diagnostics; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 사전조건(precondition) 명시용. "여기까지 왔다면 반드시 참이어야 한다" 를 코드로 적는다. /// 에디터와 개발 빌드에서만 살아 있다. /// </summary> public static class GameAssert { /// <summary>condition 이 거짓이면 오류를 남긴다. 조건에는 <b>충족해야 할 것</b>을 쓴다.</summary> [Conditional("UNITY_EDITOR")] [Conditional("DEVELOPMENT_BUILD")] public static void IsTrue(bool condition, string message) { if (condition) return; Log.Error("[사전조건 위반] {0}", message); } /// <summary>도달하면 안 되는 곳. switch 의 default 절 등에 쓴다.</summary> [Conditional("UNITY_EDITOR")] [Conditional("DEVELOPMENT_BUILD")] public static void Unreachable(string message) { Log.Error("[도달 불가 분기] {0}", message); } /// <summary>index 가 [0, count) 안인지 확인한다.</summary> [Conditional("UNITY_EDITOR")] [Conditional("DEVELOPMENT_BUILD")] public static void InRange(int index, int count, string name) { if (0 <= index && index < count) return; Log.Error("[범위 초과] {0} = {1}, 유효 범위는 [0, {2})", name, index, count); } } }

// Assets/GameMain/Entity/EntityData/EntityData.cs using GameFramework; using UnityEngine; namespace ToyBoxNightmare { /// <summary> /// 엔티티 스폰 파라미터의 공통 베이스. /// 스폰 요청 시점의 값을 로드 완료 시점까지 실어 나르는 그릇이다. /// ReferencePool 로 재사용한다. /// </summary> public abstract class EntityData : IReference { private int mId = 0; private int mTypeId = 0; private Vector3 mPosition = Vector3.zero; private Quaternion mRotation = Quaternion.identity; /// <summary> /// ReferencePool.Acquire&lt;T&gt;() 가 new() 제약을 걸기 때문에 /// 파라미터 없는 생성자가 반드시 있어야 한다. /// </summary> protected EntityData() { } /// <summary> /// 파생 Create 팩토리가 취득 직후 부르는 공통 초기화. /// </summary> protected void Fill(int entityId, int typeId) { // EntitySerialId 는 1 부터 발급한다. 0 이나 음수가 들어왔다면 발급을 거치지 않고 // 호출부가 숫자를 직접 만든 것이다 — 계약 위반이라 assert 로 잡는다. GameAssert.IsTrue(entityId > 0, "EntityData 의 entityId 가 0 이하다. EntitySerialId.Next() 로 발급받은 값을 넘겨야 한다."); mId = entityId; mTypeId = typeId; } /// <summary>엔티티 고유 ID (런타임에서 유니크).</summary> public int Id { get { return mId; } } /// <summary>엔티티 타입 ID (DataTable RowId 등).</summary> public int TypeId { get { return mTypeId; } } /// <summary>스폰 위치.</summary> public Vector3 Position { get { return mPosition; } set { mPosition = value; } } /// <summary>스폰 회전.</summary> public Quaternion Rotation { get { return mRotation; } set { mRotation = value; } } /// <summary> /// 풀 반납 시 코어가 부른다. 파생은 base.Clear() 를 먼저 부르고 /// 자기 필드를 이어서 되돌린다. /// </summary> public virtual void Clear() { mId = 0; mTypeId = 0; mPosition = Vector3.zero; mRotation = Quaternion.identity; } } }

// Assets/GameMain/Entity/EntityData/CharacterSelectData.cs using GameFramework; using UnityEngine; namespace ToyBoxNightmare { /// <summary> /// 캐릭터 선택 단계에 세워 두는 모델(<see cref="PlayerSelectLogic"/>)의 데이터. /// </summary> public class CharacterSelectData : EntityData { /// <summary> /// 선택되면 스폰할 플레이어의 Addressables 주소("Girl" / "Boy"). /// </summary> public string CharacterKey { get; private set; } public static CharacterSelectData Create(int entityId, int typeId, string characterKey, Vector3 position) { GameAssert.IsTrue(!string.IsNullOrEmpty(characterKey), "CharacterSelectData 의 characterKey 가 비어 있다."); CharacterSelectData data = ReferencePool.Acquire<CharacterSelectData>(); data.Fill(entityId, typeId); data.CharacterKey = characterKey; data.Position = position; return data; } public override void Clear() { base.Clear(); // 남겨 두면 다음 선택 캐릭터가 이전 판의 키를 물고 나와 두 캐릭터가 겹친다. CharacterKey = null; } } }

// Assets/GameMain/Entity/EntityLogic/EntityLogicBase.cs using GameFramework; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 이 프로젝트의 모든 엔티티 로직이 상속하는 공통 베이스. /// 모든 Hide 는 SafeHide() 를 거치게 하고, EntityData 의 풀 반납도 여기서 한다. /// </summary> public abstract class EntityLogicBase : EntityLogic { private bool mHidden = false; /// <summary> /// 이 엔티티가 스폰될 때 받은 데이터. 풀에 돌려줄 책임이 이 인스턴스에 있다. /// null 이면 소유한 것이 없다는 뜻이고, 그 자체가 이중 반납 가드다. /// </summary> private EntityData mOwnedData = null; /// <summary> /// 이미 Hide 요청이 나갔는지. HideEntity 는 즉시 처리되지 않고 다음 Update 의 /// 회수 큐로 넘어가므로, 그 사이에 들어오는 추가 처리를 막을 때 쓴다. /// </summary> protected bool IsHiding { get { return mHidden; } } protected internal override void OnShow(object userData) { base.OnShow(userData); mHidden = false; // 스폰 데이터의 소유권을 여기서 잡는다. mOwnedData = userData as EntityData; } protected internal override void OnHide(bool isShutdown, object userData) { mHidden = true; base.OnHide(isShutdown, userData); ReleaseOwnedData(); } /// <summary> /// 스폰 데이터를 풀에 돌려준다. 이중 Release 는 코어에서 즉시 예외이므로 /// 참조를 먼저 비우고 나서 반납한다. /// </summary> private void ReleaseOwnedData() { if (mOwnedData == null) return; EntityData data = mOwnedData; mOwnedData = null; ReferencePool.Release(data); } /// <summary> /// HideEntity 를 정확히 1회만 호출한다. 중복 호출은 조용히 무시된다. /// 엔티티 제거는 반드시 이 메서드를 통할 것 — Destroy/SetActive 는 풀을 깨뜨린다. /// </summary> public void SafeHide() { if (mHidden) return; // Entity 가 null 이라는 것은 이 인스턴스가 EntityManager 를 거치지 않고 // 프리팹에 미리 붙어 있던 로직이라는 뜻이다(규약 위반). GameAssert.IsTrue(Entity != null, "SafeHide 대상의 Entity 가 null 이다. 프리팹에 EntityLogic 이 baked 되어 있는지 확인할 것."); if (Entity == null) return; // 게임 종료나 씬 언로드 중에는 EntityComponent 가 먼저 파괴돼 있을 수 있다. EntityComponent entityComponent = GameEntry.GetComponent<EntityComponent>(); if (entityComponent == null) return; mHidden = true; entityComponent.HideEntity(Entity); } } }

// Assets/GameMain/Entity/EntityLogic/PlayerSelectLogic.cs using UnityEngine; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 캐릭터 선택 단계에서 씬에 배치되는 엔티티 로직. /// Addressables 키: "Girl", "Boy" (SurvivalGame 이 넘기는 문자열과 동일) /// </summary> public class PlayerSelectLogic : EntityLogicBase { [SerializeField] private string characterKey = "Girl"; [SerializeField] private CapsuleCollider capsuleCollider = null; [SerializeField] private Animator animator = null; public string CharacterKey => characterKey; protected internal override void OnInit(object userData) { base.OnInit(userData); capsuleCollider = GetComponent<CapsuleCollider>(); // includeInactive: true 가 필수다. 아래 설명 참조. animator = GetComponentInChildren<Animator>(true); WarnOnMissingComponents(); } /// <summary> /// 캐시가 비면 예외 대신 <b>선택이 조용히 죽는다</b> — 콜라이더가 없으면 이 캐릭터를 /// 영영 고를 수 없고, 두 캐릭터가 모두 그러면 게임이 진행되지 않는다. /// </summary> private void WarnOnMissingComponents() { if (capsuleCollider == null) { Log.Error("PlayerSelectLogic '{0}': CapsuleCollider 가 없어 클릭 선택이 불가능하다.", Name); } if (animator == null) { Log.Warning("PlayerSelectLogic '{0}': Animator 를 찾지 못했다. 낙선 연출이 재생되지 않는다.", Name); } } protected internal override void OnShow(object userData) { base.OnShow(userData); var selectData = userData as CharacterSelectData; if (selectData == null) { // 스폰 측 계약 위반. 프리팹 기본 키/위치로 남아 두 캐릭터가 겹칠 수 있다. Log.Error("Character select data is invalid."); return; } characterKey = selectData.CharacterKey; CachedTransform.position = selectData.Position; CachedTransform.rotation = selectData.Rotation; } } }

// Assets/GameMain/Game/SurvivalGame.cs using UnityEngine; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { public class SurvivalGame : GameBase { // ─── 설정 ─── // 캐릭터 키와 Addressables 주소는 같은 문자열이다("Girl" 주소로 로드한 엔티티의 키가 "Girl"). private const string GirlCharacterKey = "Girl"; private const string BoyCharacterKey = "Boy"; /// <summary>플레이어·선택 캐릭터가 들어가는 엔티티 그룹. GameFramework.prefab 의 mEntityGroups 와 일치해야 한다.</summary> private const string PlayerEntityGroup = "Player"; /// <summary> /// EntityData 의 TypeId. 아직 타입 테이블이 없어 프로젝트 전체가 1 로 고정이다. /// </summary> public const int DefaultEntityTypeId = 1; /// <summary>선택 화면에서 두 캐릭터가 서는 자리.</summary> private static readonly Vector3 GirlSelectPosition = new Vector3(-2f, 0f, 0f); private static readonly Vector3 BoySelectPosition = new Vector3( 2f, 0f, 0f); // (이하 2장에서 만든 내용)

// ─── 스폰 ─── private void SpawnSelectCharacters() { SpawnSelectCharacter(GirlCharacterKey, GirlSelectPosition); SpawnSelectCharacter(BoyCharacterKey, BoySelectPosition); } /// <summary> /// 캐릭터 선택용 엔티티를 스폰한다. /// 캐릭터 키가 곧 Addressables 주소라 인자 하나로 둘 다 쓴다. /// </summary> private void SpawnSelectCharacter(string characterKey, Vector3 position) { EntityComponent entityComponent = GameEntry.GetComponent<EntityComponent>(); if (entityComponent == null) { Log.Error("EntityComponent 를 찾을 수 없어 선택 캐릭터 '{0}' 를 스폰하지 못했다.", characterKey); return; } int id = EntitySerialId.Next(); entityComponent.ShowEntity( id, typeof(PlayerSelectLogic), characterKey, PlayerEntityGroup, CharacterSelectData.Create(id, DefaultEntityTypeId, characterKey, position)); }

public override void Initialize() { base.Initialize(); ResetRoundState(); SpawnSelectCharacters(); }

GameFramework └ Entity └ Entity Instances └ Entity Group - Player ├ Girl(Clone) └ Boy(Clone)

survivalGame.StartWith("Girl"); // ❌ 이렇게 하지 않는다 (게임 객체를 어디선가 얻어 와서 직접 부른다)

// Assets/GameMain/Game/CharacterSelectedEventArgs.cs using GameFramework; using GameFramework.Event; namespace ToyBoxNightmare { /// <summary> /// 선택 화면에서 캐릭터를 클릭했을 때 <see cref="PlayerSelectLogic"/> 이 발행한다. /// </summary> public class CharacterSelectedEventArgs : GameEventArgs { public static readonly int EventId = typeof(CharacterSelectedEventArgs).GetHashCode(); public override int Id => EventId; /// <summary>선택된 캐릭터의 키. Addressables 주소와 같은 문자열이다("Girl" / "Boy").</summary> public string CharacterKey { get; private set; } public static CharacterSelectedEventArgs Create(string characterKey) { var args = ReferencePool.Acquire<CharacterSelectedEventArgs>(); args.CharacterKey = characterKey; return args; } public override void Clear() { CharacterKey = null; } } }

using UnityEngine; using UnityEngine.EventSystems; using UnityEngine.InputSystem; using UnityGameFramework.Runtime;

// 마우스를 이 캐릭터 위에서 눌렀는지. 누른 곳과 뗀 곳이 모두 자신일 때만 선택으로 친다. private bool mPressedOnSelf = false; private const float PickDistance = 1000f;

mPressedOnSelf = false;

protected internal override void OnUpdate(float elapseSeconds, float realElapseSeconds) { base.OnUpdate(elapseSeconds, realElapseSeconds); TickSelectInput(); // 3.9 절에서 상태 기계로 옮긴다 } /// <summary> /// 클릭 판정. Input System 으로 직접 판정한다. /// </summary> internal void TickSelectInput() { Mouse mouse = Mouse.current; if (mouse == null) return; if (mouse.leftButton.wasPressedThisFrame) { mPressedOnSelf = IsPointerOnSelf(mouse); } if (!mouse.leftButton.wasReleasedThisFrame) return; // 누른 곳과 뗀 곳이 모두 자신일 때만 선택으로 친다. bool clickCompletedOnSelf = mPressedOnSelf && IsPointerOnSelf(mouse); mPressedOnSelf = false; if (clickCompletedOnSelf) { FireCharacterSelected(); } } private void FireCharacterSelected() { // Create 는 참조 풀에서 꺼내 오므로, 발행하지 못할 상황이면 만들기 전에 빠진다. EventComponent eventComponent = GameEntry.GetComponent<EventComponent>(); if (eventComponent == null) { Log.Error("EventComponent 가 없어 CharacterSelected 를 발행하지 못했다."); return; } eventComponent.Fire(this, CharacterSelectedEventArgs.Create(characterKey)); } /// <summary>마우스 커서가 이 캐릭터의 콜라이더 위에 있는가.</summary> private bool IsPointerOnSelf(Mouse mouse) { if (capsuleCollider == null || !capsuleCollider.enabled) return false; // UI 위 클릭은 무시한다. if (EventSystem.current != null && EventSystem.current.IsPointerOverGameObject()) return false; Camera cam = Camera.main; if (cam == null) return false; Ray ray = cam.ScreenPointToRay(mouse.position.ReadValue()); // 자기 콜라이더만 검사하지 않고 Physics.Raycast 로 최근접을 본다. // 앞을 가로막은 물체가 있으면 뚫고 선택되지 않는다. if (!Physics.Raycast(ray, out RaycastHit hit, PickDistance)) return false; return hit.collider == capsuleCollider; }

using GameFramework.Event;

// CharacterSelected 는 선택 순간 스스로 해제하므로, Shutdown 시점에 아직 // 구독 중인지 알아야 한다. 미등록 핸들러를 Unsubscribe 하면 코어가 예외를 던진다. private bool mCharacterSelectSubscribed = false;

private void SubscribeEvents() { // 초기화 시점에 EventComponent 가 없으면 게임이 성립하지 않는다 — 시끄럽게 알린다. EventComponent events = RequireEventComponent(); if (events == null) return; events.Subscribe(CharacterSelectedEventArgs.EventId, OnCharacterSelected); mCharacterSelectSubscribed = true; } private void UnsubscribeEvents() { // 캐릭터를 고르지 않고 종료하면 아직 구독 상태다. UnsubscribeCharacterSelected(); } private void UnsubscribeCharacterSelected() { if (!mCharacterSelectSubscribed) return; // Shutdown 경로에서도 불리므로 조용한 쪽을 쓴다. EventComponent events = FindEventComponent(); if (events == null) return; events.Unsubscribe(CharacterSelectedEventArgs.EventId, OnCharacterSelected); mCharacterSelectSubscribed = false; } // ─── 이벤트 핸들러 ─── private void OnCharacterSelected(object sender, GameEventArgs e) { CharacterSelectedEventArgs ne = e as CharacterSelectedEventArgs; if (ne == null) { GameAssert.Unreachable("CharacterSelected 핸들러에 다른 타입의 이벤트 인자가 들어왔다."); return; } // 한 번만 처리한다. UnsubscribeCharacterSelected(); Log.Info("Character selected: {0}", ne.CharacterKey); } /// <summary> /// EventComponent 조회. 없으면 <b>조용히</b> null 을 돌려준다. /// 컴포넌트가 없는 것이 정상일 수 있는 종료 경로에서 쓴다. /// </summary> private static EventComponent FindEventComponent() { return GameEntry.GetComponent<EventComponent>(); } /// <summary> /// EventComponent 조회. 없으면 원인을 로그로 남긴다. /// 반드시 있어야 하는 경로(초기화·이벤트 발행)에서 쓴다. /// </summary> private static EventComponent RequireEventComponent() { EventComponent events = FindEventComponent(); if (events == null) { Log.Error("EventComponent 를 찾을 수 없다. GameFramework.prefab 구성을 확인할 것."); } return events; }

public override void Initialize() { base.Initialize(); ResetRoundState(); SubscribeEvents(); SpawnSelectCharacters(); } public override void Shutdown() { UnsubscribeEvents(); base.Shutdown(); }

Character selected: Girl

// Assets/GameMain/Game/GameBase.cs using GameFramework; using GameFramework.Event; using UnityGameFramework.Runtime;

protected virtual void OnShowEntitySuccess(object sender, GameEventArgs e) { } protected virtual void OnShowEntityFailure(object sender, GameEventArgs e) { // 이벤트 ID 로 등록했으니 캐스팅은 항상 성공해야 한다. 실패하면 구독 등록이 잘못된 것이다. ShowEntityFailureEventArgs ne = e as ShowEntityFailureEventArgs; if (ne == null) { GameAssert.Unreachable("ShowEntityFailure 핸들러에 다른 타입의 이벤트 인자가 들어왔다."); return; } ReleaseSpawnData(ne); Log.Warning("Show entity failure with error message '{0}'.", ne.ErrorMessage); } /// <summary> /// 스폰이 실패했을 때 <see cref="EntityData"/> 를 풀에 돌려준다. /// /// 실패하면 OnShow 가 아예 불리지 않아 <see cref="EntityLogicBase"/> 가 소유권을 /// 잡지 못한다. 여기서 놓치면 그 데이터는 영영 풀로 돌아가지 않는다. /// /// <b>한 실패 이벤트당 정확히 1회만 불러야 한다.</b> /// </summary> protected static void ReleaseSpawnData(ShowEntityFailureEventArgs ne) { EntityData data = ne.UserData as EntityData; if (data == null) return; // 이미 소유자가 생긴 데이터는 건드리지 않는다. // 코어는 엔티티를 등록한 뒤에 OnShow 를 부르고, 그 이후 구간에서 난 예외도 // 같은 userData 로 실패 이벤트를 낸다. 그 경우 EntityLogicBase 가 이미 소유권을 // 잡았으므로 회수 시 거기서 반납된다 — 여기서 또 반납하면 이중 Release 다. EntityComponent entityComponent = GameEntry.GetComponent<EntityComponent>(); if (entityComponent != null && entityComponent.HasEntity(ne.EntityId)) return; ReferencePool.Release(data); }

private PlayerSelectLogic mGirlSelect = null; private PlayerSelectLogic mBoySelect = null;

private void ResetRoundState() { Score = 0; mGameTime = 0f; mGirlSelect = null; mBoySelect = null; }

private void SubscribeEvents() { // 초기화 시점에 EventComponent 가 없으면 게임이 성립하지 않는다 — 시끄럽게 알린다. EventComponent events = RequireEventComponent(); if (events == null) return; events.Subscribe(ShowEntitySuccessEventArgs.EventId, OnShowEntitySuccess); events.Subscribe(ShowEntityFailureEventArgs.EventId, OnShowEntityFailure); events.Subscribe(CharacterSelectedEventArgs.EventId, OnCharacterSelected); mCharacterSelectSubscribed = true; } private void UnsubscribeEvents() { // 앱 종료 경로에서는 EventComponent 가 먼저 파괴됐을 수 있다. // 그때는 구독도 함께 사라진 뒤라 조용히 빠져나가는 게 맞다. EventComponent events = FindEventComponent(); if (events == null) return; events.Unsubscribe(ShowEntitySuccessEventArgs.EventId, OnShowEntitySuccess); events.Unsubscribe(ShowEntityFailureEventArgs.EventId, OnShowEntityFailure); // 캐릭터를 고르지 않고 종료하면 아직 구독 상태다. UnsubscribeCharacterSelected(); }

protected override void OnShowEntitySuccess(object sender, GameEventArgs e) { ShowEntitySuccessEventArgs ne = e as ShowEntitySuccessEventArgs; if (ne == null) { GameAssert.Unreachable("ShowEntitySuccess 핸들러에 다른 타입의 이벤트 인자가 들어왔다."); return; } if (ne.EntityLogicType == typeof(PlayerSelectLogic)) { CacheSelectCharacter(ne.Entity); return; } } /// <summary>선택 캐릭터 참조를 잡아 둔다. 나중에 DismissSelectCharacters 가 쓴다.</summary> private void CacheSelectCharacter(Entity entity) { PlayerSelectLogic logic = entity.Logic as PlayerSelectLogic; if (logic == null) { Log.Error("PlayerSelectLogic 으로 스폰했는데 로직이 그 타입이 아니다: {0}", entity.EntityAssetName); return; } if (logic.CharacterKey == GirlCharacterKey) { mGirlSelect = logic; } else { mBoySelect = logic; } }

private void OnCharacterSelected(object sender, GameEventArgs e) { CharacterSelectedEventArgs ne = e as CharacterSelectedEventArgs; if (ne == null) { GameAssert.Unreachable("CharacterSelected 핸들러에 다른 타입의 이벤트 인자가 들어왔다."); return; } // 한 번만 처리한다. UnsubscribeCharacterSelected(); Log.Info("Character selected: {0}", ne.CharacterKey); DismissSelectCharacters(ne.CharacterKey); } /// <summary> /// 선택된 쪽은 즉시 회수, 선택받지 못한 쪽은 사망 연출 후 회수. /// HideEntity 를 직접 부르지 않고 SafeHide 를 쓴다 — 중복 Hide 는 코어에서 예외다. /// </summary> private void DismissSelectCharacters(string selectedCharacterKey) { bool girlSelected = selectedCharacterKey == GirlCharacterKey; PlayerSelectLogic selected = girlSelected ? mGirlSelect : mBoySelect; PlayerSelectLogic unselected = girlSelected ? mBoySelect : mGirlSelect; // 선택된 쪽을 먼저 치우는 순서를 유지한다. if (selected != null) { selected.SafeHide(); } if (unselected != null) { unselected.SafeHide(); // 3.9 절에서 DisableAndHide() 로 바꾼다 } // 회수한 뒤에는 참조를 반드시 비운다. // 엔티티는 풀에서 재사용되므로, 남겨 두면 나중에 같은 인스턴스가 다른 용도로 // 살아났을 때 그걸 선택 캐릭터로 착각해 건드리게 된다. mGirlSelect = null; mBoySelect = null; }

StartCoroutine(HideAfterDelay(1.5f)); // ❌ 엔티티에서는 쓰지 않는다

/// <summary> /// FSM 이름. 코어는 (소유자 타입, 이름) 으로 식별하므로 인스턴스마다 달라야 한다. /// </summary> private string FsmName { // Entity 가 null 이면 프레임워크를 거치지 않고 프리팹에 붙여 둔 로직이다(규약 위반). // 그래도 이름이 겹치면 안 되므로 Unity 오브젝트의 고유 id 로 대신한다. get { return Entity != null ? Entity.Id.ToString() : GetEntityId().ToString(); } }

// Assets/GameMain/Entity/EntityLogic/States/PlayerSelectStateBase.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 캐릭터 선택 엔티티 상태의 공통 베이스. /// /// <b>상태는 무상태(stateless)다.</b> 값은 전부 <c>fsm.Owner</c> 에서 읽는다 — /// 그래야 상태 인스턴스를 엔티티 풀 재사용 사이에 그대로 돌려쓸 수 있다. /// </summary> public abstract class PlayerSelectStateBase : FsmState<PlayerSelectLogic> { /// <summary> /// 회수 요청이 나간 뒤에는 어떤 상태도 돌지 않는다는 것을 한곳에서 보장한다. /// 파생은 <see cref="OnStateUpdate"/> 만 채우고 이 가드를 다시 쓰지 않는다. /// </summary> protected sealed override void OnUpdate(IFsm<PlayerSelectLogic> fsm, float elapseSeconds, float realElapseSeconds) { base.OnUpdate(fsm, elapseSeconds, realElapseSeconds); PlayerSelectLogic owner = fsm.Owner; if (!owner.CanRunStates) return; OnStateUpdate(fsm, owner, elapseSeconds); } protected abstract void OnStateUpdate(IFsm<PlayerSelectLogic> fsm, PlayerSelectLogic owner, float elapseSeconds); } }

// Assets/GameMain/Entity/EntityLogic/States/PlayerSelectSelectableState.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 고를 수 있는 상태. 마우스 클릭을 기다린다. /// </summary> public sealed class PlayerSelectSelectableState : PlayerSelectStateBase { protected override void OnEnter(IFsm<PlayerSelectLogic> fsm) { base.OnEnter(fsm); // 풀에서 재사용되므로 이전 판의 누름 상태가 남아 있으면 안 된다. fsm.Owner.ClearPressState(); } protected override void OnStateUpdate(IFsm<PlayerSelectLogic> fsm, PlayerSelectLogic owner, float elapseSeconds) { // 낙선 통보가 왔으면 이번 프레임 입력은 받지 않는다. // 상태를 밖에서 바꿀 수 없으므로(IFsm 에 ChangeState 가 없다) 소유자가 깃발만 세우고 // 여기서 폴링해 넘어간다. if (owner.IsRejected) { ChangeState<PlayerSelectDyingState>(fsm); return; } owner.TickSelectInput(); } } }

// Assets/GameMain/Entity/EntityLogic/States/PlayerSelectDyingState.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 낙선 연출 상태. 쓰러지는 모습을 보여 준 뒤 스스로 회수된다. /// </summary> public sealed class PlayerSelectDyingState : PlayerSelectStateBase { protected override void OnEnter(IFsm<PlayerSelectLogic> fsm) { base.OnEnter(fsm); // 연출 시작은 상태 진입의 일부다. 소유자가 미리 해 두면 // "연출은 시작됐는데 상태는 아직 안 바뀐" 프레임이 생긴다. fsm.Owner.StartRejectedPresentation(); } protected override void OnStateUpdate(IFsm<PlayerSelectLogic> fsm, PlayerSelectLogic owner, float elapseSeconds) { owner.TickHideDelay(elapseSeconds); } } }

// Assets/GameMain/Entity/EntityLogic/PlayerSelectLogic.cs using GameFramework.Fsm; using UnityEngine; using UnityEngine.EventSystems; using UnityEngine.InputSystem; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 캐릭터 선택 단계에서 씬에 배치되는 엔티티 로직. /// 클릭 시 CharacterSelectedEventArgs 를 발생시키고, /// 선택받지 못한 캐릭터는 사망 연출 후 HideEntity 된다. /// /// Addressables 키: "Girl", "Boy" (SurvivalGame 이 넘기는 문자열과 동일) /// </summary> public class PlayerSelectLogic : EntityLogicBase { [SerializeField] private string characterKey = "Girl"; [SerializeField] private CapsuleCollider capsuleCollider = null; [SerializeField] private Animator animator = null; [SerializeField] private Rigidbody rigidBody = null; // 프리팹 원본 감쇠값. DisableAndHide 이후 재사용될 때 되돌리기 위해 보관한다. private float mInitialLinearDamping = 0f; // 마우스를 이 캐릭터 위에서 눌렀는지. 누른 곳과 뗀 곳이 모두 자신일 때만 선택으로 친다. private bool mPressedOnSelf = false; /// <summary> /// 낙선 통보가 왔는가. 상태를 밖에서 바꿀 수 없으므로 /// <see cref="DisableAndHide"/> 는 이 깃발만 세우고, 상태가 폴링해서 넘어간다. /// </summary> private bool mRejected = false; /// <summary>낙선 연출 경과 시간.</summary> private float mRejectedElapsed = 0f; // ─── 상태 기계 ─── private IFsm<PlayerSelectLogic> mFsm = null; private FsmState<PlayerSelectLogic>[] mStates = null; private const float PickDistance = 1000f; /// <summary>사망 연출을 보여 주고 회수하기까지의 시간. 원본 낙선 연출 길이와 같다.</summary> private const float HideDelayAfterDeath = 1.5f; /// <summary>애니메이터 트리거 이름. 이름이 틀려도 Unity 는 조용히 무시한다.</summary> private const string DieTriggerParam = "Die"; public string CharacterKey => characterKey; protected internal override void OnInit(object userData) { base.OnInit(userData); capsuleCollider = GetComponent<CapsuleCollider>(); animator = GetComponentInChildren<Animator>(true); rigidBody = GetComponent<Rigidbody>(); if (rigidBody != null) { mInitialLinearDamping = rigidBody.linearDamping; } // 상태 인스턴스는 인스턴스당 1회만 만든다. 값을 전부 fsm.Owner 에서 읽으므로 // 풀 재사용 사이에 그대로 돌려쓸 수 있다. mStates = new FsmState<PlayerSelectLogic>[] { new PlayerSelectSelectableState(), new PlayerSelectDyingState(), }; WarnOnMissingComponents(); } private void WarnOnMissingComponents() { if (capsuleCollider == null) { Log.Error("PlayerSelectLogic '{0}': CapsuleCollider 가 없어 클릭 선택이 불가능하다.", Name); } if (animator == null) { Log.Warning("PlayerSelectLogic '{0}': Animator 를 찾지 못했다. 낙선 연출이 재생되지 않는다.", Name); } } protected internal override void OnShow(object userData) { base.OnShow(userData); // 풀에서 재사용되므로 DisableAndHide 가 남긴 상태를 반드시 되돌린다. // 이걸 빼면 재시작 시 낙선했던 캐릭터가 콜라이더가 꺼진 죽은 포즈로 등장한다. ResetVisualState(); mPressedOnSelf = false; mRejected = false; mRejectedElapsed = 0f; var selectData = userData as CharacterSelectData; if (selectData == null) { // 스폰 측 계약 위반. 프리팹 기본 키/위치로 남아 두 캐릭터가 겹칠 수 있다. Log.Error("Character select data is invalid."); // 배치는 못 했어도 클릭은 받아야 한다. 상태 기계 없이 두면 // 이 캐릭터를 영영 고를 수 없다. CreateStateMachine(); return; } characterKey = selectData.CharacterKey; CachedTransform.position = selectData.Position; CachedTransform.rotation = selectData.Rotation; // 상태 기계는 **맨 마지막**에 세운다. 상태가 소유자 값을 바로 읽기 때문이다. CreateStateMachine(); } protected internal override void OnHide(bool isShutdown, object userData) { // 가장 먼저 부순다. 회수된 엔티티의 상태가 계속 도는 것을 막는다. DestroyStateMachine(); base.OnHide(isShutdown, userData); } /// <summary> /// FSM 이름. 코어는 (소유자 타입, 이름) 으로 식별하므로 인스턴스마다 달라야 한다. /// </summary> private string FsmName { get { return Entity != null ? Entity.Id.ToString() : GetEntityId().ToString(); } } private void CreateStateMachine() { FsmComponent fsmComponent = GameEntry.GetComponent<FsmComponent>(); if (fsmComponent == null) { Log.Error("PlayerSelectLogic: FsmComponent 가 없다. 캐릭터를 고를 수 없다."); return; } mFsm = fsmComponent.CreateFsm(FsmName, this, mStates); mFsm.Start<PlayerSelectSelectableState>(); } /// <summary>멱등하다. 이미 부쉈거나 프레임워크가 먼저 내려갔으면 조용히 넘어간다.</summary> private void DestroyStateMachine() { if (mFsm == null) return; FsmComponent fsmComponent = GameEntry.GetComponent<FsmComponent>(); if (fsmComponent != null) { fsmComponent.DestroyFsm(mFsm); } mFsm = null; } private void ResetVisualState() { if (capsuleCollider != null) { capsuleCollider.enabled = true; } if (animator != null) { animator.Rebind(); animator.Update(0f); } if (rigidBody != null) { rigidBody.linearDamping = mInitialLinearDamping; } } /// <summary> /// 프레임 갱신은 전부 FSM 상태가 한다(FsmManager 가 이것보다 먼저 돈다). /// 여기에 로직을 다시 넣으면 상태 밖에 숨은 분기가 생기므로 그러지 말 것. /// </summary> protected internal override void OnUpdate(float elapseSeconds, float realElapseSeconds) { base.OnUpdate(elapseSeconds, realElapseSeconds); } // ─── 상태가 쓰는 창구 ─── /// <summary>상태를 굴려도 되는가. 회수 요청이 나갔으면 아니다.</summary> internal bool CanRunStates { get { return !IsHiding; } } /// <summary>낙선 통보가 왔는가. <see cref="PlayerSelectSelectableState"/> 가 폴링한다.</summary> internal bool IsRejected { get { return mRejected; } } /// <summary>누름 상태 초기화. 선택 대기 상태로 들어갈 때마다 부른다.</summary> internal void ClearPressState() { mPressedOnSelf = false; } internal void TickSelectInput() { Mouse mouse = Mouse.current; if (mouse == null) return; if (mouse.leftButton.wasPressedThisFrame) { mPressedOnSelf = IsPointerOnSelf(mouse); } if (!mouse.leftButton.wasReleasedThisFrame) return; // 누른 곳과 뗀 곳이 모두 자신일 때만 선택으로 친다. bool clickCompletedOnSelf = mPressedOnSelf && IsPointerOnSelf(mouse); mPressedOnSelf = false; if (clickCompletedOnSelf) { FireCharacterSelected(); } } /// <summary> /// 낙선 연출을 시작한다. <see cref="PlayerSelectDyingState"/> 진입 시 1회. /// </summary> internal void StartRejectedPresentation() { mRejectedElapsed = 0f; if (capsuleCollider != null) { capsuleCollider.enabled = false; } if (animator != null) { animator.SetTrigger(DieTriggerParam); } } /// <summary>연출 시간이 다 차면 회수한다.</summary> internal void TickHideDelay(float elapseSeconds) { mRejectedElapsed += elapseSeconds; if (mRejectedElapsed < HideDelayAfterDeath) return; SafeHide(); } private void FireCharacterSelected() { // Create 는 참조 풀에서 꺼내 오므로, 발행하지 못할 상황이면 만들기 전에 빠진다. EventComponent eventComponent = GameEntry.GetComponent<EventComponent>(); if (eventComponent == null) { Log.Error("EventComponent 가 없어 CharacterSelected 를 발행하지 못했다."); return; } eventComponent.Fire(this, CharacterSelectedEventArgs.Create(characterKey)); } /// <summary>마우스 커서가 이 캐릭터의 콜라이더 위에 있는가.</summary> private bool IsPointerOnSelf(Mouse mouse) { if (capsuleCollider == null || !capsuleCollider.enabled) return false; // UI 위 클릭은 무시한다. if (EventSystem.current != null && EventSystem.current.IsPointerOverGameObject()) return false; Camera cam = Camera.main; if (cam == null) return false; Ray ray = cam.ScreenPointToRay(mouse.position.ReadValue()); // 자기 콜라이더만 검사하지 않고 Physics.Raycast 로 최근접을 본다. // 앞을 가로막은 물체가 있으면 뚫고 선택되지 않는다. if (!Physics.Raycast(ray, out RaycastHit hit, PickDistance)) return false; return hit.collider == capsuleCollider; } /// <summary> /// 선택받지 못한 캐릭터에게 SurvivalGame 이 호출한다. /// 깃발만 세운다 — 실제 연출과 회수는 <see cref="PlayerSelectDyingState"/> 가 한다. /// </summary> public void DisableAndHide() { // 이미 회수 요청이 나갔으면 연출을 시작하지 않는다. if (IsHiding) return; mRejected = true; } // Death 애니메이션 이벤트에서 호출 (선택적) private void DeathComplete() { if (rigidBody != null) rigidBody.linearDamping = 0f; } } }

if (unselected != null) { unselected.DisableAndHide(); }

Character selected: Girl