284 lines
11 KiB
Markdown
284 lines
11 KiB
Markdown
|
# 09. 카드시스템 아키텍처 v1
|
||
|
|
|
||
|
|
- 작성일: 2026-04-14
|
||
|
|
- 작성자: 개발실장 (Explore 에이전트 분석 위임)
|
||
|
|
- 목적: 기획실이 관리하는 카드(G1~G5 총 311장) 이 **코드상 어떻게 표현·실행·획득되는지** 확정
|
||
|
|
- 스코프: `Assets/Script/Table/Tables/table_cardlist.cs`, `Assets/Script/InGame/Actor/Actor.cs`, `Assets/Script/My/MyClass.cs`
|
||
|
|
- 선행 문서: `08_전투시스템_SOT_v1.md`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 1. 카드 데이터 모델
|
||
|
|
|
||
|
|
### 1.1 eCardType Enum
|
||
|
|
|
||
|
|
`table_cardlist.cs:123~450` 에 `G[1-5]_<효과명>` 형태로 311개 정의.
|
||
|
|
|
||
|
|
| 등급 | 개수 | 대표 |
|
||
|
|
|---|---|---|
|
||
|
|
| G1 (Common) | 112 | G1_AddPotion ~ G1_ShieldIncreaseAttackPower |
|
||
|
|
| G2 (Uncommon) | 73 | G2_CriUpAfterCri ~ G2_RangeDodgeUp |
|
||
|
|
| G3 (Rare) | 51 | G3_CritDmgUp ~ |
|
||
|
|
| G4 (Hero) | 43 | G4_ZeroShieldCritRate ~ |
|
||
|
|
| G5 (Legend) | 32 | G5_RemoveNormalSkills ~ G5_RandomLightning_N |
|
||
|
|
| **합계** | **311** | `eCardType.Max` sentinel |
|
||
|
|
|
||
|
|
명명 규칙: `G[1-5]_<CamelCase>`. 기획실 SOT 엑셀 행과 1:1 매핑.
|
||
|
|
|
||
|
|
### 1.2 CardListTableData 필드 (`table_cardlist.cs:7~120`)
|
||
|
|
|
||
|
|
| 필드 | 타입 | 암호화 | 용도 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `e_CardType` | enum | ✗ | 식별자 |
|
||
|
|
| `n_ID` | int | **ObscuredInt** | 고유 ID |
|
||
|
|
| `e_CardGrade` | eGrade | ✗ | 등급 |
|
||
|
|
| `s_Value1~3` / `f_Value1~3` | string / float | float만 **Obscured** | 수치 (문자열/런타임 이원) |
|
||
|
|
| `s_LvUpValue1~2` / `f_LvUpValue1~2` | string / float | float만 **Obscured** | 레벨업 가중치 |
|
||
|
|
| `e_LvUpType` | enum | ✗ | 레벨업 적용 방식 |
|
||
|
|
| `b_Percent`, `b_LvUpValue*Percent` | bool | ✗ | % 해석 플래그 |
|
||
|
|
| `s_Projectile` / `e_ProjectileAttackType` / `n_ProjectileCount` / `f_ProjectileDelayTime` | — | Obscured(int/float) | 투사체 |
|
||
|
|
| `n_StatusOptionSetID` | int | **Obscured** | `table_StatusOptionSet` 조인 |
|
||
|
|
| `n_UseDmg` | int | **Obscured** | 피해 계산 방식 (0=고정, 1=%비율, 2=배수) **(확인 필요)** |
|
||
|
|
| `n_Desc`, `n_LvUpDesc` | int | ✗ | 텍스트 테이블 키 |
|
||
|
|
|
||
|
|
**핵심 관찰**: 수치는 `ObscuredFloat/Int`로 안티치트 적용. 메타(enum, 플래그)는 평문. **수치 변경은 테이블만 수정하면 코드 무수정** — 기획실 밸런싱 규칙("효과 종류 변경 금지, 수치만 조정")과 구조적으로 일치.
|
||
|
|
|
||
|
|
### 1.3 eLvUpType (`table_cardlist.cs:110~122`)
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
Use_LvUpValue1_To_Value1 // f_Value1 누적
|
||
|
|
Use_LvUpValue1_To_Value2
|
||
|
|
Use_LvUpValue1_To_Value3
|
||
|
|
Use_LvUpValue1_To_ProjectileCount
|
||
|
|
Heal_Multi / Heal_Mul // 즉시 회복 효과
|
||
|
|
GetGold // 즉시 골드
|
||
|
|
```
|
||
|
|
|
||
|
|
레벨업 수치 적용 (`CardListTableData.cs:96~100`):
|
||
|
|
```csharp
|
||
|
|
int Get_CardLv() => Mathf.Max(0, MyValue.sdata.Get_CardLv(n_ID) - 1);
|
||
|
|
float Get_LvUpValue1(eLvUpType t) =>
|
||
|
|
e_LvUpType == t ? f_LvUpValue1 * Get_CardLv() : 0;
|
||
|
|
```
|
||
|
|
→ **선형 누적**: `Value_final = Value_base + Level * Coefficient`.
|
||
|
|
|
||
|
|
### 1.4 CardSkillData 런타임 인스턴스 (`MyClass.cs:147~250`)
|
||
|
|
|
||
|
|
```csharp
|
||
|
|
public class CardSkillData
|
||
|
|
{
|
||
|
|
public CardListTableData m_Data;
|
||
|
|
Actor m_Actor;
|
||
|
|
public bool StartBattle;
|
||
|
|
public int TargetIdentity;
|
||
|
|
public int UseCount;
|
||
|
|
public int UseCount_Acc;
|
||
|
|
public float m_LifeTime; // 주기 쿨타임
|
||
|
|
public Dictionary<int, int> dic_identity; // 대상별 추적
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 2. 카드 효과 실행 구조
|
||
|
|
|
||
|
|
### 2.1 OnEvent_* 진입점 맵 (~258개 분기)
|
||
|
|
|
||
|
|
`Actor.cs` 전반:
|
||
|
|
|
||
|
|
| 메서드 | 라인 | 발동 | 분기 수 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `OnEvent_AddSkillCard()` | 1799 | 카드 획득 직후 1회 | ~80 |
|
||
|
|
| `OnEvent_RunSkillCard()` | 1655 | 획득/라인변경 반복 | ~50 |
|
||
|
|
| `OnEvent_Kill_Hitter()` | 2244 | 적 처치 | ~20 |
|
||
|
|
| `OnEvent_Cri_Hitter()` | 2616 | 크리 발동 | ~15 |
|
||
|
|
| `OnEvent_Avoid()` | 3001 | 회피 성공 | ~12 |
|
||
|
|
| `OnEvent_NoMiss_Hitter()` | 2442 | 회피 실패 | ~8 |
|
||
|
|
| `OnEvent_MyShield_Hit()` | 3131 | 쉴드 피해 | ~10 |
|
||
|
|
| `OnEvent_MyShield_Break()` | 3145 | 쉴드 소진 | ~5 |
|
||
|
|
| `OnEvent_GetDmg()` | 3202 | 피해 수신 | ~15 |
|
||
|
|
| `OnEvent_PlayAttack()` | 2022 | 공격 발동 | ~20 |
|
||
|
|
| `OnEvent_LvUp()` | 2917 | 레벨업 | ~25 |
|
||
|
|
| `OnEvent_MeetNode()` | 2746 | 노드 진입 | ~5 |
|
||
|
|
| `OnEvent_MakeMob()` | 3408 | 몬스터 생성 | ~3 |
|
||
|
|
| `OnEvent_Hit()` | 3218 | 피해 적용 후 | ~10 |
|
||
|
|
|
||
|
|
### 2.2 효과 적용 3가지 패턴
|
||
|
|
|
||
|
|
- **A. 조건 분기 (if-switch)** — 카드 1장당 1개 분기 (`Actor.cs:1801~1830` 등). 신규 추가 시 **코드 수정 필요**.
|
||
|
|
- **B. 데이터 주도 (테이블 참조)** — `CardSkillData.Add(...)` 에서 `Set_Buff(eStat, value)` 로 일반화 (`MyClass.cs:161~180`). 이 경로는 enum 케이스만 추가하면 됨.
|
||
|
|
- **C. 주기형 (m_LifeTime)** — `G1_MagicMissile` 처럼 쿨타임 기반 (`MyClass.cs:165~166`). `Update()`에서 감소.
|
||
|
|
|
||
|
|
### 2.3 트리거 분류표
|
||
|
|
|
||
|
|
| 트리거 | 예시 카드 | 위치 |
|
||
|
|
|---|---|---|
|
||
|
|
| 즉시 (획득 시) | G1_FireMagicMissiles, G1_InstantFullHeal | OnEvent_AddSkillCard |
|
||
|
|
| 온 공격 | G1_FirstAttack, G1_FifthAttackBack | OnEvent_PlayAttack |
|
||
|
|
| 온 피해 | G1_HealOnRangedHit | OnEvent_GetDmg |
|
||
|
|
| 온 킬 | G1_CastMagicMissilesOnBackKill | OnEvent_Kill_Hitter |
|
||
|
|
| 온 크리 | G1_ThirdCritDamage | OnEvent_Cri_Hitter |
|
||
|
|
| 온 회피 | G1_LifeStealOnDodge | OnEvent_Avoid |
|
||
|
|
| 온 노드시작 | G2_HeroSkillFullHeal | OnEvent_RunSkillCard |
|
||
|
|
| 영구 스탯 | G1_AddMaxAttack | CardSkillData.Add → Set_Buff |
|
||
|
|
| 1회성 버프 | G1_DodgeNextNAttacks | OnEvent_AddSkillCard |
|
||
|
|
| 주기 효과 | G1_MagicMissile | m_LifeTime |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 3. 카드 획득 · 보유 · 제거
|
||
|
|
|
||
|
|
### 3.1 획득 경로
|
||
|
|
|
||
|
|
```
|
||
|
|
노드 클리어 → Co_AllKill() → act_EndNode()
|
||
|
|
→ SelectCardUI.Set_Cards() [BattleCard.cs:37]
|
||
|
|
→ BattleCard.OnClick()
|
||
|
|
→ InGameInfo.Ins.Add_Card(CardListTableData)
|
||
|
|
→ Actor.Add_CardSkill() [Actor.cs:337]
|
||
|
|
→ dic_Card[eCardType] = CardSkillData
|
||
|
|
→ OnEvent_AddSkillCard()
|
||
|
|
```
|
||
|
|
|
||
|
|
추가 경로:
|
||
|
|
- 성소: `Actor.Add_Card_Random()` (`Actor.cs:4474`)
|
||
|
|
- 장비 특수효과: `Set_Equipment()` → `list_SkillId` (`Actor.cs:3773`)
|
||
|
|
- 상태이상 연쇄: `GetSkillCard_N` (`Actor.cs:3866~3871`)
|
||
|
|
|
||
|
|
### 3.2 보유 구조
|
||
|
|
|
||
|
|
- 저장소: `Dictionary<eCardType, CardSkillData> dic_Card` — **카드 타입별 1장**
|
||
|
|
- 조회: `IsObtainCardSkill(eCardType)` O(1)
|
||
|
|
- 슬롯 상한: **코드상 무제한** — **(확인 필요)** 기획 UI 상한 존재 여부
|
||
|
|
- 중복 방지: `if (!dic_Card.ContainsKey(...))` (`Actor.cs:4487`)
|
||
|
|
|
||
|
|
### 3.3 제거 경로
|
||
|
|
|
||
|
|
**현재 코드상 카드 제거 경로 없음** — `Actor.Set()` (`Actor.cs:148`) 에서 런 리셋 시 `dic_Card.Clear()` 만 존재.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 4. 카드 효과 카탈로그 (대표 샘플)
|
||
|
|
|
||
|
|
### 4.1 카테고리별
|
||
|
|
|
||
|
|
| 카테고리 | 수량 추정 | 대표 |
|
||
|
|
|---|---|---|
|
||
|
|
| 공격력 증강 | ~25 | G1_AddMaxAttack, G3_BacklineDoubleDmg, G5_FlatDamageMinMaxEqual |
|
||
|
|
| 피해 감소/무효화 | ~18 | G2_ReduceMeeleEnemyDamage, G2_ActivateInvincibleShieldOnKill, G1_ReflectOnRangedDodge |
|
||
|
|
| 회피/회피율 | ~12 | G1_DodgeNextNAttacks, G2_FirstMeleeAlwaysEvade, G1_MaxDodgeWhenHpBelow |
|
||
|
|
| 크리 | ~15 | G2_CriUpAfterCri, G1_ThirdCritDamage, G2_NextSevenHitsCritical, G5_EvadeCrit |
|
||
|
|
| 쉴드 | ~20 | G1_ShieldOnRangedDodge, G1_MaxShieldUpOnLevelUp, G1_SpringShieldToHP |
|
||
|
|
| 회복/생명력 | ~22 | G1_HealOnRangedHit, G1_AngelFeatherHeal, G1_StopExploreHealHP |
|
||
|
|
| 상태이상 부여 | ~15 | G1_EnemySpawnStunChance, G1_StunAllMeleeEnemies, G5_EvadeStun_N |
|
||
|
|
| 특수 투사체 | ~35 | G1_MagicMissile, G1_ThunderOnFifthHit, G4_StartArrowRainRangedImmune, G5_CritTriggerMeteor |
|
||
|
|
| 스킬 카드/특수 | ~18 | G1_GetRandomRareOrEpicSkill, G1_NextLevelChooseTwoSkillCards, G1_CastReaperOnLevelUp |
|
||
|
|
| 수집/보상 | ~12 | G1_GainGoldOnSanctuaryFind, G1_XpGainOnCritKill, G1_CampRechargePotion |
|
||
|
|
| 방어/면역 | ~10 | G2_ActivateInvincibleShieldOnKill, G5_PotionDamageImmunity |
|
||
|
|
|
||
|
|
### 4.2 등급별 경향
|
||
|
|
|
||
|
|
- **G1 112장 (36%)** — 기초재. 모든 런에서 자주 획득.
|
||
|
|
- **G2 73장 (23%)** — 조건부/조합 효과.
|
||
|
|
- **G3 51장 (16%)** — 라인·배수·크리 특수.
|
||
|
|
- **G4 43장 (14%)** — 실드·동일대상·면역 연계.
|
||
|
|
- **G5 32장 (10%)** — 투사체·무적·즉사 최상위 시너지.
|
||
|
|
|
||
|
|
G1 비중이 높은 것은 기획 의도(풀초기/보편 효과)로 해석 가능.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 5. 카드시스템과 밸런싱 훅
|
||
|
|
|
||
|
|
### 5.1 데이터 입력 흐름
|
||
|
|
|
||
|
|
```
|
||
|
|
기획실 .xlsm
|
||
|
|
→ (익스포트 도구) → JSON/CSV
|
||
|
|
→ (코드 생성) → table_cardlist.cs (자동)
|
||
|
|
→ (Awake) → CardListTableData 싱글톤
|
||
|
|
→ (전투 중) → CardSkillData.m_Data → Get_*Value*()
|
||
|
|
```
|
||
|
|
|
||
|
|
**코드상 수치 하드코딩은 확인되지 않음** — 모든 수치는 테이블 필드. → 밸런싱은 테이블만 수정하면 된다는 구조적 전제 성립.
|
||
|
|
|
||
|
|
### 5.2 핫 리로드
|
||
|
|
|
||
|
|
- **현재 불가** — 싱글톤 Awake에서 초기화, 런 중 반영 안 됨. 재시작 필요.
|
||
|
|
- 개선안: ScriptableObject / JSON 원격 동기화 / 기획실 대시보드 연동 — **Phase 1+ 고려**.
|
||
|
|
|
||
|
|
### 5.3 기획실 워크플로 접촉점
|
||
|
|
|
||
|
|
| 단계 | 파일/도구 | 비고 |
|
||
|
|
|---|---|---|
|
||
|
|
| 효과 설계 | 기획 엑셀 | 효과 종류 변경 금지 (규칙) |
|
||
|
|
| 수치 입력 | `f_Value1~3`, `f_LvUpValue1~2` | |
|
||
|
|
| 익스포트 | 도구 경로 | **(확인 필요)** 문서화 필요 |
|
||
|
|
| 코드 생성 | `table_cardlist.cs` 자동 | |
|
||
|
|
| QA | Unity 런타임 | |
|
||
|
|
| 시뮬레이터 검증 | 기획실 매크로 | **코드와 공식 일치 여부 (확인 필요)** |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 6. 리스크 · 이슈
|
||
|
|
|
||
|
|
### 6.1 조건 분기 폭발 (~258 위치)
|
||
|
|
|
||
|
|
- 단일 카드 효과가 여러 `OnEvent_*`에 분산 → 신규 추가 시 수정 누락 위험.
|
||
|
|
- 개선안: `interface ICardEffect` + `CardEffectRegistry` 디스패처 패턴으로 효과별 객체 분리. **(장기 리팩토링 과제)**
|
||
|
|
|
||
|
|
### 6.2 하드코딩 상수 (08 문서와 중복)
|
||
|
|
|
||
|
|
- `3.69` (회피 분모) `Actor.cs:623`
|
||
|
|
- `0.9f` (크리·회피 상한) `MyValue.cs:23`
|
||
|
|
- `eCardType.Max` sentinel — 선택적 테이블화 대상
|
||
|
|
|
||
|
|
### 6.3 구현 누락 후보
|
||
|
|
|
||
|
|
- G5 32장 중 일부 미구현/주석 처리 가능성 — **(확인 필요)** TODO/FIXME/주석 grep
|
||
|
|
- `G1_NullifyDamageEveryNHits` — `Dmg_Immune` 스탯 순서 버그 가능성
|
||
|
|
|
||
|
|
### 6.4 시뮬레이터 동기화
|
||
|
|
|
||
|
|
| 항목 | 코드 | 시뮬 | 상태 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| 피해 15단계 | Actor.Get_Dmg | 엑셀 매크로 | 대조 필요 |
|
||
|
|
| 크리 확률 | RandomTrue + 강제 | 고정% | 대조 필요 |
|
||
|
|
| 회피 상한 | PC 0.9f | ? | **(확인 필요)** |
|
||
|
|
| 카드 효과 트리거 | 분산 | 테이블 | 큰 차이 |
|
||
|
|
|
||
|
|
### 6.5 성능
|
||
|
|
|
||
|
|
- `ObscuredInt/Float` 복호화·재암호화 비용이 **Get_Damage 호출마다** 발생. 크리 판정/피해 계산에서 프레임당 수십 회. → Profiler 측정 필요.
|
||
|
|
|
||
|
|
### 6.6 버그 냄새
|
||
|
|
|
||
|
|
1. 중복 획득 방지 — 특수 아이템 `list_SkillId` 경로 **(확인 필요)**
|
||
|
|
2. OnEvent 순서 의존성 — `AddSkillCard` ↔ `RunSkillCard` 순서
|
||
|
|
3. G5 카드 스킵 로직 — 이미 획득 상태 체크 누락 가능성
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 7. B-2 완료 조건 체크리스트
|
||
|
|
|
||
|
|
**필수**
|
||
|
|
- [ ] 311개 전체 eCardType 하드카피 리스트 (문자열 ID)
|
||
|
|
- [ ] 각 카드의 대표 분기점 매핑 (OnEvent_*)
|
||
|
|
- [ ] G5 미구현/주석 목록 확보
|
||
|
|
- [ ] `table_cardlist` 필드 ↔ 엑셀 컬럼 1:1 매핑 확정
|
||
|
|
- [ ] eLvUpType 전 케이스 동작 테스트
|
||
|
|
- [ ] IsObtainCardSkill 258 호출 위치 전수 지도 (누락 확인)
|
||
|
|
|
||
|
|
**선택**
|
||
|
|
- [ ] 기획 엑셀 매크로 방정식 덤프 (코드 수식과 대조)
|
||
|
|
- [ ] 카드 의존성 그래프
|
||
|
|
- [ ] ObscuredFloat 프로파일링
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 8. 변경 이력
|
||
|
|
|
||
|
|
| 버전 | 일자 | 작성자 | 내용 |
|
||
|
|
|---|---|---|---|
|
||
|
|
| v1 | 2026-04-14 | 개발실장 (Explore 위임) | Phase 0-B-2 초안 |
|