DS-Combat_analy/legacy/분석도구/v2/장기과제_Blueprint변수검증.md

# 장기 과제: Blueprint 변수 검증

## 과제 개요

DT_Skill의 스킬 설명(desc)에 사용된 {0}, {1} 등의 변수가 실제 게임 로직(Blueprint, 몽타주 등)의 값과 일치하는지 검증하는 작업

## 현재 상태

### ✅ 완료된 부분
- DT_Skill의 `desc` (원본 설명 문자열) 추출
- DT_Skill의 `descValues` (UI 표시용 값 배열) 추출
- `descFormatted` (변수 치환된 최종 설명) 생성
- 문서에 완전한 스킬 설명 표시

### ⚠️ 제한 사항
**descValues는 유저에게 보여주기 위한 텍스트 정보일 뿐, 실제 게임 로직에서는 사용되지 않음**

- 실제 스킬 효과는 Blueprint, AnimMontage, GameplayEffect 등에 정의됨
- descValues와 실제 게임 로직 값이 다를 가능성 존재
- 각 변수가 어느 Blueprint/몽타주의 어떤 변수와 연결되는지 case-by-case 분석 필요

## 검증 대상 예시

### 예시 1: Hilda 반격 (SK100202)

**DT_Skill 정보**:
```
desc: "방패를 들어 {0}초 동안 반격 자세를 취합니다. 반격 성공 시 {1}%만큼 물리 피해를 줍니다."
descValues: [5, 80]
abilityClass: /Game/Blueprints/Abilities/GA_Skill_Knight_Counter.GA_Skill_Knight_Counter_C
```

**검증 필요 사항**:
- {0} = 5초 → GA_Skill_Knight_Counter의 어느 변수? (activeDuration? blockingDuration?)
- {1} = 80% → GA_Skill_Knight_Counter의 어느 변수? (counterDamageMultiplier?)

**현재 문제**:
- Blueprint.json에서 GA_Skill_Knight_Counter 추출 시 모든 VarName이 `None`으로 나타남
- 변수 이름 없이는 매칭 불가능

### 예시 2: Urud 다발 화살 (SK110205)

**DT_Skill 정보**:
```
desc: "{0}발의 화살을 동시에 발사하여 각각 {1}%만큼 물리 피해를 입힙니다."
descValues: [3, 90]
abilityClass: /Game/Blueprints/Characters/Urud/GA_Skill_Urud_MultiShot_Quick.GA_Skill_Urud_MultiShot_Quick_C
```

**검증 필요 사항**:
- {0} = 3발 → Blueprint의 ProjectileCount? 또는 몽타주의 AN_Trigger_Projectile_Shot_C 호출 횟수?
- {1} = 90% → 이미 DT_Skill.skillDamageRate=0.9로 검증됨 ✅

## 작업 범위

### 1단계: 정보 수집 (필수)

Blueprint 변수 이름을 얻기 위한 방법 선택:

#### 옵션 A: Blueprint.json 재추출
- FModel 또는 다른 추출 도구 설정 변경
- VarName 필드가 포함되도록 추출 옵션 조정
- 또는 Unreal Editor에서 직접 Blueprint을 JSON으로 Export

#### 옵션 B: 수동 조사
- Unreal Editor에서 각 GA_Skill Blueprint 열기
- 변수 목록과 기본값을 수동으로 기록
- config.py에 수동으로 정의

#### 옵션 C: 코드 분석
- C++ 소스 코드에서 WSGameplayAbility 클래스 분석
- 각 GA_Skill의 부모 클래스 변수 확인
- .h/.cpp 파일에서 변수 정의 추출

### 2단계: 변수 매칭 규칙 정의

각 스킬 타입별 변수 매칭 패턴 정의:

```python
# 예시 매칭 규칙
SKILL_VAR_MAPPING = {
    'counter_skills': {
        # 반격 스킬 계열
        '{0}': 'blockingDuration',  # 반격 지속 시간
        '{1}': 'counterDamageRate'  # 반격 피해 배율
    },
    'projectile_skills': {
        # 발사체 스킬 계열
        '{0}': 'projectileCount',   # 발사체 개수
        '{1}': 'skillDamageRate'    # 피해 배율 (DT_Skill에서 검증 가능)
    },
    'summon_skills': {
        # 소환 스킬 계열
        '{0}': 'activeDuration',    # 소환 지속 시간 (DT_Skill에서 검증 가능)
        '{1}': 'summonDamageRate'   # 소환수 피해 배율
    }
}
```

### 3단계: 자동 검증 스크립트 작성

```python
def verify_skill_desc_values(skill_id: str, skill_data: Dict) -> Dict:
    """
    스킬 설명의 변수가 실제 Blueprint/몽타주 값과 일치하는지 검증

    Returns:
        {
            'verified': bool,
            'mismatches': [],
            'sources': {
                '{0}': {'expected': 5, 'actual': 5, 'source': 'Blueprint.activeDuration'},
                '{1}': {'expected': 80, 'actual': 75, 'source': 'Blueprint.counterDamageRate'}
            }
        }
    """
    pass
```

### 4단계: 검증 리포트 생성

각 스킬별 검증 상태를 마크다운으로 출력:

```markdown
## SK100202 - 반격 (Hilda)

**Desc**: 방패를 들어 {0}초 동안 반격 자세를 취합니다. 반격 성공 시 {1}%만큼 물리 피해를 줍니다.

| 변수 | descValues | 실제 값 | 출처 | 상태 |
|------|------------|---------|------|------|
| {0} | 5 | 5 | GA_Skill_Knight_Counter.blockingDuration | ✅ 일치 |
| {1} | 80 | 75 | GA_Skill_Knight_Counter.counterDamageRate | ❌ 불일치 |

**결론**: descValues가 실제 로직과 다를 수 있음 (UI 표시용 값)
```

## 우선순위 스킬 목록

다음 스킬들을 우선적으로 검증:

### High Priority (복잡한 변수 사용)
1. SK100202 (Hilda 반격) - 지속시간, 피해량
2. SK110205 (Urud 다발 화살) - 발사체 개수, 피해량
3. SK160202 (Rene Ifrit 소환) - 지속시간, 공격력
4. SK160206 (Rene Shiva 소환) - 지속시간, 공격 주기
5. SK120202 (Nave 화염벽) - 지속시간, 틱 피해

### Medium Priority (1-2개 변수)
6. SK100201 (Hilda 칼날 격돌) - 피해량, 경직 시간
7. SK130204 (Baran 강제 끌어오기) - 피해량
8. SK180202 (Sinobu 부적폭탄) - 폭발 범위, 피해량

### Low Priority (변수 없거나 단순)
- 대부분의 유틸리티 스킬
- 변수가 없는 스킬

## 예상 결과물

1. **검증 스크립트**: `verify_blueprint_variables.py`
2. **변수 매칭 정의**: `config.py`에 `SKILL_VAR_MAPPING` 추가
3. **검증 리포트**: `Blueprint변수검증_리포트.md`
4. **업데이트된 문서**: 각 스킬에 실제 값 vs descValues 비교 추가

## 예상 소요 시간

- **옵션 A** (Blueprint 재추출): 1-2시간 (추출 설정 + 재실행)
- **옵션 B** (수동 조사): 10-15시간 (91개 스킬 × 평균 10분)
- **옵션 C** (코드 분석): 3-5시간 (C++ 코드 리뷰 + 자동화)

## 권장 접근 방법

1. **단기 (1-2시간)**:
   - Blueprint.json 재추출 시도 (FModel 설정 변경)
   - 성공 시 자동 검증 스크립트 작성

2. **중기 (3-5시간)**:
   - C++ 소스 코드 분석으로 변수 패턴 파악
   - 우선순위 High 스킬 5개만 수동 검증

3. **장기 (필요 시)**:
   - 모든 스킬 완전 검증
   - 자동화 스크립트 완성
   - CI/CD 파이프라인에 검증 단계 추가

## 참고 사항

- **descValues는 UI 표시용이므로 실제 로직과 다를 수 있음을 명심**
- 밸런스 패치 시 Blueprint는 업데이트되지만 descValues는 업데이트 안 될 수 있음
- 이 검증은 "문서의 정확성"보다 "게임 로직의 일관성"을 위한 것
- 실제 DPS 계산에는 Blueprint/몽타주의 실제 값을 사용해야 함

## 연락처 및 진행 상황

- **담당자**: (추후 할당)
- **시작일**: 2025-10-24
- **목표 완료일**: (TBD)
- **현재 상태**: 계획 단계
- **진행률**: 0% (정보 수집 대기 중)

---

**생성일**: 2025-10-24 21:34
**버전**: v1.0
**작성자**: Claude Code