CitRush

1-1. 기본 베이스 움직임 및 전투 이벤트 처리

복잡한 LLM 서버 통신 환경에서도 끊김 없는 전투 경험을 제공하기 위해 GAS(Gameplay Ability System)와 서버 주도형 FSM, 그리고 로컬 폴백(Fallback) 시스템을 결합한 하이브리드 AI 구조를 설계

🔸기본 동작 (AbstractEnemy)

🔹기술 구현 방식

🔹이동 방식

• APixelEnemy에서 CharacterMovement를 MOVE_Flying으로 설정

• GravityScale = 0.0f → 중력 없이 평면 이동

• bConstrainToPlane = true / SetPlaneConstraintAxisSetting(Z) 
  → Z축 고정, 2D 평면 이동

• 초기 스폰 시 SM_ROAD_19 액터의 Z좌표 + 1.0f 위치에 배치

• MaxWalkSpeed = MaxFlySpeed = MoveSpeed (3000.f cm/s)

🔹AI 서버 통신 및 의사결정 아키텍처

전역 싱글톤인 EnemyAISubsystem이 모든 적 개체를 중앙 집중식으로 관리하며,
서버 명령과 로컬 폴백을 조율합니다.

• 서버(LLM) 주도형 FSM: 14종의 EAIDirectiveState를 통해 단순 추격이 아닌
  '매복', '기만 후퇴', '측면 우회' 등의 고수준 전술 수행

• StateTree 폴백: 네트워크 장애 시 FEnemyTask_ChaseRacer 등 6종의
  로컬 Task가 즉시 활성화되어 AI 정지 현상 방지

🔸Pellet

🔹역할: 데미지 무적 상태, Flash 이펙트, 이벤트 브로드캐스트

🔹P-Pellet 전체 흐름

APelletActor 충돌
    └─► APixelEnemy::OnPelletCollected(Duration)
            ├─► PelletComponent->OnPelletCollected()
            │       ├─► bPowerPellet = true (Replicated)
            │       ├─► 실드 메시 표시
            │       ├─► 무적 타이머 시작 
            │       └─► 쿨다운 타이머 시작 (1초 단위 감소)
            ├─► bPowerPellet = true (레거시 플래그 동기화)
            ├─► CombatComponent->bPowerPelletActive = true
            └─► SpawnClones() (v1.5.0)
                    └─► MaxCloneCount=4 개 ACloneEnemy 스폰
                        (원형 배치, 반경 500cm)

무적 종료:
    OnInvulnerabilityEnd()
        ├─► bPowerPellet = false
        ├─► 실드 메시 숨김
        └─► DespawnClones()

• PelletComponent

  🔹역할: P-Pellet 섭취, 무적, 쿨다운, 실드 시각화

  // 주요 설정
  float CooldownDuration;        // P-Pellet 재사용 대기 (초)
  UStaticMeshComponent* ShieldMesh;      // 실드 시각 메시 
  
  // 주요 함수
  OnPelletCollected(float Duration) // 펠릿 섭취 → 무적 타이머 시작 + 실드 
  IsPowerPelletActive()                  // 현재 무적 상태 여부
  GetCooldownRemaining()                 // 남은 쿨다운 (초)
  IsOnCooldown()                        // 쿨다운 중 여부
  
  // 델리게이트
  FOnPelletStateChanged OnPelletStateChanged     // 무적 활성/해제
  FOnPelletCooldownChanged OnPelletCooldownChanged // 쿨다운 변경

🔸GAS 연동

🔹GAS 기반 전투 시스템

🔹AttributeSet (UASEnemy)

// 관리 수치 목록 (모두 Replicated)
FGameplayAttributeData Health;           // 현재 체력
FGameplayAttributeData MaxHealth;        // 최대 체력
FGameplayAttributeData DetectionRange;   // 현재 감지 범위
FGameplayAttributeData DefaultDetectionRange;
FGameplayAttributeData Speed;            // 현재 이동 속도
FGameplayAttributeData DefaultSpeed;
FGameplayAttributeData AttackPower;      // 현재 공격력
FGameplayAttributeData DefaultAttackPower;

🔹GAS Ability 부여 방식

🔸충돌 방향별 데미지 이벤트 처리

🔹충돌 감지 경로

CapsuleComponent::OnComponentHit
    └─► APixelEnemy::OnHitToRacer()
            ├─► ACoinActor   → 코인 획득 처리
            ├─► APelletActor → 펠릿 획득 처리
            └─► AAbstractRacer → 충돌 방향 판정 후 데미지 이벤트

OnOverlapToRacer()도 동일 로직으로 처리 (Sweep 충돌 대비)

🔹충돌 방향 판정 로직 (AbstractEnemy::OnCollisionHit)

FVector hitDirection = (hitLocation - EnemyLocation).GetSafeNormal();
float dotProduct = FVector::DotProduct(GetActorForwardVector(), hitDirection);

if (dotProduct < 0.0f)  // 뒤에서 충돌 → Enemy가 맞음
{
    EventTag = "Event.Gameplay.Collision.Back"
    damagedASC = Enemy ASC
    EventData.EventMagnitude = Racer.AttackPower  
											        // 레이서의 공격력으로 피해
}
else  // 앞에서 충돌 → Racer가 맞음
{
    EventTag = "Event.Gameplay.Collision.Front"
    damagedASC = Racer ASC
    EventData.EventMagnitude = Enemy.AttackPower  
                               // 적의 공격력으로 피해
}

damagedASC->HandleGameplayEvent(EventTag, &EventData);

🔹초기화 시퀀스 (BeginPlay Flow)

객체 생성 시 데이터 무결성을 위해 11단계의 엄격한 초기화 과정을 거칩니다.

1. GAS 초기화: SetReplicationMode 설정 및 초기 스탯 Effect 적용

2. 데이터 바인딩: Combat, Pellet 컴포넌트 이벤트 및 델리게이트 연결

3. 환경 설정: MOVE_Flying 고정(Z축 고정), 미니맵 태그 추가, CCTV 렌더링 개시

🔹피해 처리 흐름

graph LR
      Start(["적이 데미지를 받음"])

      CheckPP{"무적"}
      CheckUT{"무적 쿨타임"}
      Ignore["데미지 무시"]

      ApplyDmg["체력 감소"]
      CheckHP{"체력 ≤ 0"}
      Death["파괴 연출 재생"]

      CheckEffect{"피격 이펙트 에셋"}
      SpawnEffect["피격 이펙트 재생"]
      SkipEffect["이펙트 없음"]

      CheckCombat{"전투 컴포넌트"}
      NewInvuln["무적 쿨타임 시작"]
      LegacyInvuln["무적 활성화"]

      Start --> CheckPP
      CheckPP -- 예 --> Ignore
      CheckPP -- 아니오 --> CheckUT
      CheckUT -- 예 --> Ignore
      CheckUT -- 아니오 --> ApplyDmg
      ApplyDmg --> CheckHP
      CheckHP -- "예 (사망)" --> Death
      CheckHP -- "아니오 (생존)" --> CheckEffect
      CheckEffect -- 예 --> SpawnEffect
      CheckEffect -- 아니오 --> SkipEffect
      SpawnEffect --> CheckCombat
      SkipEffect --> CheckCombat
      CheckCombat -- 예 --> NewInvuln
      CheckCombat -- 아니오 --> LegacyInvuln

      style Start fill:#222,stroke:#888,color:#fff
      style Ignore fill:#1a1a1a,stroke:#444,color:#888
      style CheckPP fill:#4d2600,stroke:#ff922b,color:#fff
      style CheckUT fill:#4d2600,stroke:#ff922b,color:#fff
      style ApplyDmg fill:#1e2a38,stroke:#4a90e2,color:#fff
      style CheckHP fill:#3d2b00,stroke:#d4af37,color:#fff
      style Death fill:#3a1f1f,stroke:#ff6b6b,color:#fff
      style CheckEffect fill:#2a2a2a,stroke:#aaaaaa,color:#fff
      style SpawnEffect fill:#1b2e1b,stroke:#51cf66,color:#fff
      style SkipEffect fill:#1a1a1a,stroke:#444,color:#888
      style CheckCombat fill:#2a2a2a,stroke:#aaaaaa,color:#fff
      style NewInvuln fill:#1b2e1b,stroke:#51cf66,color:#fff
      style LegacyInvuln fill:#1b2535,stroke:#4ecdc4,color:#fff

2-1. AI 지시(FSM) 컴포넌트 구축

AI Teeth의 고도화된 전술적 판단을 인게임 유닛 행동 표준 명령어 체계 구축

🔸행동 표준 명령어 기반 상태 전환

🔹AI FSM 컴포넌트

🔹AI 전체 아키텍처

GameInstance
    └── UEnemyAISubsystem (전역 싱글톤)
            ├── HTTP 클라이언트 (단일 연결)
            ├── RegisteredEnemies: TArray<IAIDecisionReceiver*>
            │       ├── APixelEnemy (ID: "pacman_main")
            │       └── ACloneEnemy (ID: "clone_1" ~ "clone_4")
            ├── DecisionTimer (자동 요청 타이머, 기본 3초 간격)
            ├── 액터 캐시 (GetAllActorsOfClass 대체)
            │       ├── CachedVehicleArray
            │       ├── CachedPelletArray
            │       ├── CachedCoinArray
            │       └── CachedPelletSpawnerArray
            └── Request 순서 관리 (request_num)

🔹상세 통신 및 처리 시퀀스

• Response Handling: EnemyAISubsystem이 서버로부터 JSON 응답을 수신

• Order Validation: ValidateResponseOrder()를 통해 현재 request_num보다 낮은(오래된) 응답은 폐기하여 최신 명령의 무결성을 보장

• Command Dispatch: 인터페이스(IAIDecisionReceiver)를 통해 각 적(Enemy) 개체에게 명령(FUnitCommand)

• Data Translation: FUnitCommandParams를 Enemy가 이해할 수 있는 FDirectiveParams 구조체로 변환

• State Transition: AIDirectiveComponent가 ProcessDirective를 호출하여 최종적으로 14종의 FSM 상태(EAIDirectiveState) 중 하나로 전환

• 응답 처리 및 상태 전환

  // EnemyAISubsystem에서 개별 Enemy로 명령 전달
  void UEnemyAISubsystem::HandleDecisionResponse(const FString& ResponseContent)
  {
      // 1. 순서 검증 (Sequence Check)
      if (!ValidateResponseOrder(CurrentResponseNum)) return;
  
      // 2. 각 RegisteredEnemies에게 명령 분배
      for (auto* Enemy : RegisteredEnemies)
      {
          Enemy->OnAIDecisionReceived(ParsedCommand);
      }
  }
  
  // AIDirectiveComponent에서 최종 FSM 상태 전환
  void UAIDirectiveComponent::ProcessDirective(int32 Code, const FDirectiveParams& Params)
  {
      EAIDirectiveState NewState = static_cast<EAIDirectiveState>(Code);
      
      // 상태 전환 및 매개변수 적용
      TransitionToState(NewState, Params);
  }

• ProcessDirective 전환 매핑

  void ProcessDirective(int32 DirectiveCode, const FDirectiveParams& Params){
      EAIDirectiveState NewState = static_cast<EAIDirectiveState>(DirectiveCode);
      TransitionToState(NewState, Params);
  }
  
  void TransitionToState(EAIDirectiveState NewState, const FDirectiveParams& Params){
      // 이전 상태 저장
      EAIDirectiveState OldState = CurrentState;
  
      // 상태 전환
      CurrentState = NewState;        
      // Replicated → 자동으로 클라이언트 동기화
      CurrentParams = Params;
      ReplicatedTargetPosition = Params.TargetPosition;
      StateStartTime = GetWorld()->GetTimeSeconds();
  
      // GAS State Tag 적용 (옵션)
      if (ASC) ASC->AddLooseGameplayTag(GetStateTag(NewState));
      // 이벤트 브로드캐스트
      OnAIStateChanged.Broadcast(NewState, OldState);
  }

🔸네트워크 복제

🔹클라이언트 동기화 흐름

🔸타임아웃 처리

🔹단계별 타임아웃 처리

🔹폴백 응답 생성 (CreateFallbackAttackResponse)

// HTTP 실패 시 기본 공격 명령 생성 
FGetDecisionResponse2 CreateFallbackAttackResponse()

🔹요청 순서 보장

: request_num 응답 검증으로 값이 일치할 때만 처리로 연결 지연 있을 경우 llm 응답 순서 혼동 상황 제어

// request_num 형식: {room_id}_{timestamp}_{sequence}
FString GenerateRequestNum(RoomID)

// 응답 검증: LastSentRequestNum과 일치할 때만 처리
bool ValidateResponseOrder(IncomingRequestNum)
    if (incoming == LastSent) // → 처리 허용
    if (incoming < LastSent)  // → 무시 (오래된 응답)

🔹AI 서버 통신 요약

[자동 요청 루프 - 기본 3초]
EnemyAISubsystem::SendBatchDecisionRequest()
    ├── 현재 게임 상태 수집
    │     ├── APixelEnemy::GetCurrentGameState()
    │     │     ├── position, health, speed
    │     │     ├── capture_gauge (위협도)
    │     │     ├── is_invulnerable (펠릿 + 전투 무적)
    │     │     ├── p_pellet_cooldown
    │     │     └── forward_vector, rotation_yaw
    │     └── 레이서 위치/속도 정보
    │
    ├── request_num 생성 및 LastSentRequestNum 저장
    │
    ├── HTTP POST /api/v1/get_decision
    │
    └── 응답 처리
          ├── ValidateResponseOrder() 검증
          ├── units[] 배열에서 각 Enemy ID 매핑
          └── IAIDecisionReceiver::OnAIDecisionReceived() 호출

2-2. Enemy 구성 연동 및 서비스 끊김 시 StateTree

하이브리드 AI 구조
: LLM 서버의 전략적 명령과 StateTree기반의 즉각적인 로컬 대응을 결합하여 지연 시간 극복

🔸AI Perception

🔹설정 구조체 (FEnemyPerceptionConfig)

bool bEnableSight     // Sight 감각 활성화
float SightRadius     // 시야 범위 (cm)
float LoseSightRadius // 시야 상실 범위
float PeripheralVisionAngle // 주변 시야 각도 (도)
bool bEnableHearing   // Hearing 감각 활성화
float HearingRange    // 청각 범위 (cm)
bool bEnableDamage   // Damage 감각 활성화 (피격 시 자동 감지)
float MaxStimuliAge   // 자극 유효 시간

TSubclassOf<UAISense> DominantSense //지배 감각 (기본: Sight)
FAISenseAffiliationFilter SightAffiliationFilter
FAISenseAffiliationFilter HearingAffiliationFilter

🔹타임아웃 처리

float GoalMaxAge;  // GoalMaxAge(초) 이상 새 명령 없으면 Goal Stale 처리
bool IsGoalStale() // → (현재시간 - LastDirectiveTime) > GoalMaxAge

🔸StateTree (로컬 AI 폴백)

🔹활성화 조건: AI 서버 연결 끊김 시 자동 전환

🔹구현된 Task 목록 (6종 + 추가)

2-3. 연동 및 서버 연결

🔹에이전트 서버 연결

🔹LLM/StateTree AI Enemy

LLM의 전략적 지시, StateTree의 고속 실행력을 AI 적 시스템
팩맨의 추격 메커니즘을 현대적 레이싱 장르로 재해석한 프로젝트입니다.
JSON 기반 외부 AI 서버(LLM)가 실시간 게임 상황을 분석해 전략적 명령을 내리면, 로컬의 StateTree가 프레임 단위의 고속 주행 및 전투 로직을 실행합니다.
네트워크 단절 시 즉각적인 Local Fallback을 지원하여 끊김 없는 사용자 경험을 보장합니다.

네트워크 및 동기화 전략

• RPC & Replication: directive_code와 핵심 파라미터만을 패킹하여 복제함으로써 대역폭 소모를 최소화.

• Prediction: 로컬 서버 끊김 시점에도 AI가 관성에 따라 주행하며 로컬 로직으로 부드럽게 전환(Smooth Transition)되도록 보간 로직 적용.

• CPU 비용 개선

  항목	기존	개선
  조건 평가 방식	상태 전환마다 월드 탐색 반복 호출	Evaluator가 1틱 1회 캐싱 → 조건은 O(1) 비교
  실제 복잡도	O(K × N) 조건 K개 × 오브젝트 N개	O(N) 캐싱 1회 + O(1) 조건 평가
  시간 복잡도	O(N²)	O(1)

  1. 기존 방식 - FSM + AIDirectiveComponent

  TickComponent (0.1f 간격)
  └── UpdateCurrentState(DeltaTime)
      └── switch(CurrentState) → ExecuteX() 호출
          └── 내부에서 직접 월드 탐색 수행

  TickComponent (0.1f 간격)
  └── UpdateCurrentState(DeltaTime)
      └── switch(CurrentState) → ExecuteX() 호출
          └── 내부에서 직접 월드 탐색 수행

  

  ExecuteIdle, ExecuteChase 등 각 실행 함수가 독립적으로 탐색 로직
  → 상태가 바뀔 때마다 각 함수가 중복으로 탐색 수행

  

  2. 개선 후 (StateTree 트리 구조 최적화)

  FEnemyContextEvaluator::Tick() - 1틱에 1회만 실행
  └── 모든 거리 계산 → FEnemyStateTreeContextData 에 저장
  ├── bIsServerConnected
  ├── NearestRacerDistance
  ├── NearestPelletDistance
  ├── NearestCoinDistance
  ├── HealthRatio
  └── bHasPowerPellet
  
  StateTree 조건 평가 (캐싱된 값 참조)
  ├── FEnemyCondition_ServerConnected 
  |       → bIsServerConnected 읽기 = O(1)
  ├── FEnemyCondition_HasNearbyRacer  
  |       → NearestRacerDistance 비교 = O(1)
  ├── FEnemyCondition_LowHealth       → HealthRatio 비교 = O(1)
  └── FEnemyCondition_HasPowerPellet  
            → bHasPowerPellet 읽기 = O(1)