Unity ML-Agents를 활용하여 정해진 트랙을 안정적으로 주행하는 자율 주행 경주차 에이전트를 학습시킨 프로젝트입니다. 시뮬레이션 환경 구축부터 보상 체계 설계, 신경망 관측 데이터 최적화까지의 전 과정을 다룹니다.

1. 프로젝트 개요

본 프로젝트는 강화학습(Reinforcement Learning)을 통해 복잡한 트랙 환경에서 자율 주행이 가능한 경주차 에이전트를 개발하는 것을 목표로 합니다. 체크포인트 기반 네비게이션 시스템과 다층적 보상 설계를 통해 에이전트가 트랙을 순차적으로 완주하도록 유도하며, 레이캐스트 기반 환경 감지와 입력 스무딩을 통해 물리적으로 안정적인 주행 성능을 확보했습니다.

Unity ML-Agents를 통한 자율 주행 학습 과정

구불구불한 도로와 바위 지형으로 구성된 학습 트랙 환경

2. 체크포인트 기반 네비게이션 시스템

강화학습 초기 단계에서 에이전트들이 최단 경로를 찾는 과정에서 트랙을 역주행하거나 경로를 이탈하는 문제가 빈번하게 발생했습니다. 이를 해결하기 위해 순차적 체크포인트 시스템을 구축하여 에이전트가 반드시 트랙의 순방향으로 전진하도록 강제했습니다.

2.1 시스템 아키텍처

트랙의 스플라인 곡선을 분석하여 체크포인트를 자동 생성하고, 에이전트의 진행 상태를 관리하는 계층적 구조를 설계했습니다. SplineToCheckpointGenerator를 통해 수작업 없이 일정한 간격으로 체크포인트와 스타팅 그리드를 구성할 수 있습니다.

스플라인 기반 체크포인트 자동 생성 로직 Unity Spline을 기반으로 정해진 개수만큼의 체크포인트를 트랙의 곡률(탄젠트)에 맞게 회전시켜 자동 생성하고, TrackData에 연동하는 핵심 로직입니다.

// SplineToCheckpointGenerator.cs: 체크포인트 자동 생성 로직
public void GenerateCheckpoints()
{
    // ... 초기화 및 검증 생략 ...
    for (int i = 0; i < totalCheckpoints; i++)
    {
        // 스플라인을 따라 위치 계산
        float progress = (float)(i + 1) / totalCheckpoints;
        spline.Spline.Evaluate(progress, out float3 pos, out float3 tan, out float3 up);
        if (math.lengthsq(tan) == 0) tan = math.forward(); 

        // 체크포인트 GameObject 생성 및 배치
        GameObject checkpointObj = new GameObject($"Checkpoint_{i:00}");
        checkpointObj.transform.SetParent(checkpointRoot.transform);
        checkpointObj.transform.localPosition = (Vector3)pos;
        checkpointObj.transform.localRotation = Quaternion.LookRotation((Vector3)tan, (Vector3)up);

        // BoxCollider(Trigger)와 Tag 자동 추가
        BoxCollider collider = checkpointObj.AddComponent<BoxCollider>();
        collider.isTrigger = true;
        collider.size = checkpointColliderSize;
        checkpointObj.tag = checkpointTag;

        CheckPoint cpScript = checkpointObj.AddComponent<CheckPoint>();
        cpScript.Init(i); 
        checkPointsTemp[i] = checkpointObj.transform;
    }
    
    // TrackData에 최종 등록
    trackData.SetCheckPoints(checkPointsTemp);
}

순차적 체크포인트 검증 로직 차량이 통과한 체크포인트의 인덱스가 현재 기대되는 순서(NextCheckpointIndex)와 일치하는지 확인하여 논리적 주행 경로를 보장합니다.

// CarProgress.cs: 체크포인트 충돌 처리 (내부 상태 갱신)
private void CheckpointPassed(int checkpointIndex)
{
    if (IsFinished || trackData == null) return;

    // 내가 가야 할 체크포인트가 맞는지 확인
    if (checkpointIndex == NextCheckpointIndex)
    {
        // 다음 체크포인트로 인덱스 증가
        NextCheckpointIndex++;

        // 마지막 체크포인트를 넘었으면? (랩 종료 또는 완주)
        if (NextCheckpointIndex >= trackData.CheckpointCount)
        {
            NextCheckpointIndex = 0; // 다시 0번부터
            CurLap++;

            if (CurLap > maxLab)
            {
                IsFinished = true;
                FinalRank = CurRank;
                GameManager.Race.AddFinishedCount();
            }
        }
    }
}

3. 정교한 보상 설계 (Reward Engineering)

에이전트가 단순히 전진하는 것을 넘어, 사고 없이 효율적으로 주행하도록 다층적 보상 시스템을 설계했습니다.

3.1 목표 지향 보상 (Goal-Oriented)

에이전트가 트랙의 흐름에 따라 체크포인트를 순차적으로 정복하도록 유도합니다.

3.2 안전성 및 복구 보상 (Safety & Recovery)

차량이 벽에 충돌하거나 멈추는 등의 비효율적 상황을 최소화하도록 설계된 시스템입니다.

통합 보상 계산 및 페널티 부여 로직 목표 지점을 향한 거리 보상, 방향 정렬(Dot Product), 그리고 전방/후방 레이캐스트 센서를 활용한 벽 근접 페널티를 종합적으로 계산하는 핵심 함수입니다.

// SimcadeCarAgent_Auto.cs: 보상 계산 로직
private void CalculateRewards() {
    // 1. 기본 시간 페널티 (빠른 완주 유도)
    AddReward(timePenalty);

    Vector3 targetPosition = GetTargetPosition();
    float distanceToTarget = Vector3.Distance(transform.position, targetPosition); 

    if (targetPosition != transform.position) {
        // 2. 방향 정렬 보상 (목표 방향과 현재 차량의 전방 방향 일치도)
        Vector3 targetDirection = (targetPosition - transform.position).normalized;
        float directionDot = Vector3.Dot(transform.forward, targetDirection);
        AddReward(directionDot * directionAlignmentRewardFactor);

        // 3. 거리 기반 보상 (가까워질수록 보상)
        float distanceChange = lastDistanceToTarget - distanceToTarget;
        float weight = (Vector3.Dot(rb.linearVelocity, transform.forward) > 0.1f) ? 1.0f : 0.5f;
        AddReward(distanceChange * distanceRewardFactor * weight);
        
        lastDistanceToTarget = distanceToTarget;
    }

    // 4. 벽 근접 페널티 (레이캐스트 활용)
    if (!isStuckInWall) {
        ApplyProximityPenalty(wallRayDirections, wallLayer, wallProximityDistance, proximityPenalty);
    }
}

// 레이캐스트 기반 근접 페널티 계산
private void ApplyProximityPenalty(Vector3[] directions, LayerMask layer, float distance, float penaltyCoefficient) {
    for (int i = 0; i < directions.Length; i++) {
        Vector3 worldRayDir = transform.TransformDirection(directions[i]);
        if (Physics.Raycast(transform.position, worldRayDir, out RaycastHit hit, distance, layer)) {
            // 거리가 가까울수록 더 큰 페널티를 부여하여 충돌 회피 유도
            float penalty = penaltyCoefficient * (1f - (hit.distance / distance));
            AddReward(penalty * Time.fixedDeltaTime);
        }
    }
}

4. 환경 감지 및 행동 결정 아키텍처

에이전트는 주변 환경을 입체적으로 인식하기 위해 총 36차원의 관측(Observation) 데이터를 수집하며, 이를 기반으로 물리적인 제어를 수행합니다.

4.1 레이캐스트 기반 환경 센싱

에이전트가 도로의 폭, 곡률, 장애물과의 거리를 정확히 파악하도록 다방향 레이캐스트 시스템을 구축했습니다.

차량의 레이캐스트 센서 시스템 시각화 (빨간색: 감지된 대상, 초록색: 일반 센서 범위, 체크포인트 및 경로 스플라인 표시)

4.2 인지-행동 지연 없는 직접 제어 (Direct Action Control)

초기 학습 단계에서는 급격한 조향 지터링(Jittering)을 방지하기 위해 프레임 간 조향값의 변화량을 제한하는 입력 보정(Action Smoothing) 알고리즘을 테스트했습니다. 그러나 차량의 반응성을 떨어뜨려 코너링에서 에이전트의 의도가 지연되는 현상이 확인되었습니다.

신경망 출력을 물리 차량 컨트롤러에 직접 매핑하여 반응성을 극대화

즉각적 행동 매핑 로직 입력 스무딩을 제거하여 AI의 조향 및 가속 의도가 지연 없이 차량에 반영되도록 최적화한 컨트롤 메서드입니다.

public override void OnActionReceived(ActionBuffers actions)
{
    // 액션 스무딩 제거: AI의 의도가 즉각적으로 반영되도록 수정
    float steeringInput = Mathf.Clamp(actions.ContinuousActions[0], -1f, 1f);
    float accelerationInput = Mathf.Clamp(actions.ContinuousActions[1], -1f, 1f);

    lastSteeringInput = steeringInput;
    lastAccelerationInput = accelerationInput;

    // 보정 없이 차량 컨트롤러에 원시 입력값 직접 전달
    vehicleController.ProvideInputs(accelerationInput, steeringInput, 0f);
    
    CalculateRewards();
    CheckEpisodeEndConditions();
    GetComponent<CarProgress>().UpdateProgress();
}

5. 학습 설정 및 일반화 성능 확보

특정 트랙에 과적합(Overfitting)되지 않고 다양한 환경에서 안정적으로 주행할 수 있도록 학습 설정을 최적화했습니다.

5.1 하이퍼파라미터 (PPO 기반)

5.2 다중 트랙 랜덤 학습 시스템

에이전트의 일반화 성능을 극대화하기 위해 매 에피소드 시작 시 랜덤하게 트랙과 스폰 포인트를 교체하는 시스템을 도입했습니다.

다중 트랙 랜덤 스폰 로직 매 에피소드 초기화 시 다양한 트랙과 위치에서 시작하도록 설정하여 에이전트의 일반화 능력을 향상시킵니다.

public override void OnEpisodeBegin()
{
    // 1. 등록된 모든 트랙 중 하나를 랜덤 선택
    currentTrack = allTracks[Random.Range(0, allTracks.Count)];
    
    // 2. 해당 트랙의 스폰 포인트 리스트 중 랜덤 위치 선정
    Transform spawnTransform = currentTrack.GetStartPoint(Random.Range(0, currentTrack.StartPointsCount));
    
    // 3. 물리 상태 초기화 및 배치
    transform.position = spawnTransform.position;
    transform.rotation = spawnTransform.rotation;
    rb.linearVelocity = Vector3.zero;
    carProgress.Initialize();
}

6. 기술적 성과 및 결론

• 주행 안정성: 보상 체계 정밀화를 통해 조향 지터링을 스스로 극복하는 부드러운 코너링 구현.
• 환경 적응력: 다중 트랙 학습을 통해 학습되지 않은 새로운 트랙에서도 90% 이상의 완주율 달성.
• 복구 지능: 충돌 시 스스로 후진하여 경로로 복귀하거나, 복구 불가능 시 빠르게 재시도하는 효율적 학습 루프 구축.

Conclusion: ML-Agents의 연속 행동 공간(Continuous Action Space)을 물리 기반 차량 컨트롤러와 결합하여, 단순한 경로 추적을 넘어 물리적 한계를 고려하며 최적의 궤적을 그리는 자율 주행 AI를 성공적으로 구축했습니다.

File Tower Defense 프로젝트의 코어 시스템 설계를 담당하며, 유니티의 좌표계 특성을 분석한 아키텍처 재설계부터 대규모 객체의 입력 처리, 동적 버프 시스템, 그리고 그리드 기반 배치 로직까지 전반적인 시스템 개선 과정을 기록한 리포트입니다.

1. 시스템 리팩토링 및 개선

1.1 UI(RectTransform)에서 GameObject(Transform) 기반 전환

초기 설계에서는 윈도우 바탕화면의 아이콘 느낌을 살리기 위해 모든 파일 유닛을 UI 시스템(RectTransform)으로 구축했습니다. 그러나 프로젝트가 고도화됨에 따라 다음과 같은 한계에 직면했습니다.

• 좌표계 종속성: 캔버스의 앵커/피벗 설정 및 해상도에 따라 월드 좌표가 상대적으로 변하여 게임 월드 내 정밀한 위치 계산과 사거리 판정이 매우 까다로움.
• 연산 오버헤드 (Canvas Rebuilding): 유닛의 움직임, 호버 효과, 드래그 등의 UI 요소가 갱신될 때마다 Unity 내부에서 Canvas Rebuild가 강제로 유발되어 CPU 프레임 드랍 발생.
• 물리 엔진의 부재: 월드 좌표 기반의 바이러스(적)와 UI 유닛 간 물리 충돌 판정을 위해 매 프레임 Camera.WorldToScreenPoint 등의 물리-화면 좌표 변환 함수 호출 비용 발생.

이를 해결하기 위해 모든 유닛을 GameObject(Transform) 기반으로 전면 교체하여 월드 좌표계로 통일하였으며, Physics2D와의 직접적인 호환성을 확보하여 불필요한 연산을 제거하고 성능을 극적으로 최적화했습니다.

1.2 GameObjectGridLayout: 커스텀 레이아웃 엔진

화면 해상도에 맞춰 그리드의 간격과 셀 크기를 동적으로 계산하는 레이아웃 엔진을 구축했습니다. 유니티의 GridLayoutGroup은 UI 전용이므로, 일반 월드 공간 오브젝트를 위해 화면 크기에 맞게 자동으로 셀 크기를 스케일링하는 컴포넌트를 직접 개발했습니다.

// GameObjectGridLayout.cs: 해상도 대응 셀 크기 계산
public void FitToScreen() {
    Camera cam = Camera.main;
    float height = cam.orthographicSize * 2f; // 오르토그래픽 카메라 높이
    float width = height * cam.aspect;         // 카메라 종횡비 기반 너비

    // 가용 영역에서 패딩과 스페이싱을 제외한 실제 셀 크기 도출
    cellSize.x = (width - (padding.x * 2) - (spacing.x * (columns - 1))) / columns;
    cellSize.y = (height - (padding.y * 2) - (spacing.y * (rows - 1))) / rows;

    // 그리드의 좌상단 시작 월드 좌표 계산
    StartPos = new Vector2(-(width / 2) + padding.x + (cellSize.x / 2), 
                            (height / 2) - padding.y - (cellSize.y / 2));
}

2. 파일/바이러스/UI 입력 및 상호작용 시스템

수많은 유닛이 각자 Update()에서 마우스 충돌을 검사하면 연산량이 기하급수적으로 늘어납니다. 이를 방지하기 위해 Mediator 패턴을 활용하여 InputManager가 모든 마우스 입력을 통합 관리하고, IInteractable 인터페이스를 구현한 대상 객체에게만 이벤트를 전송하도록 설계했습니다.

2.1 중앙 집중식 입력 아키텍처

InputManager는 마우스의 상태 머신(InputState)을 기반으로 클릭, 드래그, 다중 선택(Ctrl+드래그)을 판단하여 InteractionHandler를 통해 이벤트를 전파합니다.

graph TD
    A[Mouse / Touch Input] --> B[InputManager]
    B -->|1. Raycast & UI Check| C{Is Pointer Over UI?}
    C -->|Yes| D[Ignore World Interaction / Handle UI]
    C -->|No| E[GetInteractableUnderMouse]
    E -->|2. Sort by Layer/Order| F[Identify Target IInteractable]
    B -->|3. Update InputState| G{InputState}
    G -->|Pressing| H[Check Drag Threshold]
    G -->|DraggingObject| I[OnDragHandler]
    G -->|DraggingBox| J[Multi-Select Drag Box]
    B -->|4. Dispatch Events| K[InteractionHandler]
    K -->|Trigger Interface Methods| L[IInteractable Objects]
    
    style B fill:#007bff,stroke:#0056b3,color:#fff
    style K fill:#28a745,stroke:#1e7e34,color:#fff
    style L fill:#17a2b8,stroke:#117a8b,color:#fff

[DEMO] InputManager 기반 마우스 호버 및 클릭 감지

객체 중첩 판정 알고리즘

마우스 아래에 여러 유닛이나 바이러스, 혹은 UI 판정이 겹쳐있을 때, 다음과 같은 우선순위 기준을 사용하여 모호함을 해결합니다.

1. UI 레이어 우선: EventSystem.current.IsPointerOverGameObject()를 통해 UI 상호작용 우선 처리.
2. 물리 레이어 필터링: Physics2D.RaycastNonAlloc을 활용하여 쓰레기 메모리(GC Alloc) 없이 감지된 콜라이더 배열을 가져옴.
3. 정렬 레이어(Sorting Order) 정렬: 감지된 객체들의 SpriteRenderer 내 Sorting Layer ID 및 Order in Layer 값을 비교하여 카메라와 가장 가까운(최상단에 렌더링된) 오브젝트를 타깃으로 최종 선택.

2.2 IInteractable 인터페이스 기반 확장성

클릭 및 드래그 상호작용이 필요한 모든 인게임 오브젝트(유닛 파일, 바이러스 등)는 IInteractable 인터페이스를 상속받아 유연하게 확장할 수 있습니다.

[DEMO] IInteractable 상속 객체의 실시간 마우스 드래그 & 배치 흐름

public interface IInteractable {
    GameObject targetObj { get; }
    bool IsSelectable { get; }
    bool IsDraggable { get; }
    
    void OnHoverEnter();
    void OnHoverExit();
    void OnClick();
    void OnBeginDrag();
    void OnDrag(Vector2 mouseDelta);
    void OnEndDrag();
    void OnSelected(bool isSelected);
}

3. 그리드 기반 오브젝트 배치 시스템

3.1 FileGrid: 데이터 중심의 지능형 셀 매니저

FileGrid는 단순한 위치 정보 홀더가 아니라, 유닛 배치 상태와 해당 셀에 작용 중인 오라(버프) 목록을 독자적으로 관리하는 지능형 컨테이너입니다.

• HashSet 기반 버프 소스 관리: 현재 그리드 공간에 영향을 주는 버프 제공 유닛의 목록을 HashSet<File_Base>로 관리하여 버프의 중복 적용을 제거하고 $O(1)$의 빠른 조회 속도를 유지합니다.
• 유닛 탈부착 시 자동 스탯 갱신: 유닛이 배치되거나 이탈할 때 그리드에 축적된 버프 목록을 분석하여 대상 유닛의 스탯을 실시간으로 갱신해 줍니다.

3.2 원자적 배치 트랜잭션 (Transactional Pattern)

드래그 앤 드롭으로 유닛의 그리드 위치를 옮길 때 발생할 수 있는 데이터 불일치 및 예외 상황을 원자적으로 보장하기 위해 배치 트랜잭션 흐름을 탐색/검증, 성공(Commit), 실패(Rollback)의 3가지 흐름으로 분할 설계하여 안전성을 확보했습니다.

1. 탐색 및 검증 단계 (Search & Validation)

배치 위치의 그리드를 감지하고, 해당 그리드가 배치 가능한 지역인지(장애물이나 다른 유닛 유무) 검사합니다.

sequenceDiagram
    autonumber
    actor Player
    participant IM as InputManager
    participant IH as InteractionHandler
    participant FGM as FileGridManager
    
    Player->>IM: Drag & Release Unit
    IM->>IH: End Drag Event
    IH->>FGM: GetGrid(Release Position)
    FGM-->>IH: Return Target Grid (New Grid)
    IH->>FGM: Validate Placement (New Grid, No Obstacles)

2. 트랜잭션 확정 단계 (Commit - 검증 성공 시)

검증에 성공하면 기존 그리드의 점유를 해제하고, 새 그리드에 유닛을 정식 등록한 후 스탯(버프) 정보를 동적으로 갱신합니다.

sequenceDiagram
    autonumber
    participant IH as InteractionHandler
    participant FG_Old as Old FileGrid
    participant FG_New as New FileGrid
    participant Unit as File Unit (File_Base)

    Note over IH, Unit: Validation Success (Commit)
    IH->>FG_Old: RemoveFileUnit() (Clear occupant & remove old buffs)
    IH->>FG_New: SetFileUnit(Unit) (Assign occupant & apply new buffs)
    IH->>Unit: Commit Position (Smooth Lerp / Snap)

3. 트랜잭션 복구 단계 (Rollback - 검증 실패 시)

새 그리드가 유효하지 않거나 장애물이 감지된 경우, 상태를 복구하고 유닛을 드래그 시작 전 원래의 그리드 위치로 되돌립니다.

sequenceDiagram
    autonumber
    participant IH as InteractionHandler
    participant Unit as File Unit (File_Base)

    Note over IH, Unit: Validation Fails (Rollback)
    IH->>Unit: Rollback (Return to Old Grid position)

3.3 동적 양방향 좌표 변환 시스템

마우스의 월드 스페이스 좌표와 그리드의 인덱스(Row, Column) 좌표계를 상호 변환하기 위해 오프셋 기반의 연산 로직을 정밀하게 구현했습니다.

3.4 공간 분할 기반 탐색 최적화 (O(1))

마우스를 드래그할 때 가장 가까운 그리드를 찾기 위해 전체 그리드($N \times M$개)를 전수 검사하는 것은 낭비입니다. 이를 극복하기 위해 공간 분할(Spatial Partitioning) 개념을 도입했습니다. 마우스 월드 좌표를 기반으로 연산 $O(1)$ 만에 예상되는 타깃 그리드 인덱스를 수학적으로 산출하고, 해당 인덱스를 중심으로 인접한 3x3 그리드 셀(총 9개)만 가중치(거리 제곱) 계산을 수행하여 탐색 성능을 획기적으로 개선했습니다.

// FileGridManager.cs: 공간 분할 기반 탐색 최적화 로직
public FileGrid GetGrid(Vector2 worldPos) {
    // 1. 월드 좌표를 그리드 인덱스로 수학적 변환 (O(1))
    if (!WorldToGridIndex(worldPos, out int xCenter, out int yCenter)) return null;

    // 2. 인덱스가 유효하면 주변 3x3 영역만 빠르게 검사 (O(1))
    if (IsValidGridIndex(xCenter, yCenter)) {
        return FindClosestGridInRange(worldPos, xCenter, yCenter);
    }

    // 화면 영역 밖의 비정상 예외 상황에서만 전체 탐색 수행 (Safety Net)
    return FindGlobalClosestGrid(worldPos);
}

private FileGrid FindClosestGridInRange(Vector2 worldPos, int centerX, int centerY) {
    float minDistSqr = float.MaxValue;
    FileGrid closestGrid = null;

    // 중심 기준 3x3 루프
    for (int dx = -1; dx <= 1; dx++) {
        for (int dy = -1; dy <= 1; dy++) {
            int x = centerX + dx;
            int y = centerY + dy;

            if (IsValidGridIndex(x, y)) {
                FileGrid candidate = gridArray[x, y];
                // 제곱 거리(sqrMagnitude) 사용으로 비용이 큰 제곱근(Sqrt) 연산 생략
                float distSqr = ((Vector2)candidate.transform.position - worldPos).sqrMagnitude;
                if (distSqr < minDistSqr) {
                    minDistSqr = distSqr;
                    closestGrid = candidate;
                }
            }
        }
    }
    return closestGrid;
}

3.5 플래그 기반 확장 가능한 검색 시스템

그리드를 검색할 때 ‘비어 있는 곳’, ‘장애물이 없는 곳’, ‘이미 아군이 배치된 곳’ 등 다양한 복합 조건을 비트 플래그 형태로 손쉽게 검색할 수 있도록 가변 플래그 검색 시스템을 설계했습니다.

4. 다형성 기반 동적 버프 시스템

4.1 Observer 패턴 기반 버프 자동 전파

파일 유닛이 그리드 상에 배치되거나 이동할 때, 버프 영역을 동적으로 계산하고 전파하기 위해 Observer 패턴 구조를 활용했습니다.

graph TD
    A[Place Unit on Grid] --> B{Is Unit a Buff Source?}
    
    B -->|Yes| C[ApplyBuffActive]
    C -->|Register Aura Area| D[Skill_BuffMain.ApplyBuffArea]
    D -->|For each grid in range| E[Grid.AddBuffSource]
    E -->|If grid has occupant| F[ApplyBuffFromSource]
    F -->|Apply BuffStat| G[Target Unit.ApplyBuff]
    
    B -->|No| H[ApplyGridBuffs]
    H -->|For each source in Grid._activeBuffSources| I[ApplyBuffFromSource]
    I -->|Apply BuffStat| J[Placed Unit.ApplyBuff]

    style C fill:#007bff,stroke:#0056b3,color:#fff
    style H fill:#28a745,stroke:#1e7e34,color:#fff
    style G fill:#17a2b8,stroke:#117a8b,color:#fff
    style J fill:#17a2b8,stroke:#117a8b,color:#fff

• 버프 전파 흐름:
  1. 버프 특성을 가진 파일 유닛(예: .mp3 힐링 버프)이 그리드에 배치되면, 자신의 사거리(Aura Area) 내에 존재하는 모든 주변 FileGrid 셀들을 찾아 자신을 버프 소스로 등록(AddBuffSource(this))합니다.
  2. 이후 새로운 유닛이 해당 버프 영향권 내부의 빈 그리드로 들어올 경우, FileGrid가 즉각 감지하여 보관하고 있던 버프 데이터 목록(_activeBuffSources)을 진입한 유닛에게 자동으로 갱신/적용(ApplyBuffFromSource)합니다.
  3. 버프 유닛이 죽거나 이동하면, 영향권 내의 모든 그리드에서 버프 소스를 제거(RemoveBuffSource)하고 즉시 피적용 유닛의 스탯을 원복시킵니다.

4.2 다형성을 활용한 틱(Tick) 기반 버프 아키텍처

단순 스탯 증가 버프 외에도 주기적인 리젠(HP 회복), 지속 피해(도트 데미지) 등을 단일 코루틴 남발 없이 처리하기 위해 MyBuff 추상 클래스와 BuffData 구조를 결합한 중앙 업데이트 방식을 채택했습니다.

// BuffData_Base.cs: 다형적 버프 업데이트 루프
public virtual void Tick(float deltaTime) {
    // 딕셔너리 순회 중 요소 삭제 에러 방지를 위해 복사본 리스트로 순회
    foreach (int key in new List<int>(activeBuffs.Keys)) {
        // BuffData 내부에서 누적 시간을 체크하여 틱 주기 도달 시 true 반환
        if (activeBuffs[key].Tick(deltaTime)) {
            OnTick(activeBuffs[key]); // 다형성에 의해 상속받은 자식 클래스의 고유 로직 실행
        }
    }
}

// Buff_MP3.cs: 구체적인 힐링(HP 지속 회복) 버프 클래스 구현
public class Buff_MP3 : MyBuff {
    public override void Init(Transform _target) {
        buffTarget = _target;
        buffParticleType = Define.ParticleType.Buff_MP3;
    }

    protected override void OnTick(BuffData buffData) {
        // 대상 오브젝트의 IHealth 인터페이스를 찾아 체력 회복
        var health = buffTarget.GetComponent<IHealth>();
        if (health != null) {
            health.Heal(buffData.Amount);
        }
    }
}

5. 전체 시스템 기술적 특징 요약

• 성능 최적화 (Optimization): UI 구조에서 물리 공간 오브젝트 구조로 전면 교체하여 Canvas Rebuilding 부하를 0으로 격리시켰으며, 마우스 드래그 시 인접 3x3 영역만 거리를 탐색하는 공간 분할 알고리즘으로 불필요한 연산을 대폭 감축했습니다.
• 지능형 상호작용 (Mediator Pattern): 개별 유닛의 업데이트 루프에 의존하지 않는 중앙 집중식 InputManager를 구축하고 렌더링 우선순위 판정을 수식화하여, 깔끔하게 설계된 IInteractable 객체 이벤트 구조를 실현했습니다.
• 데이터 무결성 (Transaction-Safe): 배치 취소, 배치 위치 이동, 장애물 충돌 등으로 발생 가능한 데이터 오차를 예방하기 위해 사전 예외 검증과 배치 롤백이 보장되는 원자적 배치 단계를 구현했습니다.
• 유연한 확장성 (Extensibility): 비트 필터링 느낌의 플래그 기반 그리드 검색 시스템과 다형성 버프 구조를 구현하여, 향후 새로운 유닛 유형이나 기믹이 추가되더라도 기존 코드를 크게 수정하지 않고 확장할 수 있는 견고한 OOP 기반 아키텍처를 확보했습니다.

기술적 성과: 윈도우 바탕화면의 파일 정렬 및 압축(Folder ZIP) 등의 조작 감성을 유니티 엔진 상에서 고성능으로 재해석하였으며, 대규모 유닛과 바이러스가 중첩되는 난전 상황 속에서도 지속적인 60 FPS 이상을 안정적으로 방어하는 고품질 인디 게임 코어 시스템을 완성했습니다.

Slime Project는 하드코어 액션 퍼즐 플랫포머 게임으로, FiniteStateMachine(FSM) 기반 상태 관리 시스템을 통해 모든 게임 엔티티의 행동을 체계적으로 관리합니다. 플레이어 슬라임의 움직임, 변신 능력, 그리고 변신 시 능력 변화를 구현했으며, 보스 몬스터와 일반 몬스터의 AI 로직을 담당하여 확장 가능한 게임 시스템을 구축했습니다.

1. 프로젝트 개요

본 프로젝트는 복잡한 게임 로직을 디자인 패턴을 활용해 구조화하는 데 집중했습니다. 모든 캐릭터와 몬스터는 통일된 인터페이스를 공유하며, 기능 중심의 컴포지션 설계를 통해 유지보수성을 극대화했습니다.

2. FiniteStateMachine 기반 상태 관리 시스템

모든 몬스터와 게임 엔티티의 행동을 FiniteStateMachine 패턴으로 관리하는 시스템을 구현했습니다. State 베이스 클래스를 통해 각 상태의 Enter/Exit/LogicUpdate/PhysicsUpdate 라이프사이클을 체계적으로 관리합니다.

2.1 상태머신 구조 및 전환 플로우

FiniteStateMachine은 현재 상태를 관리하고, 상태 전환 시 이전 상태의 Exit와 새 상태의 Enter를 자동으로 호출하여 물리 및 애니메이션 상태의 정합성을 보장합니다.

상태머신 핵심 로직 상태머신 초기화 및 안전한 상태 전환을 보장하는 핵심 로직입니다.

// FiniteStateMachine.cs: 상태머신 핵심 로직
public class FiniteStateMachine
{
    public State currentState { get; private set; } 

    // 상태머신 초기화: 시작 상태 설정 및 Enter() 호출
    public void Init(State startingState) 
    {
        currentState = startingState;     // 현재 상태 설정
        currentState.Enter();             // 시작 상태 진입
    }

    // 상태 전환: 이전 상태 종료 후 새 상태 진입
    public void ChangeState(State newState) 
    {
        currentState.Exit();                // 이전 상태 종료
        currentState = newState;            // 새 상태로 전환
        currentState.Enter();               // 새 상태 진입
    }
}

2.2 State 베이스 클래스

모든 상태는 State 베이스 클래스를 상속받아 구현됩니다. 각 상태는 애니메이션 파라미터 제어와 상태 시작 시간 기록 등을 자동으로 처리합니다.

// State.cs: 모든 상태의 베이스 클래스
public class State
{
    protected FiniteStateMachine stateMachine;  // 상태머신 참조
    protected Entity entity;                    // 엔티티 참조
    protected float startTime;                  // 상태 시작 시간
    protected string animBoolName;              // 애니메이션 파라미터 이름

    public virtual void Enter()                     // 상태 진입 시 호출
    {
        startTime = Time.time;                      // 시작 시간 기록
        entity.anim.SetBool(animBoolName, true);    // 애니메이션 트리거
        DoChecks();                                 // 상태 전환 조건 확인
    }
    
    public virtual void Exit()                     // 상태 종료 시 호출
    {
        entity.anim.SetBool(animBoolName, false);   // 애니메이션 종료
    }
    
    public virtual void LogicUpdate()         // Update()에서 호출
    {
    }
    
    public virtual void PhysicsUpdate()      // FixedUpdate()에서 호출
    {
        DoChecks();                                 // 물리 업데이트마다 조건 확인
    }

    public virtual void DoChecks()          // 상태 전환 조건 확인
    {
        // 플레이어 감지, 벽/절벽 감지 등
    }
}

3. 플레이어 슬라임 및 변신 시스템

플레이어 슬라임의 움직임, 공격, 대시, 피격 처리를 구현했습니다. 컴포지션 패턴을 활용하여 각 기능을 독립적인 클래스로 분리하고, Player_Slime에서 통합 관리합니다.

3.1 시스템 구조 (Composition Pattern)

Player_Slime은 모든 컴포넌트의 허브 역할을 수행하며, 각 기능 모듈은 자신의 도메인 로직에 집중합니다.

3.2 변신 능력 시스템

플레이어가 몬스터를 처치하면 해당 몬스터의 형태로 변신할 수 있습니다. 변신 시 각 형태의 고유 능력을 사용할 수 있으며, Player_FormMovement를 통해 특수 이동 로직이 활성화됩니다.

• 슬라임 (기본): 원거리 포물선 공격, 대시 무적 프레임 활용.
• 토끼 (변신): 더블 점프 및 벽 점프 능력 획득. Rabbit_ability와 연동하여 벽 점프 중 조작 제한 물리 로직 적용.

// Player_Slime.cs: 플레이어 슬라임 메인 클래스
public class Player_Slime : Player_Entity
{
    public Player_SlimeMovement movement { get; private set; }
    public Player_Attack attack { get; private set; }
    public Player_Dash dash { get; private set; }

    protected override void Start()
    {
        base.Start();
        // 각 기능 컴포넌트 초기화 (Composition)
        movement = new Player_SlimeMovement(this, movementData, this);
        attack = new Player_Attack(this, attackData, meleePos);
        dash = new Player_Dash(this, dashData);
    }
}

4. 보스 및 일반 몬스터 AI 시스템

보스 몬스터의 스킬 시스템을 델리게이트 기반으로 구현하여 확장 가능한 AI를 설계했습니다. HP 단계에 따라 스킬이 업그레이드되며, 거리와 상황에 따라 지능적인 패턴을 생성합니다.

4.1 보스 AI 의사결정 및 스킬 시스템

보스는 매 업데이트마다 플레이어와의 거리를 산출하고, 델리게이트 배열에 등록된 스킬 풀(Pool)에서 최적의 패턴을 선택하여 실행합니다.

// MainBossBear.cs: 보스 스킬 시스템
public class MainBossBear : BossBearSetting
{
    private delegate void BossBear_SkillAction();
    private BossBear_SkillAction[] BossBear_Skills;

    public bool IsSkillUpgrade; // HP 단계 플래그

    public override void Start()
    {
        base.Start();
        // 델리게이트 배열에 메서드 직접 할당
        BossBear_Skills = new BossBear_SkillAction[4] { Rest, Smash, Dash, Rumbling };
    }

    private void RandomBossBearSkillState()
    {
        int RandomSkill_Index = Random.Range((int)BossBear_SkillEnum.Smash, (int)BossBear_SkillEnum.Skill_Max);
        // 선택된 스킬 메서드 대리 호출
        BossBear_Skills[RandomSkill_Index].Invoke();
    }
}

4.2 일반 몬스터 AI 확장 사례

일반 몬스터들은 공통의 Enemy_State를 상속받아 고유한 행동 패턴을 가집니다.

• Bear (돌진형): DashState를 통한 강력한 물리 충격 기반 공격.
• Spider (매복형): JumpState를 활용한 공중 도약 및 플레이어 타겟팅 낙하 공격.
• Ant (기본형): 정형화된 순찰 및 근접 공격 루틴 수행.

5. 기술적 성과 요약

• FSM 아키텍처: Enter/Exit 라이프사이클 관리를 통해 복잡한 상태 전이 시 발생할 수 있는 버그를 근본적으로 차단.
• 컴포지션 기반 확장성: 플레이어 기능을 모듈화하여 새로운 변신 형태나 능력을 추가할 때 기존 코드 수정을 최소화.
• 델리게이트 기반 AI: 보스의 스킬 패턴을 인덱스 기반으로 관리하여 패턴 추가 및 확률 조정의 유연성 확보.
• 물리/애니메이션 동기화: LogicUpdate와 PhysicsUpdate를 분리하여 프레임 드랍 환경에서도 일관된 충돌 판정 및 움직임 보장.

Conclusion: Slime Project는 디자인 패턴을 실무에 어떻게 적용하여 대규모 게임 로직을 관리할 수 있는지에 대한 깊은 고민이 담긴 프로젝트입니다. FSM과 컴포지션을 통해 복잡한 액션 퍼즐의 메커니즘을 견고하게 구현해냈습니다.

게임 엔진에 의존하지 않고 C++와 WinAPI만을 이용해 완전 밑바닥부터 게임을 구축하는 데 도전한 프로젝트입니다. 게임 엔진의 추상화된 기능 뒤에 숨겨진 전체적인 실행 파이프라인을 깊이 있게 이해하고 스스로 설계해보고자 시작하였으며, 기존 게임인 ‘Don’t Starve’의 핵심 시스템을 참고하여 제작했습니다.

1. 주요 시스템 아키텍처

1.1 컴포넌트 기반 객체 설계 (Component-Based)

단일 상속의 복잡성을 피하고 객체 지향적인 유연성을 극대화하기 위해 컴포넌트 기반 구조를 채택했습니다. 모든 게임 객체(GameObject)는 기능 단위의 컴포넌트를 소유하며, 실행 시점에 필요한 기능을 동적으로 탈부착할 수 있습니다.

이러한 구조를 통해 새로운 객체를 생성할 때 상속 계층에 얽매이지 않고 유연하게 기능을 조립할 수 있습니다.

// GameObject.h - 컴포넌트 추가 및 획득 핵심 로직
template <typename T, typename... Args>
T* AddComponent(Args&&... args) {
    auto newComponent = std::make_unique<T>(this, std::forward<Args>(args)...);
    T* componentPtr = newComponent.get();
    m_components.push_back(std::move(newComponent));
    return componentPtr;
}

template <typename T>
T* GetComponent() const {
    for (const auto& component : m_components) {
        if (!component) continue;
        T* target = dynamic_cast<T*>(component.get());
        if (target) return target;
    }
    return nullptr;
}

1.2 중앙 집중식 매니저 패턴 (Singleton Managers)

시스템의 전역적인 상태 관리와 자원 공유를 위해 싱글톤 기반 매니저들을 구축했습니다.

2. 렌더링 시스템 및 파이프라인

GDI+ 환경에서 대규모 오브젝트를 효율적으로 출력하기 위해 커맨드 패턴 기반의 렌더링 파이프라인을 구축했습니다. 매 프레임 모든 객체를 즉시 그리는 대신, 렌더링 명령을 레이어별로 수집하고 정렬한 뒤 일괄 실행(Flush)하는 방식을 취합니다.

2.1 렌더링 파이프라인 흐름

렌더링 프로세스는 크게 제출(Submission) -> 정렬(Sorting) -> 실행(Execution)의 3단계로 구성됩니다.

Top-down 뷰의 입체감을 위해 객체의 발밑(Pivot) 위치의 Y 좌표를 기준으로 정렬하여 출력함으로써 오브젝트 간의 앞뒤 관계를 정확히 표현합니다.

// RenderManager.cpp - Y-Sorting 및 일괄 렌더링 처리
void RenderManager::Flush(Gdiplus::Graphics* pGraphics)
{
    if (!pGraphics) return;

    for (int i = LAYER_TILE_BACKGROUND; i < LAYER_COUNT; ++i) {
        if (m_layerCommands[i].empty()) continue;

        // zOrder(Y좌표)를 기준으로 오름차순 정렬하여 뒤에 있는 객체가 먼저 그려지도록 함
        if (m_layerCommands[i].size() > 1) {
            std::stable_sort(m_layerCommands[i].begin(), m_layerCommands[i].end(), [](const DrawCommand& a, const DrawCommand& b) {
                if (a.zOrder != b.zOrder) return a.zOrder < b.zOrder;
                return a.layer < b.layer;
            });
        }

        for (const auto& cmd : m_layerCommands[i]) {
            ExecuteDrawCommand(pGraphics, cmd);
        }
        m_layerCommands[i].clear();
    }
}

2.2 동적 타일 캐싱 및 가시 영역 렌더링

광활한 맵 전체를 그리는 부하를 막기 위해, 카메라의 뷰포트에 해당하는 타일만 선택적으로 렌더링합니다. 특히 타일 비트맵을 매번 로드하지 않고 동적 캐싱 시스템을 통해 메모리 효율을 극대화했습니다.

// CameraManager.cpp - 그리드 기반 타일 컬링 및 캐싱
void CameraManager::RenderVisibleTiles(const MapData* mapData) {
    if (!mapData) return;
    Gdiplus::RectF vp = GetViewportWorldRect();

    // 256px 그리드 단위로 가시 범위 인덱스 계산
    const int gridCellSize = 256;
    int sx = std::max(0, (int)floor(vp.X / gridCellSize)) * (gridCellSize / TILE_SIZE);
    int ex = std::min(MAP_WIDTH, (int)ceil((vp.X + vp.Width) / gridCellSize) * (gridCellSize / TILE_SIZE));
    // ... (Y 인덱스 생략)

    // 가시 영역 변경 시에만 미사용 캐시 정리
    if (sx != m_lastStartTileX || ex != m_lastEndTileX || ...) {
        CleanupUnusedTileCache(mapData, sx, ex, sy, ey);
    }

    for (int y = sy; y < ey; ++y) {
        for (int x = sx; x < ex; ++x) {
            auto& tileData = mapData->tiles[x][y];
            // 캐시 확인 및 RenderManager에 명령 제출
            Gdiplus::Bitmap* bm = GetOrLoadTileBitmap(tileData.id);
            RenderManager::GetInstance()->AddWorldObjectCommand(bm, ...);
        }
    }
}

3. 최적화 및 핵심 기술

3.1 공간 분할 기법: 그리드 기반 컬링 (Grid-based Culling)

월드에 수천 개의 오브젝트가 존재할 때, 모든 객체에 대해 매 프레임 업데이트와 충돌 검사(Brute-force, O(N))를 수행하면 심각한 성능 저하가 발생합니다. 이를 방지하기 위해 맵 전체를 256x256 픽셀 크기의 정적 2D 그리드 배열(Spatial Partitioning)로 분할했습니다.

3.1.1 쿼리 스탬프를 활용한 중복 검사 방지

크기가 큰 오브젝트는 여러 개의 그리드 셀에 걸쳐 존재할 수 있습니다. 뷰포트 영역 내의 셀들을 순회할 때 동일한 객체가 여러 번 쿼리되는 것을 막기 위해 쿼리 스탬프(Query Stamp) 기법을 도입했습니다. 쿼리가 발생할 때마다 전역 스탬프 값을 1씩 증가시키고, 이미 검사한 객체에 스탬프를 남겨 불필요한 중복 연산을 완전히 제거했습니다.

// ObjectManager.cpp - 뷰포트 기반 공간 분할 쿼리
void ObjectManager::QueryObjectsInRectArea(const Gdiplus::RectF& rectArea, std::vector<GameObject*>& targetOutObjects)
{
    // 월드 좌표를 셀 크기로 나누어 O(1)로 배열 인덱스 획득
    int startX = (int)floor(rectArea.X / GRID_CELL_SIZE);
    int startY = (int)floor(rectArea.Y / GRID_CELL_SIZE);
    int endX = (int)ceil((rectArea.X + rectArea.Width) / GRID_CELL_SIZE) - 1;
    int endY = (int)ceil((rectArea.Y + rectArea.Height) / GRID_CELL_SIZE) - 1;
    
    // ... 인덱스 클램핑 생략 ...

    // 매 쿼리마다 전역 스탬프 갱신
    if (++m_spatialQueryStamp == 0) m_spatialQueryStamp = 1;

    for (int y = startY; y <= endY; ++y) {
        for (int x = startX; x <= endX; ++x) {
            for (auto* obj : m_spatialGrid[x][y]) {
                // 이미 이번 프레임(쿼리)에서 처리된 객체는 O(1) 스킵
                if (obj->GetLastSpatialQueryStamp() == m_spatialQueryStamp) continue;
                obj->SetLastSpatialQueryStamp(m_spatialQueryStamp);

                if (!obj->IsEnabled() || obj->IsDead()) continue;

                // 해당 셀에 속한 객체만 AABB 교차 정밀 검사 수행
                if (rectArea.IntersectsWith(obj->GetBounds())) {
                    targetOutObjects.push_back(obj);
                }
            }
        }
    }
}

3.1.2 동적 오브젝트의 그리드 이동 처리

플레이어나 몬스터처럼 실시간으로 좌표가 변하는 동적 객체들은 이동할 때마다 자신이 속한 그리드 셀을 갱신해야 합니다. UpdateObjectGrid 메서드는 객체의 위치가 셀의 경계를 넘어갔을 때만 이전 벡터 배열에서 객체를 erase하고 새 배열에 push_back하여 갱신 비용을 최소화합니다.

// ObjectManager.cpp - 객체 이동 시 그리드 셀 갱신
void ObjectManager::UpdateObjectGrid(GameObject* pObj)
{
    if (!pObj || pObj->GetType() == GO_TYPE_UI) return;

    int oldX = pObj->GetGridCellX();
    int oldY = pObj->GetGridCellY();

    Gdiplus::RectF bounds = pObj->GetBounds();
    int newX = (std::max)(0, (std::min)(GRID_WIDTH - 1, (int)floor((bounds.X + bounds.Width * 0.5f) / GRID_CELL_SIZE)));
    int newY = (std::max)(0, (std::min)(GRID_HEIGHT - 1, (int)floor((bounds.Y + bounds.Height * 0.5f) / GRID_CELL_SIZE)));

    // 속한 셀이 변경된 경우에만 이동 처리
    if (oldX == newX && oldY == newY) return;

    if (oldX >= 0 && oldX < GRID_WIDTH && oldY >= 0 && oldY < GRID_HEIGHT) {
        std::vector<GameObject*>& cell = m_spatialGrid[oldX][oldY];
        cell.erase(std::remove(cell.begin(), cell.end(), pObj), cell.end());
    }

    m_spatialGrid[newX][newY].push_back(pObj);
    pObj->SetGridCell(newX, newY);
}

3.1.3 오브젝트 그리드 추가/제거 및 선언 구조 (Spatial Lifecycle Management)

오브젝트가 새로 생성되거나 소멸할 때, 해당 오브젝트를 그리드 시스템에 안전하게 등록하고 지워주는 과정이 필수적입니다. 또한, 월드의 크기와 타일 크기에 맞추어 그리드의 너비와 높이를 런타임 최적화를 위해 상수로 정의했습니다.

// ObjectManager.h - 공간 분할 시스템의 선언부
class ObjectManager {
public:
    void UpdateObjectGrid(GameObject* pObj);
    void AddToGrid(GameObject* pObj);
    void RemoveFromGrid(GameObject* pObj);

private:
    // 256px 정사각형 셀 기준의 정적 그리드 크기 정의
    static constexpr int GRID_CELL_SIZE = 256;
    static constexpr int GRID_WIDTH = (MAP_WIDTH * TILE_SIZE / GRID_CELL_SIZE) + 2;
    static constexpr int GRID_HEIGHT = (MAP_HEIGHT * TILE_SIZE / GRID_CELL_SIZE) + 2;

    // 2D 공간 분할 그리드 (각 셀마다 속한 오브젝트 포인터 벡터 관리)
    std::vector<GameObject*> m_spatialGrid[GRID_WIDTH][GRID_HEIGHT];
    uint32_t m_spatialQueryStamp = 1;
};

// ObjectManager.cpp - 객체 생성 시 그리드 등록
void ObjectManager::AddToGrid(GameObject* pObj)
{
    if (!pObj || pObj->GetType() == GO_TYPE_UI) return;

    Gdiplus::RectF bounds = pObj->GetBounds();
    int x = (int)floor((bounds.X + bounds.Width * 0.5f) / GRID_CELL_SIZE);
    int y = (int)floor((bounds.Y + bounds.Height * 0.5f) / GRID_CELL_SIZE);

    x = (std::max<int>)(0, (std::min<int>)(GRID_WIDTH - 1, x));
    y = (std::max<int>)(0, (std::min<int>)(GRID_HEIGHT - 1, y));

    m_spatialGrid[x][y].push_back(pObj);
    pObj->SetGridCell(x, y);
}

// ObjectManager.cpp - 객체 소멸 시 그리드 제거
void ObjectManager::RemoveFromGrid(GameObject* pObj)
{
    if (!pObj) return;
    int x = pObj->GetGridCellX();
    int y = pObj->GetGridCellY();

    if (x >= 0 && x < GRID_WIDTH && y >= 0 && y < GRID_HEIGHT) {
        std::vector<GameObject*>& cell = m_spatialGrid[x][y];
        cell.erase(std::remove(cell.begin(), cell.end(), pObj), cell.end());
        pObj->SetGridCell(-1, -1);
    }
}

4. 애니메이션 시스템 및 이벤트 콜백

Animator와 AnimationClip을 분리하여 고도로 제어 가능한 프레임 기반 애니메이션 시스템을 구축했습니다. 특히, 애니메이션의 시각적 흐름과 게임의 논리적 흐름(데미지 판정, 사운드 재생 등)을 일치시키기 위해 프레임 이벤트 콜백(Frame Event Callback) 시스템을 도입했습니다.

4.1 클립 분리 및 프레임 진행

하나의 SpriteSheet에서 특정 프레임들을 잘라내어 AnimationClip 객체를 생성합니다. Animator는 현재 재생 중인 클립의 경과 시간(m_elapsed)을 바탕으로 현재 출력해야 할 프레임 인덱스를 계산합니다.

4.2 프레임 이벤트 검사 및 콜백 실행

프레임 델타 타임에 의해 여러 프레임을 한 번에 건너뛰더라도(Frame Skip), 이벤트가 누락되지 않도록 m_lastTriggeredFrame부터 currentFrameIndex까지 반복문을 돌며 등록된 모든 이벤트를 순차적으로 실행합니다.

// Animator.cpp - 프레임 이벤트 처리 로직
if (currentFrameIndex != -1 && currentFrameIndex != m_lastTriggeredFrame)
{
    const std::map<int, std::wstring>& eventFrames = m_currentClip->GetEventFrames();
    const AnimationEventCallback& callback = m_currentClip->GetEventCallback();

    AnimationClip* pCurrentClipBeforeCallback = m_currentClip;

    // 건너뛴 프레임(startIdx)부터 현재 프레임(endIdx)까지 모두 검사하여 누락 방지
    for (int fi = m_lastTriggeredFrame + 1; fi <= currentFrameIndex && callback; ++fi ) {
        auto eventIt = eventFrames.find(fi);
        if (eventIt != eventFrames.end())
        {
            callback(fi, eventIt->second); // 등록된 콜백 실행 (공격 판정, 사운드 등)

            // 콜백 내부의 로직(예: 사망, 피격)으로 인해 애니메이션 상태가 변경되었다면 즉시 루프 중단
            if (pCurrentClipBeforeCallback != m_currentClip) {
                return;
            }
        }
    }
    m_lastTriggeredFrame = currentFrameIndex;
}

4.3 람다 캡처를 활용한 이벤트 바인딩

객체(Player 등) 초기화 시점에 RegisterAnimation을 통해 클립을 생성하고, 특정 프레임 번호에 이벤트 문자열(eventName)을 등록합니다. 이후 람다 함수를 통해 콜백을 바인딩하여 직관적으로 로직을 구성했습니다.

// Player.cpp - 도끼질 애니메이션 설정 및 이벤트 콜백 바인딩
const int CHOP_HIT_FRAME = 4; // 도끼가 나무에 맞는 프레임

// 클립에 이벤트 프레임 등록
AnimationClip* clip = m_animator->GetAnimationClip((int)PlayerState::CHOP, dir);
if (clip) {
    clip->AddEventFrame(CHOP_HIT_FRAME, L"chop_hit");
    clip->AddEventFrame(CHOP_LAST_FRAME, L"chop_end");

    // 이벤트 콜백 람다 바인딩
    clip->SetEventCallback([this](int frameIndex, const std::wstring& eventName) {
        if (eventName == L"chop_hit") {
            SoundManager::GetInstance()->PlaySFX(L"Resource/Sound/PlayerSound/Chop_tree.wav");
            this->OnChopHit(); // 타겟 나무에 데미지 적용
        }
        else if (eventName == L"chop_end") {
            this->OnChopEnd(); // 상태 전이
        }
    });
}

5. 데이터 로드 및 게임 진행 정보 저장

하드코딩을 배제하고 유지보수성을 높이기 위해 게임의 거의 모든 요소를 데이터 주도(Data-Driven) 방식으로 설계했습니다. 맵 배치부터 오브젝트의 고유 속성, 그리고 플레이어의 진행 상황까지 파일 기반으로 관리됩니다.

5.1 커스텀 맵 포맷(.dsm) 파싱 시스템

자체 제작한 맵 에디터에서 출력되는 .dsm (Don’t Starve Map) 포맷을 파싱하여 게임 씬을 초기화합니다. 이 파일에는 맵의 메타데이터, 타일 정보, 이동 가능 구역(Walkable Area), 그리고 오브젝트의 배치 좌표가 포함됩니다.

// Function.h - 맵 파일 파싱 로직 일부
template<typename GetObjectResourceInfoFunc>
inline bool ParseMapFileInto(const std::wstring& mapFileName, MapData& outMapData, GetObjectResourceInfoFunc getObjectResourceInfo)
{
    std::wifstream file(mapFileName);
    if (!file.is_open()) return false;
    
    // ... BOM 처리 생략 ...

    std::wstring line;
    enum Section { NONE, METADATA, PLAYER, TILES, OBJECTS, WALKABLE } section = NONE;

    while (std::getline(file, line)) {
        if (line.empty() || line[0] == L'#') {
            if (line.find(L"# TILES") != std::wstring::npos) section = TILES;
            else if (line.find(L"# OBJECTS") != std::wstring::npos) section = OBJECTS;
            // ... 섹션 분기 ...
            continue;
        }

        // 오브젝트 배치 정보 파싱
        if (section == OBJECTS) {
            std::wstringstream ss(line);
            std::wstring id, x, y;
            if (std::getline(ss, id, L',') && std::getline(ss, x, L',') && std::getline(ss, y, L',')) {
                
                GameObjectID objID = EnumTables::GetGameObjectID(id.c_str());
                if (objID != GOID_NONE) {
                    ResourcePathUtils::ObjectResourceDef objData;
                    objData.id = objID;
                    objData.x = std::stof(x);
                    objData.y = std::stof(y);
                    outMapData.gameObjects.push_back(objData);
                }
            }
        }
    }
    file.close();
    return true;
}

5.2 동적 속성 덮어쓰기 (Object Overrides)

맵 파싱 과정에서 생성될 오브젝트들의 크기, 콜라이더 정보, 피벗 좌표 등은 소스 코드를 수정하지 않고 텍스트 파일(object_resource_overrides.txt)을 수정하여 즉시 게임에 반영할 수 있습니다. DataManager가 게임 초기화 시점에 이 파일을 읽어 기본값을 덮어씌웁니다.

// DataManager.cpp - 오브젝트 리소스 및 콜라이더 데이터 오버라이드
void DataManager::Init()
{
    // ... 정적 테이블 초기화 생략 ...

    ResourcePathUtils::ParseObjectResourceOverridesFile(L"GameData/object_resource_overrides.txt",
        [this](GameObjectID id, const ResourcePathUtils::ObjectResourceDef& overrideDef) {
            auto it = m_objectResources.find(id);
            if (it != m_objectResources.end()) {
                // 텍스트 파일에 정의된 값을 실제 게임 데이터 딕셔너리에 덮어씌움
                it->second.pivotX = overrideDef.pivotX;
                it->second.pivotY = overrideDef.pivotY;
                it->second.hasCollider = overrideDef.hasCollider;
                it->second.colliderWidth = overrideDef.colliderWidth;
                it->second.colliderHeight = overrideDef.colliderHeight;
                // ...
            }
        });
}

5.3 스냅샷 기반 씬(Scene) 상태 보존

게임 플레이 도중 씬을 이동(포탈 이용 등)할 때, 플레이어의 현재 체력과 인벤토리 상태를 유지해야 합니다. GameProgressManager는 씬 전환 직전에 PlayerStateSnapshot 구조체를 이용해 플레이어의 상태를 캡처하고, 새로운 씬이 로드된 직후 RestoreState 함수를 통해 완벽하게 복원합니다.

// Player.cpp - 상태 캡처 (씬 전환용)
PlayerStateSnapshot Player::SaveState() const
{
    PlayerStateSnapshot snapshot;
    snapshot.hp = m_hp;
    snapshot.equippedSlotIndex = m_equippedSlotIndex;

    if (m_inventory) {
        snapshot.inventoryItems = m_inventory->GetAllItemsSnapshot();
    }
    return snapshot;
}

// Player.cpp - 상태 복원
void Player::RestoreState(const PlayerStateSnapshot& snapshot)
{
    m_hp = snapshot.hp;
    
    if (m_inventory) {
        m_inventory->ClearAllItems();
        for (const auto& item : snapshot.inventoryItems) {
            m_inventory->AddItem(item.first, item.second);
        }
    }

    if (snapshot.equippedSlotIndex >= 0) {
        ToggleEquipItem(snapshot.equippedSlotIndex);
    }
}

또한, 특정 보스를 클리어했을 때 신규 캐릭터가 해금되는 요소는 game_progress.txt에 문자열 포맷(CHARACTER:1002,UNLOCKED:1)으로 디스크에 영구 저장되어 다음 실행 시에도 로드됩니다.

5.4 영구적인 게임 진행도 저장 (Save/Load)

보스를 클리어하여 캐릭터가 해금되는 등의 영구적인 게임 진행 상황은 GameProgressManager를 통해 파일(game_progress.txt) 시스템에 기록됩니다. 파일 입출력을 통해 진행도를 파싱하고 직렬화하여 데이터를 안전하게 보존합니다.

// GameProgressManager.cpp - 캐릭터 해금 정보 저장 및 로드
void GameProgressManager::SaveToFile(const std::wstring& filePath)
{
    // ... 디렉토리 생성 로직 생략 ...
    std::wofstream file(filePath);
    if (!file.is_open()) return;
    
    for (const auto& charInfo : m_gameProgress.characterUnlockInfos)
    {
        file << L"CHARACTER:" << (int)charInfo.characterID
             << L",UNLOCKED:" << (charInfo.isUnlocked ? 1 : 0) << L"\n";
    }
    file.close();
}

void GameProgressManager::LoadFromFile(const std::wstring& filePath)
{
    std::wifstream file(filePath);
    if (!file.is_open()) return;
    
    std::wstring line;
    while (std::getline(file, line))
    {
        if (line.empty() || line[0] == L'#' || line[0] == L'[') continue;
        
        if (line.find(L"CHARACTER:") == 0) {
            ParseCharacterLine(line); // 문자열을 파싱하여 해금 데이터 배열 업데이트
        }
    }
    file.close();
}

void GameProgressManager::ParseCharacterLine(const std::wstring& line)
{
    size_t charPos = line.find(L"CHARACTER:") + 10;
    size_t unlockedPos = line.find(L",UNLOCKED:") + 10;
    
    int characterID = std::stoi(line.substr(charPos, line.find(L',', charPos) - charPos));
    int unlocked = std::stoi(line.substr(unlockedPos));
    
    for (auto& charInfo : m_gameProgress.characterUnlockInfos) {
        if ((int)charInfo.characterID == characterID) {
            if (unlocked == 1) charInfo.isUnlocked = true;
            break;
        }
    }
}

Conclusion: WINAPI_DONT_STARVE는 저수준의 WinAPI 환경에서도 고성능 아키텍처와 공간 최적화 기법을 통해 대규모 오브젝트 시스템을 안정적으로 구현해냈습니다.

서버(구글 스프레드시트) 기반 게임 데이터 관리와, Seed/Token을 활용한 완벽한 상태 복원 시스템입니다. 리플렉션을 통한 동적 파싱과 비동기 로딩 시스템을 통해 유지보수성과 유저 경험을 동시에 확보했습니다.

1. 리플렉션 기반 CSV 파싱 및 버전 관리 시스템

서버에서 다운로드한 CSV 파일의 헤더와 데이터 클래스의 필드를 자동으로 매핑하여 동적으로 파싱하는 시스템을 구현했습니다. 리플렉션(Reflection)을 활용하여 타입 안전성을 보장하면서도 확장 가능한 파싱 로직을 설계했습니다.

1.1 서버 버전 동기화 및 선택적 다운로드

게임 시작 시 ServerCSV_ConvertData 클래스가 메타 시트를 우선 다운로드하여 서버의 데이터 버전 정보를 확인합니다. 이후 로컬에 저장된 data_versions.json 파일과 대조하여 변경된 파일만 선택적으로 다운로드함으로써 네트워크 비용과 로딩 시간을 최소화했습니다.

1.2 CSV 파싱 프로세스 플로우

다운로드 된 데이터 파싱은 다음과 같은 4단계로 진행됩니다:

1.3 핵심 파싱 로직 및 SmartSplit

제네릭 메서드를 사용하여 타입에 독립적인 파싱을 수행합니다. 특히, CSV 내부의 쉼표(,)를 포함하는 문자열(“이름, 설명”)을 안전하게 처리하기 위해 정규식을 활용한 SmartSplit 함수를 구현했습니다.

CSV 파싱 핵심 로직 및 SmartSplit 정규식을 활용하여 따옴표 내부의 쉼표를 안전하게 처리하고, 리플렉션을 통해 동적으로 객체에 값을 할당합니다.

// CSVParser.cs: 정규식을 이용한 안전한 CSV 행 분할
string[] SmartSplit(string line)
{
    return Regex.Matches(line, @"(?:^|,)(?:""(?<val>[^""]*)""|(?<val>[^,""]*))")
                .Cast<Match>()
                .Select(m => m.Groups["val"].Value)
                .ToArray();
}

// 리플렉션 기반 CSV 파싱 핵심 메서드
public List<T> parseCSV<T>(string csvData, bool isCutColumn, int start, int end) where T : BaseData, new()
{
    // 1. 제네릭 타입 T의 구조 분석
    Type myType = typeof(T);
    FieldInfo[] myFieldInfo = myType.GetFields(BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Public | BindingFlags.Static);

    string[] csvIndexData = csvData.Split('\n').Where(x => !string.IsNullOrWhiteSpace(x)).ToArray();
    if (csvIndexData.Length == 0) return null;

    // 2. 헤더 매핑 딕셔너리 세팅
    string[] attributeColumnArray = csvIndexData[0].Trim().Split(',');
    SetupFieldDict(attributeColumnArray, myFieldInfo);

    List<T> csvDataList = new List<T>();
    // 3. 데이터 행 순회 및 파싱
    for (int rowIndex = 1; rowIndex < csvIndexData.Length; rowIndex++)
    {
        string[] column = SmartSplit(csvIndexData[rowIndex].Trim());
        if (column.Length == 0 || string.IsNullOrWhiteSpace(column[0])) continue;

        T objectData = Activator.CreateInstance<T>();
        
        // 4. 타입 변환 및 할당
        for (int i = 0; i < column.Length; i++)
        {
            if (DataIndex_Dict.TryGetValue(i, out string attribute) && Data_Dict.TryGetValue(attribute, out string fieldName))
            {
                FieldInfo fieldInfo = myType.GetField(fieldName);
                if (fieldInfo != null)
                {
                    SetFieldValue(objectData, fieldInfo, column[i]); // ChangeType 수행
                }
            }
        }
        csvDataList.Add(objectData);
    }
    return csvDataList;
}

2. 비동기 로딩 및 UI 블로킹 방지

방대한 CSV 데이터와 복잡한 맵 데이터를 메인 스레드에서 동기적으로 처리하면 화면 멈춤(Freezing) 현상이 발생합니다. 이를 방지하기 위해 async/await 기반의 비동기 로딩 및 맵 초기화 시스템을 구축했습니다.

2.1 가중치 기반 로딩 시스템 (LoadingManager)

데이터 다운로드, 파싱, 그리고 맵 생성의 진행 과정을 각 파트의 비중에 따라 가중치(Weight)를 두어 세밀하게 계산합니다. Task.Yield()를 활용하여 연산 도중 주기적으로 메인 렌더링 루프에 제어권을 양보함으로써 로딩 UI 애니메이션이 부드럽게 유지되도록 최적화했습니다.

비동기 데이터 로딩 흐름 서버 데이터 다운로드부터 파싱 적재까지 하나의 비동기 파이프라인으로 관리합니다.

// LoadingManager.cs: 비동기 데이터 로딩 흐름
public async Task<bool> StartLoadingDataAsync(CancellationToken cancellationToken = default)
{
    UpdateProgress(0.01f, "서버 목록 확인 중...");

    // 1. 메타 시트 비동기 다운로드
    bool metaSuccess = await ServerCSV_ConvertData.DownloadMetaSheetAsync();
    
    // 2. 조건부 CSV 다운로드 (진행률 가중치 적용 5% ~ 80%)
    bool csvSuccess = await ServerCSV_ConvertData.DownloadAllCSVAsync((progress, fileName) =>
    {
        UpdateProgress(0.05f + (progress * 0.75f), $"데이터 수신 중: {fileName}");
    });

    // 3. 서버 데이터 로드 (DataManager 비동기 파싱)
    UpdateProgress(0.80f, "데이터 로드 중...");
    await Managers.Data.ServerDataLoadAsync();

    UpdateProgress(1.0f, "데이터 로딩 완료!");
    return true;
}

3. 퀘스트 수락, 진행 및 동적 보상 시스템

구글 시트에서 파싱된 퀘스트 데이터 형식을 바탕으로, QuestManager가 상황에 맞는 퀘스트 객체를 팩토리 패턴(Handler)으로 생성합니다. 퀘스트 진행 상황은 이벤트 버스 시스템에 의해 완벽히 디커플링되어 처리됩니다.

3.1 이벤트 구동형 퀘스트 진행 (Event-Driven)

몬스터가 처치될 때마다 발생하는 OnMonsterKilled 이벤트를 QuestManager가 구독합니다. 활성화된 퀘스트(ActiveQuestList)의 타겟 정보와 일치할 경우 진행도를 올리며, 목표 수치에 도달하면 퀘스트 완료 이벤트를 다시 발행합니다.

3.2 시드(Seed) 기반 동적 보상

퀘스트 레벨과 Data_Resource 베이스 값을 기준으로, 퀘스트 수락 시점의 난이도와 GameSeed 가중치를 곱하여 게임할 때마다 조금씩 달라지는 동적 보상(Gold, Exp)을 산출합니다.

퀘스트 이벤트 및 보상 계산 로직 몬스터 처치 이벤트 구독과 시드 기반 보상 변동 로직입니다.

// QuestManager.cs: 몬스터 처치 이벤트 핸들링 및 진행도 체크
private void HandleMonsterKilled(int monsterId)
{
    var key = (typeof(Unit_Monster), monsterId);
    List<int> completedQuestIndices = new List<int>();

    foreach (Quest quest in ActiveQuestList)
    {
        if (IsTargetQuest(quest, key))
        {
            // 진행도 증가 및 UI 업데이트 이벤트 발행
            UpdateQuestProgress(quest);

            if (quest.IsQuestCompleted())
                completedQuestIndices.Add(CompleteQuest(quest));
        }
    }

    if (completedQuestIndices.Count > 0)
    {
        Managers.Event.QuestCompleted(completedQuestIndices);
    }
}

// Quest.cs: 시드 기반 동적 보상 산출 (생성자 단계)
// GameSeed의 Reward 도메인을 사용하여 동일한 시드일 때 동일한 퀘스트 보상을 보장
float RewardRatio = (float)GameSeed.NextInt(GameSeed.Domain.Reward, 0, 11) / 10f;

m_rewardGold = Mathf.RoundToInt(Managers.Data.ResourceData[m_questLevel].questGold * ((float)ctx.difficultyTag * RewardRatio));
m_rewardExp = Mathf.RoundToInt(Managers.Data.ResourceData[m_questLevel].questExp * ((float)ctx.difficultyTag * (1f - RewardRatio)));

4. 계층적 맵 생성 및 이동 아키텍처

게임의 월드는 거대한 1개의 세계(Map) 안에 여러 지역(Region)이 있고, 지역 안에 수많은 전투 전장(Field)이 존재하는 Map -> Region -> Field의 계층적 구조를 가집니다.

4.1 비동기 맵 초기화 및 구성

대규모 맵 객체를 한 번에 생성하면 부하가 크기 때문에, MapManager의 NewGame_InitMap 메서드가 async/await 흐름을 타고 Map과 Region 내부의 퀘스트/필드를 순차적으로 생성합니다. 생성에 관여하는 모든 무작위 확률은 GameSeed.Domain.Map, GameSeed.Domain.Region 등 분리된 난수 스트림에 의해 결정론적(Deterministic)으로 구성됩니다.

4.2 이벤트 기반 맵 이동 시스템

유저가 UI를 통해 특정 Field를 선택하면, Managers.Event.OnEnterFieldEvent가 발생합니다. MapManager는 이를 수신하여 현재 전투 환경(Battle Manager 상태)을 업데이트하고 BGRender 컴포넌트를 이용해 배경 이미지를 교체하며 페이드인 효과를 발생시킵니다.

비동기 맵 계층 초기화 로직 Map 객체 하위에 Region을 묶고, Region 내부에 퀘스트와 Field를 생성하여 인덱스로 연결합니다.

// MapManager.cs: 비동기 맵 초기화 진입점
public async Task<bool> NewGame_InitMap(Func<float, string, Task> onProgress)
{
    // 1. 최상위 월드 맵 생성 (레벨/개수 지정)
    Map map1 = DataFactory.MakeMap(1, 3, m_mapParentObj.transform);
    Map map10 = DataFactory.MakeMap(10, 3, m_mapParentObj.transform);
    Map map20 = DataFactory.MakeMap(20, 3, m_mapParentObj.transform);

    // 2. 월드맵 하위에 할당된 모든 지역(Region)들에 대한 내부 필드/퀘스트 비동기 생성 
    if (WorldRegionList != null && WorldRegionList.Count != 0)
    {
        foreach (Region region in WorldRegionList)
        {
            // Region.GenerateRegion 안에서 Field 객체들이 생성되며 진행도 보고를 전달
            await region.GenerateRegion(onProgress);
        }
    }

    IsLoadedData = true;
    return true;
}

// Region.cs: 지역 내 필드 및 퀘스트 생성
public async Task GenerateRegion(Func<float, string, Task> onProgress)
{
    int questCount = GameSeed.NextInt(GameSeed.Domain.Region, 4, 7);
    MonsterType monsterType = GameSeed.RandomEnum<MonsterType>(GameSeed.Domain.Region);
    monsterSet = new MonsterSet(monsterType);
    
    // ... 생략 ...

    for (int i = 0; i < questCount; i++)
    {
        Quest mainQuest = Managers.Quest.GenerateQuest(monsterSet, ref currentQuestLevel, questDataList, questDialogList);
        int questIndex = Managers.Quest.MainQuestList.IndexOf(mainQuest);

        // Field 객체를 생성하고, 방금 생성된 메인 퀘스트의 인덱스를 넘겨 결합시킴
        Field field = DataFactory.MakeField(this, questIndex, transform);
        
        // ... (인덱스 저장 관리 생략)
        if (onProgress != null)
            await onProgress((float)(i + 1) / questCount, $"지역 생성 중...");
    }
}

5. Seed / Token 시스템 (RNG 완전 복원)

게임을 세이브하고 로드했을 때, 단순히 맵과 캐릭터의 상태만을 저장하는 것을 넘어 생성 규칙(시드) 자체를 완벽히 롤백해야 합니다. 초기 시드값만 저장할 경우 게임 도중 이미 소모된 난수 횟수로 인해 세이브 로드 시점에 다음 생성되는 아이템이나 맵이 달라지는 문제가 발생합니다. 이를 극복하기 위한 Seed/Token 복원 시스템입니다.

5.1 도메인 격리 구조 (Domain Isolation)

System.Random 객체를 하나만 사용하면, 퀘스트 생성 시 난수를 소모한 횟수에 따라 맵 생성 결과가 뒤틀리게 됩니다. 이를 방지하기 위해 GameSeed는 Domain(Map, Quest, Field, Reward 등)을 분리하여 각각 독립된 Random 객체 스트림을 보유합니다.

5.2 고정 폭 인코딩 기반 토큰 다이어그램

모든 도메인의 난수 사용 횟수(Usage Count)를 하나의 암호화된 토큰(Token)으로 병합합니다. 파싱 시 데이터가 꼬이지 않도록 고정 폭(Fixed-Width) 인코딩을 사용했습니다.

5.3 토큰 빌드 및 상태 복원 흐름

저장 시 위 규칙대로 텍스트 토큰을 빌드하여 저장하고, 로드할 때는 이 문자열을 길이 단위로 잘라낸 뒤 각 도메인의 Random 객체를 생성하고 사용 횟수만큼 Next()를 더미 호출(Skip) 시켜 게임의 미래 확률 상태를 정확히 세이브 시점과 동일하게 동기화합니다.

토큰 인코딩 및 RNG 상태 강제 복구 로직 고정 폭 문자열을 결합하여 저장하고, 로드시 추출하여 각 도메인의 스트림을 동기화합니다.

// SaveLoadManager.cs: 시드와 도메인 사용량을 하나의 고정 폭 토큰으로 결합
private static string BuildSeedToken(long baseSeed, Dictionary<GameSeed.Domain, ulong> usage)
{
    ulong encodedSeed = unchecked((ulong)baseSeed);
    string token = Pad(encodedSeed, 20); // 20자리 패딩

    List<GameSeed.Domain> domains = new List<GameSeed.Domain>((GameSeed.Domain[])Enum.GetValues(typeof(GameSeed.Domain)));
    domains.Sort((a, b) => ((uint)a).CompareTo((uint)b));

    token += Pad((uint)domains.Count, 3);
    foreach (var d in domains)
    {
        ulong count = usage != null ? usage.GetValueOrDefault(d, 0UL) : 0UL;
        token += Pad((uint)d, 3);    // 도메인 ID 3자리
        token += Pad(count, 12);     // 사용량 12자리
    }
    return token;
}

// GameSeed.cs: 토큰에서 추출된 정보로 RNG 엔진을 과거 상태로 복원
public static void RestoreRNG(long baseSeed, Dictionary<Domain, ulong> usageCounts)
{
    foreach (var kv in usageCounts)
    {
        Domain d = kv.Key;
        ulong count = kv.Value;     
        
        // BaseSeed를 해싱(Salt)하여 도메인별 고유 서브 시드로 RNG 재생성
        System.Random rng = new System.Random(DeriveSubSeed(baseSeed, (uint)d));
        
        // 토큰에 기록된 횟수만큼 난수를 버림(Skip) 호출하여 확률 스트림 위치를 강제 동기화
        for (ulong i = 0; i < count; i++)
        {
            rng.Next();     
        }
        
        domainRng[d] = rng;
        domainUsageCounts[d] = count;
    }
}

Conclusion: WorldFirstKill은 비동기 파싱과 계층적 맵 생성으로 방대한 데이터 로딩 문제를 최적화했으며, Seed/Token 시스템을 통해 로그라이크 특유의 ‘완벽한 게임 플레이(RNG) 복원력’을 기술적으로 완성한 수준 높은 아키텍처를 자랑합니다.