04. 플레이어 — FSM 으로 상태 나누기

// 3장 — 선택 화면에 세울 때 ShowEntity(id, typeof(PlayerSelectLogic), "Girl", "Player", CharacterSelectData.Create(…)); // 이 장 — 플레이어로 띄울 때 ShowEntity(id, typeof(Player), "Girl", "Player", PlayerData.Create(…));

// Assets/GameMain/Entity/EntityData/TargetableObjectData.cs namespace ToyBoxNightmare { /// <summary> /// 체력을 가지는 엔티티의 데이터 베이스. /// 피격/사망 판정은 전부 여기 담긴 <see cref="HitPoints"/> 로 이뤄진다. /// </summary> public abstract class TargetableObjectData : EntityData { /// <summary> /// 취득 직후에는 0 이다. <b>파생 클래스의 <c>Create</c> 가 자신의 MaxHitPoints 로 /// 반드시 채워야 한다</b> — 빠뜨리면 스폰 직후 IsDead 가 true 가 된다. /// </summary> private int mHitPoints = 0; /// <summary> /// 현재 체력. 0 이하면 죽은 것으로 본다. /// 과다 피해를 입으면 음수가 될 수 있다. /// </summary> public int HitPoints { get { return mHitPoints; } set { mHitPoints = value; } } /// <summary>파생 클래스가 자신의 스탯에서 돌려주는 최대 체력.</summary> public abstract int MaxHitPoints { get; } /// <summary> /// 체력 비율(0~1). MaxHitPoints 가 0 인 데이터가 들어올 수 있어 0 나눗셈을 막는다. /// </summary> public float HitPointRatio { get { return MaxHitPoints > 0 ? (float)HitPoints / MaxHitPoints : 0.0f; } } public override void Clear() { base.Clear(); mHitPoints = 0; } } }

// Assets/GameMain/Entity/EntityData/PlayerData.cs using GameFramework; using UnityEngine; namespace ToyBoxNightmare { /// <summary> /// 플레이어 엔티티 데이터. SurvivalGame 이 스폰할 때 만들어 <see cref="Player"/> 의 OnShow 로 넘긴다. /// </summary> public class PlayerData : TargetableObjectData { /// <summary> /// 이동 속도 하한. 0 이하가 되면 플레이어가 아예 움직이지 못하므로 세터에서 잘라낸다. /// </summary> private const float MinMoveSpeed = 1f; // 풀에서 나온 객체는 필드 초기화식이 다시 돌지 않는다. Clear 가 이 상수로 되돌린다. private const int DefaultMaxHP = 100; private const float DefaultMoveSpeed = 5f; private int mMaxHP = DefaultMaxHP; private float mMoveSpeed = DefaultMoveSpeed; public static PlayerData Create(int entityId, int typeId) { PlayerData data = ReferencePool.Acquire<PlayerData>(); data.Fill(entityId, typeId); // TargetableObjectData 는 HitPoints 를 0 으로 두므로 여기서 반드시 채운다. // 빠뜨리면 스폰 직후 IsDead 가 true 다. data.HitPoints = data.mMaxHP; return data; } public override int MaxHitPoints => mMaxHP; /// <summary>초당 이동 거리. 세터는 <see cref="MinMoveSpeed"/> 아래로 내려가지 않게 막는다.</summary> public float MoveSpeed { get => mMoveSpeed; set => mMoveSpeed = Mathf.Max(MinMoveSpeed, value); } public override void Clear() { base.Clear(); mMaxHP = DefaultMaxHP; mMoveSpeed = DefaultMoveSpeed; } } }

// Assets/GameMain/Entity/EntityLogic/TargetableObject.cs using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 체력을 가지고 피격/사망 처리를 하는 엔티티의 공통 베이스. /// </summary> public abstract class TargetableObject : EntityLogicBase { private TargetableObjectData mTargetableObjectData = null; public bool IsDead { get { return mTargetableObjectData != null && mTargetableObjectData.HitPoints <= 0; } } /// <summary> /// 현재 체력 비율(0~1). 데이터가 없으면 0. /// </summary> protected float HitPointRatio { get { return mTargetableObjectData != null ? mTargetableObjectData.HitPointRatio : 0f; } } public void ApplyDamage(Entity attacker, int damageHitPoints) { // 아직 OnShow 를 거치지 않았거나 잘못된 userData 로 뜬 인스턴스. if (mTargetableObjectData == null) return; // 이미 죽은 대상에 대한 추가 피격은 무시한다. // 사망 연출이 끝나고 Hide 될 때까지 엔티티가 살아 있으므로, // 가드가 없으면 그 사이의 피격이 OnDead 를 여러 번 호출해 Hide 가 중복된다. if (IsDead) return; // 회복 경로는 없다. 음수가 들어오면 체력이 도로 늘어 사망 판정이 영영 안 난다. GameAssert.IsTrue(damageHitPoints >= 0, "ApplyDamage 에 음수 데미지가 들어왔다. 회복은 이 경로로 처리하지 않는다."); float ratioBeforeDamage = mTargetableObjectData.HitPointRatio; mTargetableObjectData.HitPoints -= damageHitPoints; float ratioAfterDamage = mTargetableObjectData.HitPointRatio; // 사망 여부와 무관하게 매 피격 호출한다. OnDamaged(attacker, damageHitPoints); if (ratioBeforeDamage > ratioAfterDamage) { OnHitPointChanged(ratioBeforeDamage, ratioAfterDamage); } if (mTargetableObjectData.HitPoints <= 0) { OnDead(attacker); } } /// <summary>피격될 때마다 호출된다. 타격 이펙트/사운드를 여기서 낸다.</summary> protected virtual void OnDamaged(Entity attacker, int damageHitPoints) { } /// <summary>체력 비율이 실제로 줄었을 때 호출된다. HUD 갱신 이벤트를 여기서 발행한다.</summary> protected virtual void OnHitPointChanged(float fromRatio, float toRatio) { } protected internal override void OnShow(object userData) { base.OnShow(userData); mTargetableObjectData = userData as TargetableObjectData; if (mTargetableObjectData == null) { Log.Error("Targetable object data is invalid."); return; } } /// <summary> /// <b><see cref="mTargetableObjectData"/> 를 반드시 여기서 놓아야 한다.</b> /// 데이터는 EntityLogicBase.OnHide 가 맨 끝에서 ReferencePool 로 반납한다. /// 반납은 참조를 null 로 만들어 주지 않으므로, 여기서 안 지우면 이 필드는 /// 풀에 들어간 객체를 계속 가리킨다. /// base 보다 <b>먼저</b> 지운다 — 반납이 base 체인 끝에서 일어나기 때문이다. /// </summary> protected internal override void OnHide(bool isShutdown, object userData) { mTargetableObjectData = null; base.OnHide(isShutdown, userData); } protected virtual void OnDead(Entity attacker) { SafeHide(); } } }

// Assets/GameMain/Entity/EntityLogic/Player.cs using UnityEngine; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 플레이어 엔티티 로직. /// </summary> [RequireComponent(typeof(Rigidbody))] public class Player : TargetableObject { private PlayerData mPlayerData = null; private Rigidbody mRigidbody = null; private Animator mAnimator = null; private CapsuleCollider mCollider = null; // ─── EntityLogic 생명주기 ─── protected internal override void OnInit(object userData) { base.OnInit(userData); mRigidbody = GetComponent<Rigidbody>(); // includeInactive: true 가 필수다. 3장 PlayerSelectLogic 과 같은 이유다. mAnimator = GetComponentInChildren<Animator>(true); mCollider = GetComponent<CapsuleCollider>(); WarnOnMissingComponents(); } /// <summary> /// 캐시가 비어도 사용처마다 null 가드가 있어 예외는 나지 않는다. 대신 이동이나 /// 애니메이션이 <b>조용히</b> 죽어 원인을 찾기 어려우므로 여기서 한 번 알린다. /// </summary> private void WarnOnMissingComponents() { if (mRigidbody == null) { Log.Error("Player '{0}': Rigidbody 가 없어 이동이 동작하지 않는다.", Name); } if (mAnimator == null) { Log.Warning("Player '{0}': Animator 를 찾지 못했다. 이동/사망 애니메이션이 재생되지 않는다.", Name); } if (mCollider == null) { Log.Warning("Player '{0}': CapsuleCollider 가 없다. 중심점이 트랜스폼 원점으로 대체된다.", Name); } } protected internal override void OnShow(object userData) { base.OnShow(userData); // 상태 리셋은 userData 검사보다 <b>먼저</b> 한다. // 데이터가 없어도 인스턴스는 깨끗해야 한다. ResetRuntimeState(); mPlayerData = userData as PlayerData; if (mPlayerData == null) { Log.Error("Player data is invalid."); return; } CachedTransform.position = mPlayerData.Position; CachedTransform.rotation = mPlayerData.Rotation; } /// <summary> /// 풀에서 재사용되므로 이전 판의 상태를 반드시 리셋한다. /// </summary> private void ResetRuntimeState() { if (mCollider != null) { mCollider.enabled = true; } if (mAnimator != null) { mAnimator.Rebind(); mAnimator.Update(0f); } } protected internal override void OnHide(bool isShutdown, object userData) { // 데이터는 base 체인 끝(EntityLogicBase)에서 ReferencePool 로 반납된다. mPlayerData = null; base.OnHide(isShutdown, userData); } } }

// ─── 런타임 상태 ─── private Player mPlayer = null; private PlayerSelectLogic mGirlSelect = null; private PlayerSelectLogic mBoySelect = null;

/// <summary> /// 현재 플레이어. 선택 전이거나 이미 회수된 뒤에는 null. /// 엔티티는 풀에서 재사용되므로 참조가 살아 있어도 Available 을 확인해야 한다. /// </summary> public Player Player => (mPlayer != null && mPlayer.Available) ? mPlayer : null;

private void SpawnPlayer(string characterKey) { EntityComponent entityComponent = GameEntry.GetComponent<EntityComponent>(); if (entityComponent == null) { Log.Error("EntityComponent 를 찾을 수 없어 플레이어 '{0}' 를 스폰하지 못했다.", characterKey); return; } int id = EntitySerialId.Next(); entityComponent.ShowEntity( id, typeof(Player), characterKey, PlayerEntityGroup, PlayerData.Create(id, DefaultEntityTypeId)); }

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); SpawnPlayer(ne.CharacterKey); }

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; } if (ne.EntityLogicType == typeof(Player)) { CachePlayer(ne.Entity); } } private void CachePlayer(Entity entity) { Player player = entity.Logic as Player; if (player == null) { Log.Error("Player 로 스폰했는데 로직이 그 타입이 아니다: {0}", entity.EntityAssetName); return; } mPlayer = player; Log.Info("Player spawned: {0}", entity.EntityAssetName); }

/// <summary> /// <b>base.OnShowEntityFailure 를 부르지 않는다.</b> 베이스도 스폰 데이터를 반납하므로 /// 같이 부르면 이중 Release 가 되어 코어가 예외를 던진다. 대신 반납만 여기서 직접 한다. /// </summary> protected override void OnShowEntityFailure(object sender, GameEventArgs e) { ShowEntityFailureEventArgs ne = e as ShowEntityFailureEventArgs; if (ne == null) { GameAssert.Unreachable("ShowEntityFailure 핸들러에 다른 타입의 이벤트 인자가 들어왔다."); return; } // 스폰이 실패하면 OnShow 가 불리지 않아 아무도 소유권을 잡지 않는다. // 어느 분기로 빠지든 반드시 반납되도록 분기보다 먼저 처리한다. ReleaseSpawnData(ne); // 플레이어 실패만 Warning 이 아니라 Error 로 따로 다룬다. if (ne.EntityLogicType == typeof(Player)) { FailRoundOnPlayerSpawnFailure(ne); return; } Log.Warning("Show entity failure: {0} ({1})", ne.ErrorMessage, ne.EntityAssetName); } /// <summary> /// 플레이어 스폰 실패 처리. 판을 게임오버로 끝낸다. /// /// <b>이 처리를 빼면 게임이 조용히 영구 정지한다.</b> mPlayer 는 영원히 null 로 남고 /// Update 가 Player == null 에서 매 프레임 조기 리턴하므로, 시계도 스포너도 /// 게임오버도 돌지 않는다. 화면은 멀쩡한데 아무 일도 일어나지 않는 상태다. /// </summary> private void FailRoundOnPlayerSpawnFailure(ShowEntityFailureEventArgs ne) { Log.Error("플레이어 '{0}' 스폰에 실패했다. 판을 진행할 수 없어 게임오버로 끝낸다. 원인: {1}", ne.EntityAssetName, ne.ErrorMessage); GameOver = true; }

public override void Update(float elapseSeconds, float realElapseSeconds) { base.Update(elapseSeconds, realElapseSeconds); if (GameOver) return; // 캐릭터 선택 중에는 시계를 세워 둔다. 선택 시점부터가 '게임 시작'이다. if (Player == null) return; mGameTime += elapseSeconds; }

Character selected: Girl Player spawned: Girl

Entity Group - Player ├ Girl(Clone) ← 회색. 선택 화면에 서 있던 인스턴스 (풀에서 쉬는 중) ├ Boy(Clone) ← 회색. 쓰러졌다 사라진 인스턴스 (풀에서 쉬는 중) └ Girl(Clone) ← 흰색. 지금의 플레이어

// Assets/GameMain/Utility/EntityFinder.cs using System.Collections.Generic; using GameFramework.Entity; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 지금 떠 있는 엔티티 중에서 특정 대상을 찾는다. /// /// 정적 싱글턴(<c>Player.Instance</c> 같은 것)을 두지 않기 위한 창구다. 싱글턴은 엔티티가 /// 풀에서 재사용될 때마다 "누가 지금 진짜인가" 를 손으로 맞춰 줘야 하고, 한 번 어긋나면 /// 회수된 인스턴스를 가리킨다. 여기서는 그 답을 매번 <see cref="EntityComponent"/> 에 묻는다 — /// 프레임워크가 이미 알고 있는 사실을 따로 복사해 두지 않는다. /// /// 그룹 하나에 엔티티가 한두 개뿐인 대상만 찾는다. 적처럼 수십 개가 있는 /// 그룹을 매 프레임 훑는 용도가 아니다. /// </summary> public static class EntityFinder { /// <summary>조회용 재사용 버퍼. 호출마다 배열을 새로 만들지 않기 위해 둔다.</summary> private static readonly List<IEntity> sBuffer = new List<IEntity>(); /// <summary> /// 지금 떠 있는 플레이어. 캐릭터를 고르기 전이거나 회수된 뒤면 null 이다. /// 죽어서 쓰러지는 중인 플레이어는 아직 떠 있으므로 그대로 돌려준다(<c>IsDead</c> 로 구분한다). /// </summary> public static Player FindPlayer() { return Find<Player>(SurvivalGame.PlayerEntityGroup); } private static T Find<T>(string entityGroupName) where T : EntityLogic { EntityComponent entityComponent = GameEntry.GetComponent<EntityComponent>(); if (entityComponent == null) return null; IEntityGroup entityGroup = entityComponent.GetEntityGroup(entityGroupName); if (entityGroup == null) return null; sBuffer.Clear(); entityGroup.GetAllEntities(sBuffer); T found = null; for (int i = 0; i < sBuffer.Count; i++) { Entity entity = sBuffer[i] as Entity; if (entity == null) continue; // 같은 그룹에 다른 로직이 섞여 있을 수 있다(플레이어 그룹에는 선택 화면 캐릭터도 있다). T logic = entity.Logic as T; if (logic == null || !logic.Available) continue; found = logic; break; } // 엔티티 참조를 버퍼에 남겨 두지 않는다. sBuffer.Clear(); return found; } } }

/// <summary>플레이어·선택 캐릭터가 들어가는 엔티티 그룹. GameFramework.prefab 의 mEntityGroups 와 일치해야 한다.</summary> public const string PlayerEntityGroup = "Player";

// Assets/GameMain/Camera/PlayerCameraFollow.cs using UnityEngine; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 플레이어를 따라다니는 카메라. MainCamera 에 붙인다. /// /// <b>프레임워크 컴포넌트다</b>(<see cref="GameFrameworkComponent"/>). 판이 바뀌어도 살아 있는 /// 전역 시스템은 이렇게 프레임워크에 등록한다. 따라갈 플레이어도 정적 싱글턴이 아니라 /// 프레임워크에 물어서 찾는다(<see cref="EntityFinder.FindPlayer"/>). /// /// 플레이어가 아직 없는 캐릭터 선택 단계에서는 씬에 배치된 선택 앵글에 그대로 머문다. /// 플레이어가 스폰되면 위치와 회전을 함께 보간해 게임 앵글로 넘어간다. /// </summary> public class PlayerCameraFollow : GameFrameworkComponent { // offset 이 이보다 짧으면 방향을 구할 수 없다. 길이 0 벡터를 LookRotation 에 // 넘기면 Unity 가 에러를 뱉는다. private const float MinOffsetSqrMagnitude = 0.0001f; [Tooltip("플레이어 기준 카메라 위치. 원본 게임 앵글은 (0, 15, -22).")] [SerializeField] private Vector3 offset = new Vector3(0f, 15f, -22f); [Tooltip("추종 보간 속도. 클수록 빠르게 따라붙는다. 원본은 5.")] [SerializeField] private float smoothing = 5f; // offset 의 반대 방향을 바라보면 항상 플레이어를 향한다. // 회전을 따로 하드코딩하지 않으므로 offset 만 바꾸면 각도가 함께 맞는다. private Quaternion mTargetRotation = Quaternion.identity; // 씬에 배치된 원본 위치/회전 = 캐릭터 선택 앵글. 플레이어가 사라지면 여기로 돌아간다. private Vector3 mSelectPosition = Vector3.zero; private Quaternion mSelectRotation = Quaternion.identity; private void Start() { mSelectPosition = transform.position; mSelectRotation = transform.rotation; RecalculateRotation(); WarnIfMisconfigured(); } private void OnValidate() { RecalculateRotation(); } private void LateUpdate() { // 프레임 독립 보간 계수. Lerp/Slerp 가 내부에서 [0, 1] 로 클램프한다. float smoothStep = smoothing * Time.deltaTime; Transform followTarget = FindFollowTarget(); if (followTarget == null) { MoveTowardSelectAngle(smoothStep); return; } MoveTowardPlayerAngle(followTarget, smoothStep); } /// <summary> /// 따라갈 플레이어의 Transform. 아직 스폰 전이거나 이미 회수됐으면 null. /// 매 프레임 프레임워크에 묻는다. 한 번 받은 참조를 들고 있지 않으므로 /// 회수된 인스턴스를 가리킬 일이 없다. /// </summary> private static Transform FindFollowTarget() { Player player = EntityFinder.FindPlayer(); if (player == null) return null; return player.CachedTransform; } /// <summary> /// 플레이어가 없다 = 캐릭터 선택 단계이거나 게임오버 직후다. /// 여기서 아무것도 하지 않으면 카메라가 플레이어가 죽은 자리에 얼어붙고, /// 재시작 시 선택 캐릭터가 화면 밖이라 클릭할 수 없게 된다. 반드시 선택 앵글로 되돌린다. /// </summary> private void MoveTowardSelectAngle(float smoothStep) { transform.position = Vector3.Lerp(transform.position, mSelectPosition, smoothStep); transform.rotation = Quaternion.Slerp(transform.rotation, mSelectRotation, smoothStep); } private void MoveTowardPlayerAngle(Transform followTarget, float smoothStep) { transform.position = Vector3.Lerp(transform.position, followTarget.position + offset, smoothStep); transform.rotation = Quaternion.Slerp(transform.rotation, mTargetRotation, smoothStep); } private void RecalculateRotation() { if (offset.sqrMagnitude <= MinOffsetSqrMagnitude) { // 방향을 못 구하는 상황이다. 마지막으로 성립했던 회전을 그대로 둔다. return; } mTargetRotation = Quaternion.LookRotation(-offset); } /// <summary> /// 인스펙터 설정 실수 방어. 둘 다 증상이 "카메라가 안 따라온다" 하나로만 보여서 /// 원인을 짚기 어렵기 때문에 기동 시점에 한 번 알린다. /// </summary> private void WarnIfMisconfigured() { if (smoothing <= 0f) { Log.Warning("PlayerCameraFollow: smoothing 이 {0} 이라 카메라가 제자리에 멈춘다.", smoothing); } if (offset.sqrMagnitude <= MinOffsetSqrMagnitude) { Log.Warning("PlayerCameraFollow: offset 이 사실상 0 이라 카메라가 플레이어와 겹치고 회전도 갱신되지 않는다."); } } } }

// Assets/GameMain/Utility/MouseGround.cs using UnityEngine; using UnityEngine.InputSystem; namespace ToyBoxNightmare { /// <summary> /// 마우스 커서 아래의 지면 좌표. /// <b>필요한 쪽이 필요할 때 직접 묻는</b> 순수 함수로 둔다 — 갱신 순서에 의존하지 않고, /// 씬에 오브젝트를 하나 더 두지 않아도 된다. /// </summary> public static class MouseGround { /// <summary> /// 커서 아래 지면 좌표를 구한다. 못 구하면 false — 호출부가 대체값을 정한다. /// 카메라가 없거나 마우스가 없거나 시선이 지면과 평행하면 실패한다. /// 전부 정상적으로 일어날 수 있어 로그를 남기지 않는다. /// </summary> public static bool TryGetGroundPoint(out Vector3 point) { point = Vector3.zero; Camera mainCamera = Camera.main; if (mainCamera == null || Mouse.current == null) return false; Vector2 screenPosition = Mouse.current.position.ReadValue(); Ray ray = mainCamera.ScreenPointToRay(screenPosition); Plane groundPlane = new Plane(Vector3.up, Vector3.zero); if (!groundPlane.Raycast(ray, out float distance)) return false; point = ray.GetPoint(distance); return true; } } }

// ─── 애니메이터 파라미터 이름 ─── // 이름이 틀려도 Unity 는 조용히 무시하므로 문자열을 흩뿌리지 않고 여기 모아 둔다. private const string WalkingBoolParam = "IsWalking"; /// <summary> /// 방향 벡터가 이보다 짧으면 "방향이 없다" 로 본다. /// 길이 0 에 가까운 벡터를 <c>Quaternion.LookRotation</c> 에 넘기면 회전이 튄다. /// </summary> private const float MinLookSqrMagnitude = 0.001f; // FixedUpdate 에 전달할 이동/회전 방향 private Vector3 mMoveDirection = Vector3.zero; private Vector3 mLookDirection = Vector3.forward; /// <summary>마우스가 가리키는 지면 위 월드 좌표. 지면에 안 닿으면 캐릭터 전방 한 칸으로 대체된다.</summary> public Vector3 AimPoint { get; private set; } /// <summary>이번 프레임 지면 레이캐스트가 실제로 성공했는지. false 면 AimPoint 는 대체값이다.</summary> public bool HasAimPoint { get; private set; }

protected internal override void OnUpdate(float elapseSeconds, float realElapseSeconds) { base.OnUpdate(elapseSeconds, realElapseSeconds); ReadInput(); // 4.6 절에서 상태 기계로 옮긴다 } // ─── 물리 이동 (FixedUpdate) ─── private void FixedUpdate() { if (mRigidbody == null || mPlayerData == null || IsDead) return; MoveByInput(); TurnToLookDirection(); UpdateWalkAnimation(); } private void MoveByInput() { // normalized 는 길이 0 벡터에 대해 0 을 돌려주므로 0 나눗셈이 없다. Vector3 step = mMoveDirection.normalized * mPlayerData.MoveSpeed * Time.fixedDeltaTime; mRigidbody.MovePosition(mRigidbody.position + step); } private void TurnToLookDirection() { Vector3 look = mLookDirection; look.y = 0f; if (look.sqrMagnitude <= MinLookSqrMagnitude) return; mRigidbody.MoveRotation(Quaternion.LookRotation(look)); } private void UpdateWalkAnimation() { if (mAnimator == null) return; mAnimator.SetBool(WalkingBoolParam, mMoveDirection.sqrMagnitude > 0f); } // ─── 입력 처리 ─── /// <summary> /// 이번 프레임의 조준점과 이동 방향을 잡는다. /// 조준을 이동보다 먼저, 그리고 키보드 유무와 <b>무관하게</b> 갱신한다. /// </summary> private void ReadInput() { UpdateAimPoint(); UpdateLookDirection(); Keyboard keyboard = Keyboard.current; mMoveDirection = keyboard != null ? ReadMoveDirection(keyboard) : Vector3.zero; } /// <summary>WASD 와 방향키를 같은 축으로 합친다.</summary> private static Vector3 ReadMoveDirection(Keyboard keyboard) { float horizontal = ReadAxis( keyboard.dKey.isPressed || keyboard.rightArrowKey.isPressed, keyboard.aKey.isPressed || keyboard.leftArrowKey.isPressed); float vertical = ReadAxis( keyboard.wKey.isPressed || keyboard.upArrowKey.isPressed, keyboard.sKey.isPressed || keyboard.downArrowKey.isPressed); return new Vector3(horizontal, 0f, vertical); } /// <summary>양쪽을 동시에 누르면 0 이 된다(레거시 GetAxisRaw 와 같은 의미).</summary> private static float ReadAxis(bool positivePressed, bool negativePressed) { return (positivePressed ? 1f : 0f) - (negativePressed ? 1f : 0f); } /// <summary> /// 프레임당 딱 한 번 도는 지면 레이캐스트. 결과가 AimPoint / HasAimPoint 로 나가고, /// 캐릭터 회전도 여기서 나온 값을 쓴다. /// </summary> private void UpdateAimPoint() { HasAimPoint = MouseGround.TryGetGroundPoint(out Vector3 groundPoint); AimPoint = HasAimPoint ? groundPoint : ForwardAimPoint; } /// <summary>스폰 시점의 조준 상태. 아직 입력을 읽기 전이므로 지금 보는 방향으로 채운다.</summary> private void ResetAim() { mLookDirection = CachedTransform.forward; HasAimPoint = false; AimPoint = ForwardAimPoint; } /// <summary>조준점 쪽으로 바라볼 방향을 갱신한다.</summary> private void UpdateLookDirection() { Vector3 toAim = AimPoint - CachedTransform.position; toAim.y = 0f; // 커서가 캐릭터와 겹치면 방향이 0 에 수렴한다. 그때는 직전 방향을 유지한다. if (toAim.sqrMagnitude <= MinLookSqrMagnitude) return; mLookDirection = toAim; } /// <summary>마우스 지면 조준점을 못 구할 때 쓰는 대체 조준점. 지금 보는 방향을 유지한다.</summary> private Vector3 ForwardAimPoint { get { return CachedTransform.position + CachedTransform.forward; } }

mMoveDirection = Vector3.zero; ResetAim();

CachedTransform.position = mPlayerData.Position; CachedTransform.rotation = mPlayerData.Rotation; // 회전을 적용한 뒤에 다시 잡아야 스폰 자세를 그대로 바라본다. // 리셋 시점의 forward 는 아직 이전 판의 자세다. ResetAim();

// Assets/GameMain/Utility/GamePause.cs using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 일시정지 상태의 단일 소유자. /// /// <b>timeScale 은 직접 건드리지 않는다.</b> 프레임워크의 /// BaseComponent.PauseGame / ResumeGame 이 그 일을 하고, /// 정지 직전 속도를 기억했다가 되돌려 주는 것까지 맡는다. /// /// <b>그런데 timeScale 만으로는 부족하다.</b> GameFramework 는 정지 중에도 매 프레임 /// OnUpdate 를 부르고 elapseSeconds 만 0 이 된다 — 즉 타이머는 멈추지만 /// 입력 처리는 그대로 돈다. 그래서 입력을 읽는 쪽이 이 플래그를 직접 봐야 한다. /// </summary> public static class GamePause { /// <summary>지금 일시정지 중인가.</summary> public static bool IsPaused { get; private set; } public static void SetPaused(bool paused) { if (IsPaused == paused) return; // 입력 게이트는 프레임워크 상태와 무관하게 반드시 서야 한다. IsPaused = paused; BaseComponent baseComponent = GameEntry.GetComponent<BaseComponent>(); if (baseComponent == null) { Log.Warning("GamePause: BaseComponent 가 없다. 입력만 막히고 시간은 계속 흐른다."); return; } if (paused) { baseComponent.PauseGame(); return; } baseComponent.ResumeGame(); } /// <summary> /// 판을 벗어날 때 반드시 부른다. 정지 상태로 프로시저가 바뀌면 /// 게임 속도가 0 인 채로 남아 다음 판이 통째로 멈춘다. /// </summary> public static void Clear() { SetPaused(false); } } }

// Assets/GameMain/Game/PlayerDiedEventArgs.cs using GameFramework; using GameFramework.Event; namespace ToyBoxNightmare { /// <summary> /// 플레이어가 죽었을 때 발행된다. SurvivalGame 이 이걸 받아 GameOver 를 세운다. /// /// 점수는 싣지 않는다. 점수를 아는 것은 게임(SurvivalGame)이지 플레이어가 아니다 — /// 필요한 쪽이 게임에서 읽는다. /// </summary> public class PlayerDiedEventArgs : GameEventArgs { public static readonly int EventId = typeof(PlayerDiedEventArgs).GetHashCode(); public override int Id => EventId; public static PlayerDiedEventArgs Create() { return ReferencePool.Acquire<PlayerDiedEventArgs>(); } public override void Clear() { } } }

// States/PlayerStateBase.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 플레이어 상태의 공통 베이스. /// <b>상태는 무상태(stateless)다.</b> 모든 값은 <c>fsm.Owner</c> 에서 읽는다. /// </summary> public abstract class PlayerStateBase : FsmState<Player> { /// <summary> /// 어느 상태에 있든 사망이 시작되면 사망 연출로 넘어간다. /// 전이했으면 true — 호출한 상태는 그 프레임의 나머지 일을 하지 말아야 한다. /// </summary> protected bool TryChangeToDying(IFsm<Player> fsm) { if (!fsm.Owner.IsDeathSequenceRunning) return false; ChangeState<PlayerDyingState>(fsm); return true; } } }

// States/PlayerAliveState.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 살아서 조작 가능한 상태. /// </summary> public sealed class PlayerAliveState : PlayerStateBase { protected override void OnUpdate(IFsm<Player> fsm, float elapseSeconds, float realElapseSeconds) { base.OnUpdate(fsm, elapseSeconds, realElapseSeconds); if (TryChangeToDying(fsm)) return; Player owner = fsm.Owner; // 이미 체력이 0 인데 사망 연출이 아직 시작 안 된 프레임이 있을 수 있다. // 그 사이 입력을 받으면 시체가 한 프레임 더 움직인다. if (owner.IsDead) return; // 일시정지는 별도 상태로 뺀다. timeScale 0 이어도 OnUpdate 자체는 계속 불리므로 // 여기서 걸러 주지 않으면 메뉴를 띄운 채 사격이 나간다. if (GamePause.IsPaused) { ChangeState<PlayerPausedState>(fsm); return; } owner.TickAliveInput(); } } }

// States/PlayerPausedState.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 일시정지 상태. 아무 입력도 읽지 않는다. /// /// 진입할 때 이동 방향을 비우는 것이 핵심이다 — 안 그러면 재개하는 순간 /// 정지 직전의 입력으로 한 걸음 튀어나간다(FixedUpdate 는 계속 돌기 때문이다). /// </summary> public sealed class PlayerPausedState : PlayerStateBase { protected override void OnEnter(IFsm<Player> fsm) { base.OnEnter(fsm); fsm.Owner.ClearMoveInput(); } protected override void OnUpdate(IFsm<Player> fsm, float elapseSeconds, float realElapseSeconds) { base.OnUpdate(fsm, elapseSeconds, realElapseSeconds); if (TryChangeToDying(fsm)) return; if (GamePause.IsPaused) return; ChangeState<PlayerAliveState>(fsm); } } }

// States/PlayerDyingState.cs using GameFramework.Fsm; namespace ToyBoxNightmare { /// <summary> /// 사망 연출 상태. 즉시 사라지지 않고 사망 애니메이션이 보일 시간을 준다. /// 회수(Hide)는 Player.OnDead 가 아니라 이 상태의 타이머가 담당한다. /// </summary> public sealed class PlayerDyingState : PlayerStateBase { protected override void OnUpdate(IFsm<Player> fsm, float elapseSeconds, float realElapseSeconds) { base.OnUpdate(fsm, elapseSeconds, realElapseSeconds); fsm.Owner.TickDeathSequence(elapseSeconds); } } }

// Assets/GameMain/Entity/EntityLogic/Player.cs using GameFramework.Fsm; using UnityEngine; using UnityEngine.InputSystem; using UnityGameFramework.Runtime; namespace ToyBoxNightmare { /// <summary> /// 플레이어 엔티티 로직. /// - Rigidbody 기반 이동 (FixedUpdate) /// - 마우스 방향으로 회전 /// - WASD 이동 /// </summary> [RequireComponent(typeof(Rigidbody))] public class Player : TargetableObject { // ─── 애니메이터 파라미터 이름 ─── private const string WalkingBoolParam = "IsWalking"; private const string DieTriggerParam = "Die"; private const float MinLookSqrMagnitude = 0.001f; private PlayerData mPlayerData = null; private Rigidbody mRigidbody = null; private Animator mAnimator = null; private CapsuleCollider mCollider = null; // FixedUpdate 에 전달할 이동/회전 방향 private Vector3 mMoveDirection = Vector3.zero; private Vector3 mLookDirection = Vector3.forward; // ─── 상태 기계 ─── // 상태는 무상태라 인스턴스를 풀 재사용 사이에 그대로 돌려쓴다(OnInit 에서 1회 생성). // FSM 자체는 스폰마다 만들고 회수마다 부순다 — 회수된 엔티티의 상태가 계속 돌면 안 된다. private IFsm<Player> mFsm = null; private FsmState<Player>[] mStates = null; // 사망 연출 private bool mDying = false; private float mDeathTimer = 0f; private bool mDeathNotified = false; private const float DeathDelay = 1f; public Vector3 AimPoint { get; private set; } public bool HasAimPoint { get; private set; } // ─── EntityLogic 생명주기 ─── protected internal override void OnInit(object userData) { base.OnInit(userData); // 상태 인스턴스는 여기서 한 번만 만든다. mStates = new FsmState<Player>[] { new PlayerAliveState(), new PlayerPausedState(), new PlayerDyingState(), }; mRigidbody = GetComponent<Rigidbody>(); mAnimator = GetComponentInChildren<Animator>(true); mCollider = GetComponent<CapsuleCollider>(); WarnOnMissingComponents(); } private void WarnOnMissingComponents() { if (mRigidbody == null) { Log.Error("Player '{0}': Rigidbody 가 없어 이동이 동작하지 않는다.", Name); } if (mAnimator == null) { Log.Warning("Player '{0}': Animator 를 찾지 못했다. 이동/사망 애니메이션이 재생되지 않는다.", Name); } if (mCollider == null) { Log.Warning("Player '{0}': CapsuleCollider 가 없다. 중심점이 트랜스폼 원점으로 대체된다.", Name); } } protected internal override void OnShow(object userData) { base.OnShow(userData); ResetRuntimeState(); mPlayerData = userData as PlayerData; if (mPlayerData == null) { Log.Error("Player data is invalid."); return; } CachedTransform.position = mPlayerData.Position; CachedTransform.rotation = mPlayerData.Rotation; // 회전을 적용한 뒤에 다시 잡아야 스폰 자세를 그대로 바라본다. ResetAim(); // 상태 기계는 **맨 마지막**에 세운다. 상태가 OnEnter 에서 소유자 값을 읽기 때문이다. CreateStateMachine(); } /// <summary> /// FSM 이름. 코어는 (소유자 타입, 이름) 으로 FSM 을 식별하므로 /// 인스턴스마다 달라야 한다. 엔티티 Id 가 그 조건을 만족한다. /// </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("Player: FsmComponent 가 없다. 입력도 사망 연출도 돌지 않는다."); return; } mFsm = fsmComponent.CreateFsm(FsmName, this, mStates); mFsm.Start<PlayerAliveState>(); } /// <summary>멱등하다. 이미 부쉈거나 프레임워크가 먼저 내려갔으면 조용히 넘어간다.</summary> private void DestroyStateMachine() { if (mFsm == null) return; FsmComponent fsmComponent = GameEntry.GetComponent<FsmComponent>(); if (fsmComponent != null) { fsmComponent.DestroyFsm(mFsm); } mFsm = null; } /// <summary> /// 풀에서 재사용되므로 이전 판의 이동/애니/사망 상태를 반드시 리셋한다. /// 빠뜨리면 두 번째 판이 죽은 포즈에 콜라이더가 꺼진 채로 시작한다. /// </summary> private void ResetRuntimeState() { mMoveDirection = Vector3.zero; mDying = false; mDeathTimer = 0f; mDeathNotified = false; ResetAim(); if (mCollider != null) { mCollider.enabled = true; } if (mAnimator != null) { mAnimator.Rebind(); mAnimator.Update(0f); } } protected internal override void OnHide(bool isShutdown, object userData) { // 가장 먼저 부순다. 회수된 엔티티의 상태가 계속 도는 것을 막는다. DestroyStateMachine(); mPlayerData = null; base.OnHide(isShutdown, userData); } /// <summary> /// 프레임 갱신은 전부 FSM 상태가 한다(FsmManager 가 이것보다 먼저 돈다). /// 여기에 로직을 다시 넣으면 상태 밖에 숨은 분기가 생기므로 그러지 말 것. /// </summary> protected internal override void OnUpdate(float elapseSeconds, float realElapseSeconds) { base.OnUpdate(elapseSeconds, realElapseSeconds); } // ─── 상태가 쓰는 창구 ─── /// <summary>사망 연출이 시작됐는가. 모든 상태가 이것을 보고 사망 상태로 넘어간다.</summary> internal bool IsDeathSequenceRunning { get { return mDying; } } /// <summary>살아있는 동안의 한 프레임.</summary> internal void TickAliveInput() { ReadInput(); } /// <summary>이동 입력을 비운다. FixedUpdate 는 계속 돌기 때문에 정지 진입 시 필요하다.</summary> internal void ClearMoveInput() { mMoveDirection = Vector3.zero; } /// <summary> /// 사망 연출 한 프레임. 즉시 사라지지 않고 사망 애니메이션이 보일 시간을 준다. /// 이 타이머가 <see cref="OnDead"/> 대신 회수(Hide)를 담당한다. /// </summary> internal void TickDeathSequence(float elapseSeconds) { mDeathTimer += elapseSeconds; if (mDeathTimer < DeathDelay) return; NotifyDied(); SafeHide(); } // ─── 물리 이동 (FixedUpdate) ─── private void FixedUpdate() { if (mRigidbody == null || mPlayerData == null || IsDead) return; MoveByInput(); TurnToLookDirection(); UpdateWalkAnimation(); } private void MoveByInput() { Vector3 step = mMoveDirection.normalized * mPlayerData.MoveSpeed * Time.fixedDeltaTime; mRigidbody.MovePosition(mRigidbody.position + step); } private void TurnToLookDirection() { Vector3 look = mLookDirection; look.y = 0f; if (look.sqrMagnitude <= MinLookSqrMagnitude) return; mRigidbody.MoveRotation(Quaternion.LookRotation(look)); } private void UpdateWalkAnimation() { if (mAnimator == null) return; mAnimator.SetBool(WalkingBoolParam, mMoveDirection.sqrMagnitude > 0f); } // ─── 입력 처리 ─── private void ReadInput() { UpdateAimPoint(); UpdateLookDirection(); Keyboard keyboard = Keyboard.current; mMoveDirection = keyboard != null ? ReadMoveDirection(keyboard) : Vector3.zero; } private static Vector3 ReadMoveDirection(Keyboard keyboard) { float horizontal = ReadAxis( keyboard.dKey.isPressed || keyboard.rightArrowKey.isPressed, keyboard.aKey.isPressed || keyboard.leftArrowKey.isPressed); float vertical = ReadAxis( keyboard.wKey.isPressed || keyboard.upArrowKey.isPressed, keyboard.sKey.isPressed || keyboard.downArrowKey.isPressed); return new Vector3(horizontal, 0f, vertical); } private static float ReadAxis(bool positivePressed, bool negativePressed) { return (positivePressed ? 1f : 0f) - (negativePressed ? 1f : 0f); } private void UpdateAimPoint() { HasAimPoint = MouseGround.TryGetGroundPoint(out Vector3 groundPoint); AimPoint = HasAimPoint ? groundPoint : ForwardAimPoint; } private void ResetAim() { mLookDirection = CachedTransform.forward; HasAimPoint = false; AimPoint = ForwardAimPoint; } private void UpdateLookDirection() { Vector3 toAim = AimPoint - CachedTransform.position; toAim.y = 0f; if (toAim.sqrMagnitude <= MinLookSqrMagnitude) return; mLookDirection = toAim; } private Vector3 ForwardAimPoint { get { return CachedTransform.position + CachedTransform.forward; } } // ─── 사망 ─── /// <summary> /// 주의: <c>base.OnDead</c> 를 부르지 않는다. base 는 즉시 SafeHide 하므로 /// 사망 연출이 통째로 생략되고, 연출 종료 시점의 Hide 와 겹쳐 중복이 된다. /// 회수는 사망 타이머가 담당한다. /// </summary> protected override void OnDead(Entity attacker) { GameAssert.IsTrue(IsDead, "OnDead 는 체력이 0 이하가 된 뒤에만 호출되어야 한다."); if (mDying) return; mDying = true; mDeathTimer = 0f; StopMovementAndCollision(); PlayDeathAnimation(); // 사망 이벤트는 여기서 쏘지 않는다. NotifyDied() 를 볼 것. } /// <summary>이동/충돌을 즉시 끊는다. 적이 시체를 계속 때리지 않게 콜라이더도 끈다.</summary> private void StopMovementAndCollision() { mMoveDirection = Vector3.zero; if (mCollider != null) { mCollider.enabled = false; } } private void PlayDeathAnimation() { if (mAnimator == null) return; mAnimator.SetBool(WalkingBoolParam, false); mAnimator.SetTrigger(DieTriggerParam); } /// <summary> /// 사망을 알린다. <b>사망 연출이 끝난 뒤에 부른다</b> — OnDead 에서 바로 쏘면 /// 연출이 1프레임으로 잘린다. /// </summary> private void NotifyDied() { if (mDeathNotified) return; mDeathNotified = true; // Create 는 참조 풀에서 꺼내 오므로, 발행하지 못할 상황이면 만들기 전에 빠진다. EventComponent eventComponent = GameEntry.GetComponent<EventComponent>(); if (eventComponent == null) { Log.Error("EventComponent 가 없어 PlayerDied 를 발행하지 못했다."); return; } eventComponent.Fire(this, PlayerDiedEventArgs.Create()); } } }

events.Subscribe(PlayerDiedEventArgs.EventId, OnPlayerDied);

events.Unsubscribe(PlayerDiedEventArgs.EventId, OnPlayerDied);

private void OnPlayerDied(object sender, GameEventArgs e) { if (GameOver) return; GameOver = true; Log.Info("Game over. Final score: {0}", Score); }

internal void TickAliveInput() { ReadInput(); // 확인용: K 를 누르면 스스로 피해를 입는다. 확인한 뒤 지운다 Keyboard keyboard = Keyboard.current; if (keyboard != null && keyboard.kKey.wasPressedThisFrame) { ApplyDamage(null, 50); } }

Character selected: Girl Player spawned: Girl Game over. Final score: 0