From b110b2dc53ff1f46da58d1e7fc0074b36c85d50f Mon Sep 17 00:00:00 2001 From: JiWoong Sul Date: Tue, 16 Dec 2025 19:33:57 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B2=8C=EC=9E=84=20=EC=8B=9C=EC=8A=A4?= =?UTF-8?q?=ED=85=9C=20=EA=B0=9C=ED=8E=B8=20=EA=B3=84=ED=9A=8D=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=EB=B6=84=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 121KB 단일 문서를 22개 태스크 문서로 분리 - 메인 인덱스 문서 (game-system-overhaul-index.md) 생성 - Phase 1-10 태스크 문서 10개 분리 - 추가 시스템 태스크 문서 10개 분리 - 재미 요소 설계 문서 1개 분리 - 기존 문서는 archive/ 폴더로 이동 --- doc/archive/game-system-overhaul-plan.md | 3511 ++++++++++++++++++++++ doc/game-system-overhaul-index.md | 242 ++ doc/game-system-overhaul-plan.md | 1502 --------- doc/task-ext-audio-access.md | 130 + doc/task-ext-combat.md | 238 ++ doc/task-ext-events.md | 198 ++ doc/task-ext-items.md | 316 ++ doc/task-ext-meta-systems.md | 251 ++ doc/task-ext-platform.md | 184 ++ doc/task-ext-save-data.md | 223 ++ doc/task-ext-settings-infra.md | 160 + doc/task-ext-ui-tech.md | 238 ++ doc/task-ext-world.md | 215 ++ doc/task-fun-design.md | 292 ++ doc/task-phase-01-combat.md | 122 + doc/task-phase-02-items.md | 136 + doc/task-phase-03-skills.md | 90 + doc/task-phase-04-death.md | 122 + doc/task-phase-05-race-class.md | 66 + doc/task-phase-06-balance.md | 119 + doc/task-phase-07-content.md | 83 + doc/task-phase-08-ui.md | 60 + doc/task-phase-09-story.md | 63 + doc/task-phase-10-hall.md | 83 + 24 files changed, 7142 insertions(+), 1502 deletions(-) create mode 100644 doc/archive/game-system-overhaul-plan.md create mode 100644 doc/game-system-overhaul-index.md delete mode 100644 doc/game-system-overhaul-plan.md create mode 100644 doc/task-ext-audio-access.md create mode 100644 doc/task-ext-combat.md create mode 100644 doc/task-ext-events.md create mode 100644 doc/task-ext-items.md create mode 100644 doc/task-ext-meta-systems.md create mode 100644 doc/task-ext-platform.md create mode 100644 doc/task-ext-save-data.md create mode 100644 doc/task-ext-settings-infra.md create mode 100644 doc/task-ext-ui-tech.md create mode 100644 doc/task-ext-world.md create mode 100644 doc/task-fun-design.md create mode 100644 doc/task-phase-01-combat.md create mode 100644 doc/task-phase-02-items.md create mode 100644 doc/task-phase-03-skills.md create mode 100644 doc/task-phase-04-death.md create mode 100644 doc/task-phase-05-race-class.md create mode 100644 doc/task-phase-06-balance.md create mode 100644 doc/task-phase-07-content.md create mode 100644 doc/task-phase-08-ui.md create mode 100644 doc/task-phase-09-story.md create mode 100644 doc/task-phase-10-hall.md diff --git a/doc/archive/game-system-overhaul-plan.md b/doc/archive/game-system-overhaul-plan.md new file mode 100644 index 0000000..dd0efdf --- /dev/null +++ b/doc/archive/game-system-overhaul-plan.md @@ -0,0 +1,3511 @@ +# ASCII Never Die - 게임 시스템 개편 계획 + +## 1. 개요 + +### 1.1 목적 +Progress Quest 클론에서 **실제 게임성을 갖춘 RPG**로 전환한다. +Idle game의 자동 진행 특성은 유지하되, 전투/성장/사망의 의미있는 시스템을 도입한다. + +### 1.2 핵심 변경 사항 +- Stats가 전투에 실제 영향을 미침 +- 사망 시스템 및 부활 메커니즘 +- MP 기반 스킬 시스템 +- 아이템 스탯 및 가중치 +- 레벨 1-100 밸런싱 +- 종족/클래스 특화 + +### 1.3 현재 상태 +| 항목 | 현재 | 목표 | +|------|------|------| +| Stats | 장식용 (CON→HP, INT→MP, WIS→주문, STR→무게만 영향) | 전투력에 직접 영향 | +| 전투 | 시간 경과 시 자동 승리 | 데미지 계산, 승패 결정 | +| 사망 | 없음 | 장비 상실, 부활 버튼 | +| 스킬 | 획득만 (사용 없음) | MP 소모, 쿨타임 | +| 아이템 | 이름만 존재 | 스탯 보정, 가중치 | +| 레벨 | 무한 성장 | 1-100 (100에서 성장 멈춤) | + +--- + +## 2. 수정 단계 (Phase) + +``` +Phase 1: 핵심 전투 시스템 ████████████████████ (기반) +Phase 2: 아이템 시스템 ████████████████ (의존: Phase 1) +Phase 3: 스킬 시스템 ████████████ (의존: Phase 1, 2) +Phase 4: 사망/부활 시스템 ████████ (의존: Phase 1, 2, 3) +Phase 5: 종족/클래스 특화 ██████ (의존: Phase 1) +Phase 6: 밸런싱 ████████████████████ (전체 의존) +Phase 7: 콘텐츠 확장 ████████████ (의존: Phase 6) +Phase 8: UI/UX 개선 ████████ (병렬 가능) +Phase 9: 스토리/엔딩 ██████ (의존: Phase 7) +Phase 10: 명예의 전당 ████ (최종) +``` + +--- + +## 3. Phase 1: 핵심 전투 시스템 + +### 3.1 목표 +Stats가 전투에 실제 영향을 미치도록 전투 계산 로직을 구현한다. + +### 3.2 새로운 Stats 구조 + +```dart +class CombatStats { + // 기본 스탯 (캐릭터 고유) + final int str; // 힘: 물리 공격력 보정 + final int con; // 체력: HP, 방어력 보정 + final int dex; // 민첩: 회피율, 크리티컬율, 명중률 + final int intelligence; // 지능: 마법 공격력, MP + final int wis; // 지혜: 마법 방어력, MP 회복 + final int cha; // 매력: 상점 가격, 드롭률 보정 + + // 파생 스탯 (장비 + 기본 스탯으로 계산) + final int atk; // 공격력 + final int def; // 방어력 + final int magAtk; // 마법 공격력 + final int magDef; // 마법 방어력 + final double criRate; // 크리티컬 확률 (0.0 ~ 1.0) + final double criDamage; // 크리티컬 데미지 배율 (1.5 ~ 3.0) + final double evasion; // 회피율 (0.0 ~ 0.5) + final double accuracy; // 명중률 (0.8 ~ 1.0) + final double blockRate; // 방패 방어율 (0.0 ~ 0.4) + final double parryRate; // 무기로 쳐내기 확률 (0.0 ~ 0.3) + + // 자원 + final int hpMax; + final int hpCurrent; + final int mpMax; + final int mpCurrent; +} +``` + +### 3.3 전투 계산 공식 + +``` +1. 명중 판정 + 명중 = random() < (공격자.accuracy - 방어자.evasion) + +2. 방어 판정 (명중 시) + 방패 방어 = random() < 방어자.blockRate + 무기 쳐내기 = random() < 방어자.parryRate + +3. 데미지 계산 + 기본 데미지 = 공격자.atk * (1 + random() * 0.2) - 방어자.def * 0.5 + + 크리티컬 판정 = random() < 공격자.criRate + if (크리티컬) 데미지 *= 공격자.criDamage + + if (방패 방어) 데미지 *= 0.3 + if (무기 쳐내기) 데미지 *= 0.5 + + 최종 데미지 = max(1, 데미지) + +4. 전투 결과 + 방어자.hp -= 최종 데미지 + if (방어자.hp <= 0) 전투 종료 +``` + +### 3.4 전투 틱 시스템 + +``` +현재: 2초 후 자동 승리 +변경: 매 틱(200ms)마다 공격 교환, HP가 0이 되면 승패 결정 + +전투 흐름: +1. 플레이어 턴 (atk 기반 공격) +2. 몬스터 턴 (몬스터 레벨 기반 공격) +3. HP 체크 +4. 반복 또는 종료 +``` + +#### 3.4.1 공격 속도 시스템 + +```dart +class AttackSpeed { + final int baseDelayMs; // 기본 공격 딜레이 (1000ms) + final double speedModifier; // DEX 기반 속도 배율 + + int get actualDelayMs => (baseDelayMs / speedModifier).round(); +} + +// 공격 속도 계산 +double calculateSpeedModifier(int dex) { + // DEX 10 = 1.0배, DEX 20 = 1.2배, DEX 50 = 1.8배 + return 1.0 + (dex - 10) * 0.02; +} +``` + +| DEX | 공격 속도 배율 | 실제 딜레이 | +|-----|---------------|------------| +| 10 | 1.0x | 1000ms | +| 20 | 1.2x | 833ms | +| 30 | 1.4x | 714ms | +| 50 | 1.8x | 556ms | +| 100 | 2.8x | 357ms | + +**몬스터 공격 속도**: 몬스터 타입별로 고정 (빠름/보통/느림) + +### 3.5 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | CombatStats 클래스 추가, Stats 구조 변경 | +| `core/engine/progress_service.dart` | 전투 틱 로직 변경 | +| `core/util/pq_logic.dart` | 전투 계산 함수 추가 | +| `core/engine/combat_calculator.dart` | **신규** - 전투 계산 전담 | + +### 3.6 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~400 LOC +- 수정 코드: ~200 LOC + +--- + +## 4. Phase 2: 아이템 시스템 + +### 4.1 목표 +아이템에 스탯 보정치를 부여하고, 가중치 시스템을 도입한다. + +### 4.2 아이템 스탯 구조 + +```dart +class ItemStats { + final int atk; // 공격력 보정 + final int def; // 방어력 보정 + final int magAtk; // 마법 공격력 보정 + final int magDef; // 마법 방어력 보정 + final double criRate; // 크리티컬 확률 보정 + final double evasion; // 회피율 보정 + final double blockRate; // 방패 방어율 (방패 전용) + final double parryRate; // 무기 쳐내기 (무기 전용) + + // 추가 효과 + final int hpBonus; + final int mpBonus; + final int strBonus; + final int dexBonus; + // ... 기타 스탯 보너스 +} + +class Equipment { + final String name; + final EquipmentSlot slot; + final int level; // 아이템 레벨 + final int weight; // 가중치 (높을수록 좋은 아이템) + final ItemStats stats; + final ItemRarity rarity; // Common, Uncommon, Rare, Epic, Legendary +} +``` + +### 4.3 아이템 가중치 계산 + +``` +가중치 = 기본값 + (레벨 * 10) + (희귀도 보너스) + (스탯 합계) + +희귀도 보너스: +- Common: 0 +- Uncommon: 50 +- Rare: 150 +- Epic: 400 +- Legendary: 1000 +``` + +### 4.4 자동 장착 로직 + +``` +1. 인벤토리에서 장착 가능한 아이템 필터링 +2. 슬롯별로 그룹화 +3. 각 슬롯에서 가장 높은 가중치 아이템 선택 +4. 무게 제한 체크 (총 무게 ≤ STR 기반 최대 무게) +5. 현재 장비와 비교하여 더 좋으면 교체 +``` + +#### 4.4.1 무게 제한 시스템 + +```dart +class WeightSystem { + /// STR 기반 최대 휴대 가능 무게 + int calculateMaxWeight(int str) { + // 기본 100 + STR당 10 + return 100 + str * 10; + } + + /// 현재 장비 총 무게 + int calculateCurrentWeight(List equipped) { + return equipped.fold(0, (sum, item) => sum + item.weight); + } + + /// 장착 가능 여부 + bool canEquip(Equipment newItem, List current, int str) { + final maxWeight = calculateMaxWeight(str); + final currentWeight = calculateCurrentWeight(current); + final newWeight = currentWeight + newItem.weight; + return newWeight <= maxWeight; + } +} +``` + +| STR | 최대 무게 | 설명 | +|-----|----------|------| +| 10 | 200 | 경장비 + 일부 중장비 | +| 20 | 300 | 대부분의 장비 | +| 30 | 400 | 중장비 풀세트 | +| 50 | 600 | 최중량 장비 | + +**무게 초과 페널티**: 장착 불가 (자동 장착 시 무게 고려) + +### 4.5 아이템 생성 공식 + +```dart +/// 아이템 스탯 생성 (레벨 기반) +ItemStats generateItemStats(int level, ItemRarity rarity, EquipmentSlot slot) { + final rarityMultiplier = { + ItemRarity.common: 1.0, + ItemRarity.uncommon: 1.3, + ItemRarity.rare: 1.7, + ItemRarity.epic: 2.2, + ItemRarity.legendary: 3.0, + }[rarity]!; + + final baseValue = (level * 2 * rarityMultiplier).round(); + + // 슬롯별 주요 스탯 결정 + return switch (slot) { + EquipmentSlot.weapon => ItemStats(atk: baseValue, ...), + EquipmentSlot.shield => ItemStats(def: baseValue ~/ 2, blockRate: 0.1, ...), + EquipmentSlot.armor => ItemStats(def: baseValue, ...), + // ... + }; +} +``` + +### 4.6 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | Equipment 구조 변경, ItemStats 추가 | +| `core/model/equipment_slot.dart` | 슬롯별 기본 스탯 정의 | +| `core/util/pq_logic.dart` | 아이템 생성 로직 변경 | +| `core/engine/item_service.dart` | **신규** - 아이템 관리 전담 | +| `data/pq_config_data.dart` | 아이템 기본 데이터 확장 | + +### 4.7 예상 작업량 +- 예상 파일 수: 5-6개 +- 신규 코드: ~500 LOC +- 수정 코드: ~300 LOC + +--- + +## 5. Phase 3: 스킬 시스템 + +### 5.1 목표 +MP를 소모하여 스킬을 사용하고, 쿨타임을 관리한다. + +### 5.2 스킬 구조 + +```dart +class Skill { + final String id; + final String name; + final SkillType type; // attack, heal, buff, debuff + final int mpCost; + final int cooldownMs; // 쿨타임 (밀리초) + final int power; // 스킬 위력 + + // 효과 + final double damageMultiplier; // 공격 스킬: 데미지 배율 + final int healAmount; // 회복 스킬: 회복량 + final BuffEffect? buff; // 버프 효과 +} + +class SkillState { + final String skillId; + final int lastUsedMs; // 마지막 사용 시간 + final int rank; // 스킬 레벨 + + bool isReady(int currentMs) => + currentMs - lastUsedMs >= skill.cooldownMs; +} +``` + +### 5.3 MP 시스템 + +``` +MP 회복: +- 비전투 시: 50ms당 1 회복 +- 전투 중: 회복 없음 (또는 WIS에 비례하여 느리게 회복) +- 전투 종료: 즉시 전체 회복 + +MP 소모: +- 스킬 사용 시 즉시 차감 +- MP 부족 시 스킬 사용 불가 (일반 공격으로 대체) +``` + +### 5.4 스킬 사용 로직 + +``` +자동 스킬 사용 우선순위: +1. HP < 30% → 회복 스킬 (있으면) +2. 보스전 → 가장 강력한 공격 스킬 +3. 일반 전투 → MP 효율이 좋은 스킬 +4. MP < 20% → 일반 공격만 + +수동 개입: +- 현재 버전에서는 자동만 지원 +- 향후 수동 스킬 사용 UI 추가 가능 +``` + +### 5.5 스킬 목록 예시 + +| 스킬명 | 타입 | MP | 쿨타임 | 효과 | +|--------|------|-----|--------|------| +| Debug Strike | attack | 10 | 3s | 데미지 150% | +| Memory Leak | attack | 25 | 8s | 데미지 250%, 적 방어력 -20% | +| Hot Reload | heal | 20 | 10s | HP 30% 회복 | +| Safe Mode | buff | 30 | 30s | 방어력 +50%, 10초 지속 | +| Core Dump | attack | 50 | 20s | 데미지 400% | +| Kernel Panic | attack | 100 | 60s | 데미지 800%, 자신 HP -10% | + +### 5.6 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | SkillState 추가 | +| `core/model/skill.dart` | **신규** - 스킬 정의 | +| `core/engine/skill_service.dart` | **신규** - 스킬 사용 로직 | +| `core/engine/progress_service.dart` | MP 회복 로직, 스킬 자동 사용 | +| `data/skill_data.dart` | **신규** - 스킬 데이터 | + +### 5.7 예상 작업량 +- 예상 파일 수: 5-6개 +- 신규 코드: ~600 LOC +- 수정 코드: ~200 LOC + +--- + +## 6. Phase 4: 사망/부활 시스템 + +### 6.1 목표 +사망 개념을 도입하고, 페널티 및 부활 메커니즘을 구현한다. + +### 6.2 사망 조건 + +``` +사망 = HP <= 0 + +사망 시 처리: +1. 게임 루프 일시 정지 +2. 장착 중인 모든 장비 제거 (인벤토리로 이동하지 않음 - 상실) +3. 인벤토리 아이템 유지 +4. 골드 유지 +5. 경험치 유지 (레벨 다운 없음) +6. 사망 UI 표시 (부활 버튼) +``` + +### 6.3 부활 프로세스 + +``` +부활 버튼 클릭 시: +1. HP/MP 전체 회복 +2. 부활 위치로 이동 (안전 지역: 마을) +3. 자동으로 샵 이동 +4. 골드로 구매 가능한 최고 장비 자동 구매 +5. 각 슬롯에 장비 자동 장착 +6. 게임 루프 재개 (퀘스트 진행도 유지) +``` + +#### 6.3.1 부활 위치 + +| 상황 | 부활 위치 | 설명 | +|------|----------|------| +| 일반 사망 | 마을 (시작 지점) | 안전 지역, 샵 접근 가능 | +| 보스전 사망 | 보스 던전 입구 | 보스방 직전 | +| 퀘스트 중 사망 | 퀘스트 시작 지점 | 퀘스트 진행도 유지 | + +#### 6.3.2 부활 페널티 완화 (선택적) + +| 아이템/스킬 | 효과 | +|------------|------| +| 부활의 부적 (소모품) | 사망 시 장비 1개 보존 | +| 영혼 보호 (패시브) | 사망 시 50% 확률로 장비 1개 보존 | +| 불사 버프 | 사망 시 HP 1로 생존 (1회) | + +### 6.4 샵 시스템 + +```dart +class Shop { + /// 현재 레벨에서 구매 가능한 장비 목록 + List getAvailableItems(int playerLevel, int gold); + + /// 최적의 장비 세트 자동 구매 + PurchaseResult autoBuy(int playerLevel, int gold, List emptySlots); +} + +class PurchaseResult { + final List purchased; + final int totalCost; + final int remainingGold; +} +``` + +### 6.5 장비 가격 공식 + +``` +기본 가격 = 아이템 레벨 * 50 * 희귀도 배율 + +희귀도 배율: +- Common: 1.0 +- Uncommon: 2.0 +- Rare: 5.0 +- Epic: 15.0 +- Legendary: 50.0 + +판매 가격 = 구매 가격 * 0.3 +``` + +### 6.6 사망 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ YOU DIED │ +│ │ +│ Level 45 버그 헌터 │ +│ │ +│ 사망 원인: 커널 패닉 │ +│ │ +│ ───────────────────────── │ +│ 장비 상실: 7개 │ +│ 보유 골드: 15,420 │ +│ ───────────────────────── │ +│ │ +│ [ 부활하기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +### 6.7 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | isDead 플래그, deathInfo 추가 | +| `core/engine/progress_service.dart` | 사망 판정 로직 | +| `core/engine/resurrection_service.dart` | **신규** - 부활 처리 | +| `core/engine/shop_service.dart` | **신규** - 샵 로직 | +| `features/game/widgets/death_overlay.dart` | **신규** - 사망 UI | +| `features/game/game_session_controller.dart` | 사망/부활 상태 관리 | + +### 6.8 예상 작업량 +- 예상 파일 수: 6-7개 +- 신규 코드: ~500 LOC +- 수정 코드: ~200 LOC + +--- + +## 7. Phase 5: 종족/클래스 특화 + +### 7.1 목표 +종족과 클래스에 고유한 능력치 보정과 특수 능력을 부여한다. + +### 7.2 종족 특성 + +```dart +class RaceTraits { + final String raceId; + final Map statModifiers; // 스탯 보정 + final List passives; // 패시브 능력 + final double expMultiplier; // 경험치 배율 +} +``` + +| 종족 | STR | CON | DEX | INT | WIS | CHA | 특수 능력 | +|------|-----|-----|-----|-----|-----|-----|----------| +| Byte Human | 0 | 0 | 0 | 0 | 0 | +2 | 경험치 +10% | +| Null Elf | -1 | -1 | +2 | +2 | 0 | 0 | 마법 데미지 +15% | +| Buffer Dwarf | +2 | +2 | -1 | -1 | 0 | 0 | 방어력 +10% | +| Stack Goblin | -1 | -1 | +3 | 0 | 0 | +1 | 크리티컬 확률 +5% | +| Heap Troll | +3 | +3 | -2 | -2 | 0 | 0 | HP +20% | +| Pointer Fairy | -2 | -2 | +2 | +2 | +2 | 0 | MP +20% | +| Coredump Undead | +1 | +2 | -1 | 0 | 0 | -2 | 사망 시 장비 1개 유지 | + +### 7.3 클래스 특성 + +```dart +class ClassTraits { + final String classId; + final Map statModifiers; + final List startingSkills; // 시작 스킬 + final List classSkills; // 클래스 전용 스킬 + final EquipmentRestriction restrictions; // 장비 제한 +} +``` + +| 클래스 | 주요 스탯 | 장비 제한 | 특수 능력 | +|--------|----------|----------|----------| +| Bug Hunter | STR/DEX | 전체 가능 | 일반 공격 +20% | +| Debugger Paladin | STR/CON | 중갑, 방패 | 방어력 +15%, 회복력 +10% | +| Compiler Mage | INT/WIS | 경갑, 지팡이 | 마법 데미지 +25% | +| Refactor Monk | DEX/WIS | 경갑, 맨손 | 회피율 +15%, 연속 공격 | +| Pointer Assassin | DEX/STR | 경갑, 단검 | 크리티컬 +20%, 첫 공격 2배 | +| Garbage Collector | CON/STR | 중갑 | HP +30%, 전투 후 HP 10% 회복 | + +### 7.4 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/race_traits.dart` | **신규** - 종족 특성 | +| `core/model/class_traits.dart` | **신규** - 클래스 특성 | +| `data/race_data.dart` | **신규** - 종족 데이터 | +| `data/class_data.dart` | **신규** - 클래스 데이터 | +| `core/engine/stat_calculator.dart` | **신규** - 최종 스탯 계산 | +| `features/character/character_creation.dart` | 종족/클래스 선택 UI 개선 | + +### 7.5 예상 작업량 +- 예상 파일 수: 6-7개 +- 신규 코드: ~400 LOC +- 수정 코드: ~150 LOC + +--- + +## 8. Phase 6: 밸런싱 + +### 8.1 목표 +레벨 1-100 구간에서 적절한 난이도 곡선을 설계한다. + +### 8.2 레벨 구간 설계 + +| 구간 | 레벨 | 특징 | 예상 플레이 시간 | +|------|------|------|-----------------| +| 초반 | 1-20 | 튜토리얼, 기본 시스템 학습 | 1-2시간 | +| 중반 | 21-50 | 본격적인 성장, 다양한 스킬 | 3-5시간 | +| 후반 | 51-80 | 고급 장비, 어려운 몬스터 | 5-8시간 | +| 엔드게임 | 81-100 | 최종 보스, 명예의 전당 | 3-5시간 | + +### 8.3 경험치 곡선 + +``` +레벨업 필요 경험치 = 기본값 * (1.15 ^ 레벨) + +기본값 = 100 +레벨 10: 405 exp +레벨 50: 108,366 exp +레벨 100: 11,739,085 exp +``` + +### 8.4 몬스터 스탯 스케일링 + +```dart +MonsterStats generateMonster(int level, MonsterType type) { + final baseStats = MonsterStats( + hp: 50 + level * 20 + (level * level / 5).round(), + atk: 5 + level * 3, + def: 2 + level * 2, + exp: 10 + level * 5, + gold: 5 + level * 3, + ); + + return _applyTypeModifier(baseStats, type); +} +``` + +#### 8.4.1 몬스터 타입별 배율 + +| 타입 | HP | ATK | DEF | EXP | GOLD | +|------|-----|-----|-----|-----|------| +| 일반 | 1.0x | 1.0x | 1.0x | 1.0x | 1.0x | +| 정예 | 2.0x | 1.3x | 1.2x | 2.0x | 2.0x | +| 미니보스 | 5.0x | 1.5x | 1.5x | 5.0x | 5.0x | +| 보스 | 10.0x | 2.0x | 2.0x | 15.0x | 10.0x | +| 최종보스 | 20.0x | 2.5x | 2.5x | 50.0x | 30.0x | + +#### 8.4.2 보스 몬스터 특수 스탯 + +```dart +class BossStats extends MonsterStats { + final List phases; + final double enrageThreshold; // 분노 HP % + final double enrageMultiplier; // 분노 시 스탯 배율 + final bool hasShield; // 보호막 여부 + final int shieldAmount; // 보호막 수치 +} +``` + +| 보스 | 특수 능력 | +|------|----------| +| Syntax Error Dragon | 페이즈 3에서 연속 공격 | +| Memory Leak Hydra | HP 30% 이하 시 회복 | +| Buffer Overflow Titan | 보호막 (일정 데미지 흡수) | +| Kernel Panic Archon | 분노 시 스턴 공격 | +| Glitch God | 5페이즈, 각 페이즈별 완전히 다른 패턴 | + +### 8.5 사망 확률 목표 + +| 레벨 구간 | 목표 사망 확률 (전투당) | +|----------|----------------------| +| 1-20 | 1-3% | +| 21-50 | 3-5% | +| 51-80 | 5-10% | +| 81-100 | 10-20% | + +### 8.6 밸런스 테스트 도구 + +```dart +/// 시뮬레이션으로 밸런스 검증 +class BalanceSimulator { + /// 특정 레벨 구간을 N회 시뮬레이션 + SimulationResult simulate({ + required int startLevel, + required int endLevel, + required int iterations, + }); +} + +class SimulationResult { + final double averageDeaths; + final double averageTimeMinutes; + final double survivalRate; + final List deathCauses; +} +``` + +### 8.7 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/util/balance_constants.dart` | **신규** - 밸런스 상수 | +| `core/util/pq_logic.dart` | 경험치/몬스터 스케일링 | +| `data/pq_config_data.dart` | 몬스터 레벨 재조정 | +| `test/balance_test.dart` | **신규** - 밸런스 테스트 | + +### 8.8 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~300 LOC +- 수정 코드: ~400 LOC +- 테스트 및 조정: 반복 작업 필요 + +--- + +## 9. Phase 7: 콘텐츠 확장 + +### 9.1 목표 +더 많은 몬스터, 아이템, 애니메이션을 추가한다. + +### 9.2 몬스터 확장 + +현재: ~100종 +목표: ~200종 + +추가할 몬스터 카테고리: +- 레벨 81-100 엔드게임 몬스터 (30종) +- 보스 몬스터 (10종, 각 Act 마다) +- 미니 보스 (20종) +- 특수 이벤트 몬스터 (20종) +- 퀘스트 전용 몬스터 (20종) + +### 9.3 아이템 확장 + +현재: 이름만 존재 +목표: 스탯이 있는 300+ 아이템 + +카테고리별 추가: +- 무기 (50종): 검, 도끼, 활, 지팡이, 단검 등 +- 방어구 (80종): 투구, 갑옷, 장갑, 부츠, 망토 +- 방패 (30종) +- 악세서리 (50종): 반지, 목걸이, 귀걸이 +- 소모품 (50종): 물약, 스크롤 + +### 9.4 ASCII 애니메이션 확장 + +#### 9.4.1 전투 결과별 애니메이션 + +| 상황 | 애니메이션 | +|------|----------| +| 일반 공격 | 기존 battle_mode | +| 크리티컬 히트 | 화려한 이펙트 | +| 회피 성공 | 살짝 비켜가는 모션 | +| 방패 방어 | 방패 들어올리기 | +| 스킬 사용 | 스킬별 고유 애니메이션 | +| 사망 | 쓰러지는 애니메이션 | +| 레벨업 | 빛나는 이펙트 | + +#### 9.4.2 몬스터별 애니메이션 + +```dart +class MonsterAnimation { + final String monsterId; + final List idleFrames; + final List attackFrames; + final List hitFrames; + final List deathFrames; +} +``` + +카테고리별 기본 애니메이션: +- 버그류 (곤충 형태) +- 언데드류 (좀비, 유령) +- 드래곤류 (대형) +- 휴머노이드류 (NPC형) +- 기계류 (로봇, 바이러스) + +### 9.5 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `data/pq_config_data.dart` | 몬스터/아이템 데이터 확장 | +| `data/ascii_animation_data.dart` | 애니메이션 프레임 추가 | +| `data/monster_animations.dart` | **신규** - 몬스터별 애니메이션 | +| `features/game/widgets/ascii_animation_card.dart` | 상황별 애니메이션 선택 | + +### 9.6 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~1000 LOC (대부분 데이터) +- 수정 코드: ~200 LOC + +--- + +## 10. Phase 8: UI/UX 개선 + +### 10.1 목표 +능력치 변화를 실시간으로 표시하고, 전반적인 UI를 개선한다. + +### 10.2 실시간 스탯 변화 표시 + +``` +┌─ Stats ─────────────────┐ +│ HP: 450/500 ████████░░ │ +│ MP: 80/120 ██████░░░░ │ +│ │ +│ ATK: 125 (+15) ▲ │ ← 장비 변경 시 변화량 표시 +│ DEF: 89 (-5) ▼ │ +│ CRI: 12.5% │ +│ EVA: 8.3% │ +└─────────────────────────┘ +``` + +### 10.3 전투 로그 + +``` +┌─ Combat Log ────────────────────┐ +│ > 문법 오류를 공격! 45 데미지 │ +│ > 문법 오류의 반격! 12 데미지 │ +│ > 크리티컬! 98 데미지 │ +│ > Debug Strike 사용! 150 데미지 │ +│ > 문법 오류 처치! +25 exp │ +└─────────────────────────────────┘ +``` + +### 10.4 알림 시스템 + +| 이벤트 | 표시 방식 | +|--------|----------| +| 레벨업 | 화면 중앙 팝업 + 사운드 | +| 장비 획득 | 우측 하단 토스트 | +| 스탯 변화 | 해당 스탯 옆 애니메이션 | +| 사망 위험 (HP < 20%) | HP 바 깜빡임 | +| 스킬 쿨타임 완료 | 스킬 아이콘 빛남 | + +### 10.5 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `features/game/widgets/stats_panel.dart` | 스탯 변화 애니메이션 | +| `features/game/widgets/combat_log.dart` | **신규** - 전투 로그 | +| `features/game/widgets/notification_overlay.dart` | **신규** - 알림 | +| `core/service/notification_service.dart` | **신규** - 알림 관리 | + +### 10.6 예상 작업량 +- 예상 파일 수: 5-6개 +- 신규 코드: ~400 LOC +- 수정 코드: ~200 LOC + +--- + +## 11. Phase 9: 스토리/엔딩 + +### 11.1 목표 +프롤로그부터 엔딩까지 일관된 스토리를 구성한다. + +### 11.2 스토리 구조 + +``` +Act I (레벨 1-20): 각성 +- 프롤로그: 코드의 신으로부터 비전을 받음 +- 마을에서 기본 훈련 +- 첫 번째 던전: 버그 둥지 +- Act I 보스: Syntax Error Dragon + +Act II (레벨 21-40): 성장 +- 디버거 기사단 가입 +- 손상된 네트워크 탐험 +- 배신자 발견 +- Act II 보스: Memory Leak Hydra + +Act III (레벨 41-60): 시련 +- 널 왕국 진입 +- 고대 컴파일러의 시험 +- 동료의 희생 +- Act III 보스: Buffer Overflow Titan + +Act IV (레벨 61-80): 결전 +- 글리치 신의 성채 침입 +- 최후의 동맹 결성 +- Act IV 보스: Kernel Panic Archon + +Act V (레벨 81-100): 종말 +- 글리치 신과의 최종 대결 +- 다중 페이즈 보스전 +- 엔딩: 시스템 재부팅, 평화 회복 +``` + +### 11.3 시네마틱 개선 + +각 Act 전환 시: +- 전용 시네마틱 텍스트 (5-10개 단계) +- ASCII 아트 일러스트 +- 분위기에 맞는 색상 테마 + +### 11.4 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `data/story_data.dart` | **신규** - 스토리 텍스트 | +| `data/game_text_l10n.dart` | 시네마틱 텍스트 확장 | +| `core/engine/story_service.dart` | **신규** - 스토리 진행 관리 | +| `features/game/widgets/cinematic_view.dart` | **신규** - 시네마틱 UI | + +### 11.5 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~600 LOC (대부분 텍스트) +- 수정 코드: ~100 LOC + +--- + +## 12. Phase 10: 명예의 전당 + +### 12.1 목표 +게임 클리어 시 캐릭터를 명예의 전당에 등재한다. + +### 12.2 클리어 조건 + +``` +클리어 = 레벨 100 달성 + 글리치 신 처치 +``` + +### 12.3 명예의 전당 데이터 + +```dart +class HallOfFameEntry { + final String id; + final String characterName; + final String race; + final String klass; + final int level; + final Duration totalPlayTime; + final int totalDeaths; + final int monstersKilled; + final DateTime clearedAt; + + // 향후 아스키 아레나용 + final CombatStats finalStats; + final List finalEquipment; + final List skills; +} +``` + +### 12.4 명예의 전당 UI + +``` +╔═══════════════════════════════════════════════════╗ +║ 명예의 전당 ║ +╠═══════════════════════════════════════════════════╣ +║ ║ +║ 1. 버퍼 드워프 디버거 성기사 "CodeSlayer" ║ +║ Lv.100 | 12시간 34분 | 사망 3회 ║ +║ 2024.03.15 ║ +║ ║ +║ 2. 널 엘프 컴파일러 마법사 "NullMaster" ║ +║ Lv.100 | 15시간 22분 | 사망 7회 ║ +║ 2024.03.10 ║ +║ ║ +║ 3. 스택 고블린 포인터 암살자 "StackKiller" ║ +║ Lv.100 | 18시간 05분 | 사망 12회 ║ +║ 2024.03.08 ║ +║ ║ +╚═══════════════════════════════════════════════════╝ +``` + +### 12.5 클리어 후 처리 + +``` +1. 축하 시네마틱 표시 +2. 명예의 전당 등재 +3. 통계 표시 (플레이 시간, 사망 횟수, 처치 몬스터 등) +4. "새 게임 시작" 버튼 +5. 기존 캐릭터 데이터는 명예의 전당에만 보존 +``` + +### 12.6 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/hall_of_fame.dart` | **신규** - 명예의 전당 모델 | +| `core/storage/hall_of_fame_storage.dart` | **신규** - 저장/로드 | +| `features/hall_of_fame/hall_of_fame_screen.dart` | **신규** - UI | +| `features/game/game_session_controller.dart` | 클리어 처리 | + +### 12.7 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~400 LOC +- 수정 코드: ~100 LOC + +--- + +## 13. 추가 권장 사항 + +### 13.1 사운드/음악/진동 시스템 + +#### 13.1.1 사운드 효과 (SFX) + +| 상황 | 효과음 | 우선순위 | +|------|--------|----------| +| 일반 공격 | 타격음 | 상 | +| 크리티컬 히트 | 강한 타격음 + 효과음 | 상 | +| 스킬 사용 | 스킬별 고유 효과음 | 중 | +| 피격 | 피해 효과음 | 상 | +| 사망 | 쓰러지는 효과음 | 상 | +| 레벨업 | 팡파레 | 상 | +| 아이템 획득 | 획득 효과음 (희귀도별 차등) | 중 | +| 장비 장착 | 장착 효과음 | 하 | +| 퀘스트 완료 | 완료 효과음 | 중 | +| UI 조작 | 버튼 클릭음 | 하 | + +#### 13.1.2 배경 음악 (BGM) + +| 상황 | BGM 타입 | 우선순위 | +|------|----------|----------| +| 메인 화면 | 웅장한 타이틀 테마 | 중 | +| 일반 탐험 | 평화로운 필드 음악 | 중 | +| 전투 중 | 긴박한 전투 음악 | 상 | +| 보스전 | 강렬한 보스 테마 | 상 | +| 사망 화면 | 슬픈/긴장된 음악 | 중 | +| 시네마틱 | 스토리 테마 | 중 | +| 명예의 전당 | 영광스러운 엔딩 테마 | 중 | + +#### 13.1.3 진동 (모바일 전용) + +| 상황 | 진동 패턴 | 강도 | +|------|----------|------| +| 일반 공격 | 짧은 단일 진동 | 약 | +| 크리티컬 히트 | 강한 단일 진동 | 강 | +| 피격 | 짧은 이중 진동 | 중 | +| 사망 | 긴 진동 | 강 | +| 레벨업 | 리듬 있는 연속 진동 | 중 | +| 희귀 아이템 획득 | 짧은 삼중 진동 | 중 | +| 보스 등장 | 점점 강해지는 진동 | 강 | + +#### 13.1.4 구현 방안 + +```dart +// 사운드 서비스 +class AudioService { + void playSfx(SfxType type); + void playBgm(BgmType type); + void stopBgm(); + void setVolume(double sfx, double bgm); +} + +// 진동 서비스 (모바일) +class HapticService { + void vibrate(HapticPattern pattern); + bool get isSupported; +} +``` + +--- + +### 13.2 업적 시스템 + +#### 13.2.1 업적 카테고리 + +| 카테고리 | 예시 업적 | +|----------|----------| +| **전투** | 첫 번째 몬스터 처치, 100마리 처치, 1000마리 처치, 무피해 보스 처치 | +| **성장** | 레벨 10 달성, 레벨 50 달성, 레벨 100 달성 | +| **수집** | 첫 에픽 아이템, 전설 아이템 획득, 모든 슬롯 에픽 이상 장착 | +| **탐험** | 첫 퀘스트 완료, 100개 퀘스트 완료, 모든 Act 클리어 | +| **생존** | 10연전 생존, HP 1로 생존, 사망 없이 Act 1 클리어 | +| **스킬** | 첫 스킬 사용, 스킬로 100마리 처치, 모든 스킬 습득 | +| **도전** | 레벨 10 이하로 Act 1 보스 처치, 장비 없이 10마리 처치 | +| **히든** | 특정 조합 발견, 이스터에그 발견 | + +#### 13.2.2 업적 보상 + +| 등급 | 보상 | +|------|------| +| 브론즈 | 골드 100-500 | +| 실버 | 골드 500-2000, 아이템 박스 | +| 골드 | 골드 2000-10000, 희귀 아이템 박스 | +| 플래티넘 | 전설 아이템 박스, 특별 칭호 | + +#### 13.2.3 업적 UI + +``` +┌─ 업적 ──────────────────────────┐ +│ ★ 전투 [12/25] │ +│ ☑ 첫 번째 사냥꾼 - 몬스터 처치│ +│ ☑ 백전용사 - 100마리 처치 │ +│ ☐ 천인의 적 - 1000마리 처치 │ +│ │ +│ ★ 성장 [3/10] │ +│ ☑ 신입 개발자 - 레벨 10 │ +│ ☐ 시니어 개발자 - 레벨 50 │ +└─────────────────────────────────┘ +``` + +--- + +### 13.3 도감 시스템 + +#### 13.3.1 도감 종류 + +| 도감 | 기록 내용 | 수집 조건 | +|------|----------|----------| +| **몬스터 도감** | 이름, 레벨 범위, 드롭 아이템, 출현 지역 | 한번이라도 처치 | +| **아이템 도감** | 이름, 스탯, 희귀도, 획득 방법 | 한번이라도 획득 | +| **스킬 도감** | 이름, 효과, MP 소모, 쿨타임 | 한번이라도 습득 | +| **NPC 도감** | 이름, 역할, 등장 시네마틱 | 시네마틱에서 등장 | + +#### 13.3.2 몬스터 도감 상세 + +```dart +class MonsterEntry { + final String id; + final String name; + final int minLevel; + final int maxLevel; + final List dropItems; + final String description; + final int killCount; // 처치 횟수 + final DateTime firstMet; // 첫 조우 시간 + final bool isDefeated; // 처치 여부 +} +``` + +#### 13.3.3 도감 UI + +``` +┌─ 몬스터 도감 [127/200] ─────────┐ +│ │ +│ ┌──────┐ Syntax Error │ +│ │ ∧∧∧ │ Lv. 1-5 │ +│ │ \○/ │ 드롭: 오타, 구두점 │ +│ │ │ │ 처치: 47회 │ +│ └──────┘ │ +│ │ +│ ┌──────┐ Memory Leak │ +│ │ ~~~ │ Lv. 6-12 │ +│ │ ⊂⊃ │ 드롭: 누수 바이트 │ +│ │ ~~~ │ 처치: 23회 │ +│ └──────┘ │ +│ │ +│ ┌──────┐ ??? │ +│ │ ? │ 미발견 │ +│ └──────┘ │ +└─────────────────────────────────┘ +``` + +#### 13.3.4 수집률 보상 + +| 수집률 | 보상 | +|--------|------| +| 25% | 칭호 "수집가 견습생" | +| 50% | 드롭률 +5% | +| 75% | 칭호 "마스터 수집가" | +| 100% | 전설 아이템 + 칭호 "완벽주의자" | + +--- + +### 13.4 통계 화면 + +#### 13.4.1 통계 카테고리 + +| 카테고리 | 통계 항목 | +|----------|----------| +| **시간** | 총 플레이 시간, 현재 세션 시간, 평균 세션 시간 | +| **전투** | 총 전투 횟수, 처치 몬스터 수, 총 데미지, 최고 단일 데미지, 크리티컬 횟수 | +| **생존** | 총 사망 횟수, 사망 원인 Top 5, 최장 생존 시간, 연속 전투 생존 기록 | +| **획득** | 총 획득 골드, 총 획득 아이템, 희귀도별 아이템 수, 가장 비싼 아이템 | +| **스킬** | 총 스킬 사용 횟수, 스킬별 사용 횟수, 스킬 데미지 합계, 가장 많이 쓴 스킬 | +| **탐험** | 완료 퀘스트 수, 방문 지역 수, 현재 Act, 최고 도달 레벨 | +| **효율** | 시간당 경험치, 시간당 골드, 평균 전투 시간, 승률 | + +#### 13.4.2 통계 UI + +``` +┌─ 플레이 통계 ───────────────────┐ +│ │ +│ ⏱ 플레이 시간 │ +│ 총: 15시간 34분 │ +│ 현재 세션: 2시간 12분 │ +│ │ +│ ⚔ 전투 │ +│ 처치 몬스터: 1,247마리 │ +│ 총 데미지: 458,291 │ +│ 최고 데미지: 2,847 (크리티컬) │ +│ 크리티컬 횟수: 312회 │ +│ │ +│ 💀 사망 │ +│ 총 사망: 7회 │ +│ ┌ 사망 원인 Top 3 ┐ │ +│ │ 1. 커널 패닉 (3회)│ │ +│ │ 2. 메모리 누수 (2회)│ │ +│ │ 3. 스택 오버플로우 (2회)│ │ +│ └─────────────────┘ │ +│ │ +│ 💰 획득 │ +│ 총 골드: 124,560 │ +│ 아이템: 892개 │ +│ 전설: 3개 | 에픽: 12개 │ +└─────────────────────────────────┘ +``` + +#### 13.4.3 통계 데이터 구조 + +```dart +class GameStatistics { + // 시간 + final Duration totalPlayTime; + final Duration currentSessionTime; + + // 전투 + final int totalBattles; + final int monstersKilled; + final int totalDamageDealt; + final int highestDamage; + final int criticalHits; + + // 생존 + final int totalDeaths; + final Map deathCauses; + final Duration longestSurvival; + + // 획득 + final int totalGoldEarned; + final int totalItemsObtained; + final Map itemsByRarity; + + // 스킬 + final int totalSkillUses; + final Map skillUseCounts; + + // 탐험 + final int questsCompleted; + final int highestLevel; + final int currentAct; +} +``` + +--- + +### 13.5 설정 화면 + +| 설정 항목 | 옵션 | +|----------|------| +| 게임 속도 | 0.5x, 1x, 2x, 5x | +| 자동 저장 간격 | 1분, 5분, 10분 | +| SFX 볼륨 | 0-100% | +| BGM 볼륨 | 0-100% | +| 진동 | 켜기/끄기 (모바일) | +| 알림 표시 | 켜기/끄기 | +| 전투 로그 | 간략/상세/끄기 | +| 언어 | 한국어/English | + +#### 13.5.1 데이터 관리 설정 + +| 설정 항목 | 설명 | 경고 | +|----------|------|------| +| 튜토리얼 초기화 | 튜토리얼 다시 보기 | - | +| 도움말 초기화 | 모든 도움말 팁 다시 표시 | - | +| 캐시 삭제 | 임시 파일 삭제 | - | +| 설정 초기화 | 모든 설정을 기본값으로 | 확인 필요 | +| 현재 캐릭터 삭제 | 현재 슬롯 데이터 삭제 | 2중 확인 필요 | +| 모든 데이터 삭제 | 전체 초기화 | 3중 확인 + 입력 확인 | + +#### 13.5.2 데이터 삭제 확인 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ ⚠️ 모든 데이터 삭제 │ +│ │ +│ 이 작업은 되돌릴 수 없습니다! │ +│ │ +│ 삭제될 항목: │ +│ • 모든 캐릭터 (5개 슬롯) │ +│ • 명예의 전당 기록 │ +│ • 업적 │ +│ • 통계 │ +│ • 설정 │ +│ │ +│ 확인하려면 "삭제합니다"를 입력: │ +│ ┌───────────────────────────┐ │ +│ │ │ │ +│ └───────────────────────────┘ │ +│ │ +│ [ 취소 ] [ 삭제 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.6 성능 최적화 + +| 항목 | 현재 | 개선 방안 | +|------|------|----------| +| 상태 업데이트 | 매 틱마다 전체 rebuild | 변경된 부분만 업데이트 | +| 애니메이션 | Timer 기반 | AnimationController 사용 | +| 저장 | 자동 저장 빈번 | 변경 감지 후 디바운스 | + +### 13.7 테스트 전략 + +| 테스트 유형 | 대상 | 도구 | +|------------|------|------| +| 유닛 테스트 | 전투 계산, 스탯 계산 | flutter_test | +| 위젯 테스트 | UI 컴포넌트 | flutter_test | +| 통합 테스트 | 전체 게임 플로우 | integration_test | +| 밸런스 테스트 | 시뮬레이션 | 커스텀 도구 | + +--- + +### 13.8 튜토리얼 시스템 + +#### 13.8.1 튜토리얼 흐름 + +``` +첫 실행 감지 → 튜토리얼 시작 → 단계별 가이드 → 완료 보상 → 본 게임 시작 +``` + +#### 13.8.2 튜토리얼 단계 + +| 단계 | 내용 | 하이라이트 UI | 완료 조건 | +|------|------|--------------|----------| +| 1 | 게임 소개 | 전체 화면 | 탭하여 계속 | +| 2 | 캐릭터 스탯 설명 | 스탯 패널 | 스탯 패널 탭 | +| 3 | 전투 시스템 설명 | 전투 영역 | 첫 몬스터 처치 | +| 4 | 장비 시스템 설명 | 장비 패널 | 첫 장비 장착 | +| 5 | 스킬 사용 설명 | 스킬 바 | 첫 스킬 사용 | +| 6 | 경험치/레벨업 설명 | 경험치 바 | 레벨 2 달성 | +| 7 | 퀘스트 설명 | 퀘스트 패널 | 첫 퀘스트 확인 | +| 8 | 사망/부활 설명 | 안내 팝업 | 탭하여 계속 | +| 9 | 설정 및 기타 | 설정 버튼 | 설정 화면 열기 | +| 10 | 튜토리얼 완료 | 보상 팝업 | 보상 수령 | + +#### 13.8.3 튜토리얼 UI + +``` +┌─────────────────────────────────────┐ +│ ┌─────────────────────────────┐ │ +│ │ 하이라이트된 영역 │◄───│ 이 부분을 탭해보세요! +│ └─────────────────────────────┘ │ +│ │ +│ ══════════════════════════════ │ +│ 스탯은 전투력에 직접 영향을 │ +│ 미칩니다. STR은 공격력, │ +│ CON은 HP에 영향을 줍니다. │ +│ ══════════════════════════════ │ +│ │ +│ [ 다음 ] [ 건너뛰기 ] │ +└─────────────────────────────────────┘ +``` + +#### 13.8.4 튜토리얼 완료 보상 + +| 보상 | 수량 | +|------|------| +| 골드 | 500 | +| 초보자 무기 | 1 | +| 초보자 방어구 | 1 | +| 경험치 물약 | 1 | + +#### 13.8.5 구현 방안 + +```dart +class TutorialService { + int currentStep = 0; + bool isCompleted = false; + + void startTutorial(); + void nextStep(); + void skipTutorial(); + void completeStep(int step); + Widget? getHighlightWidget(); + String getCurrentMessage(); +} + +class TutorialOverlay extends StatelessWidget { + final int step; + final VoidCallback onNext; + final VoidCallback onSkip; +} +``` + +#### 13.8.6 튜토리얼 관련 파일 + +| 파일 | 역할 | +|------|------| +| `core/service/tutorial_service.dart` | **신규** - 튜토리얼 로직 | +| `features/game/widgets/tutorial_overlay.dart` | **신규** - 튜토리얼 UI | +| `data/tutorial_data.dart` | **신규** - 튜토리얼 텍스트 | + +--- + +### 13.9 오프라인/백그라운드 진행 + +#### 13.9.1 오프라인 진행 개념 + +``` +앱 종료 시점 기록 → 재접속 시 경과 시간 계산 → 오프라인 보상 계산 → 결과 표시 +``` + +#### 13.9.2 오프라인 보상 계산 + +```dart +class OfflineProgressCalculator { + /// 오프라인 보상 계산 + OfflineReward calculate({ + required DateTime lastPlayedAt, + required int playerLevel, + required CombatStats stats, + }) { + final duration = DateTime.now().difference(lastPlayedAt); + final cappedMinutes = min(duration.inMinutes, maxOfflineMinutes); + + // 분당 예상 전투 수 (레벨 기반) + final battlesPerMinute = 2.0; + final totalBattles = (cappedMinutes * battlesPerMinute).round(); + + // 오프라인 효율 (온라인의 50%) + final efficiency = 0.5; + + return OfflineReward( + exp: (totalBattles * expPerBattle * efficiency).round(), + gold: (totalBattles * goldPerBattle * efficiency).round(), + items: generateOfflineItems(totalBattles, efficiency), + duration: Duration(minutes: cappedMinutes), + ); + } +} +``` + +#### 13.9.3 오프라인 제한 + +| 항목 | 제한 | +|------|------| +| 최대 오프라인 시간 | 8시간 (480분) | +| 오프라인 효율 | 온라인의 50% | +| 사망 가능성 | 없음 (오프라인 중 사망 불가) | +| 레벨업 | 가능 (최대 3레벨) | +| 퀘스트 진행 | 불가 (전투만 계산) | +| 스킬 사용 | 자동 (효율 계산에 포함) | + +#### 13.9.4 재접속 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ 🌙 오프라인 보상 │ +│ │ +│ 부재 시간: 4시간 32분 │ +│ │ +│ ───────────────────────── │ +│ 💰 획득 골드: 2,450 │ +│ ⭐ 획득 경험치: 12,800 │ +│ 📦 획득 아이템: 3개 │ +│ ───────────────────────── │ +│ │ +│ 레벨업! Lv.23 → Lv.24 │ +│ │ +│ [ 보상 받기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.9.5 백그라운드 진행 (모바일) + +| 모드 | 동작 | +|------|------| +| 포그라운드 | 정상 진행 | +| 백그라운드 (5분 이내) | 실시간 진행 유지 | +| 백그라운드 (5분 초과) | 앱 일시 정지, 재진입 시 오프라인 계산 | +| 완전 종료 | 오프라인 계산 | + +#### 13.9.6 관련 파일 + +| 파일 | 역할 | +|------|------| +| `core/service/offline_service.dart` | **신규** - 오프라인 보상 계산 | +| `core/storage/last_played_storage.dart` | **신규** - 마지막 플레이 시간 저장 | +| `features/game/widgets/offline_reward_dialog.dart` | **신규** - 보상 UI | + +--- + +### 13.10 멀티 세이브 슬롯 + +#### 13.10.1 세이브 슬롯 구조 + +```dart +class SaveSlot { + final int slotIndex; // 0-4 (5개 슬롯) + final String? characterName; + final String? race; + final String? klass; + final int? level; + final Duration? playTime; + final DateTime? lastPlayedAt; + final bool isEmpty; +} +``` + +#### 13.10.2 세이브 슬롯 UI + +``` +┌─ 세이브 슬롯 선택 ──────────────────┐ +│ │ +│ ┌─ 슬롯 1 ─────────────────────┐ │ +│ │ 🎮 CodeSlayer (Lv.45) │ │ +│ │ 버퍼 드워프 디버거 성기사 │ │ +│ │ 플레이: 8시간 22분 │ │ +│ │ 마지막: 2024.03.15 14:30 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 2 ─────────────────────┐ │ +│ │ 🎮 NullMaster (Lv.12) │ │ +│ │ 널 엘프 컴파일러 마법사 │ │ +│ │ 플레이: 1시간 05분 │ │ +│ │ 마지막: 2024.03.14 20:15 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 3 ─────────────────────┐ │ +│ │ 빈 슬롯 │ │ +│ │ [ + 새 게임 시작 ] │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 4 ─────────────────────┐ │ +│ │ 빈 슬롯 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 5 ─────────────────────┐ │ +│ │ 빈 슬롯 │ │ +│ └──────────────────────────────┘ │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.10.3 슬롯 관리 기능 + +| 기능 | 설명 | +|------|------| +| 새 게임 | 빈 슬롯에 새 캐릭터 생성 | +| 계속하기 | 해당 슬롯 캐릭터로 게임 재개 | +| 삭제 | 슬롯 데이터 삭제 (확인 필요) | +| 복사 | 다른 빈 슬롯으로 복사 | +| 내보내기 | 세이브 파일로 내보내기 | + +#### 13.10.4 관련 파일 + +| 파일 | 역할 | +|------|------| +| `core/model/save_slot.dart` | **신규** - 세이브 슬롯 모델 | +| `core/storage/multi_save_manager.dart` | **신규** - 멀티 세이브 관리 | +| `features/save/save_slot_screen.dart` | **신규** - 슬롯 선택 화면 | + +--- + +### 13.11 데이터 마이그레이션 + +#### 13.11.1 버전별 마이그레이션 전략 + +```dart +class SaveMigrator { + /// 세이브 데이터 버전 확인 및 마이그레이션 + SaveData migrate(Map rawData) { + final version = rawData['version'] as int? ?? 1; + + var data = rawData; + + // 단계별 마이그레이션 + if (version < 2) data = _migrateV1ToV2(data); + if (version < 3) data = _migrateV2ToV3(data); + if (version < 4) data = _migrateV3ToV4(data); + // ... + + return SaveData.fromJson(data); + } +} +``` + +#### 13.11.2 버전별 변경 사항 + +| 버전 | 변경 내용 | 마이그레이션 | +|------|----------|-------------| +| v1→v2 | CombatStats 추가 | 기본 스탯에서 파생 스탯 계산 | +| v2→v3 | ItemStats 추가 | 기존 아이템에 기본 스탯 부여 | +| v3→v4 | SkillState 추가 | 보유 스킬에 상태 초기화 | +| v4→v5 | DeathInfo 추가 | 사망 기록 초기화 | +| v5→v6 | 통계 데이터 추가 | 기존 플레이 기반 추정 | + +#### 13.11.3 마이그레이션 안전 장치 + +```dart +class MigrationSafetyNet { + /// 마이그레이션 전 백업 생성 + Future createBackup(int slotIndex) async { + final backup = await loadRawSave(slotIndex); + await saveBackup(slotIndex, backup, DateTime.now()); + } + + /// 마이그레이션 실패 시 롤백 + Future rollback(int slotIndex) async { + final backup = await loadLatestBackup(slotIndex); + await restoreSave(slotIndex, backup); + } +} +``` + +#### 13.11.4 마이그레이션 실패 처리 + +``` +┌─────────────────────────────────────┐ +│ │ +│ ⚠️ 세이브 데이터 업그레이드 실패 │ +│ │ +│ 이전 버전의 세이브 데이터를 │ +│ 현재 버전으로 변환하는 데 │ +│ 문제가 발생했습니다. │ +│ │ +│ [ 백업에서 복원 ] │ +│ [ 새 게임 시작 ] │ +│ [ 버그 리포트 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.12 몬스터 AI/보스 패턴 + +#### 13.12.1 일반 몬스터 AI + +```dart +enum MonsterBehavior { + aggressive, // 공격 우선 + defensive, // 방어 우선 + balanced, // 균형 + berserker, // HP 낮을수록 공격력 증가 + healer, // 자가 회복 +} + +class MonsterAI { + final MonsterBehavior behavior; + final double skillUseChance; // 스킬 사용 확률 + final List skills; + + MonsterAction decideAction(BattleState state) { + // AI 로직 + } +} +``` + +#### 13.12.2 보스 몬스터 페이즈 + +```dart +class BossMonster { + final String id; + final String name; + final List phases; + final int currentPhaseIndex; + + BossPhase get currentPhase => phases[currentPhaseIndex]; +} + +class BossPhase { + final double hpThreshold; // 이 HP% 이하일 때 다음 페이즈 + final String phaseName; // "분노", "최후의 발악" 등 + final Map statModifiers; // 스탯 변화 + final List availableSkills; + final String? phaseStartMessage; // "커널 패닉이 분노합니다!" +} +``` + +#### 13.12.3 보스 패턴 예시 + +| 보스 | 페이즈 1 (100-70%) | 페이즈 2 (70-30%) | 페이즈 3 (30-0%) | +|------|-------------------|-------------------|------------------| +| **Syntax Error Dragon** | 일반 공격 | 문법 오류 브레스 (범위) | 무한 루프 (연속 공격) | +| **Memory Leak Hydra** | 단일 공격 | 메모리 침식 (DOT) | 머리 재생 (회복 + 분열) | +| **Buffer Overflow Titan** | 강타 | 오버플로우 (즉사 위험) | 시스템 붕괴 (전체 공격) | +| **Kernel Panic Archon** | 패닉 공격 | 블루스크린 (스턴) | 시스템 재부팅 (HP 회복) | +| **Glitch God** | 글리치 (랜덤 효과) | 차원 왜곡 (회피 불가) | 존재 삭제 (다중 페이즈) | + +#### 13.12.4 보스 스킬 + +```dart +class BossSkill { + final String id; + final String name; + final SkillType type; + final int cooldownTurns; // 턴 기반 쿨타임 + final double damageMultiplier; + final List? effects; + final String? castMessage; // "커널 패닉이 블루스크린을 시전합니다!" + final int castTime; // 시전 시간 (경고 표시용) +} +``` + +#### 13.12.5 보스전 특수 메커니즘 + +| 메커니즘 | 설명 | +|----------|------| +| **시전 경고** | 강력한 스킬 사용 전 1-2턴 경고 표시 | +| **페이즈 전환 연출** | HP 임계점 도달 시 특별 애니메이션 | +| **분노 게이지** | 특정 보스는 분노 시 패턴 변화 | +| **약점 노출** | 특정 행동 후 약점 노출 (추가 데미지) | +| **환경 효과** | 보스에 따라 필드 효과 (독, 화염 등) | + +--- + +### 13.13 퀘스트 시스템 상세 + +#### 13.13.1 퀘스트 구조 + +```dart +class Quest { + final String id; + final String name; + final QuestType type; // main, side, daily, event + final String description; + final List objectives; + final QuestReward reward; + final int requiredLevel; + final String? prerequisiteQuestId; +} + +class QuestObjective { + final ObjectiveType type; // kill, collect, reach, survive + final String targetId; // 대상 몬스터/아이템/지역 + final int targetCount; + final int currentCount; + final bool isCompleted; +} +``` + +#### 13.13.2 퀘스트 타입 + +| 타입 | 설명 | 갱신 | +|------|------|------| +| **메인 퀘스트** | 스토리 진행 필수 | 일회성 | +| **서브 퀘스트** | 추가 보상 | 일회성 | +| **일일 퀘스트** | 매일 갱신 | 매일 자정 | +| **주간 퀘스트** | 매주 갱신 | 매주 월요일 | +| **이벤트 퀘스트** | 기간 한정 | 이벤트 기간 | +| **업적 퀘스트** | 장기 목표 | 영구 | + +#### 13.13.3 메인 퀘스트 흐름 + +``` +Act I: 각성 +├── [메인] 첫 번째 버그 처치 +├── [메인] 버그 둥지 탐험 +├── [메인] Syntax Error Dragon 처치 +└── [보상] Act II 해금 + +Act II: 성장 +├── [메인] 디버거 기사단 가입 +├── [메인] 손상된 네트워크 조사 +├── [메인] 배신자 추적 +├── [메인] Memory Leak Hydra 처치 +└── [보상] Act III 해금 + +... (Act III ~ V) +``` + +#### 13.13.4 서브 퀘스트 예시 + +| 퀘스트명 | 목표 | 보상 | +|----------|------|------| +| 백전용사 | 몬스터 100마리 처치 | 골드 1000, 칭호 | +| 수집가 | 무기 10종 획득 | 희귀 무기 박스 | +| 생존자 | 사망 없이 Act I 클리어 | 칭호 "완벽주의자" | +| 속도전 | 30분 내 레벨 10 달성 | 경험치 물약 x3 | + +#### 13.13.5 퀘스트 UI + +``` +┌─ 퀘스트 ────────────────────────────┐ +│ │ +│ ★ 메인 퀘스트 │ +│ ▶ 버그 둥지 탐험 │ +│ 목표: 버그 둥지 도달 [진행 중] │ +│ 보상: 골드 500, 경험치 1000 │ +│ │ +│ ☆ 서브 퀘스트 │ +│ ○ 백전용사 [45/100] │ +│ ○ 수집가 [3/10] │ +│ │ +│ 📅 일일 퀘스트 (남은 시간: 4시간) │ +│ ☑ 몬스터 30마리 처치 [완료] │ +│ ☐ 크리티컬 10회 [7/10] │ +│ ☐ 레벨업 1회 [0/1] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.14 세이브 파일 관리 + +#### 13.14.1 세이브 파일 구조 + +```dart +class SaveFileManager { + /// 세이브 파일 경로 + Future getSavePath(int slotIndex); + + /// 백업 파일 경로 + Future getBackupPath(int slotIndex, DateTime timestamp); + + /// 내보내기 파일 생성 + Future exportSave(int slotIndex); + + /// 외부 파일에서 가져오기 + Future importSave(File file, int slotIndex); +} +``` + +#### 13.14.2 자동 백업 + +| 시점 | 백업 유형 | 보관 기간 | +|------|----------|----------| +| 레벨업 시 | 자동 | 최근 5개 | +| 퀘스트 완료 시 | 자동 | 최근 5개 | +| 앱 종료 시 | 자동 | 최근 3개 | +| 수동 저장 시 | 수동 | 무제한 | +| 버전 업데이트 전 | 마이그레이션 | 영구 | + +#### 13.14.3 내보내기/가져오기 + +``` +내보내기 형식: JSON (압축) +파일명: ascii_never_die_save_{slot}_{timestamp}.json + +내보내기 내용: +- 캐릭터 데이터 +- 인벤토리 +- 장비 +- 퀘스트 진행 +- 통계 +- 업적 +- 설정 (선택적) +``` + +#### 13.14.4 클라우드 저장 (향후) + +| 플랫폼 | 저장 위치 | +|--------|----------| +| iOS | iCloud | +| Android | Google Play Games | +| Desktop | 로컬만 (향후 자체 서버) | + +#### 13.14.5 세이브 파일 UI + +``` +┌─ 세이브 파일 관리 ──────────────────┐ +│ │ +│ 📁 슬롯 1: CodeSlayer │ +│ │ +│ 자동 백업 (최근 5개) │ +│ ├─ 2024-03-15 14:30 (레벨업) │ +│ ├─ 2024-03-15 14:15 (퀘스트) │ +│ ├─ 2024-03-15 13:45 (레벨업) │ +│ └─ ... │ +│ │ +│ [ 내보내기 ] [ 가져오기 ] │ +│ [ 백업에서 복원 ] [ 삭제 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.15 접근성 (Accessibility) + +#### 13.15.1 시각 접근성 + +| 기능 | 설명 | 기본값 | +|------|------|--------| +| **색맹 모드** | 색상 팔레트 변경 | 끄기 | +| - 적록 색맹 | 빨강/초록 → 파랑/노랑 | - | +| - 청황 색맹 | 파랑/노랑 → 빨강/초록 | - | +| - 완전 색맹 | 명도/채도 기반 | - | +| **고대비 모드** | 배경/전경 대비 증가 | 끄기 | +| **폰트 크기** | 0.8x ~ 1.5x | 1.0x | +| **애니메이션 감소** | 움직임 최소화 | 끄기 | + +#### 13.15.2 청각 접근성 + +| 기능 | 설명 | 기본값 | +|------|------|--------| +| **자막** | 효과음을 텍스트로 표시 | 끄기 | +| **시각 알림** | 소리 대신 화면 깜빡임 | 끄기 | +| **진동 알림** | 소리 대신 진동 | 끄기 | + +#### 13.15.3 운동 접근성 + +| 기능 | 설명 | 기본값 | +|------|------|--------| +| **터치 영역 확대** | 버튼 크기 증가 | 끄기 | +| **길게 누르기 비활성화** | 탭으로 대체 | 끄기 | +| **자동 진행** | 수동 입력 최소화 | 켜기 | + +#### 13.15.4 게임 난이도 조절 + +| 난이도 | 설명 | +|--------|------| +| **이야기 모드** | 사망 없음, 경험치 2배 | +| **쉬움** | 데미지 50%, 회복 2배 | +| **보통** | 기본 설정 | +| **어려움** | 데미지 150%, 드롭률 증가 | +| **극한** | 데미지 200%, 사망 시 영구 삭제 | + +#### 13.15.5 접근성 UI + +``` +┌─ 접근성 설정 ───────────────────────┐ +│ │ +│ 👁 시각 │ +│ 색맹 모드 [없음 ▼] │ +│ 고대비 모드 [○ 끄기] │ +│ 폰트 크기 [━━●━━] 1.0x │ +│ 애니메이션 [● 켜기] │ +│ │ +│ 👂 청각 │ +│ 자막 표시 [○ 끄기] │ +│ 시각 알림 [○ 끄기] │ +│ │ +│ 🎮 게임플레이 │ +│ 난이도 [보통 ▼] │ +│ 터치 영역 확대 [○ 끄기] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.16 세트 아이템 + +#### 13.16.1 세트 아이템 구조 + +```dart +class ItemSet { + final String id; + final String name; + final List itemIds; // 세트 구성 아이템 + final Map bonuses; // 착용 개수별 보너스 +} + +class SetBonus { + final int requiredCount; // 필요 착용 개수 + final String description; // "2세트: 공격력 +10%" + final Map statBonuses; + final PassiveEffect? passiveEffect; +} +``` + +#### 13.16.2 세트 목록 예시 + +| 세트명 | 부위 | 2세트 | 4세트 | 6세트 | +|--------|------|-------|-------|-------| +| **디버거의 유산** | 무기, 방어구, 투구, 장갑, 부츠, 반지 | 공격력 +10% | 크리티컬 +15% | 스킬 데미지 +25% | +| **널 가드** | 방패, 방어구, 투구, 장갑, 부츠, 목걸이 | 방어력 +15% | 블록률 +10% | 피해 반사 10% | +| **컴파일러의 지혜** | 지팡이, 로브, 모자, 장갑, 부츠, 반지 | MP +20% | 마법 데미지 +15% | 스킬 쿨타임 -20% | +| **가비지 컬렉터** | 무기, 중갑, 투구, 장갑, 부츠, 벨트 | HP +20% | 전투 후 HP 5% 회복 | 사망 시 50% 확률로 생존 | + +#### 13.16.3 세트 UI + +``` +┌─ 장착 장비 ─────────────────────────┐ +│ │ +│ 디버거의 유산 [4/6] ✨ │ +│ ├─ 디버거의 검 ☑ │ +│ ├─ 디버거의 갑옷 ☑ │ +│ ├─ 디버거의 투구 ☑ │ +│ ├─ 디버거의 장갑 ☑ │ +│ ├─ 디버거의 부츠 ☐ │ +│ └─ 디버거의 반지 ☐ │ +│ │ +│ 세트 효과: │ +│ ✓ 2세트: 공격력 +10% │ +│ ✓ 4세트: 크리티컬 +15% │ +│ ○ 6세트: 스킬 데미지 +25% │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.17 강화/합성 시스템 + +#### 13.17.1 아이템 강화 + +```dart +class EnhancementSystem { + /// 강화 시도 + EnhanceResult enhance(Equipment item, int gold) { + final successRate = getSuccessRate(item.enhanceLevel); + final success = random() < successRate; + + if (success) { + return EnhanceResult.success( + item.copyWith(enhanceLevel: item.enhanceLevel + 1), + ); + } else { + // 실패 시 강화 레벨 유지 (파괴 없음) + return EnhanceResult.failure(); + } + } +} +``` + +#### 13.17.2 강화 단계 + +| 강화 레벨 | 성공률 | 비용 배율 | 스탯 증가 | +|----------|--------|----------|----------| +| +1 | 90% | 1x | +5% | +| +2 | 80% | 2x | +10% | +| +3 | 70% | 3x | +15% | +| +4 | 60% | 4x | +20% | +| +5 | 50% | 5x | +30% | +| +6 | 40% | 7x | +40% | +| +7 | 30% | 10x | +50% | +| +8 | 20% | 15x | +65% | +| +9 | 10% | 20x | +80% | +| +10 | 5% | 30x | +100% | + +#### 13.17.3 아이템 합성 + +```dart +class SynthesisSystem { + /// 동일 아이템 3개 → 상위 희귀도 1개 + Equipment? synthesize(List items) { + if (items.length != 3) return null; + if (!_isSameItem(items)) return null; + + final baseItem = items.first; + final nextRarity = _getNextRarity(baseItem.rarity); + + if (nextRarity == null) return null; // 이미 최고 희귀도 + + return baseItem.copyWith(rarity: nextRarity); + } +} +``` + +#### 13.17.4 합성 규칙 + +``` +Common x3 → Uncommon x1 +Uncommon x3 → Rare x1 +Rare x3 → Epic x1 +Epic x3 → Legendary x1 +Legendary → 합성 불가 +``` + +#### 13.17.5 강화/합성 UI + +``` +┌─ 대장간 ────────────────────────────┐ +│ │ +│ [강화] [합성] │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ 디버거의 검 +3 │ │ +│ │ 공격력: 45 (+15%) │ │ +│ │ 희귀도: Rare │ │ +│ └───────────────────────────────┘ │ +│ │ +│ 강화 정보: │ +│ 현재: +3 → +4 │ +│ 성공률: 60% │ +│ 비용: 2,000 골드 │ +│ 스탯 증가: +15% → +20% │ +│ │ +│ [ 강화하기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.18 인벤토리 관리 + +#### 13.18.1 인벤토리 구조 + +```dart +class Inventory { + final int maxSlots; // 최대 슬롯 수 + final List items; + + int get usedSlots => items.length; + int get freeSlots => maxSlots - usedSlots; + bool get isFull => freeSlots <= 0; +} +``` + +#### 13.18.2 인벤토리 크기 + +| 레벨 | 기본 슬롯 | 확장 가능 | +|------|----------|----------| +| 1-20 | 30 | +10 (골드) | +| 21-50 | 40 | +15 (골드) | +| 51-80 | 55 | +20 (골드) | +| 81-100 | 75 | +25 (골드) | +| 최대 | 100 | - | + +#### 13.18.3 정렬 옵션 + +| 정렬 기준 | 설명 | +|----------|------| +| 최근 획득 | 획득 시간 내림차순 | +| 희귀도 | 전설 > 에픽 > 레어 > ... | +| 레벨 | 아이템 레벨 내림차순 | +| 이름 | 가나다/ABC 순 | +| 슬롯 | 무기 → 방어구 → 악세서리 | +| 가중치 | 높은 가중치 우선 | + +#### 13.18.4 필터 옵션 + +| 필터 | 옵션 | +|------|------| +| 슬롯 | 전체, 무기, 방어구, 악세서리 등 | +| 희귀도 | 전체, Common ~ Legendary | +| 장착 가능 | 현재 레벨에서 장착 가능한 것만 | +| 세트 | 세트 아이템만 | + +#### 13.18.5 자동 정리 + +```dart +class InventoryAutoClean { + /// 인벤토리 자동 정리 + void autoClean(Inventory inventory, AutoCleanSettings settings) { + if (settings.sellCommon) { + _sellByRarity(ItemRarity.common); + } + if (settings.sellBelowLevel) { + _sellBelowLevel(settings.minLevel); + } + if (settings.keepBestPerSlot) { + _keepBestPerSlot(settings.keepCount); + } + } +} +``` + +#### 13.18.6 인벤토리 UI + +``` +┌─ 인벤토리 [45/50] ──────────────────┐ +│ │ +│ [정렬: 희귀도 ▼] [필터: 전체 ▼] │ +│ │ +│ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ +│ │ ★ │ │ ★ │ │ ◆ │ │ ◆ │ │ ○ │ ... │ +│ │검 │ │갑 │ │방 │ │투 │ │단 │ │ +│ └───┘ └───┘ └───┘ └───┘ └───┘ │ +│ │ +│ 선택: 디버거의 검 +3 │ +│ 공격력 +45, 크리티컬 +5% │ +│ │ +│ [장착] [판매] [강화] [분해] │ +│ │ +│ ───────────────────────────────── │ +│ [ 자동 정리 ] [ 일괄 판매 ] │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.19 버프/디버프 시스템 + +#### 13.19.1 버프/디버프 구조 + +```dart +class StatusEffect { + final String id; + final String name; + final EffectType type; // buff, debuff + final EffectTarget target; // self, enemy + final Duration duration; // 지속 시간 + final int stacks; // 중첩 횟수 + final int maxStacks; // 최대 중첩 + final Map modifiers; +} +``` + +#### 13.19.2 버프 목록 + +| 버프명 | 효과 | 지속 시간 | 획득 방법 | +|--------|------|----------|----------| +| **공격력 증가** | ATK +20% | 30초 | 스킬, 물약 | +| **방어력 증가** | DEF +20% | 30초 | 스킬, 물약 | +| **크리티컬 증가** | CRI +10% | 30초 | 스킬, 물약 | +| **회피 증가** | EVA +10% | 30초 | 스킬 | +| **재생** | 초당 HP 1% 회복 | 10초 | 스킬 | +| **경험치 부스트** | EXP +50% | 5분 | 물약, 이벤트 | +| **골드 부스트** | GOLD +50% | 5분 | 물약, 이벤트 | +| **무적** | 피해 면역 | 3초 | 스킬 | +| **분노** | ATK +50%, DEF -20% | 10초 | 스킬, 종족 특성 | + +#### 13.19.3 디버프 목록 + +| 디버프명 | 효과 | 지속 시간 | 발생 원인 | +|----------|------|----------|----------| +| **독** | 초당 HP 2% 손실 | 5초 | 몬스터 공격 | +| **출혈** | 초당 HP 1% 손실 | 10초 | 크리티컬 피격 | +| **화상** | 초당 HP 3% 손실 | 3초 | 화염 공격 | +| **둔화** | 공격 속도 -30% | 5초 | 몬스터 스킬 | +| **약화** | ATK -20% | 10초 | 보스 스킬 | +| **취약** | DEF -30% | 10초 | 보스 스킬 | +| **스턴** | 행동 불가 | 2초 | 보스 스킬 | +| **침묵** | 스킬 사용 불가 | 5초 | 보스 스킬 | +| **저주** | 회복량 -50% | 15초 | 언데드 공격 | + +#### 13.19.4 버프/디버프 UI + +``` +┌─ 상태 효과 ─────────────────────────┐ +│ │ +│ 버프: │ +│ [⚔️+20%] [🛡️+15%] [💨재생] │ +│ 25초 18초 5초 │ +│ │ +│ 디버프: │ +│ [🩸출혈] [⚡스턴] │ +│ 3초 1초 │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.20 칭호 시스템 + +#### 13.20.1 칭호 구조 + +```dart +class Title { + final String id; + final String name; + final String description; + final TitleRarity rarity; // 일반, 희귀, 영웅, 전설 + final Map? statBonus; // 착용 시 보너스 + final String unlockCondition; // 해금 조건 설명 +} +``` + +#### 13.20.2 칭호 목록 + +| 칭호 | 해금 조건 | 보너스 | 희귀도 | +|------|----------|--------|--------| +| **초보 개발자** | 게임 시작 | - | 일반 | +| **버그 헌터** | 몬스터 100마리 처치 | ATK +2 | 일반 | +| **백전용사** | 몬스터 1000마리 처치 | ATK +5 | 희귀 | +| **천인의 적** | 몬스터 10000마리 처치 | ATK +10, CRI +2% | 영웅 | +| **불사신** | 레벨 50 무사망 | HP +100, DEF +5 | 영웅 | +| **완벽주의자** | 도감 100% | 모든 스탯 +3 | 전설 | +| **글리치 슬레이어** | 글리치 신 처치 | 모든 스탯 +5 | 전설 | +| **전설의 코더** | 명예의 전당 입성 | 경험치 +10% | 전설 | +| **스피드러너** | 10시간 내 클리어 | 이동 속도 +10% | 영웅 | +| **생존주의자** | 사망 3회 이하 클리어 | HP 재생 +5% | 영웅 | +| **무자비한 디버거** | 20 콤보 달성 | CRI +5% | 희귀 | +| **행운아** | 전설 아이템 10개 획득 | 드롭률 +5% | 희귀 | + +#### 13.20.3 칭호 UI + +``` +┌─ 칭호 ──────────────────────────────┐ +│ │ +│ 현재 칭호: [백전용사] ATK +5 │ +│ │ +│ 보유 칭호 [15/50]: │ +│ │ +│ ★★★ 전설 │ +│ ☐ 글리치 슬레이어 (미해금) │ +│ ☐ 완벽주의자 (미해금) │ +│ │ +│ ★★ 영웅 │ +│ ☑ 불사신 - HP +100, DEF +5 │ +│ ☐ 스피드러너 (미해금) │ +│ │ +│ ★ 희귀 │ +│ ☑ 백전용사 - ATK +5 [장착 중] │ +│ ☑ 무자비한 디버거 - CRI +5% │ +│ │ +│ ○ 일반 │ +│ ☑ 초보 개발자 │ +│ ☑ 버그 헌터 - ATK +2 │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.21 플랫폼별 고려사항 + +#### 13.21.1 플랫폼 지원 현황 + +| 플랫폼 | 지원 | 우선순위 | 특이사항 | +|--------|------|----------|----------| +| iOS | ✓ | 상 | App Store 심사 | +| Android | ✓ | 상 | Google Play 심사 | +| Web | ✓ | 중 | 브라우저 호환성 | +| macOS | ✓ | 하 | 데스크톱 UI | +| Windows | ✓ | 하 | 데스크톱 UI | +| Linux | △ | 최하 | 테스트 제한적 | + +#### 13.21.2 플랫폼별 기능 차이 + +| 기능 | iOS | Android | Web | Desktop | +|------|-----|---------|-----|---------| +| 진동 | ✓ | ✓ | ✗ | ✗ | +| 푸시 알림 | ✓ | ✓ | △ | △ | +| 백그라운드 | △ | ✓ | ✗ | ✓ | +| 클라우드 저장 | iCloud | Google Play | ✗ | ✗ | +| IAP | App Store | Google Play | ✗ | ✗ | +| 키보드 단축키 | ✗ | ✗ | ✓ | ✓ | + +#### 13.21.3 화면 크기 대응 + +| 카테고리 | 화면 크기 | 레이아웃 | +|----------|----------|----------| +| 소형 모바일 | < 360dp | 단일 컬럼, 축소 UI | +| 일반 모바일 | 360-600dp | 단일 컬럼 | +| 대형 모바일/태블릿 | 600-900dp | 2단 컬럼 | +| 태블릿/데스크톱 | > 900dp | 3단 컬럼 | + +#### 13.21.4 플랫폼별 테스트 체크리스트 + +| 항목 | iOS | Android | Web | +|------|-----|---------|-----| +| 최소 OS 버전 | iOS 12+ | Android 6+ | 최신 브라우저 | +| 기기 테스트 | iPhone SE, 15 Pro | 저사양, 고사양 | Chrome, Safari, Firefox | +| 가로/세로 | 세로 고정 | 세로 고정 | 반응형 | +| 노치/펀치홀 | SafeArea | SafeArea | N/A | +| 다크 모드 | ✓ | ✓ | ✓ | + +--- + +### 13.22 향후 고려 사항 + +#### 13.22.1 타임어택/스피드런 모드 + +| 기능 | 설명 | +|------|------| +| 타이머 표시 | 실시간 플레이 시간 표시 | +| 구간 기록 | Act별 클리어 시간 | +| 리더보드 | 최고 기록 순위 (향후 온라인) | +| 고스트 데이터 | 이전 기록과 비교 (로컬) | + +#### 13.22.2 애널리틱스 (익명) + +| 수집 데이터 | 목적 | +|------------|------| +| 레벨별 사망률 | 밸런싱 조정 | +| 인기 스킬/장비 | 콘텐츠 밸런싱 | +| 플레이 세션 시간 | 게임 흐름 개선 | +| 이탈 지점 | 문제 구간 파악 | + +#### 13.22.3 다국어 확장 + +| 언어 | 우선순위 | 현황 | +|------|----------|------| +| 한국어 | 완료 | ✓ | +| 영어 | 완료 | ✓ | +| 일본어 | 높음 | 계획 | +| 중국어 (간체) | 높음 | 계획 | +| 중국어 (번체) | 중간 | 계획 | +| 스페인어 | 중간 | 계획 | + +#### 13.22.4 개발자/디버그 모드 + +| 기능 | 설명 | +|------|------| +| 레벨 조정 | 즉시 레벨 변경 | +| 아이템 지급 | 모든 아이템 획득 | +| 골드 지급 | 무제한 골드 | +| 무적 모드 | 사망 불가 | +| 스킵 | 전투/시네마틱 스킵 | +| 로그 표시 | 상세 디버그 로그 | + +--- + +### 13.23 물약/소모품 시스템 + +#### 13.23.1 소모품 종류 + +| 카테고리 | 아이템 | 효과 | 획득 방법 | +|----------|--------|------|----------| +| **HP 물약** | 소형 HP 물약 | HP +100 | 상점, 드롭 | +| | 중형 HP 물약 | HP +300 | 상점, 드롭 | +| | 대형 HP 물약 | HP +500 | 상점, 드롭 | +| | 최상급 HP 물약 | HP 100% 회복 | 보스 드롭, 제작 | +| **MP 물약** | 소형 MP 물약 | MP +50 | 상점, 드롭 | +| | 중형 MP 물약 | MP +150 | 상점, 드롭 | +| | 대형 MP 물약 | MP +300 | 상점, 드롭 | +| | 최상급 MP 물약 | MP 100% 회복 | 보스 드롭, 제작 | +| **버프 물약** | 공격력 물약 | ATK +20%, 5분 | 상점, 제작 | +| | 방어력 물약 | DEF +20%, 5분 | 상점, 제작 | +| | 경험치 물약 | EXP +50%, 5분 | 이벤트, 퀘스트 | +| | 골드 물약 | GOLD +50%, 5분 | 이벤트, 퀘스트 | +| | 행운 물약 | 드롭률 +30%, 5분 | 희귀 드롭 | +| **특수 소모품** | 귀환 스크롤 | 마을로 즉시 이동 | 상점 | +| | 부활의 부적 | 사망 시 장비 1개 보존 | 보스 드롭 | +| | 감정 스크롤 | 미감정 아이템 감정 | 상점 | + +#### 13.23.2 소모품 데이터 구조 + +```dart +class Consumable { + final String id; + final String name; + final ConsumableType type; // hp, mp, buff, special + final int value; // 회복량 또는 효과 수치 + final Duration? duration; // 버프 지속 시간 + final int maxStack; // 최대 중첩 수 (인벤토리) + final int buyPrice; + final int sellPrice; +} + +class ConsumableInventory { + final Map items; // id -> 수량 + + void use(String id); + void add(String id, int amount); + bool has(String id) => (items[id] ?? 0) > 0; +} +``` + +#### 13.23.3 자동 사용 설정 + +``` +┌─ 물약 자동 사용 설정 ───────────────┐ +│ │ +│ HP 물약 자동 사용 │ +│ ● 켜기 ○ 끄기 │ +│ HP가 [30]% 이하일 때 사용 │ +│ 사용 우선순위: [소형 > 중형 > 대형]│ +│ │ +│ MP 물약 자동 사용 │ +│ ● 켜기 ○ 끄기 │ +│ MP가 [20]% 이하일 때 사용 │ +│ │ +│ 버프 물약 자동 사용 │ +│ ○ 켜기 ● 끄기 │ +│ (보스전에서만 자동 사용) │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.23.4 물약 쿨타임 + +| 물약 종류 | 쿨타임 | +|----------|--------| +| HP 물약 | 3초 | +| MP 물약 | 3초 | +| 버프 물약 | 60초 | +| 특수 소모품 | 없음 | + +--- + +### 13.24 던전/지역 시스템 + +#### 13.24.1 월드 구조 + +``` +┌─ 코드 왕국 (세계) ─────────────────────────────────────┐ +│ │ +│ Act I: 버그 평원 │ +│ ├─ 시작 마을 (안전 지역) │ +│ ├─ 버그 초원 (Lv.1-5) │ +│ ├─ 에러 숲 (Lv.6-10) │ +│ ├─ 버그 둥지 [던전] (Lv.8-12) │ +│ └─ 문법 오류의 탑 [보스] (Lv.15) │ +│ │ +│ Act II: 손상된 네트워크 │ +│ ├─ 디버거 요새 (안전 지역) │ +│ ├─ 손상된 회로 (Lv.16-25) │ +│ ├─ 메모리 늪 (Lv.21-30) │ +│ ├─ 누수 동굴 [던전] (Lv.25-35) │ +│ └─ 히드라의 서버실 [보스] (Lv.40) │ +│ │ +│ Act III: 널 왕국 │ +│ ├─ 바이너리 신전 (안전 지역) │ +│ ├─ 널 사막 (Lv.41-50) │ +│ ├─ 포인터 미궁 (Lv.46-55) │ +│ ├─ 버퍼의 심연 [던전] (Lv.50-60) │ +│ └─ 타이탄의 성채 [보스] (Lv.60) │ +│ │ +│ Act IV: 글리치 영역 │ +│ ├─ 저항군 기지 (안전 지역) │ +│ ├─ 커널 황무지 (Lv.61-70) │ +│ ├─ 패닉 협곡 (Lv.66-80) │ +│ ├─ 시스템 감옥 [던전] (Lv.70-85) │ +│ └─ 아콘의 왕좌 [보스] (Lv.80) │ +│ │ +│ Act V: 최종 결전 │ +│ ├─ 최후의 캐시 (안전 지역) │ +│ ├─ 글리치 회랑 (Lv.81-90) │ +│ ├─ 차원의 틈 (Lv.86-95) │ +│ ├─ 신의 코어 [던전] (Lv.90-100) │ +│ └─ 글리치 신의 영역 [최종 보스] (Lv.100) │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +#### 13.24.2 지역 타입 + +| 타입 | 설명 | 특징 | +|------|------|------| +| **안전 지역** | 마을, 요새 | 전투 없음, 상점, NPC, 회복 | +| **필드** | 일반 사냥터 | 일반 몬스터, 퀘스트 | +| **던전** | 인스턴스 지역 | 강화 몬스터, 미니보스, 보상 증가 | +| **보스 지역** | Act 보스 | 보스 몬스터, 스토리 진행 | + +#### 13.24.3 지역 이동 (Idle 방식) + +```dart +class AreaProgress { + final String currentAreaId; + final double explorationProgress; // 0.0 ~ 1.0 + final bool isBossUnlocked; + + /// 탐험 진행 (자동) + void progressExploration(Duration elapsed) { + // 시간 경과에 따라 탐험도 증가 + // 탐험도 100% 달성 시 다음 지역/보스 해금 + } +} +``` + +#### 13.24.4 던전 시스템 + +| 요소 | 설명 | +|------|------| +| **입장 조건** | 최소 레벨, 이전 던전 클리어 | +| **층 구조** | 3-5층, 층별 강화 몬스터 | +| **보스 층** | 마지막 층에 미니보스 | +| **보상** | 일반 필드 대비 2-3배 | +| **재입장** | 클리어 후 24시간 대기 (일일 1회) | + +#### 13.24.5 지역 UI + +``` +┌─ 현재 위치 ─────────────────────────┐ +│ │ +│ 📍 Act II: 손상된 회로 │ +│ Lv.16-25 │ +│ │ +│ 탐험 진행도: ████████░░ 78% │ +│ 다음 지역까지: 22% │ +│ │ +│ ─────────────────────────────────── │ +│ │ +│ 🏰 디버거 요새 [방문하기] │ +│ 🌲 손상된 회로 [현재] │ +│ 🌊 메모리 늪 [해금 필요: 탐험 100%] │ +│ 🏔 누수 동굴 [해금 필요: Lv.25] │ +│ 👹 히드라 서버실 [해금 필요] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.25 상점 시스템 상세 + +#### 13.25.1 상점 종류 + +| 상점 | 위치 | 판매 품목 | +|------|------|----------| +| **일반 상점** | 모든 마을 | 물약, 기본 장비, 소모품 | +| **대장간** | 모든 마을 | 무기, 방어구 (레벨 기반) | +| **마법 상점** | Act II 이후 | 스킬서, 마법 장비 | +| **비밀 상점** | 랜덤 등장 | 희귀 아이템, 한정품 | +| **길드 상점** | 요새 | 길드 포인트 교환 | + +#### 13.25.2 상점 갱신 시스템 + +```dart +class Shop { + final ShopType type; + final List items; + final DateTime lastRefresh; + final Duration refreshInterval; + + /// 상점 아이템 갱신 + void refresh(int playerLevel) { + items.clear(); + items.addAll(_generateItems(playerLevel)); + lastRefresh = DateTime.now(); + } +} +``` + +| 상점 | 갱신 주기 | 갱신 조건 | +|------|----------|----------| +| 일반 상점 | 매일 자정 | 자동 | +| 대장간 | 레벨업 시 | 레벨업 | +| 마법 상점 | 매주 월요일 | 자동 | +| 비밀 상점 | 랜덤 | 5% 확률로 등장 | + +#### 13.25.3 가격 계산 공식 + +```dart +/// 구매 가격 계산 +int calculateBuyPrice(Equipment item) { + final basePrice = item.level * 50; + final rarityMultiplier = { + ItemRarity.common: 1.0, + ItemRarity.uncommon: 2.0, + ItemRarity.rare: 5.0, + ItemRarity.epic: 15.0, + ItemRarity.legendary: 50.0, + }[item.rarity]!; + + return (basePrice * rarityMultiplier).round(); +} + +/// 판매 가격 계산 +int calculateSellPrice(Equipment item) { + return (calculateBuyPrice(item) * 0.3).round(); +} + +/// CHA 보너스 적용 +int applyCharismaDiscount(int price, int cha) { + // CHA 10당 1% 할인, 최대 20% 할인 + final discount = min(0.20, (cha - 10) * 0.01); + return (price * (1 - discount)).round(); +} +``` + +#### 13.25.4 상점 UI + +``` +┌─ 대장간 ────────────────────────────┐ +│ │ +│ 👤 레벨: 25 💰 골드: 15,420 │ +│ 📦 인벤토리: 42/50 │ +│ │ +│ ─────────────────────────────────── │ +│ 판매 중인 아이템 (갱신까지: 2시간) │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ ⚔️ 디버거의 검 (Lv.25) │ │ +│ │ ATK +35, CRI +3% │ │ +│ │ 💰 1,250 골드 [구매] │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ 🛡️ 강철 갑옷 (Lv.24) │ │ +│ │ DEF +42, HP +50 │ │ +│ │ 💰 1,100 골드 [구매] │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ [판매하기] [강화하기] [수리하기] │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.25.5 특별 거래 + +| 기능 | 설명 | +|------|------| +| **일괄 구매** | 물약 10개/50개 묶음 구매 (5% 할인) | +| **일괄 판매** | 선택한 아이템 일괄 판매 | +| **자동 구매** | 물약 부족 시 자동 구매 설정 | +| **예약 구매** | 비밀 상점 아이템 등장 시 알림 | + +--- + +### 13.26 이벤트 시스템 상세 + +#### 13.26.1 이벤트 종류 + +| 이벤트 타입 | 주기 | 지속 시간 | +|------------|------|----------| +| **일일 보너스** | 매일 | 접속 시 | +| **주간 보스** | 매주 일요일 | 24시간 | +| **시즌 이벤트** | 시즌별 | 2-4주 | +| **기념일 이벤트** | 특정 날짜 | 1-7일 | +| **돌발 이벤트** | 랜덤 | 1-2시간 | + +#### 13.26.2 이벤트 구조 + +```dart +class GameEvent { + final String id; + final String name; + final EventType type; + final DateTime startTime; + final DateTime endTime; + final List rewards; + final List quests; + final EventBonuses? bonuses; +} + +class EventBonuses { + final double expMultiplier; // 경험치 배율 + final double goldMultiplier; // 골드 배율 + final double dropRateBonus; // 드롭률 보너스 +} +``` + +#### 13.26.3 시즌 이벤트 예시 + +| 시즌 | 테마 | 특별 콘텐츠 | +|------|------|------------| +| **봄** | 버그 헌팅 시즌 | 특별 몬스터, 봄 한정 장비 | +| **여름** | 핫픽스 페스티벌 | 경험치 2배, 여름 코스튬 | +| **가을** | 수확의 코드 | 골드 2배, 가을 한정 펫 | +| **겨울** | 시스템 동면 | 특별 던전, 겨울 한정 세트 | + +#### 13.26.4 이벤트 보상 구조 + +``` +┌─ 신년 이벤트 ───────────────────────┐ +│ │ +│ 🎉 2025 신년 맞이 특별 이벤트 │ +│ 기간: 1/1 ~ 1/7 │ +│ │ +│ ─────────────────────────────────── │ +│ 📋 이벤트 미션 │ +│ │ +│ ☑ 몬스터 100마리 처치 [100/100] │ +│ 보상: 신년 무기 상자 │ +│ │ +│ ☐ 던전 5회 클리어 [3/5] │ +│ 보상: 전설 물약 세트 │ +│ │ +│ ☐ 보스 처치 [0/1] │ +│ 보상: 신년 한정 칭호 │ +│ │ +│ ─────────────────────────────────── │ +│ 🎁 출석 보상 (7일) │ +│ [✓][✓][✓][✓][ ][ ][ ] │ +│ 1 2 3 4 5 6 7 │ +│ │ +│ 7일 완료 보상: 신년 한정 세트 │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.26.5 돌발 이벤트 + +| 이벤트 | 발생 확률 | 효과 | +|--------|----------|------| +| **골드 러시** | 5% | 1시간 골드 3배 | +| **경험치 폭풍** | 5% | 1시간 경험치 2배 | +| **보물 사냥** | 3% | 희귀 아이템 드롭률 +100% | +| **엘리트 침공** | 3% | 정예 몬스터 대량 등장 | +| **행운의 시간** | 2% | 모든 보너스 적용 | + +--- + +### 13.27 알림/푸시 시스템 상세 + +#### 13.27.1 알림 종류 + +| 카테고리 | 알림 | 기본 설정 | +|----------|------|----------| +| **게임 진행** | 레벨업 | 켜기 | +| | 퀘스트 완료 | 켜기 | +| | 보스 해금 | 켜기 | +| | 업적 달성 | 켜기 | +| **전투** | 사망 | 켜기 | +| | 희귀 아이템 획득 | 켜기 | +| | HP 위험 (20% 이하) | 끄기 | +| **시스템** | 오프라인 보상 준비 | 켜기 | +| | 일일 미션 갱신 | 켜기 | +| | 이벤트 시작/종료 | 켜기 | +| | 상점 갱신 | 끄기 | +| **소셜 (향후)** | 친구 요청 | 켜기 | +| | 길드 알림 | 켜기 | + +#### 13.27.2 푸시 알림 (모바일) + +```dart +class PushNotificationService { + /// 로컬 푸시 알림 예약 + Future scheduleNotification({ + required String title, + required String body, + required DateTime scheduledTime, + String? payload, + }); + + /// 반복 알림 설정 + Future scheduleRepeating({ + required String title, + required String body, + required RepeatInterval interval, + }); +} + +enum RepeatInterval { + hourly, + daily, + weekly, +} +``` + +#### 13.27.3 푸시 알림 시나리오 + +| 시나리오 | 트리거 | 메시지 예시 | +|----------|--------|------------| +| **복귀 유도** | 24시간 미접속 | "⚔️ 버그들이 기다리고 있어요!" | +| **오프라인 보상** | 8시간 경과 | "🎁 오프라인 보상이 가득 찼어요!" | +| **일일 미션** | 매일 오전 9시 | "📋 새로운 일일 미션이 도착했어요!" | +| **이벤트** | 이벤트 시작 | "🎉 신년 이벤트가 시작되었어요!" | +| **이벤트 종료** | 이벤트 종료 1시간 전 | "⏰ 이벤트가 1시간 후 종료됩니다!" | + +#### 13.27.4 인앱 알림 + +``` +┌─ 알림 센터 ─────────────────────────┐ +│ │ +│ 오늘 │ +│ ─────────────────────────────────── │ +│ 🎮 레벨 26 달성! 14:32 │ +│ │ +│ ⚔️ 디버거의 검 획득 (Epic) 14:15 │ +│ │ +│ 📋 일일 미션 완료 13:45 │ +│ 보상: 골드 500, 경험치 물약 │ +│ │ +│ 어제 │ +│ ─────────────────────────────────── │ +│ 🏆 업적 달성: 백전용사 23:12 │ +│ │ +│ 💀 사망: 메모리 누수에 의해 21:30 │ +│ │ +│ [ 모두 읽음 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.27.5 알림 설정 UI + +``` +┌─ 알림 설정 ─────────────────────────┐ +│ │ +│ 🔔 푸시 알림 │ +│ 마스터 스위치 [● 켜기] │ +│ │ +│ ─────────────────────────────────── │ +│ 게임 진행 │ +│ 레벨업 [● 켜기] │ +│ 퀘스트 완료 [● 켜기] │ +│ 업적 달성 [● 켜기] │ +│ │ +│ 시스템 │ +│ 오프라인 보상 [● 켜기] │ +│ 일일 미션 갱신 [● 켜기] │ +│ 이벤트 [● 켜기] │ +│ │ +│ 방해 금지 시간 │ +│ [22:00] ~ [08:00] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +### 13.28 UI 레이아웃/네비게이션 + +#### 13.28.1 메인 게임 화면 레이아웃 + +``` +┌─────────────────────────────────────────────────────────┐ +│ [메뉴] CodeSlayer Lv.25 💰 15,420 [알림] [설정] │ ← 헤더 +├─────────────────────────────────────────────────────────┤ +│ │ +│ ┌─ 캐릭터 ─────┐ ┌─ 전투 영역 ──────────────────┐ │ +│ │ │ │ │ │ +│ │ HP ████░░ │ │ ╔═══╗ ╔═══╗ │ │ +│ │ MP ███░░░ │ │ ║ ☺ ║ VS ║ ☠ ║ │ │ +│ │ │ │ ╚═══╝ ╚═══╝ │ │ +│ │ STR: 25 │ │ │ │ +│ │ CON: 20 │ │ Syntax Error Lv.24 │ │ +│ │ DEX: 18 │ │ HP ██████░░░░ │ │ +│ │ INT: 15 │ │ │ │ +│ │ WIS: 12 │ │ [45 데미지!] │ │ +│ │ CHA: 10 │ │ │ │ +│ └──────────────┘ └───────────────────────────────┘ │ +│ │ +│ ┌─ 장비 ───────────────────────────────────────────┐ │ +│ │ ⚔️ 디버거의 검 🛡️ 강철 갑옷 🎩 마법 투구 ... │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ 진행 상황 ──────────────────────────────────────┐ │ +│ │ 🗡️ 버그 처치 중... [일시정지] │ │ +│ │ ████████████████░░░░░░░░ 60% │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────┤ +│ [전투] [인벤] [스킬] [퀘스트] [더보기] │ ← 탭 바 +└─────────────────────────────────────────────────────────┘ +``` + +#### 13.28.2 화면 구성 + +| 화면 | 접근 방법 | 주요 기능 | +|------|----------|----------| +| **메인 (전투)** | 기본 화면 | 전투 진행, 스탯, 장비 | +| **인벤토리** | 탭 바 | 아이템 관리, 장착 | +| **스킬** | 탭 바 | 스킬 관리, 빌드 | +| **퀘스트** | 탭 바 | 퀘스트 목록, 진행 | +| **더보기** | 탭 바 | 도감, 업적, 통계, 상점 등 | +| **지역** | 더보기 | 월드맵, 던전 | +| **설정** | 헤더 | 게임 설정 | + +#### 13.28.3 네비게이션 흐름 + +```mermaid +graph TD + A[앱 시작] --> B{세이브 존재?} + B -->|No| C[세이브 슬롯 선택] + B -->|Yes| D[세이브 슬롯 선택] + C --> E[캐릭터 생성] + D --> F{튜토리얼 완료?} + E --> F + F -->|No| G[튜토리얼] + F -->|Yes| H[메인 게임] + G --> H + + H --> I[인벤토리] + H --> J[스킬] + H --> K[퀘스트] + H --> L[더보기] + + L --> M[도감] + L --> N[업적] + L --> O[통계] + L --> P[상점] + L --> Q[지역] + L --> R[명예의 전당] +``` + +#### 13.28.4 모달/오버레이 + +| 타입 | 사용 상황 | +|------|----------| +| **풀스크린 모달** | 사망 화면, 레벨업, 업적 달성 | +| **바텀 시트** | 아이템 상세, 스킬 상세, 퀵 액션 | +| **다이얼로그** | 확인, 경고, 선택 | +| **토스트** | 간단한 알림, 획득 메시지 | +| **툴팁** | 스탯 설명, 효과 설명 | + +#### 13.28.5 반응형 레이아웃 + +```dart +class ResponsiveLayout extends StatelessWidget { + @override + Widget build(BuildContext context) { + return LayoutBuilder( + builder: (context, constraints) { + if (constraints.maxWidth < 360) { + return CompactLayout(); // 소형 모바일 + } else if (constraints.maxWidth < 600) { + return MobileLayout(); // 일반 모바일 + } else if (constraints.maxWidth < 900) { + return TabletLayout(); // 태블릿 + } else { + return DesktopLayout(); // 데스크톱 + } + }, + ); + } +} +``` + +--- + +### 13.29 기술적 상세 + +#### 13.29.1 State Management + +```dart +// Riverpod 사용 권장 +final gameStateProvider = StateNotifierProvider( + (ref) => GameStateNotifier(), +); + +class GameStateNotifier extends StateNotifier { + GameStateNotifier() : super(GameState.initial()); + + void tick() { /* 게임 틱 처리 */ } + void attack() { /* 공격 처리 */ } + void useSkill(String skillId) { /* 스킬 사용 */ } + void equip(Equipment item) { /* 장비 장착 */ } +} + +// 분리된 Provider들 +final combatProvider = ...; // 전투 상태 +final inventoryProvider = ...; // 인벤토리 상태 +final questProvider = ...; // 퀘스트 상태 +final settingsProvider = ...; // 설정 상태 +``` + +#### 13.29.2 에러 처리 전략 + +```dart +class AppException implements Exception { + final String code; + final String message; + final dynamic originalError; + + AppException(this.code, this.message, [this.originalError]); +} + +// 에러 타입 +class SaveLoadException extends AppException { ... } +class MigrationException extends AppException { ... } +class NetworkException extends AppException { ... } // 향후 온라인용 + +// 전역 에러 핸들러 +void handleError(AppException e, StackTrace stack) { + // 1. 로깅 + Logger.error(e.code, e.message, stack); + + // 2. 사용자 알림 + showErrorDialog(e.message); + + // 3. 복구 시도 (가능한 경우) + attemptRecovery(e); +} +``` + +#### 13.29.3 에러 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ ⚠️ 오류가 발생했습니다 │ +│ │ +│ 세이브 데이터를 불러오는 중 │ +│ 문제가 발생했습니다. │ +│ │ +│ 오류 코드: SAVE_LOAD_001 │ +│ │ +│ [ 다시 시도 ] [ 백업 복원 ] │ +│ [ 새 게임 ] [ 문의하기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +#### 13.29.4 로깅 전략 + +```dart +class Logger { + static LogLevel currentLevel = kDebugMode + ? LogLevel.debug + : LogLevel.warning; + + static void debug(String message) { ... } + static void info(String message) { ... } + static void warning(String message) { ... } + static void error(String code, String message, StackTrace? stack) { ... } +} + +enum LogLevel { debug, info, warning, error } + +// 로그 출력 예시 +// [DEBUG] 2024-03-15 14:30:00 - Combat: Player attacks for 45 damage +// [INFO] 2024-03-15 14:30:01 - Level up: 24 -> 25 +// [WARN] 2024-03-15 14:30:02 - Low HP warning: 15% +// [ERROR] 2024-03-15 14:30:03 - SAVE_001: Failed to save game +``` + +#### 13.29.5 성능 모니터링 + +```dart +class PerformanceMonitor { + /// FPS 측정 + double get currentFps => ...; + + /// 메모리 사용량 + int get memoryUsageMb => ...; + + /// 틱 처리 시간 + Duration get averageTickTime => ...; + + /// 성능 경고 + void checkPerformance() { + if (currentFps < 30) { + Logger.warning('Low FPS: $currentFps'); + } + if (memoryUsageMb > 500) { + Logger.warning('High memory usage: $memoryUsageMb MB'); + } + } +} +``` + +--- + +## 14. 재미 요소 설계 (Fun Factor Design) + +### 14.1 즉각적인 보상감 (Dopamine Hits) + +| 요소 | 설명 | 우선순위 | +|------|------|----------| +| **데미지 숫자 팝업** | 공격 시 데미지가 화면에 튀어오름 (크리티컬은 크게, 빨간색) | 상 | +| **콤보 시스템** | 연속 처치 시 "x5 COMBO!" 표시 + 보너스 경험치 (10% per combo) | 상 | +| **희귀 드롭 연출** | 전설 아이템 획득 시 화면 번쩍 + 특별 효과음 + 진동 | 상 | +| **레벨업 축하** | 레벨업 시 3초간 화려한 ASCII 이펙트 | 중 | +| **크리티컬 이펙트** | 크리티컬 히트 시 화면 흔들림 + "CRITICAL!" 텍스트 | 상 | + +#### 14.1.1 데미지 팝업 구현 + +```dart +class DamagePopup { + final int damage; + final bool isCritical; + final Offset position; + final double opacity; // 1.0 → 0.0 fade out + final double offsetY; // 위로 떠오름 +} + +// 표시 예시 +// 일반: "45" (흰색, 작게) +// 크리티컬: "127!" (빨간색, 크게, 흔들림) +// 회복: "+30" (녹색) +// 스킬: "DEBUG STRIKE 250" (노란색) +``` + +#### 14.1.2 콤보 시스템 + +``` +콤보 조건: 5초 내 연속 처치 +콤보 보상: +- x2: 경험치 +10% +- x3: 경험치 +15% +- x5: 경험치 +25%, 골드 +10% +- x10: 경험치 +50%, 골드 +25%, 희귀 드롭률 +5% +- x20+: "UNSTOPPABLE!" 칭호 획득 조건 +``` + +--- + +### 14.2 "한 판 더" 유발 요소 + +#### 14.2.1 일일 도전 + +| 요소 | 설명 | +|------|------| +| **일일 미션** | 매일 3개의 미션 (예: "버그 30마리 처치", "크리티컬 10회") | +| **일일 보너스** | 첫 접속 시 골드/아이템 박스 | +| **연속 접속 보상** | 7일 연속 시 전설 아이템 박스 | + +``` +┌─ 일일 도전 ─────────────────────┐ +│ │ +│ ☑ 버그 30마리 처치 [30/30] │ +│ 보상: 골드 500 │ +│ │ +│ ☐ 크리티컬 10회 달성 [7/10] │ +│ 보상: 경험치 물약 │ +│ │ +│ ☐ 레벨업 1회 [0/1] │ +│ 보상: 랜덤 장비 박스 │ +│ │ +│ ───────────────────────────────│ +│ 연속 접속: 5일째 🔥 │ +│ 7일 보상까지: 2일 남음 │ +└─────────────────────────────────┘ +``` + +#### 14.2.2 주간/이벤트 보스 + +| 보스 타입 | 출현 조건 | 보상 | +|----------|----------|------| +| **주간 보스** | 매주 일요일 등장 | 한정 아이템, 대량 골드 | +| **시즌 보스** | 명절/기념일 | 시즌 한정 장비, 칭호 | +| **랜덤 레이드** | 랜덤 (1% 확률) | 희귀 아이템 + 업적 | + +#### 14.2.3 "거의 다 됐어" 심리 + +``` +레벨업까지 남은 경험치가 10% 이하일 때: +→ 경험치 바 색상 변경 (황금색) +→ "조금만 더!" 메시지 표시 +→ 다음 레벨 보상 미리보기 +``` + +--- + +### 14.3 플레이어 선택권 확대 + +#### 14.3.1 스킬 빌드 시스템 + +```dart +class SkillBuild { + final List activeSkills; // 3개 슬롯 + final List passiveSkills; // 2개 슬롯 + final String buildName; // "공격형", "탱커형" 등 +} +``` + +| 빌드 타입 | 특징 | +|----------|------| +| **공격형** | 데미지 스킬 위주, 높은 DPS | +| **방어형** | 회복/방어 스킬, 생존력 특화 | +| **균형형** | 공격 + 회복 혼합 | +| **스피드형** | 쿨타임 감소, 연속 공격 | + +#### 14.3.2 전투 스타일 전환 + +``` +[공격 모드] 🗡️ +- 공격력 +20% +- 방어력 -10% +- 크리티컬 +5% + +[방어 모드] 🛡️ +- 방어력 +30% +- 공격력 -10% +- 블록율 +10% + +[균형 모드] ⚖️ +- 기본 스탯 +- 회복량 +10% +``` + +#### 14.3.3 자동/반자동 전환 + +| 모드 | 설명 | +|------|------| +| **완전 자동** | 모든 것 자동 (기본) | +| **스킬 수동** | 스킬만 수동 선택 | +| **보스전 수동** | 보스전에서만 수동 전환 | + +--- + +### 14.4 감정적 연결 + +#### 14.4.1 캐릭터 성장 기록 + +``` +┌─ 나의 여정 ─────────────────────┐ +│ │ +│ 🎮 함께한 시간: 15시간 34분 │ +│ ⚔️ 처치한 버그: 1,247마리 │ +│ 💀 사망 횟수: 7회 │ +│ 🏆 획득 업적: 23개 │ +│ │ +│ 📝 기억에 남는 순간: │ +│ • 첫 레벨업 (0시간 2분) │ +│ • 첫 사망 (1시간 15분) │ +│ • 첫 전설 아이템 (8시간 22분) │ +│ • 첫 보스 처치 (5시간 47분) │ +└─────────────────────────────────┘ +``` + +#### 14.4.2 상황별 메시지 (유머/위로) + +| 상황 | 메시지 예시 | +|------|------------| +| **첫 사망** | "축하합니다! 첫 번째 교훈을 얻었습니다. 버그는 누구나 만납니다." | +| **연속 사망** | "잠시 쉬어가는 건 어떨까요? 커피 한 잔의 여유..." | +| **레벨업** | "레벨 {n} 달성! 당신의 코드가 더 강해졌습니다." | +| **희귀 아이템** | "운이 좋으시네요! 이건 정말 드문 거에요!" | +| **100 연속 처치** | "무자비한 디버거! 버그들이 당신을 두려워합니다." | +| **장시간 플레이** | "3시간째 플레이 중... 물 한 잔 드세요! 💧" | + +#### 14.4.3 마일스톤 축하 + +| 마일스톤 | 축하 연출 | +|----------|----------| +| 100마리 처치 | "백전용사" 칭호 + 특별 이펙트 | +| 1000마리 처치 | "천인의 적" 칭호 + 업적 팝업 | +| 10시간 플레이 | "헌신적인 개발자" 칭호 | +| 무사망 Act 클리어 | "완벽주의자" 칭호 + 보너스 골드 | + +--- + +### 14.5 예측 불가능한 재미 + +#### 14.5.1 랜덤 이벤트 + +| 이벤트 | 확률 | 효과 | +|--------|------|------| +| **전설 몬스터 출현** | 5% | "갑자기 전설 몬스터가 나타났다!" - 처치 시 대량 보상 | +| **황금 몬스터** | 3% | 골드 10배 드롭 | +| **보물 상자** | 2% | 랜덤 아이템 발견 | +| **도움의 NPC** | 5% | 버프 or 회복 제공 | +| **함정** | 3% | 데미지 or 디버프 (긴장감) | +| **경험치 폭풍** | 1% | 다음 5분간 경험치 2배 | + +#### 14.5.2 행운 시스템 + +```dart +class LuckEvent { + // 연속 불운 시 행운 상승 + int unluckyStreak = 0; + + double getLuckBonus() { + // 10회 연속 일반 드롭 시 희귀 드롭 확률 +50% + return unluckyStreak >= 10 ? 0.5 : 0.0; + } +} +``` + +--- + +### 14.6 사회적 요소 (향후 확장) + +#### 14.6.1 현재 버전 (오프라인) + +| 기능 | 설명 | +|------|------| +| **스크린샷 공유** | 명예의 전당 달성 시 공유 버튼 | +| **기록 내보내기** | 통계를 이미지로 저장 | + +#### 14.6.2 향후 버전 (아스키 아레나) + +| 기능 | 설명 | +|------|------| +| **글로벌 랭킹** | 레벨, 사망 횟수, 클리어 시간 순위 | +| **친구 비교** | 친구의 기록과 비교 | +| **PvP 아레나** | 명예의 전당 캐릭터로 대전 | +| **길드 시스템** | 협력 레이드 보스 | + +--- + +## 15. 피해야 할 요소 + +### 15.1 지루함 유발 요소 + +| 피해야 할 것 | 이유 | 대안 | +|-------------|------|------| +| **긴 대기 시간** | 아무 일도 안 일어나면 지루함 | 항상 뭔가 진행 중 표시 | +| **반복 메시지** | 같은 문구 반복은 지루함 | 30+ 가지 변형 메시지 | +| **단조로운 전투** | 항상 같은 패턴 | 랜덤 이벤트, 크리티컬, 콤보 | +| **느린 초반** | 첫 30분이 지루하면 이탈 | 초반 빠른 레벨업 + 튜토리얼 보상 | + +### 15.2 불쾌감 유발 요소 + +| 피해야 할 것 | 이유 | 대안 | +|-------------|------|------| +| **불공정한 즉사** | 예측 불가능한 사망은 스트레스 | HP 보고 대응 가능하도록 | +| **과도한 페널티** | 레벨 다운은 너무 가혹 | 장비 상실만 (레벨/인벤 유지) | +| **강제 광고** | 게임 흐름 방해 | 광고 없음 | +| **과금 유도** | 필수 과금은 불쾌 | 무과금 완전 클리어 가능 | +| **복잡한 UI** | 정보 과다는 혼란 | 핵심 정보만, 상세는 별도 탭 | + +### 15.3 혼란 유발 요소 + +| 피해야 할 것 | 이유 | 대안 | +|-------------|------|------| +| **설명 없는 시스템** | 무엇인지 모르면 답답 | 첫 등장 시 툴팁/튜토리얼 | +| **너무 많은 스탯** | 이해하기 어려움 | 핵심 6개만 강조 | +| **숨겨진 메커니즘** | 어떻게 작동하는지 모름 | 공식 공개 (도움말) | + +--- + +## 16. 핵심 재미 요약 + +``` +┌─────────────────────────────────────────────────────┐ +│ │ +│ 🎮 ASCII Never Die의 5가지 재미 │ +│ │ +│ 1. "조금만 더" - 다음 레벨업이 가까워! │ +│ → 경험치 바, 레벨업 보상 미리보기 │ +│ │ +│ 2. "오 뭐지?" - 예상 못한 전설 아이템! │ +│ → 랜덤 이벤트, 희귀 드롭 연출 │ +│ │ +│ 3. "다시 해보자" - 사망해도 다시 도전! │ +│ → 적절한 페널티, 빠른 복귀 │ +│ │ +│ 4. "나 잘하네" - 통계로 보는 내 성장! │ +│ → 상세 통계, 업적, 마일스톤 │ +│ │ +│ 5. "수집 완료!" - 도감 100% 달성! │ +│ → 몬스터/아이템 도감, 수집 보상 │ +│ │ +└─────────────────────────────────────────────────────┘ +``` + +--- + +## 17. 작업 우선순위 및 의존성 + +```mermaid +graph TD + P1[Phase 1: 전투 시스템] --> P2[Phase 2: 아이템] + P1 --> P5[Phase 5: 종족/클래스] + P2 --> P3[Phase 3: 스킬] + P1 --> P4[Phase 4: 사망/부활] + P2 --> P4 + P3 --> P4 + P5 --> P6[Phase 6: 밸런싱] + P4 --> P6 + P6 --> P7[Phase 7: 콘텐츠] + P7 --> P9[Phase 9: 스토리] + P9 --> P10[Phase 10: 명예의 전당] + + P8[Phase 8: UI/UX] -.-> P1 + P8 -.-> P4 +``` + +### 권장 작업 순서 + +1. **Phase 1: 핵심 전투 시스템** (필수, 모든 것의 기반) +2. **Phase 2: 아이템 시스템** (전투 시스템 활용) +3. **Phase 5: 종족/클래스 특화** (전투 시스템과 병렬 가능) +4. **Phase 3: 스킬 시스템** (전투 + 아이템 필요) +5. **Phase 4: 사망/부활 시스템** (전투 + 아이템 + 스킬 필요) +6. **Phase 8: UI/UX 개선** (다른 Phase와 병렬 진행 가능) +7. **Phase 6: 밸런싱** (모든 시스템 완료 후) +8. **Phase 7: 콘텐츠 확장** (밸런싱 후) +9. **Phase 9: 스토리/엔딩** (콘텐츠 확장 후) +10. **Phase 10: 명예의 전당** (최종) + +--- + +## 18. 총 예상 작업량 + +### 18.1 핵심 Phase (Phase 1-10) + +| Phase | 신규 코드 | 수정 코드 | 파일 수 | +|-------|----------|----------|---------| +| 1. 전투 시스템 | 400 | 200 | 5 | +| 2. 아이템 | 500 | 300 | 6 | +| 3. 스킬 | 600 | 200 | 6 | +| 4. 사망/부활 | 500 | 200 | 7 | +| 5. 종족/클래스 | 400 | 150 | 7 | +| 6. 밸런싱 | 300 | 400 | 5 | +| 7. 콘텐츠 | 1000 | 200 | 5 | +| 8. UI/UX | 400 | 200 | 6 | +| 9. 스토리 | 600 | 100 | 5 | +| 10. 명예의 전당 | 400 | 100 | 5 | +| **소계** | **5,100** | **2,050** | **57** | + +### 18.2 추가 시스템 (Section 13) + +| 시스템 | 신규 코드 | 수정 코드 | 파일 수 | +|--------|----------|----------|---------| +| 13.1 사운드/음악/진동 | 300 | 100 | 4 | +| 13.2 업적 시스템 | 400 | 150 | 5 | +| 13.3 도감 시스템 | 350 | 100 | 4 | +| 13.4 통계 화면 | 300 | 100 | 4 | +| 13.8 튜토리얼 | 400 | 150 | 4 | +| 13.9 오프라인 진행 | 300 | 100 | 4 | +| 13.10 멀티 세이브 | 250 | 150 | 4 | +| 13.11 데이터 마이그레이션 | 200 | 100 | 3 | +| 13.12 몬스터 AI/보스 | 500 | 200 | 5 | +| 13.13 퀘스트 시스템 | 600 | 200 | 6 | +| 13.14 세이브 파일 관리 | 250 | 100 | 3 | +| 13.15 접근성 | 200 | 100 | 3 | +| 13.16 세트 아이템 | 300 | 100 | 3 | +| 13.17 강화/합성 | 350 | 150 | 4 | +| 13.18 인벤토리 관리 | 300 | 150 | 4 | +| 13.19 버프/디버프 | 400 | 150 | 4 | +| 13.20 칭호 시스템 | 250 | 100 | 3 | +| **소계** | **5,650** | **2,100** | **67** | + +### 18.3 총합 + +| 구분 | 신규 코드 | 수정 코드 | 파일 수 | +|------|----------|----------|---------| +| 핵심 Phase | 5,100 | 2,050 | 57 | +| 추가 시스템 | 5,650 | 2,100 | 67 | +| **총합** | **10,750** | **4,150** | **124** | + +### 18.4 총 예상 코드량 + +약 14,900 LOC + +--- + +## 19. 위험 요소 및 대응 + +| 위험 | 영향 | 대응 방안 | +|------|------|----------| +| 밸런스 붕괴 | 게임성 저하 | 시뮬레이션 테스트, 점진적 조정 | +| 복잡도 증가 | 유지보수 어려움 | 모듈화, 문서화 철저 | +| 기존 세이브 호환성 | 사용자 데이터 손실 | 마이그레이션 로직 필수 | +| 성능 저하 | UX 저하 | 프로파일링, 최적화 | +| 원본과의 괴리 | 정체성 혼란 | 명확한 차별화 선언 | + +--- + +## 20. 버전 계획 + +### 20.1 MVP (Minimum Viable Product) + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.5.0 | Phase 1, 2 | 기본 전투 + 아이템 스탯 | +| v0.6.0 | Phase 3, 5 | 스킬 + 종족/클래스 특화 | +| v0.7.0 | Phase 4, 13.11 | 사망/부활 + 데이터 마이그레이션 | + +### 20.2 Core Features + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.8.0 | Phase 8, 13.8 | UI/UX + 튜토리얼 | +| v0.9.0 | 13.10, 13.14 | 멀티 세이브 + 세이브 관리 | +| v0.10.0 | Phase 6, 13.12 | 밸런싱 + 보스 패턴 | + +### 20.3 Content Expansion + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.11.0 | 13.13, 13.16 | 퀘스트 시스템 + 세트 아이템 | +| v0.12.0 | 13.17, 13.18 | 강화/합성 + 인벤토리 | +| v0.13.0 | 13.19, 13.20 | 버프/디버프 + 칭호 | + +### 20.4 Polish & Release + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.14.0 | Phase 7, 9 | 콘텐츠 확장 + 스토리 | +| v0.15.0 | 13.2, 13.3 | 업적 + 도감 | +| v0.16.0 | 13.4, 13.1 | 통계 + 사운드 | +| v0.17.0 | 13.9, 13.15 | 오프라인 진행 + 접근성 | +| v0.18.0 | Phase 10 | 명예의 전당 | + +### 20.5 정식 출시 + +| 버전 | 목표 | +|------|------| +| v1.0.0-beta | 전체 기능 테스트 | +| v1.0.0-rc | 버그 수정, 밸런싱 미세조정 | +| v1.0.0 | 정식 출시 | + +### 20.6 Post-Launch + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v1.1.0 | 13.22.1 | 타임어택/스피드런 | +| v1.2.0 | 13.22.3 | 다국어 확장 (일본어, 중국어) | +| v1.5.0 | 13.6.2 | 아스키 아레나 (온라인 기능) | + +--- + +*문서 작성일: 2024년* +*ASCII Never Die - 게임 시스템 개편 계획 v2.0* diff --git a/doc/game-system-overhaul-index.md b/doc/game-system-overhaul-index.md new file mode 100644 index 0000000..a770fbc --- /dev/null +++ b/doc/game-system-overhaul-index.md @@ -0,0 +1,242 @@ +# ASCII Never Die - 게임 시스템 개편 계획 + +## 1. 개요 + +### 1.1 목적 +Progress Quest 클론에서 **실제 게임성을 갖춘 RPG**로 전환한다. +Idle game의 자동 진행 특성은 유지하되, 전투/성장/사망의 의미있는 시스템을 도입한다. + +### 1.2 핵심 변경 사항 +- Stats가 전투에 실제 영향을 미침 +- 사망 시스템 및 부활 메커니즘 +- MP 기반 스킬 시스템 +- 아이템 스탯 및 가중치 +- 레벨 1-100 밸런싱 +- 종족/클래스 특화 + +### 1.3 현재 상태 +| 항목 | 현재 | 목표 | +|------|------|------| +| Stats | 장식용 (CON→HP, INT→MP, WIS→주문, STR→무게만 영향) | 전투력에 직접 영향 | +| 전투 | 시간 경과 시 자동 승리 | 데미지 계산, 승패 결정 | +| 사망 | 없음 | 장비 상실, 부활 버튼 | +| 스킬 | 획득만 (사용 없음) | MP 소모, 쿨타임 | +| 아이템 | 이름만 존재 | 스탯 보정, 가중치 | +| 레벨 | 무한 성장 | 1-100 (100에서 성장 멈춤) | + +--- + +## 2. 수정 단계 (Phase) + +``` +Phase 1: 핵심 전투 시스템 ████████████████████ (기반) +Phase 2: 아이템 시스템 ████████████████ (의존: Phase 1) +Phase 3: 스킬 시스템 ████████████ (의존: Phase 1, 2) +Phase 4: 사망/부활 시스템 ████████ (의존: Phase 1, 2, 3) +Phase 5: 종족/클래스 특화 ██████ (의존: Phase 1) +Phase 6: 밸런싱 ████████████████████ (전체 의존) +Phase 7: 콘텐츠 확장 ████████████ (의존: Phase 6) +Phase 8: UI/UX 개선 ████████ (병렬 가능) +Phase 9: 스토리/엔딩 ██████ (의존: Phase 7) +Phase 10: 명예의 전당 ████ (최종) +``` + +--- + +## 문서 구조 + +이 계획서는 다음 태스크 문서들로 구성됩니다: + +### 핵심 Phase 문서 +| 문서 | 내용 | +|------|------| +| [task-phase-01-combat.md](task-phase-01-combat.md) | Phase 1: 핵심 전투 시스템 | +| [task-phase-02-items.md](task-phase-02-items.md) | Phase 2: 아이템 시스템 | +| [task-phase-03-skills.md](task-phase-03-skills.md) | Phase 3: 스킬 시스템 | +| [task-phase-04-death.md](task-phase-04-death.md) | Phase 4: 사망/부활 시스템 | +| [task-phase-05-race-class.md](task-phase-05-race-class.md) | Phase 5: 종족/클래스 특화 | +| [task-phase-06-balance.md](task-phase-06-balance.md) | Phase 6: 밸런싱 | +| [task-phase-07-content.md](task-phase-07-content.md) | Phase 7: 콘텐츠 확장 | +| [task-phase-08-ui.md](task-phase-08-ui.md) | Phase 8: UI/UX 개선 | +| [task-phase-09-story.md](task-phase-09-story.md) | Phase 9: 스토리/엔딩 | +| [task-phase-10-hall.md](task-phase-10-hall.md) | Phase 10: 명예의 전당 | + +### 추가 시스템 문서 +| 문서 | 내용 | +|------|------| +| [task-ext-audio-access.md](task-ext-audio-access.md) | 사운드/진동/접근성 | +| [task-ext-meta-systems.md](task-ext-meta-systems.md) | 업적/도감/통계/칭호 | +| [task-ext-settings-infra.md](task-ext-settings-infra.md) | 설정/튜토리얼/성능/테스트 | +| [task-ext-save-data.md](task-ext-save-data.md) | 세이브/멀티슬롯/마이그레이션 | +| [task-ext-combat.md](task-ext-combat.md) | 몬스터 AI/퀘스트/버프 | +| [task-ext-items.md](task-ext-items.md) | 세트/강화/인벤토리/물약 | +| [task-ext-world.md](task-ext-world.md) | 던전/지역/상점 | +| [task-ext-events.md](task-ext-events.md) | 이벤트/알림 | +| [task-ext-ui-tech.md](task-ext-ui-tech.md) | UI 레이아웃/기술 상세 | +| [task-ext-platform.md](task-ext-platform.md) | 오프라인/플랫폼/향후 | + +### 게임 디자인 문서 +| 문서 | 내용 | +|------|------| +| [task-fun-design.md](task-fun-design.md) | 재미 요소 설계 | + +--- + +## 17. 작업 우선순위 및 의존성 + +```mermaid +graph TD + P1[Phase 1: 전투 시스템] --> P2[Phase 2: 아이템] + P1 --> P5[Phase 5: 종족/클래스] + P2 --> P3[Phase 3: 스킬] + P1 --> P4[Phase 4: 사망/부활] + P2 --> P4 + P3 --> P4 + P5 --> P6[Phase 6: 밸런싱] + P4 --> P6 + P6 --> P7[Phase 7: 콘텐츠] + P7 --> P9[Phase 9: 스토리] + P9 --> P10[Phase 10: 명예의 전당] + + P8[Phase 8: UI/UX] -.-> P1 + P8 -.-> P4 +``` + +### 권장 작업 순서 + +1. **Phase 1: 핵심 전투 시스템** (필수, 모든 것의 기반) +2. **Phase 2: 아이템 시스템** (전투 시스템 활용) +3. **Phase 5: 종족/클래스 특화** (전투 시스템과 병렬 가능) +4. **Phase 3: 스킬 시스템** (전투 + 아이템 필요) +5. **Phase 4: 사망/부활 시스템** (전투 + 아이템 + 스킬 필요) +6. **Phase 8: UI/UX 개선** (다른 Phase와 병렬 진행 가능) +7. **Phase 6: 밸런싱** (모든 시스템 완료 후) +8. **Phase 7: 콘텐츠 확장** (밸런싱 후) +9. **Phase 9: 스토리/엔딩** (콘텐츠 확장 후) +10. **Phase 10: 명예의 전당** (최종) + +--- + +## 18. 총 예상 작업량 + +### 18.1 핵심 Phase (Phase 1-10) + +| Phase | 신규 코드 | 수정 코드 | 파일 수 | +|-------|----------|----------|---------| +| 1. 전투 시스템 | 400 | 200 | 5 | +| 2. 아이템 | 500 | 300 | 6 | +| 3. 스킬 | 600 | 200 | 6 | +| 4. 사망/부활 | 500 | 200 | 7 | +| 5. 종족/클래스 | 400 | 150 | 7 | +| 6. 밸런싱 | 300 | 400 | 5 | +| 7. 콘텐츠 | 1000 | 200 | 5 | +| 8. UI/UX | 400 | 200 | 6 | +| 9. 스토리 | 600 | 100 | 5 | +| 10. 명예의 전당 | 400 | 100 | 5 | +| **소계** | **5,100** | **2,050** | **57** | + +### 18.2 추가 시스템 (Section 13) + +| 시스템 | 신규 코드 | 수정 코드 | 파일 수 | +|--------|----------|----------|---------| +| 13.1 사운드/음악/진동 | 300 | 100 | 4 | +| 13.2 업적 시스템 | 400 | 150 | 5 | +| 13.3 도감 시스템 | 350 | 100 | 4 | +| 13.4 통계 화면 | 300 | 100 | 4 | +| 13.8 튜토리얼 | 400 | 150 | 4 | +| 13.9 오프라인 진행 | 300 | 100 | 4 | +| 13.10 멀티 세이브 | 250 | 150 | 4 | +| 13.11 데이터 마이그레이션 | 200 | 100 | 3 | +| 13.12 몬스터 AI/보스 | 500 | 200 | 5 | +| 13.13 퀘스트 시스템 | 600 | 200 | 6 | +| 13.14 세이브 파일 관리 | 250 | 100 | 3 | +| 13.15 접근성 | 200 | 100 | 3 | +| 13.16 세트 아이템 | 300 | 100 | 3 | +| 13.17 강화/합성 | 350 | 150 | 4 | +| 13.18 인벤토리 관리 | 300 | 150 | 4 | +| 13.19 버프/디버프 | 400 | 150 | 4 | +| 13.20 칭호 시스템 | 250 | 100 | 3 | +| **소계** | **5,650** | **2,100** | **67** | + +### 18.3 총합 + +| 구분 | 신규 코드 | 수정 코드 | 파일 수 | +|------|----------|----------|---------| +| 핵심 Phase | 5,100 | 2,050 | 57 | +| 추가 시스템 | 5,650 | 2,100 | 67 | +| **총합** | **10,750** | **4,150** | **124** | + +### 18.4 총 예상 코드량 + +약 14,900 LOC + +--- + +## 19. 위험 요소 및 대응 + +| 위험 | 영향 | 대응 방안 | +|------|------|----------| +| 밸런스 붕괴 | 게임성 저하 | 시뮬레이션 테스트, 점진적 조정 | +| 복잡도 증가 | 유지보수 어려움 | 모듈화, 문서화 철저 | +| 기존 세이브 호환성 | 사용자 데이터 손실 | 마이그레이션 로직 필수 | +| 성능 저하 | UX 저하 | 프로파일링, 최적화 | +| 원본과의 괴리 | 정체성 혼란 | 명확한 차별화 선언 | + +--- + +## 20. 버전 계획 + +### 20.1 MVP (Minimum Viable Product) + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.5.0 | Phase 1, 2 | 기본 전투 + 아이템 스탯 | +| v0.6.0 | Phase 3, 5 | 스킬 + 종족/클래스 특화 | +| v0.7.0 | Phase 4, 13.11 | 사망/부활 + 데이터 마이그레이션 | + +### 20.2 Core Features + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.8.0 | Phase 8, 13.8 | UI/UX + 튜토리얼 | +| v0.9.0 | 13.10, 13.14 | 멀티 세이브 + 세이브 관리 | +| v0.10.0 | Phase 6, 13.12 | 밸런싱 + 보스 패턴 | + +### 20.3 Content Expansion + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.11.0 | 13.13, 13.16 | 퀘스트 시스템 + 세트 아이템 | +| v0.12.0 | 13.17, 13.18 | 강화/합성 + 인벤토리 | +| v0.13.0 | 13.19, 13.20 | 버프/디버프 + 칭호 | + +### 20.4 Polish & Release + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v0.14.0 | Phase 7, 9 | 콘텐츠 확장 + 스토리 | +| v0.15.0 | 13.2, 13.3 | 업적 + 도감 | +| v0.16.0 | 13.4, 13.1 | 통계 + 사운드 | +| v0.17.0 | 13.9, 13.15 | 오프라인 진행 + 접근성 | +| v0.18.0 | Phase 10 | 명예의 전당 | + +### 20.5 정식 출시 + +| 버전 | 목표 | +|------|------| +| v1.0.0-beta | 전체 기능 테스트 | +| v1.0.0-rc | 버그 수정, 밸런싱 미세조정 | +| v1.0.0 | 정식 출시 | + +### 20.6 Post-Launch + +| 버전 | 포함 내용 | 목표 | +|------|----------|------| +| v1.1.0 | 13.22.1 | 타임어택/스피드런 | +| v1.2.0 | 13.22.3 | 다국어 확장 (일본어, 중국어) | +| v1.5.0 | 13.6.2 | 아스키 아레나 (온라인 기능) | + +--- + +*문서 작성일: 2024년* +*ASCII Never Die - 게임 시스템 개편 계획 v2.0* diff --git a/doc/game-system-overhaul-plan.md b/doc/game-system-overhaul-plan.md deleted file mode 100644 index 09a5eb7..0000000 --- a/doc/game-system-overhaul-plan.md +++ /dev/null @@ -1,1502 +0,0 @@ -# ASCII Never Die - 게임 시스템 개편 계획 - -## 1. 개요 - -### 1.1 목적 -Progress Quest 클론에서 **실제 게임성을 갖춘 RPG**로 전환한다. -Idle game의 자동 진행 특성은 유지하되, 전투/성장/사망의 의미있는 시스템을 도입한다. - -### 1.2 핵심 변경 사항 -- Stats가 전투에 실제 영향을 미침 -- 사망 시스템 및 부활 메커니즘 -- MP 기반 스킬 시스템 -- 아이템 스탯 및 가중치 -- 레벨 1-100 밸런싱 -- 종족/클래스 특화 - -### 1.3 현재 상태 -| 항목 | 현재 | 목표 | -|------|------|------| -| Stats | 장식용 (CON→HP, INT→MP, WIS→주문, STR→무게만 영향) | 전투력에 직접 영향 | -| 전투 | 시간 경과 시 자동 승리 | 데미지 계산, 승패 결정 | -| 사망 | 없음 | 장비 상실, 부활 버튼 | -| 스킬 | 획득만 (사용 없음) | MP 소모, 쿨타임 | -| 아이템 | 이름만 존재 | 스탯 보정, 가중치 | -| 레벨 | 무한 성장 | 1-100 (100에서 성장 멈춤) | - ---- - -## 2. 수정 단계 (Phase) - -``` -Phase 1: 핵심 전투 시스템 ████████████████████ (기반) -Phase 2: 아이템 시스템 ████████████████ (의존: Phase 1) -Phase 3: 스킬 시스템 ████████████ (의존: Phase 1, 2) -Phase 4: 사망/부활 시스템 ████████ (의존: Phase 1, 2, 3) -Phase 5: 종족/클래스 특화 ██████ (의존: Phase 1) -Phase 6: 밸런싱 ████████████████████ (전체 의존) -Phase 7: 콘텐츠 확장 ████████████ (의존: Phase 6) -Phase 8: UI/UX 개선 ████████ (병렬 가능) -Phase 9: 스토리/엔딩 ██████ (의존: Phase 7) -Phase 10: 명예의 전당 ████ (최종) -``` - ---- - -## 3. Phase 1: 핵심 전투 시스템 - -### 3.1 목표 -Stats가 전투에 실제 영향을 미치도록 전투 계산 로직을 구현한다. - -### 3.2 새로운 Stats 구조 - -```dart -class CombatStats { - // 기본 스탯 (캐릭터 고유) - final int str; // 힘: 물리 공격력 보정 - final int con; // 체력: HP, 방어력 보정 - final int dex; // 민첩: 회피율, 크리티컬율, 명중률 - final int intelligence; // 지능: 마법 공격력, MP - final int wis; // 지혜: 마법 방어력, MP 회복 - final int cha; // 매력: 상점 가격, 드롭률 보정 - - // 파생 스탯 (장비 + 기본 스탯으로 계산) - final int atk; // 공격력 - final int def; // 방어력 - final int magAtk; // 마법 공격력 - final int magDef; // 마법 방어력 - final double criRate; // 크리티컬 확률 (0.0 ~ 1.0) - final double criDamage; // 크리티컬 데미지 배율 (1.5 ~ 3.0) - final double evasion; // 회피율 (0.0 ~ 0.5) - final double accuracy; // 명중률 (0.8 ~ 1.0) - final double blockRate; // 방패 방어율 (0.0 ~ 0.4) - final double parryRate; // 무기로 쳐내기 확률 (0.0 ~ 0.3) - - // 자원 - final int hpMax; - final int hpCurrent; - final int mpMax; - final int mpCurrent; -} -``` - -### 3.3 전투 계산 공식 - -``` -1. 명중 판정 - 명중 = random() < (공격자.accuracy - 방어자.evasion) - -2. 방어 판정 (명중 시) - 방패 방어 = random() < 방어자.blockRate - 무기 쳐내기 = random() < 방어자.parryRate - -3. 데미지 계산 - 기본 데미지 = 공격자.atk * (1 + random() * 0.2) - 방어자.def * 0.5 - - 크리티컬 판정 = random() < 공격자.criRate - if (크리티컬) 데미지 *= 공격자.criDamage - - if (방패 방어) 데미지 *= 0.3 - if (무기 쳐내기) 데미지 *= 0.5 - - 최종 데미지 = max(1, 데미지) - -4. 전투 결과 - 방어자.hp -= 최종 데미지 - if (방어자.hp <= 0) 전투 종료 -``` - -### 3.4 전투 틱 시스템 - -``` -현재: 2초 후 자동 승리 -변경: 매 틱(200ms)마다 공격 교환, HP가 0이 되면 승패 결정 - -전투 흐름: -1. 플레이어 턴 (atk 기반 공격) -2. 몬스터 턴 (몬스터 레벨 기반 공격) -3. HP 체크 -4. 반복 또는 종료 -``` - -### 3.5 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/model/game_state.dart` | CombatStats 클래스 추가, Stats 구조 변경 | -| `core/engine/progress_service.dart` | 전투 틱 로직 변경 | -| `core/util/pq_logic.dart` | 전투 계산 함수 추가 | -| `core/engine/combat_calculator.dart` | **신규** - 전투 계산 전담 | - -### 3.6 예상 작업량 -- 예상 파일 수: 4-5개 -- 신규 코드: ~400 LOC -- 수정 코드: ~200 LOC - ---- - -## 4. Phase 2: 아이템 시스템 - -### 4.1 목표 -아이템에 스탯 보정치를 부여하고, 가중치 시스템을 도입한다. - -### 4.2 아이템 스탯 구조 - -```dart -class ItemStats { - final int atk; // 공격력 보정 - final int def; // 방어력 보정 - final int magAtk; // 마법 공격력 보정 - final int magDef; // 마법 방어력 보정 - final double criRate; // 크리티컬 확률 보정 - final double evasion; // 회피율 보정 - final double blockRate; // 방패 방어율 (방패 전용) - final double parryRate; // 무기 쳐내기 (무기 전용) - - // 추가 효과 - final int hpBonus; - final int mpBonus; - final int strBonus; - final int dexBonus; - // ... 기타 스탯 보너스 -} - -class Equipment { - final String name; - final EquipmentSlot slot; - final int level; // 아이템 레벨 - final int weight; // 가중치 (높을수록 좋은 아이템) - final ItemStats stats; - final ItemRarity rarity; // Common, Uncommon, Rare, Epic, Legendary -} -``` - -### 4.3 아이템 가중치 계산 - -``` -가중치 = 기본값 + (레벨 * 10) + (희귀도 보너스) + (스탯 합계) - -희귀도 보너스: -- Common: 0 -- Uncommon: 50 -- Rare: 150 -- Epic: 400 -- Legendary: 1000 -``` - -### 4.4 자동 장착 로직 - -``` -1. 인벤토리에서 장착 가능한 아이템 필터링 -2. 슬롯별로 그룹화 -3. 각 슬롯에서 가장 높은 가중치 아이템 선택 -4. 현재 장비와 비교하여 더 좋으면 교체 -``` - -### 4.5 아이템 생성 공식 - -```dart -/// 아이템 스탯 생성 (레벨 기반) -ItemStats generateItemStats(int level, ItemRarity rarity, EquipmentSlot slot) { - final rarityMultiplier = { - ItemRarity.common: 1.0, - ItemRarity.uncommon: 1.3, - ItemRarity.rare: 1.7, - ItemRarity.epic: 2.2, - ItemRarity.legendary: 3.0, - }[rarity]!; - - final baseValue = (level * 2 * rarityMultiplier).round(); - - // 슬롯별 주요 스탯 결정 - return switch (slot) { - EquipmentSlot.weapon => ItemStats(atk: baseValue, ...), - EquipmentSlot.shield => ItemStats(def: baseValue ~/ 2, blockRate: 0.1, ...), - EquipmentSlot.armor => ItemStats(def: baseValue, ...), - // ... - }; -} -``` - -### 4.6 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/model/game_state.dart` | Equipment 구조 변경, ItemStats 추가 | -| `core/model/equipment_slot.dart` | 슬롯별 기본 스탯 정의 | -| `core/util/pq_logic.dart` | 아이템 생성 로직 변경 | -| `core/engine/item_service.dart` | **신규** - 아이템 관리 전담 | -| `data/pq_config_data.dart` | 아이템 기본 데이터 확장 | - -### 4.7 예상 작업량 -- 예상 파일 수: 5-6개 -- 신규 코드: ~500 LOC -- 수정 코드: ~300 LOC - ---- - -## 5. Phase 3: 스킬 시스템 - -### 5.1 목표 -MP를 소모하여 스킬을 사용하고, 쿨타임을 관리한다. - -### 5.2 스킬 구조 - -```dart -class Skill { - final String id; - final String name; - final SkillType type; // attack, heal, buff, debuff - final int mpCost; - final int cooldownMs; // 쿨타임 (밀리초) - final int power; // 스킬 위력 - - // 효과 - final double damageMultiplier; // 공격 스킬: 데미지 배율 - final int healAmount; // 회복 스킬: 회복량 - final BuffEffect? buff; // 버프 효과 -} - -class SkillState { - final String skillId; - final int lastUsedMs; // 마지막 사용 시간 - final int rank; // 스킬 레벨 - - bool isReady(int currentMs) => - currentMs - lastUsedMs >= skill.cooldownMs; -} -``` - -### 5.3 MP 시스템 - -``` -MP 회복: -- 비전투 시: 50ms당 1 회복 -- 전투 중: 회복 없음 (또는 WIS에 비례하여 느리게 회복) -- 전투 종료: 즉시 전체 회복 - -MP 소모: -- 스킬 사용 시 즉시 차감 -- MP 부족 시 스킬 사용 불가 (일반 공격으로 대체) -``` - -### 5.4 스킬 사용 로직 - -``` -자동 스킬 사용 우선순위: -1. HP < 30% → 회복 스킬 (있으면) -2. 보스전 → 가장 강력한 공격 스킬 -3. 일반 전투 → MP 효율이 좋은 스킬 -4. MP < 20% → 일반 공격만 - -수동 개입: -- 현재 버전에서는 자동만 지원 -- 향후 수동 스킬 사용 UI 추가 가능 -``` - -### 5.5 스킬 목록 예시 - -| 스킬명 | 타입 | MP | 쿨타임 | 효과 | -|--------|------|-----|--------|------| -| Debug Strike | attack | 10 | 3s | 데미지 150% | -| Memory Leak | attack | 25 | 8s | 데미지 250%, 적 방어력 -20% | -| Hot Reload | heal | 20 | 10s | HP 30% 회복 | -| Safe Mode | buff | 30 | 30s | 방어력 +50%, 10초 지속 | -| Core Dump | attack | 50 | 20s | 데미지 400% | -| Kernel Panic | attack | 100 | 60s | 데미지 800%, 자신 HP -10% | - -### 5.6 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/model/game_state.dart` | SkillState 추가 | -| `core/model/skill.dart` | **신규** - 스킬 정의 | -| `core/engine/skill_service.dart` | **신규** - 스킬 사용 로직 | -| `core/engine/progress_service.dart` | MP 회복 로직, 스킬 자동 사용 | -| `data/skill_data.dart` | **신규** - 스킬 데이터 | - -### 5.7 예상 작업량 -- 예상 파일 수: 5-6개 -- 신규 코드: ~600 LOC -- 수정 코드: ~200 LOC - ---- - -## 6. Phase 4: 사망/부활 시스템 - -### 6.1 목표 -사망 개념을 도입하고, 페널티 및 부활 메커니즘을 구현한다. - -### 6.2 사망 조건 - -``` -사망 = HP <= 0 - -사망 시 처리: -1. 게임 루프 일시 정지 -2. 장착 중인 모든 장비 제거 (인벤토리로 이동하지 않음 - 상실) -3. 인벤토리 아이템 유지 -4. 골드 유지 -5. 경험치 유지 (레벨 다운 없음) -6. 사망 UI 표시 (부활 버튼) -``` - -### 6.3 부활 프로세스 - -``` -부활 버튼 클릭 시: -1. HP/MP 전체 회복 -2. 자동으로 샵 이동 -3. 골드로 구매 가능한 최고 장비 자동 구매 -4. 각 슬롯에 장비 자동 장착 -5. 게임 루프 재개 -``` - -### 6.4 샵 시스템 - -```dart -class Shop { - /// 현재 레벨에서 구매 가능한 장비 목록 - List getAvailableItems(int playerLevel, int gold); - - /// 최적의 장비 세트 자동 구매 - PurchaseResult autoBuy(int playerLevel, int gold, List emptySlots); -} - -class PurchaseResult { - final List purchased; - final int totalCost; - final int remainingGold; -} -``` - -### 6.5 장비 가격 공식 - -``` -기본 가격 = 아이템 레벨 * 50 * 희귀도 배율 - -희귀도 배율: -- Common: 1.0 -- Uncommon: 2.0 -- Rare: 5.0 -- Epic: 15.0 -- Legendary: 50.0 - -판매 가격 = 구매 가격 * 0.3 -``` - -### 6.6 사망 UI - -``` -┌─────────────────────────────────────┐ -│ │ -│ YOU DIED │ -│ │ -│ Level 45 버그 헌터 │ -│ │ -│ 사망 원인: 커널 패닉 │ -│ │ -│ ───────────────────────── │ -│ 장비 상실: 7개 │ -│ 보유 골드: 15,420 │ -│ ───────────────────────── │ -│ │ -│ [ 부활하기 ] │ -│ │ -└─────────────────────────────────────┘ -``` - -### 6.7 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/model/game_state.dart` | isDead 플래그, deathInfo 추가 | -| `core/engine/progress_service.dart` | 사망 판정 로직 | -| `core/engine/resurrection_service.dart` | **신규** - 부활 처리 | -| `core/engine/shop_service.dart` | **신규** - 샵 로직 | -| `features/game/widgets/death_overlay.dart` | **신규** - 사망 UI | -| `features/game/game_session_controller.dart` | 사망/부활 상태 관리 | - -### 6.8 예상 작업량 -- 예상 파일 수: 6-7개 -- 신규 코드: ~500 LOC -- 수정 코드: ~200 LOC - ---- - -## 7. Phase 5: 종족/클래스 특화 - -### 7.1 목표 -종족과 클래스에 고유한 능력치 보정과 특수 능력을 부여한다. - -### 7.2 종족 특성 - -```dart -class RaceTraits { - final String raceId; - final Map statModifiers; // 스탯 보정 - final List passives; // 패시브 능력 - final double expMultiplier; // 경험치 배율 -} -``` - -| 종족 | STR | CON | DEX | INT | WIS | CHA | 특수 능력 | -|------|-----|-----|-----|-----|-----|-----|----------| -| Byte Human | 0 | 0 | 0 | 0 | 0 | +2 | 경험치 +10% | -| Null Elf | -1 | -1 | +2 | +2 | 0 | 0 | 마법 데미지 +15% | -| Buffer Dwarf | +2 | +2 | -1 | -1 | 0 | 0 | 방어력 +10% | -| Stack Goblin | -1 | -1 | +3 | 0 | 0 | +1 | 크리티컬 확률 +5% | -| Heap Troll | +3 | +3 | -2 | -2 | 0 | 0 | HP +20% | -| Pointer Fairy | -2 | -2 | +2 | +2 | +2 | 0 | MP +20% | -| Coredump Undead | +1 | +2 | -1 | 0 | 0 | -2 | 사망 시 장비 1개 유지 | - -### 7.3 클래스 특성 - -```dart -class ClassTraits { - final String classId; - final Map statModifiers; - final List startingSkills; // 시작 스킬 - final List classSkills; // 클래스 전용 스킬 - final EquipmentRestriction restrictions; // 장비 제한 -} -``` - -| 클래스 | 주요 스탯 | 장비 제한 | 특수 능력 | -|--------|----------|----------|----------| -| Bug Hunter | STR/DEX | 전체 가능 | 일반 공격 +20% | -| Debugger Paladin | STR/CON | 중갑, 방패 | 방어력 +15%, 회복력 +10% | -| Compiler Mage | INT/WIS | 경갑, 지팡이 | 마법 데미지 +25% | -| Refactor Monk | DEX/WIS | 경갑, 맨손 | 회피율 +15%, 연속 공격 | -| Pointer Assassin | DEX/STR | 경갑, 단검 | 크리티컬 +20%, 첫 공격 2배 | -| Garbage Collector | CON/STR | 중갑 | HP +30%, 전투 후 HP 10% 회복 | - -### 7.4 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/model/race_traits.dart` | **신규** - 종족 특성 | -| `core/model/class_traits.dart` | **신규** - 클래스 특성 | -| `data/race_data.dart` | **신규** - 종족 데이터 | -| `data/class_data.dart` | **신규** - 클래스 데이터 | -| `core/engine/stat_calculator.dart` | **신규** - 최종 스탯 계산 | -| `features/character/character_creation.dart` | 종족/클래스 선택 UI 개선 | - -### 7.5 예상 작업량 -- 예상 파일 수: 6-7개 -- 신규 코드: ~400 LOC -- 수정 코드: ~150 LOC - ---- - -## 8. Phase 6: 밸런싱 - -### 8.1 목표 -레벨 1-100 구간에서 적절한 난이도 곡선을 설계한다. - -### 8.2 레벨 구간 설계 - -| 구간 | 레벨 | 특징 | 예상 플레이 시간 | -|------|------|------|-----------------| -| 초반 | 1-20 | 튜토리얼, 기본 시스템 학습 | 1-2시간 | -| 중반 | 21-50 | 본격적인 성장, 다양한 스킬 | 3-5시간 | -| 후반 | 51-80 | 고급 장비, 어려운 몬스터 | 5-8시간 | -| 엔드게임 | 81-100 | 최종 보스, 명예의 전당 | 3-5시간 | - -### 8.3 경험치 곡선 - -``` -레벨업 필요 경험치 = 기본값 * (1.15 ^ 레벨) - -기본값 = 100 -레벨 10: 405 exp -레벨 50: 108,366 exp -레벨 100: 11,739,085 exp -``` - -### 8.4 몬스터 스탯 스케일링 - -```dart -MonsterStats generateMonster(int level) { - return MonsterStats( - hp: 50 + level * 20 + (level * level / 5).round(), - atk: 5 + level * 3, - def: 2 + level * 2, - exp: 10 + level * 5, - gold: 5 + level * 3, - ); -} -``` - -### 8.5 사망 확률 목표 - -| 레벨 구간 | 목표 사망 확률 (전투당) | -|----------|----------------------| -| 1-20 | 1-3% | -| 21-50 | 3-5% | -| 51-80 | 5-10% | -| 81-100 | 10-20% | - -### 8.6 밸런스 테스트 도구 - -```dart -/// 시뮬레이션으로 밸런스 검증 -class BalanceSimulator { - /// 특정 레벨 구간을 N회 시뮬레이션 - SimulationResult simulate({ - required int startLevel, - required int endLevel, - required int iterations, - }); -} - -class SimulationResult { - final double averageDeaths; - final double averageTimeMinutes; - final double survivalRate; - final List deathCauses; -} -``` - -### 8.7 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/util/balance_constants.dart` | **신규** - 밸런스 상수 | -| `core/util/pq_logic.dart` | 경험치/몬스터 스케일링 | -| `data/pq_config_data.dart` | 몬스터 레벨 재조정 | -| `test/balance_test.dart` | **신규** - 밸런스 테스트 | - -### 8.8 예상 작업량 -- 예상 파일 수: 4-5개 -- 신규 코드: ~300 LOC -- 수정 코드: ~400 LOC -- 테스트 및 조정: 반복 작업 필요 - ---- - -## 9. Phase 7: 콘텐츠 확장 - -### 9.1 목표 -더 많은 몬스터, 아이템, 애니메이션을 추가한다. - -### 9.2 몬스터 확장 - -현재: ~100종 -목표: ~200종 - -추가할 몬스터 카테고리: -- 레벨 81-100 엔드게임 몬스터 (30종) -- 보스 몬스터 (10종, 각 Act 마다) -- 미니 보스 (20종) -- 특수 이벤트 몬스터 (20종) -- 퀘스트 전용 몬스터 (20종) - -### 9.3 아이템 확장 - -현재: 이름만 존재 -목표: 스탯이 있는 300+ 아이템 - -카테고리별 추가: -- 무기 (50종): 검, 도끼, 활, 지팡이, 단검 등 -- 방어구 (80종): 투구, 갑옷, 장갑, 부츠, 망토 -- 방패 (30종) -- 악세서리 (50종): 반지, 목걸이, 귀걸이 -- 소모품 (50종): 물약, 스크롤 - -### 9.4 ASCII 애니메이션 확장 - -#### 9.4.1 전투 결과별 애니메이션 - -| 상황 | 애니메이션 | -|------|----------| -| 일반 공격 | 기존 battle_mode | -| 크리티컬 히트 | 화려한 이펙트 | -| 회피 성공 | 살짝 비켜가는 모션 | -| 방패 방어 | 방패 들어올리기 | -| 스킬 사용 | 스킬별 고유 애니메이션 | -| 사망 | 쓰러지는 애니메이션 | -| 레벨업 | 빛나는 이펙트 | - -#### 9.4.2 몬스터별 애니메이션 - -```dart -class MonsterAnimation { - final String monsterId; - final List idleFrames; - final List attackFrames; - final List hitFrames; - final List deathFrames; -} -``` - -카테고리별 기본 애니메이션: -- 버그류 (곤충 형태) -- 언데드류 (좀비, 유령) -- 드래곤류 (대형) -- 휴머노이드류 (NPC형) -- 기계류 (로봇, 바이러스) - -### 9.5 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `data/pq_config_data.dart` | 몬스터/아이템 데이터 확장 | -| `data/ascii_animation_data.dart` | 애니메이션 프레임 추가 | -| `data/monster_animations.dart` | **신규** - 몬스터별 애니메이션 | -| `features/game/widgets/ascii_animation_card.dart` | 상황별 애니메이션 선택 | - -### 9.6 예상 작업량 -- 예상 파일 수: 4-5개 -- 신규 코드: ~1000 LOC (대부분 데이터) -- 수정 코드: ~200 LOC - ---- - -## 10. Phase 8: UI/UX 개선 - -### 10.1 목표 -능력치 변화를 실시간으로 표시하고, 전반적인 UI를 개선한다. - -### 10.2 실시간 스탯 변화 표시 - -``` -┌─ Stats ─────────────────┐ -│ HP: 450/500 ████████░░ │ -│ MP: 80/120 ██████░░░░ │ -│ │ -│ ATK: 125 (+15) ▲ │ ← 장비 변경 시 변화량 표시 -│ DEF: 89 (-5) ▼ │ -│ CRI: 12.5% │ -│ EVA: 8.3% │ -└─────────────────────────┘ -``` - -### 10.3 전투 로그 - -``` -┌─ Combat Log ────────────────────┐ -│ > 문법 오류를 공격! 45 데미지 │ -│ > 문법 오류의 반격! 12 데미지 │ -│ > 크리티컬! 98 데미지 │ -│ > Debug Strike 사용! 150 데미지 │ -│ > 문법 오류 처치! +25 exp │ -└─────────────────────────────────┘ -``` - -### 10.4 알림 시스템 - -| 이벤트 | 표시 방식 | -|--------|----------| -| 레벨업 | 화면 중앙 팝업 + 사운드 | -| 장비 획득 | 우측 하단 토스트 | -| 스탯 변화 | 해당 스탯 옆 애니메이션 | -| 사망 위험 (HP < 20%) | HP 바 깜빡임 | -| 스킬 쿨타임 완료 | 스킬 아이콘 빛남 | - -### 10.5 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `features/game/widgets/stats_panel.dart` | 스탯 변화 애니메이션 | -| `features/game/widgets/combat_log.dart` | **신규** - 전투 로그 | -| `features/game/widgets/notification_overlay.dart` | **신규** - 알림 | -| `core/service/notification_service.dart` | **신규** - 알림 관리 | - -### 10.6 예상 작업량 -- 예상 파일 수: 5-6개 -- 신규 코드: ~400 LOC -- 수정 코드: ~200 LOC - ---- - -## 11. Phase 9: 스토리/엔딩 - -### 11.1 목표 -프롤로그부터 엔딩까지 일관된 스토리를 구성한다. - -### 11.2 스토리 구조 - -``` -Act I (레벨 1-20): 각성 -- 프롤로그: 코드의 신으로부터 비전을 받음 -- 마을에서 기본 훈련 -- 첫 번째 던전: 버그 둥지 -- Act I 보스: Syntax Error Dragon - -Act II (레벨 21-40): 성장 -- 디버거 기사단 가입 -- 손상된 네트워크 탐험 -- 배신자 발견 -- Act II 보스: Memory Leak Hydra - -Act III (레벨 41-60): 시련 -- 널 왕국 진입 -- 고대 컴파일러의 시험 -- 동료의 희생 -- Act III 보스: Buffer Overflow Titan - -Act IV (레벨 61-80): 결전 -- 글리치 신의 성채 침입 -- 최후의 동맹 결성 -- Act IV 보스: Kernel Panic Archon - -Act V (레벨 81-100): 종말 -- 글리치 신과의 최종 대결 -- 다중 페이즈 보스전 -- 엔딩: 시스템 재부팅, 평화 회복 -``` - -### 11.3 시네마틱 개선 - -각 Act 전환 시: -- 전용 시네마틱 텍스트 (5-10개 단계) -- ASCII 아트 일러스트 -- 분위기에 맞는 색상 테마 - -### 11.4 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `data/story_data.dart` | **신규** - 스토리 텍스트 | -| `data/game_text_l10n.dart` | 시네마틱 텍스트 확장 | -| `core/engine/story_service.dart` | **신규** - 스토리 진행 관리 | -| `features/game/widgets/cinematic_view.dart` | **신규** - 시네마틱 UI | - -### 11.5 예상 작업량 -- 예상 파일 수: 4-5개 -- 신규 코드: ~600 LOC (대부분 텍스트) -- 수정 코드: ~100 LOC - ---- - -## 12. Phase 10: 명예의 전당 - -### 12.1 목표 -게임 클리어 시 캐릭터를 명예의 전당에 등재한다. - -### 12.2 클리어 조건 - -``` -클리어 = 레벨 100 달성 + 글리치 신 처치 -``` - -### 12.3 명예의 전당 데이터 - -```dart -class HallOfFameEntry { - final String id; - final String characterName; - final String race; - final String klass; - final int level; - final Duration totalPlayTime; - final int totalDeaths; - final int monstersKilled; - final DateTime clearedAt; - - // 향후 아스키 아레나용 - final CombatStats finalStats; - final List finalEquipment; - final List skills; -} -``` - -### 12.4 명예의 전당 UI - -``` -╔═══════════════════════════════════════════════════╗ -║ 명예의 전당 ║ -╠═══════════════════════════════════════════════════╣ -║ ║ -║ 1. 버퍼 드워프 디버거 성기사 "CodeSlayer" ║ -║ Lv.100 | 12시간 34분 | 사망 3회 ║ -║ 2024.03.15 ║ -║ ║ -║ 2. 널 엘프 컴파일러 마법사 "NullMaster" ║ -║ Lv.100 | 15시간 22분 | 사망 7회 ║ -║ 2024.03.10 ║ -║ ║ -║ 3. 스택 고블린 포인터 암살자 "StackKiller" ║ -║ Lv.100 | 18시간 05분 | 사망 12회 ║ -║ 2024.03.08 ║ -║ ║ -╚═══════════════════════════════════════════════════╝ -``` - -### 12.5 클리어 후 처리 - -``` -1. 축하 시네마틱 표시 -2. 명예의 전당 등재 -3. 통계 표시 (플레이 시간, 사망 횟수, 처치 몬스터 등) -4. "새 게임 시작" 버튼 -5. 기존 캐릭터 데이터는 명예의 전당에만 보존 -``` - -### 12.6 수정 대상 파일 - -| 파일 | 변경 내용 | -|------|----------| -| `core/model/hall_of_fame.dart` | **신규** - 명예의 전당 모델 | -| `core/storage/hall_of_fame_storage.dart` | **신규** - 저장/로드 | -| `features/hall_of_fame/hall_of_fame_screen.dart` | **신규** - UI | -| `features/game/game_session_controller.dart` | 클리어 처리 | - -### 12.7 예상 작업량 -- 예상 파일 수: 4-5개 -- 신규 코드: ~400 LOC -- 수정 코드: ~100 LOC - ---- - -## 13. 추가 권장 사항 - -### 13.1 사운드/음악/진동 시스템 - -#### 13.1.1 사운드 효과 (SFX) - -| 상황 | 효과음 | 우선순위 | -|------|--------|----------| -| 일반 공격 | 타격음 | 상 | -| 크리티컬 히트 | 강한 타격음 + 효과음 | 상 | -| 스킬 사용 | 스킬별 고유 효과음 | 중 | -| 피격 | 피해 효과음 | 상 | -| 사망 | 쓰러지는 효과음 | 상 | -| 레벨업 | 팡파레 | 상 | -| 아이템 획득 | 획득 효과음 (희귀도별 차등) | 중 | -| 장비 장착 | 장착 효과음 | 하 | -| 퀘스트 완료 | 완료 효과음 | 중 | -| UI 조작 | 버튼 클릭음 | 하 | - -#### 13.1.2 배경 음악 (BGM) - -| 상황 | BGM 타입 | 우선순위 | -|------|----------|----------| -| 메인 화면 | 웅장한 타이틀 테마 | 중 | -| 일반 탐험 | 평화로운 필드 음악 | 중 | -| 전투 중 | 긴박한 전투 음악 | 상 | -| 보스전 | 강렬한 보스 테마 | 상 | -| 사망 화면 | 슬픈/긴장된 음악 | 중 | -| 시네마틱 | 스토리 테마 | 중 | -| 명예의 전당 | 영광스러운 엔딩 테마 | 중 | - -#### 13.1.3 진동 (모바일 전용) - -| 상황 | 진동 패턴 | 강도 | -|------|----------|------| -| 일반 공격 | 짧은 단일 진동 | 약 | -| 크리티컬 히트 | 강한 단일 진동 | 강 | -| 피격 | 짧은 이중 진동 | 중 | -| 사망 | 긴 진동 | 강 | -| 레벨업 | 리듬 있는 연속 진동 | 중 | -| 희귀 아이템 획득 | 짧은 삼중 진동 | 중 | -| 보스 등장 | 점점 강해지는 진동 | 강 | - -#### 13.1.4 구현 방안 - -```dart -// 사운드 서비스 -class AudioService { - void playSfx(SfxType type); - void playBgm(BgmType type); - void stopBgm(); - void setVolume(double sfx, double bgm); -} - -// 진동 서비스 (모바일) -class HapticService { - void vibrate(HapticPattern pattern); - bool get isSupported; -} -``` - ---- - -### 13.2 업적 시스템 - -#### 13.2.1 업적 카테고리 - -| 카테고리 | 예시 업적 | -|----------|----------| -| **전투** | 첫 번째 몬스터 처치, 100마리 처치, 1000마리 처치, 무피해 보스 처치 | -| **성장** | 레벨 10 달성, 레벨 50 달성, 레벨 100 달성 | -| **수집** | 첫 에픽 아이템, 전설 아이템 획득, 모든 슬롯 에픽 이상 장착 | -| **탐험** | 첫 퀘스트 완료, 100개 퀘스트 완료, 모든 Act 클리어 | -| **생존** | 10연전 생존, HP 1로 생존, 사망 없이 Act 1 클리어 | -| **스킬** | 첫 스킬 사용, 스킬로 100마리 처치, 모든 스킬 습득 | -| **도전** | 레벨 10 이하로 Act 1 보스 처치, 장비 없이 10마리 처치 | -| **히든** | 특정 조합 발견, 이스터에그 발견 | - -#### 13.2.2 업적 보상 - -| 등급 | 보상 | -|------|------| -| 브론즈 | 골드 100-500 | -| 실버 | 골드 500-2000, 아이템 박스 | -| 골드 | 골드 2000-10000, 희귀 아이템 박스 | -| 플래티넘 | 전설 아이템 박스, 특별 칭호 | - -#### 13.2.3 업적 UI - -``` -┌─ 업적 ──────────────────────────┐ -│ ★ 전투 [12/25] │ -│ ☑ 첫 번째 사냥꾼 - 몬스터 처치│ -│ ☑ 백전용사 - 100마리 처치 │ -│ ☐ 천인의 적 - 1000마리 처치 │ -│ │ -│ ★ 성장 [3/10] │ -│ ☑ 신입 개발자 - 레벨 10 │ -│ ☐ 시니어 개발자 - 레벨 50 │ -└─────────────────────────────────┘ -``` - ---- - -### 13.3 도감 시스템 - -#### 13.3.1 도감 종류 - -| 도감 | 기록 내용 | 수집 조건 | -|------|----------|----------| -| **몬스터 도감** | 이름, 레벨 범위, 드롭 아이템, 출현 지역 | 한번이라도 처치 | -| **아이템 도감** | 이름, 스탯, 희귀도, 획득 방법 | 한번이라도 획득 | -| **스킬 도감** | 이름, 효과, MP 소모, 쿨타임 | 한번이라도 습득 | -| **NPC 도감** | 이름, 역할, 등장 시네마틱 | 시네마틱에서 등장 | - -#### 13.3.2 몬스터 도감 상세 - -```dart -class MonsterEntry { - final String id; - final String name; - final int minLevel; - final int maxLevel; - final List dropItems; - final String description; - final int killCount; // 처치 횟수 - final DateTime firstMet; // 첫 조우 시간 - final bool isDefeated; // 처치 여부 -} -``` - -#### 13.3.3 도감 UI - -``` -┌─ 몬스터 도감 [127/200] ─────────┐ -│ │ -│ ┌──────┐ Syntax Error │ -│ │ ∧∧∧ │ Lv. 1-5 │ -│ │ \○/ │ 드롭: 오타, 구두점 │ -│ │ │ │ 처치: 47회 │ -│ └──────┘ │ -│ │ -│ ┌──────┐ Memory Leak │ -│ │ ~~~ │ Lv. 6-12 │ -│ │ ⊂⊃ │ 드롭: 누수 바이트 │ -│ │ ~~~ │ 처치: 23회 │ -│ └──────┘ │ -│ │ -│ ┌──────┐ ??? │ -│ │ ? │ 미발견 │ -│ └──────┘ │ -└─────────────────────────────────┘ -``` - -#### 13.3.4 수집률 보상 - -| 수집률 | 보상 | -|--------|------| -| 25% | 칭호 "수집가 견습생" | -| 50% | 드롭률 +5% | -| 75% | 칭호 "마스터 수집가" | -| 100% | 전설 아이템 + 칭호 "완벽주의자" | - ---- - -### 13.4 통계 화면 - -#### 13.4.1 통계 카테고리 - -| 카테고리 | 통계 항목 | -|----------|----------| -| **시간** | 총 플레이 시간, 현재 세션 시간, 평균 세션 시간 | -| **전투** | 총 전투 횟수, 처치 몬스터 수, 총 데미지, 최고 단일 데미지, 크리티컬 횟수 | -| **생존** | 총 사망 횟수, 사망 원인 Top 5, 최장 생존 시간, 연속 전투 생존 기록 | -| **획득** | 총 획득 골드, 총 획득 아이템, 희귀도별 아이템 수, 가장 비싼 아이템 | -| **스킬** | 총 스킬 사용 횟수, 스킬별 사용 횟수, 스킬 데미지 합계, 가장 많이 쓴 스킬 | -| **탐험** | 완료 퀘스트 수, 방문 지역 수, 현재 Act, 최고 도달 레벨 | -| **효율** | 시간당 경험치, 시간당 골드, 평균 전투 시간, 승률 | - -#### 13.4.2 통계 UI - -``` -┌─ 플레이 통계 ───────────────────┐ -│ │ -│ ⏱ 플레이 시간 │ -│ 총: 15시간 34분 │ -│ 현재 세션: 2시간 12분 │ -│ │ -│ ⚔ 전투 │ -│ 처치 몬스터: 1,247마리 │ -│ 총 데미지: 458,291 │ -│ 최고 데미지: 2,847 (크리티컬) │ -│ 크리티컬 횟수: 312회 │ -│ │ -│ 💀 사망 │ -│ 총 사망: 7회 │ -│ ┌ 사망 원인 Top 3 ┐ │ -│ │ 1. 커널 패닉 (3회)│ │ -│ │ 2. 메모리 누수 (2회)│ │ -│ │ 3. 스택 오버플로우 (2회)│ │ -│ └─────────────────┘ │ -│ │ -│ 💰 획득 │ -│ 총 골드: 124,560 │ -│ 아이템: 892개 │ -│ 전설: 3개 | 에픽: 12개 │ -└─────────────────────────────────┘ -``` - -#### 13.4.3 통계 데이터 구조 - -```dart -class GameStatistics { - // 시간 - final Duration totalPlayTime; - final Duration currentSessionTime; - - // 전투 - final int totalBattles; - final int monstersKilled; - final int totalDamageDealt; - final int highestDamage; - final int criticalHits; - - // 생존 - final int totalDeaths; - final Map deathCauses; - final Duration longestSurvival; - - // 획득 - final int totalGoldEarned; - final int totalItemsObtained; - final Map itemsByRarity; - - // 스킬 - final int totalSkillUses; - final Map skillUseCounts; - - // 탐험 - final int questsCompleted; - final int highestLevel; - final int currentAct; -} -``` - ---- - -### 13.5 설정 화면 - -| 설정 항목 | 옵션 | -|----------|------| -| 게임 속도 | 0.5x, 1x, 2x, 5x | -| 자동 저장 간격 | 1분, 5분, 10분 | -| SFX 볼륨 | 0-100% | -| BGM 볼륨 | 0-100% | -| 진동 | 켜기/끄기 (모바일) | -| 알림 표시 | 켜기/끄기 | -| 전투 로그 | 간략/상세/끄기 | -| 언어 | 한국어/English | - ---- - -### 13.6 성능 최적화 - -| 항목 | 현재 | 개선 방안 | -|------|------|----------| -| 상태 업데이트 | 매 틱마다 전체 rebuild | 변경된 부분만 업데이트 | -| 애니메이션 | Timer 기반 | AnimationController 사용 | -| 저장 | 자동 저장 빈번 | 변경 감지 후 디바운스 | - -### 13.7 테스트 전략 - -| 테스트 유형 | 대상 | 도구 | -|------------|------|------| -| 유닛 테스트 | 전투 계산, 스탯 계산 | flutter_test | -| 위젯 테스트 | UI 컴포넌트 | flutter_test | -| 통합 테스트 | 전체 게임 플로우 | integration_test | -| 밸런스 테스트 | 시뮬레이션 | 커스텀 도구 | - ---- - -## 14. 재미 요소 설계 (Fun Factor Design) - -### 14.1 즉각적인 보상감 (Dopamine Hits) - -| 요소 | 설명 | 우선순위 | -|------|------|----------| -| **데미지 숫자 팝업** | 공격 시 데미지가 화면에 튀어오름 (크리티컬은 크게, 빨간색) | 상 | -| **콤보 시스템** | 연속 처치 시 "x5 COMBO!" 표시 + 보너스 경험치 (10% per combo) | 상 | -| **희귀 드롭 연출** | 전설 아이템 획득 시 화면 번쩍 + 특별 효과음 + 진동 | 상 | -| **레벨업 축하** | 레벨업 시 3초간 화려한 ASCII 이펙트 | 중 | -| **크리티컬 이펙트** | 크리티컬 히트 시 화면 흔들림 + "CRITICAL!" 텍스트 | 상 | - -#### 14.1.1 데미지 팝업 구현 - -```dart -class DamagePopup { - final int damage; - final bool isCritical; - final Offset position; - final double opacity; // 1.0 → 0.0 fade out - final double offsetY; // 위로 떠오름 -} - -// 표시 예시 -// 일반: "45" (흰색, 작게) -// 크리티컬: "127!" (빨간색, 크게, 흔들림) -// 회복: "+30" (녹색) -// 스킬: "DEBUG STRIKE 250" (노란색) -``` - -#### 14.1.2 콤보 시스템 - -``` -콤보 조건: 5초 내 연속 처치 -콤보 보상: -- x2: 경험치 +10% -- x3: 경험치 +15% -- x5: 경험치 +25%, 골드 +10% -- x10: 경험치 +50%, 골드 +25%, 희귀 드롭률 +5% -- x20+: "UNSTOPPABLE!" 칭호 획득 조건 -``` - ---- - -### 14.2 "한 판 더" 유발 요소 - -#### 14.2.1 일일 도전 - -| 요소 | 설명 | -|------|------| -| **일일 미션** | 매일 3개의 미션 (예: "버그 30마리 처치", "크리티컬 10회") | -| **일일 보너스** | 첫 접속 시 골드/아이템 박스 | -| **연속 접속 보상** | 7일 연속 시 전설 아이템 박스 | - -``` -┌─ 일일 도전 ─────────────────────┐ -│ │ -│ ☑ 버그 30마리 처치 [30/30] │ -│ 보상: 골드 500 │ -│ │ -│ ☐ 크리티컬 10회 달성 [7/10] │ -│ 보상: 경험치 물약 │ -│ │ -│ ☐ 레벨업 1회 [0/1] │ -│ 보상: 랜덤 장비 박스 │ -│ │ -│ ───────────────────────────────│ -│ 연속 접속: 5일째 🔥 │ -│ 7일 보상까지: 2일 남음 │ -└─────────────────────────────────┘ -``` - -#### 14.2.2 주간/이벤트 보스 - -| 보스 타입 | 출현 조건 | 보상 | -|----------|----------|------| -| **주간 보스** | 매주 일요일 등장 | 한정 아이템, 대량 골드 | -| **시즌 보스** | 명절/기념일 | 시즌 한정 장비, 칭호 | -| **랜덤 레이드** | 랜덤 (1% 확률) | 희귀 아이템 + 업적 | - -#### 14.2.3 "거의 다 됐어" 심리 - -``` -레벨업까지 남은 경험치가 10% 이하일 때: -→ 경험치 바 색상 변경 (황금색) -→ "조금만 더!" 메시지 표시 -→ 다음 레벨 보상 미리보기 -``` - ---- - -### 14.3 플레이어 선택권 확대 - -#### 14.3.1 스킬 빌드 시스템 - -```dart -class SkillBuild { - final List activeSkills; // 3개 슬롯 - final List passiveSkills; // 2개 슬롯 - final String buildName; // "공격형", "탱커형" 등 -} -``` - -| 빌드 타입 | 특징 | -|----------|------| -| **공격형** | 데미지 스킬 위주, 높은 DPS | -| **방어형** | 회복/방어 스킬, 생존력 특화 | -| **균형형** | 공격 + 회복 혼합 | -| **스피드형** | 쿨타임 감소, 연속 공격 | - -#### 14.3.2 전투 스타일 전환 - -``` -[공격 모드] 🗡️ -- 공격력 +20% -- 방어력 -10% -- 크리티컬 +5% - -[방어 모드] 🛡️ -- 방어력 +30% -- 공격력 -10% -- 블록율 +10% - -[균형 모드] ⚖️ -- 기본 스탯 -- 회복량 +10% -``` - -#### 14.3.3 자동/반자동 전환 - -| 모드 | 설명 | -|------|------| -| **완전 자동** | 모든 것 자동 (기본) | -| **스킬 수동** | 스킬만 수동 선택 | -| **보스전 수동** | 보스전에서만 수동 전환 | - ---- - -### 14.4 감정적 연결 - -#### 14.4.1 캐릭터 성장 기록 - -``` -┌─ 나의 여정 ─────────────────────┐ -│ │ -│ 🎮 함께한 시간: 15시간 34분 │ -│ ⚔️ 처치한 버그: 1,247마리 │ -│ 💀 사망 횟수: 7회 │ -│ 🏆 획득 업적: 23개 │ -│ │ -│ 📝 기억에 남는 순간: │ -│ • 첫 레벨업 (0시간 2분) │ -│ • 첫 사망 (1시간 15분) │ -│ • 첫 전설 아이템 (8시간 22분) │ -│ • 첫 보스 처치 (5시간 47분) │ -└─────────────────────────────────┘ -``` - -#### 14.4.2 상황별 메시지 (유머/위로) - -| 상황 | 메시지 예시 | -|------|------------| -| **첫 사망** | "축하합니다! 첫 번째 교훈을 얻었습니다. 버그는 누구나 만납니다." | -| **연속 사망** | "잠시 쉬어가는 건 어떨까요? 커피 한 잔의 여유..." | -| **레벨업** | "레벨 {n} 달성! 당신의 코드가 더 강해졌습니다." | -| **희귀 아이템** | "운이 좋으시네요! 이건 정말 드문 거에요!" | -| **100 연속 처치** | "무자비한 디버거! 버그들이 당신을 두려워합니다." | -| **장시간 플레이** | "3시간째 플레이 중... 물 한 잔 드세요! 💧" | - -#### 14.4.3 마일스톤 축하 - -| 마일스톤 | 축하 연출 | -|----------|----------| -| 100마리 처치 | "백전용사" 칭호 + 특별 이펙트 | -| 1000마리 처치 | "천인의 적" 칭호 + 업적 팝업 | -| 10시간 플레이 | "헌신적인 개발자" 칭호 | -| 무사망 Act 클리어 | "완벽주의자" 칭호 + 보너스 골드 | - ---- - -### 14.5 예측 불가능한 재미 - -#### 14.5.1 랜덤 이벤트 - -| 이벤트 | 확률 | 효과 | -|--------|------|------| -| **전설 몬스터 출현** | 5% | "갑자기 전설 몬스터가 나타났다!" - 처치 시 대량 보상 | -| **황금 몬스터** | 3% | 골드 10배 드롭 | -| **보물 상자** | 2% | 랜덤 아이템 발견 | -| **도움의 NPC** | 5% | 버프 or 회복 제공 | -| **함정** | 3% | 데미지 or 디버프 (긴장감) | -| **경험치 폭풍** | 1% | 다음 5분간 경험치 2배 | - -#### 14.5.2 행운 시스템 - -```dart -class LuckEvent { - // 연속 불운 시 행운 상승 - int unluckyStreak = 0; - - double getLuckBonus() { - // 10회 연속 일반 드롭 시 희귀 드롭 확률 +50% - return unluckyStreak >= 10 ? 0.5 : 0.0; - } -} -``` - ---- - -### 14.6 사회적 요소 (향후 확장) - -#### 14.6.1 현재 버전 (오프라인) - -| 기능 | 설명 | -|------|------| -| **스크린샷 공유** | 명예의 전당 달성 시 공유 버튼 | -| **기록 내보내기** | 통계를 이미지로 저장 | - -#### 14.6.2 향후 버전 (아스키 아레나) - -| 기능 | 설명 | -|------|------| -| **글로벌 랭킹** | 레벨, 사망 횟수, 클리어 시간 순위 | -| **친구 비교** | 친구의 기록과 비교 | -| **PvP 아레나** | 명예의 전당 캐릭터로 대전 | -| **길드 시스템** | 협력 레이드 보스 | - ---- - -## 15. 피해야 할 요소 - -### 15.1 지루함 유발 요소 - -| 피해야 할 것 | 이유 | 대안 | -|-------------|------|------| -| **긴 대기 시간** | 아무 일도 안 일어나면 지루함 | 항상 뭔가 진행 중 표시 | -| **반복 메시지** | 같은 문구 반복은 지루함 | 30+ 가지 변형 메시지 | -| **단조로운 전투** | 항상 같은 패턴 | 랜덤 이벤트, 크리티컬, 콤보 | -| **느린 초반** | 첫 30분이 지루하면 이탈 | 초반 빠른 레벨업 + 튜토리얼 보상 | - -### 15.2 불쾌감 유발 요소 - -| 피해야 할 것 | 이유 | 대안 | -|-------------|------|------| -| **불공정한 즉사** | 예측 불가능한 사망은 스트레스 | HP 보고 대응 가능하도록 | -| **과도한 페널티** | 레벨 다운은 너무 가혹 | 장비 상실만 (레벨/인벤 유지) | -| **강제 광고** | 게임 흐름 방해 | 광고 없음 | -| **과금 유도** | 필수 과금은 불쾌 | 무과금 완전 클리어 가능 | -| **복잡한 UI** | 정보 과다는 혼란 | 핵심 정보만, 상세는 별도 탭 | - -### 15.3 혼란 유발 요소 - -| 피해야 할 것 | 이유 | 대안 | -|-------------|------|------| -| **설명 없는 시스템** | 무엇인지 모르면 답답 | 첫 등장 시 툴팁/튜토리얼 | -| **너무 많은 스탯** | 이해하기 어려움 | 핵심 6개만 강조 | -| **숨겨진 메커니즘** | 어떻게 작동하는지 모름 | 공식 공개 (도움말) | - ---- - -## 16. 핵심 재미 요약 - -``` -┌─────────────────────────────────────────────────────┐ -│ │ -│ 🎮 ASCII Never Die의 5가지 재미 │ -│ │ -│ 1. "조금만 더" - 다음 레벨업이 가까워! │ -│ → 경험치 바, 레벨업 보상 미리보기 │ -│ │ -│ 2. "오 뭐지?" - 예상 못한 전설 아이템! │ -│ → 랜덤 이벤트, 희귀 드롭 연출 │ -│ │ -│ 3. "다시 해보자" - 사망해도 다시 도전! │ -│ → 적절한 페널티, 빠른 복귀 │ -│ │ -│ 4. "나 잘하네" - 통계로 보는 내 성장! │ -│ → 상세 통계, 업적, 마일스톤 │ -│ │ -│ 5. "수집 완료!" - 도감 100% 달성! │ -│ → 몬스터/아이템 도감, 수집 보상 │ -│ │ -└─────────────────────────────────────────────────────┘ -``` - ---- - -## 17. 작업 우선순위 및 의존성 - -```mermaid -graph TD - P1[Phase 1: 전투 시스템] --> P2[Phase 2: 아이템] - P1 --> P5[Phase 5: 종족/클래스] - P2 --> P3[Phase 3: 스킬] - P1 --> P4[Phase 4: 사망/부활] - P2 --> P4 - P3 --> P4 - P5 --> P6[Phase 6: 밸런싱] - P4 --> P6 - P6 --> P7[Phase 7: 콘텐츠] - P7 --> P9[Phase 9: 스토리] - P9 --> P10[Phase 10: 명예의 전당] - - P8[Phase 8: UI/UX] -.-> P1 - P8 -.-> P4 -``` - -### 권장 작업 순서 - -1. **Phase 1: 핵심 전투 시스템** (필수, 모든 것의 기반) -2. **Phase 2: 아이템 시스템** (전투 시스템 활용) -3. **Phase 5: 종족/클래스 특화** (전투 시스템과 병렬 가능) -4. **Phase 3: 스킬 시스템** (전투 + 아이템 필요) -5. **Phase 4: 사망/부활 시스템** (전투 + 아이템 + 스킬 필요) -6. **Phase 8: UI/UX 개선** (다른 Phase와 병렬 진행 가능) -7. **Phase 6: 밸런싱** (모든 시스템 완료 후) -8. **Phase 7: 콘텐츠 확장** (밸런싱 후) -9. **Phase 9: 스토리/엔딩** (콘텐츠 확장 후) -10. **Phase 10: 명예의 전당** (최종) - ---- - -## 18. 총 예상 작업량 - -| Phase | 신규 코드 | 수정 코드 | 파일 수 | -|-------|----------|----------|---------| -| 1. 전투 시스템 | 400 | 200 | 5 | -| 2. 아이템 | 500 | 300 | 6 | -| 3. 스킬 | 600 | 200 | 6 | -| 4. 사망/부활 | 500 | 200 | 7 | -| 5. 종족/클래스 | 400 | 150 | 7 | -| 6. 밸런싱 | 300 | 400 | 5 | -| 7. 콘텐츠 | 1000 | 200 | 5 | -| 8. UI/UX | 400 | 200 | 6 | -| 9. 스토리 | 600 | 100 | 5 | -| 10. 명예의 전당 | 400 | 100 | 5 | -| **합계** | **5,100** | **2,050** | **57** | - -총 예상 코드량: ~7,150 LOC - ---- - -## 19. 위험 요소 및 대응 - -| 위험 | 영향 | 대응 방안 | -|------|------|----------| -| 밸런스 붕괴 | 게임성 저하 | 시뮬레이션 테스트, 점진적 조정 | -| 복잡도 증가 | 유지보수 어려움 | 모듈화, 문서화 철저 | -| 기존 세이브 호환성 | 사용자 데이터 손실 | 마이그레이션 로직 필수 | -| 성능 저하 | UX 저하 | 프로파일링, 최적화 | -| 원본과의 괴리 | 정체성 혼란 | 명확한 차별화 선언 | - ---- - -## 20. 버전 계획 - -| 버전 | 포함 Phase | 목표 | -|------|-----------|------| -| v0.5.0 | 1, 2 | 기본 전투 + 아이템 | -| v0.6.0 | 3, 5 | 스킬 + 종족/클래스 | -| v0.7.0 | 4, 8 | 사망/부활 + UI | -| v0.8.0 | 6 | 밸런싱 완료 | -| v0.9.0 | 7, 9 | 콘텐츠 + 스토리 | -| v1.0.0 | 10 | 명예의 전당, 정식 출시 | - ---- - -*문서 작성일: 2024년* -*ASCII Never Die - 게임 시스템 개편 계획 v1.0* diff --git a/doc/task-ext-audio-access.md b/doc/task-ext-audio-access.md new file mode 100644 index 0000000..23026a8 --- /dev/null +++ b/doc/task-ext-audio-access.md @@ -0,0 +1,130 @@ +# 사운드/진동/접근성 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 사운드/음악/진동 시스템 + +### 1.1 사운드 효과 (SFX) + +| 상황 | 효과음 | 우선순위 | +|------|--------|----------| +| 일반 공격 | 타격음 | 상 | +| 크리티컬 히트 | 강한 타격음 + 효과음 | 상 | +| 스킬 사용 | 스킬별 고유 효과음 | 중 | +| 피격 | 피해 효과음 | 상 | +| 사망 | 쓰러지는 효과음 | 상 | +| 레벨업 | 팡파레 | 상 | +| 아이템 획득 | 획득 효과음 (희귀도별 차등) | 중 | +| 장비 장착 | 장착 효과음 | 하 | +| 퀘스트 완료 | 완료 효과음 | 중 | +| UI 조작 | 버튼 클릭음 | 하 | + +### 1.2 배경 음악 (BGM) + +| 상황 | BGM 타입 | 우선순위 | +|------|----------|----------| +| 메인 화면 | 웅장한 타이틀 테마 | 중 | +| 일반 탐험 | 평화로운 필드 음악 | 중 | +| 전투 중 | 긴박한 전투 음악 | 상 | +| 보스전 | 강렬한 보스 테마 | 상 | +| 사망 화면 | 슬픈/긴장된 음악 | 중 | +| 시네마틱 | 스토리 테마 | 중 | +| 명예의 전당 | 영광스러운 엔딩 테마 | 중 | + +### 1.3 진동 (모바일 전용) + +| 상황 | 진동 패턴 | 강도 | +|------|----------|------| +| 일반 공격 | 짧은 단일 진동 | 약 | +| 크리티컬 히트 | 강한 단일 진동 | 강 | +| 피격 | 짧은 이중 진동 | 중 | +| 사망 | 긴 진동 | 강 | +| 레벨업 | 리듬 있는 연속 진동 | 중 | +| 희귀 아이템 획득 | 짧은 삼중 진동 | 중 | +| 보스 등장 | 점점 강해지는 진동 | 강 | + +### 1.4 구현 방안 + +```dart +// 사운드 서비스 +class AudioService { + void playSfx(SfxType type); + void playBgm(BgmType type); + void stopBgm(); + void setVolume(double sfx, double bgm); +} + +// 진동 서비스 (모바일) +class HapticService { + void vibrate(HapticPattern pattern); + bool get isSupported; +} +``` + +--- + +## 2. 접근성 (Accessibility) + +### 2.1 시각 접근성 + +| 기능 | 설명 | 기본값 | +|------|------|--------| +| **색맹 모드** | 색상 팔레트 변경 | 끄기 | +| - 적록 색맹 | 빨강/초록 → 파랑/노랑 | - | +| - 청황 색맹 | 파랑/노랑 → 빨강/초록 | - | +| - 완전 색맹 | 명도/채도 기반 | - | +| **고대비 모드** | 배경/전경 대비 증가 | 끄기 | +| **폰트 크기** | 0.8x ~ 1.5x | 1.0x | +| **애니메이션 감소** | 움직임 최소화 | 끄기 | + +### 2.2 청각 접근성 + +| 기능 | 설명 | 기본값 | +|------|------|--------| +| **자막** | 효과음을 텍스트로 표시 | 끄기 | +| **시각 알림** | 소리 대신 화면 깜빡임 | 끄기 | +| **진동 알림** | 소리 대신 진동 | 끄기 | + +### 2.3 운동 접근성 + +| 기능 | 설명 | 기본값 | +|------|------|--------| +| **터치 영역 확대** | 버튼 크기 증가 | 끄기 | +| **길게 누르기 비활성화** | 탭으로 대체 | 끄기 | +| **자동 진행** | 수동 입력 최소화 | 켜기 | + +### 2.4 게임 난이도 조절 + +| 난이도 | 설명 | +|--------|------| +| **이야기 모드** | 사망 없음, 경험치 2배 | +| **쉬움** | 데미지 50%, 회복 2배 | +| **보통** | 기본 설정 | +| **어려움** | 데미지 150%, 드롭률 증가 | +| **극한** | 데미지 200%, 사망 시 영구 삭제 | + +### 2.5 접근성 UI + +``` +┌─ 접근성 설정 ───────────────────────┐ +│ │ +│ 👁 시각 │ +│ 색맹 모드 [없음 ▼] │ +│ 고대비 모드 [○ 끄기] │ +│ 폰트 크기 [━━●━━] 1.0x │ +│ 애니메이션 [● 켜기] │ +│ │ +│ 👂 청각 │ +│ 자막 표시 [○ 끄기] │ +│ 시각 알림 [○ 끄기] │ +│ │ +│ 🎮 게임플레이 │ +│ 난이도 [보통 ▼] │ +│ 터치 영역 확대 [○ 끄기] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- diff --git a/doc/task-ext-combat.md b/doc/task-ext-combat.md new file mode 100644 index 0000000..2a6cdf3 --- /dev/null +++ b/doc/task-ext-combat.md @@ -0,0 +1,238 @@ +# 전투 확장: 몬스터 AI/퀘스트/버프 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 몬스터 AI/보스 패턴 + +### 1.1 일반 몬스터 AI + +```dart +enum MonsterBehavior { + aggressive, // 공격 우선 + defensive, // 방어 우선 + balanced, // 균형 + berserker, // HP 낮을수록 공격력 증가 + healer, // 자가 회복 +} + +class MonsterAI { + final MonsterBehavior behavior; + final double skillUseChance; // 스킬 사용 확률 + final List skills; + + MonsterAction decideAction(BattleState state) { + // AI 로직 + } +} +``` + +### 1.2 보스 몬스터 페이즈 + +```dart +class BossMonster { + final String id; + final String name; + final List phases; + final int currentPhaseIndex; + + BossPhase get currentPhase => phases[currentPhaseIndex]; +} + +class BossPhase { + final double hpThreshold; // 이 HP% 이하일 때 다음 페이즈 + final String phaseName; // "분노", "최후의 발악" 등 + final Map statModifiers; // 스탯 변화 + final List availableSkills; + final String? phaseStartMessage; // "커널 패닉이 분노합니다!" +} +``` + +### 1.3 보스 패턴 예시 + +| 보스 | 페이즈 1 (100-70%) | 페이즈 2 (70-30%) | 페이즈 3 (30-0%) | +|------|-------------------|-------------------|------------------| +| **Syntax Error Dragon** | 일반 공격 | 문법 오류 브레스 (범위) | 무한 루프 (연속 공격) | +| **Memory Leak Hydra** | 단일 공격 | 메모리 침식 (DOT) | 머리 재생 (회복 + 분열) | +| **Buffer Overflow Titan** | 강타 | 오버플로우 (즉사 위험) | 시스템 붕괴 (전체 공격) | +| **Kernel Panic Archon** | 패닉 공격 | 블루스크린 (스턴) | 시스템 재부팅 (HP 회복) | +| **Glitch God** | 글리치 (랜덤 효과) | 차원 왜곡 (회피 불가) | 존재 삭제 (다중 페이즈) | + +### 1.4 보스 스킬 + +```dart +class BossSkill { + final String id; + final String name; + final SkillType type; + final int cooldownTurns; // 턴 기반 쿨타임 + final double damageMultiplier; + final List? effects; + final String? castMessage; // "커널 패닉이 블루스크린을 시전합니다!" + final int castTime; // 시전 시간 (경고 표시용) +} +``` + +### 1.5 보스전 특수 메커니즘 + +| 메커니즘 | 설명 | +|----------|------| +| **시전 경고** | 강력한 스킬 사용 전 1-2턴 경고 표시 | +| **페이즈 전환 연출** | HP 임계점 도달 시 특별 애니메이션 | +| **분노 게이지** | 특정 보스는 분노 시 패턴 변화 | +| **약점 노출** | 특정 행동 후 약점 노출 (추가 데미지) | +| **환경 효과** | 보스에 따라 필드 효과 (독, 화염 등) | + +--- + +## 2. 퀘스트 시스템 상세 + +### 2.1 퀘스트 구조 + +```dart +class Quest { + final String id; + final String name; + final QuestType type; // main, side, daily, event + final String description; + final List objectives; + final QuestReward reward; + final int requiredLevel; + final String? prerequisiteQuestId; +} + +class QuestObjective { + final ObjectiveType type; // kill, collect, reach, survive + final String targetId; // 대상 몬스터/아이템/지역 + final int targetCount; + final int currentCount; + final bool isCompleted; +} +``` + +### 2.2 퀘스트 타입 + +| 타입 | 설명 | 갱신 | +|------|------|------| +| **메인 퀘스트** | 스토리 진행 필수 | 일회성 | +| **서브 퀘스트** | 추가 보상 | 일회성 | +| **일일 퀘스트** | 매일 갱신 | 매일 자정 | +| **주간 퀘스트** | 매주 갱신 | 매주 월요일 | +| **이벤트 퀘스트** | 기간 한정 | 이벤트 기간 | +| **업적 퀘스트** | 장기 목표 | 영구 | + +### 2.3 메인 퀘스트 흐름 + +``` +Act I: 각성 +├── [메인] 첫 번째 버그 처치 +├── [메인] 버그 둥지 탐험 +├── [메인] Syntax Error Dragon 처치 +└── [보상] Act II 해금 + +Act II: 성장 +├── [메인] 디버거 기사단 가입 +├── [메인] 손상된 네트워크 조사 +├── [메인] 배신자 추적 +├── [메인] Memory Leak Hydra 처치 +└── [보상] Act III 해금 + +... (Act III ~ V) +``` + +### 2.4 서브 퀘스트 예시 + +| 퀘스트명 | 목표 | 보상 | +|----------|------|------| +| 백전용사 | 몬스터 100마리 처치 | 골드 1000, 칭호 | +| 수집가 | 무기 10종 획득 | 희귀 무기 박스 | +| 생존자 | 사망 없이 Act I 클리어 | 칭호 "완벽주의자" | +| 속도전 | 30분 내 레벨 10 달성 | 경험치 물약 x3 | + +### 2.5 퀘스트 UI + +``` +┌─ 퀘스트 ────────────────────────────┐ +│ │ +│ ★ 메인 퀘스트 │ +│ ▶ 버그 둥지 탐험 │ +│ 목표: 버그 둥지 도달 [진행 중] │ +│ 보상: 골드 500, 경험치 1000 │ +│ │ +│ ☆ 서브 퀘스트 │ +│ ○ 백전용사 [45/100] │ +│ ○ 수집가 [3/10] │ +│ │ +│ 📅 일일 퀘스트 (남은 시간: 4시간) │ +│ ☑ 몬스터 30마리 처치 [완료] │ +│ ☐ 크리티컬 10회 [7/10] │ +│ ☐ 레벨업 1회 [0/1] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## 3. 버프/디버프 시스템 + +### 3.1 버프/디버프 구조 + +```dart +class StatusEffect { + final String id; + final String name; + final EffectType type; // buff, debuff + final EffectTarget target; // self, enemy + final Duration duration; // 지속 시간 + final int stacks; // 중첩 횟수 + final int maxStacks; // 최대 중첩 + final Map modifiers; +} +``` + +### 3.2 버프 목록 + +| 버프명 | 효과 | 지속 시간 | 획득 방법 | +|--------|------|----------|----------| +| **공격력 증가** | ATK +20% | 30초 | 스킬, 물약 | +| **방어력 증가** | DEF +20% | 30초 | 스킬, 물약 | +| **크리티컬 증가** | CRI +10% | 30초 | 스킬, 물약 | +| **회피 증가** | EVA +10% | 30초 | 스킬 | +| **재생** | 초당 HP 1% 회복 | 10초 | 스킬 | +| **경험치 부스트** | EXP +50% | 5분 | 물약, 이벤트 | +| **골드 부스트** | GOLD +50% | 5분 | 물약, 이벤트 | +| **무적** | 피해 면역 | 3초 | 스킬 | +| **분노** | ATK +50%, DEF -20% | 10초 | 스킬, 종족 특성 | + +### 3.3 디버프 목록 + +| 디버프명 | 효과 | 지속 시간 | 발생 원인 | +|----------|------|----------|----------| +| **독** | 초당 HP 2% 손실 | 5초 | 몬스터 공격 | +| **출혈** | 초당 HP 1% 손실 | 10초 | 크리티컬 피격 | +| **화상** | 초당 HP 3% 손실 | 3초 | 화염 공격 | +| **둔화** | 공격 속도 -30% | 5초 | 몬스터 스킬 | +| **약화** | ATK -20% | 10초 | 보스 스킬 | +| **취약** | DEF -30% | 10초 | 보스 스킬 | +| **스턴** | 행동 불가 | 2초 | 보스 스킬 | +| **침묵** | 스킬 사용 불가 | 5초 | 보스 스킬 | +| **저주** | 회복량 -50% | 15초 | 언데드 공격 | + +### 3.4 버프/디버프 UI + +``` +┌─ 상태 효과 ─────────────────────────┐ +│ │ +│ 버프: │ +│ [⚔️+20%] [🛡️+15%] [💨재생] │ +│ 25초 18초 5초 │ +│ │ +│ 디버프: │ +│ [🩸출혈] [⚡스턴] │ +│ 3초 1초 │ +│ │ +└─────────────────────────────────────┘ +``` + +--- diff --git a/doc/task-ext-events.md b/doc/task-ext-events.md new file mode 100644 index 0000000..fbf8803 --- /dev/null +++ b/doc/task-ext-events.md @@ -0,0 +1,198 @@ +# 이벤트/알림 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 이벤트 시스템 + +### 1.1 이벤트 종류 + +| 이벤트 타입 | 주기 | 지속 시간 | +|------------|------|----------| +| **일일 보너스** | 매일 | 접속 시 | +| **주간 보스** | 매주 일요일 | 24시간 | +| **시즌 이벤트** | 시즌별 | 2-4주 | +| **기념일 이벤트** | 특정 날짜 | 1-7일 | +| **돌발 이벤트** | 랜덤 | 1-2시간 | + +### 1.2 이벤트 구조 + +```dart +class GameEvent { + final String id; + final String name; + final EventType type; + final DateTime startTime; + final DateTime endTime; + final List rewards; + final List quests; + final EventBonuses? bonuses; +} + +class EventBonuses { + final double expMultiplier; // 경험치 배율 + final double goldMultiplier; // 골드 배율 + final double dropRateBonus; // 드롭률 보너스 +} +``` + +### 1.3 시즌 이벤트 예시 + +| 시즌 | 테마 | 특별 콘텐츠 | +|------|------|------------| +| **봄** | 버그 헌팅 시즌 | 특별 몬스터, 봄 한정 장비 | +| **여름** | 핫픽스 페스티벌 | 경험치 2배, 여름 코스튬 | +| **가을** | 수확의 코드 | 골드 2배, 가을 한정 펫 | +| **겨울** | 시스템 동면 | 특별 던전, 겨울 한정 세트 | + +### 1.4 이벤트 보상 구조 + +``` +┌─ 신년 이벤트 ───────────────────────┐ +│ │ +│ 🎉 2025 신년 맞이 특별 이벤트 │ +│ 기간: 1/1 ~ 1/7 │ +│ │ +│ ─────────────────────────────────── │ +│ 📋 이벤트 미션 │ +│ │ +│ ☑ 몬스터 100마리 처치 [100/100] │ +│ 보상: 신년 무기 상자 │ +│ │ +│ ☐ 던전 5회 클리어 [3/5] │ +│ 보상: 전설 물약 세트 │ +│ │ +│ ☐ 보스 처치 [0/1] │ +│ 보상: 신년 한정 칭호 │ +│ │ +│ ─────────────────────────────────── │ +│ 🎁 출석 보상 (7일) │ +│ [✓][✓][✓][✓][ ][ ][ ] │ +│ 1 2 3 4 5 6 7 │ +│ │ +│ 7일 완료 보상: 신년 한정 세트 │ +│ │ +└─────────────────────────────────────┘ +``` + +### 1.5 돌발 이벤트 + +| 이벤트 | 발생 확률 | 효과 | +|--------|----------|------| +| **골드 러시** | 5% | 1시간 골드 3배 | +| **경험치 폭풍** | 5% | 1시간 경험치 2배 | +| **보물 사냥** | 3% | 희귀 아이템 드롭률 +100% | +| **엘리트 침공** | 3% | 정예 몬스터 대량 등장 | +| **행운의 시간** | 2% | 모든 보너스 적용 | + +--- + +## 2. 알림/푸시 시스템 + +### 2.1 알림 종류 + +| 카테고리 | 알림 | 기본 설정 | +|----------|------|----------| +| **게임 진행** | 레벨업 | 켜기 | +| | 퀘스트 완료 | 켜기 | +| | 보스 해금 | 켜기 | +| | 업적 달성 | 켜기 | +| **전투** | 사망 | 켜기 | +| | 희귀 아이템 획득 | 켜기 | +| | HP 위험 (20% 이하) | 끄기 | +| **시스템** | 오프라인 보상 준비 | 켜기 | +| | 일일 미션 갱신 | 켜기 | +| | 이벤트 시작/종료 | 켜기 | +| | 상점 갱신 | 끄기 | +| **소셜 (향후)** | 친구 요청 | 켜기 | +| | 길드 알림 | 켜기 | + +### 2.2 푸시 알림 (모바일) + +```dart +class PushNotificationService { + /// 로컬 푸시 알림 예약 + Future scheduleNotification({ + required String title, + required String body, + required DateTime scheduledTime, + String? payload, + }); + + /// 반복 알림 설정 + Future scheduleRepeating({ + required String title, + required String body, + required RepeatInterval interval, + }); +} + +enum RepeatInterval { + hourly, + daily, + weekly, +} +``` + +### 2.3 푸시 알림 시나리오 + +| 시나리오 | 트리거 | 메시지 예시 | +|----------|--------|------------| +| **복귀 유도** | 24시간 미접속 | "⚔️ 버그들이 기다리고 있어요!" | +| **오프라인 보상** | 8시간 경과 | "🎁 오프라인 보상이 가득 찼어요!" | +| **일일 미션** | 매일 오전 9시 | "📋 새로운 일일 미션이 도착했어요!" | +| **이벤트** | 이벤트 시작 | "🎉 신년 이벤트가 시작되었어요!" | +| **이벤트 종료** | 이벤트 종료 1시간 전 | "⏰ 이벤트가 1시간 후 종료됩니다!" | + +### 2.4 인앱 알림 + +``` +┌─ 알림 센터 ─────────────────────────┐ +│ │ +│ 오늘 │ +│ ─────────────────────────────────── │ +│ 🎮 레벨 26 달성! 14:32 │ +│ │ +│ ⚔️ 디버거의 검 획득 (Epic) 14:15 │ +│ │ +│ 📋 일일 미션 완료 13:45 │ +│ 보상: 골드 500, 경험치 물약 │ +│ │ +│ 어제 │ +│ ─────────────────────────────────── │ +│ 🏆 업적 달성: 백전용사 23:12 │ +│ │ +│ 💀 사망: 메모리 누수에 의해 21:30 │ +│ │ +│ [ 모두 읽음 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +### 2.5 알림 설정 UI + +``` +┌─ 알림 설정 ─────────────────────────┐ +│ │ +│ 🔔 푸시 알림 │ +│ 마스터 스위치 [● 켜기] │ +│ │ +│ ─────────────────────────────────── │ +│ 게임 진행 │ +│ 레벨업 [● 켜기] │ +│ 퀘스트 완료 [● 켜기] │ +│ 업적 달성 [● 켜기] │ +│ │ +│ 시스템 │ +│ 오프라인 보상 [● 켜기] │ +│ 일일 미션 갱신 [● 켜기] │ +│ 이벤트 [● 켜기] │ +│ │ +│ 방해 금지 시간 │ +│ [22:00] ~ [08:00] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- diff --git a/doc/task-ext-items.md b/doc/task-ext-items.md new file mode 100644 index 0000000..6d656c5 --- /dev/null +++ b/doc/task-ext-items.md @@ -0,0 +1,316 @@ +# 아이템 확장: 세트/강화/인벤토리/물약 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 세트 아이템 + +### 1.1 세트 아이템 구조 + +```dart +class ItemSet { + final String id; + final String name; + final List itemIds; // 세트 구성 아이템 + final Map bonuses; // 착용 개수별 보너스 +} + +class SetBonus { + final int requiredCount; // 필요 착용 개수 + final String description; // "2세트: 공격력 +10%" + final Map statBonuses; + final PassiveEffect? passiveEffect; +} +``` + +### 1.2 세트 목록 예시 + +| 세트명 | 부위 | 2세트 | 4세트 | 6세트 | +|--------|------|-------|-------|-------| +| **디버거의 유산** | 무기, 방어구, 투구, 장갑, 부츠, 반지 | 공격력 +10% | 크리티컬 +15% | 스킬 데미지 +25% | +| **널 가드** | 방패, 방어구, 투구, 장갑, 부츠, 목걸이 | 방어력 +15% | 블록률 +10% | 피해 반사 10% | +| **컴파일러의 지혜** | 지팡이, 로브, 모자, 장갑, 부츠, 반지 | MP +20% | 마법 데미지 +15% | 스킬 쿨타임 -20% | +| **가비지 컬렉터** | 무기, 중갑, 투구, 장갑, 부츠, 벨트 | HP +20% | 전투 후 HP 5% 회복 | 사망 시 50% 확률로 생존 | + +### 1.3 세트 UI + +``` +┌─ 장착 장비 ─────────────────────────┐ +│ │ +│ 디버거의 유산 [4/6] ✨ │ +│ ├─ 디버거의 검 ☑ │ +│ ├─ 디버거의 갑옷 ☑ │ +│ ├─ 디버거의 투구 ☑ │ +│ ├─ 디버거의 장갑 ☑ │ +│ ├─ 디버거의 부츠 ☐ │ +│ └─ 디버거의 반지 ☐ │ +│ │ +│ 세트 효과: │ +│ ✓ 2세트: 공격력 +10% │ +│ ✓ 4세트: 크리티컬 +15% │ +│ ○ 6세트: 스킬 데미지 +25% │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## 2. 강화/합성 시스템 + +### 2.1 아이템 강화 + +```dart +class EnhancementSystem { + /// 강화 시도 + EnhanceResult enhance(Equipment item, int gold) { + final successRate = getSuccessRate(item.enhanceLevel); + final success = random() < successRate; + + if (success) { + return EnhanceResult.success( + item.copyWith(enhanceLevel: item.enhanceLevel + 1), + ); + } else { + // 실패 시 강화 레벨 유지 (파괴 없음) + return EnhanceResult.failure(); + } + } +} +``` + +### 2.2 강화 단계 + +| 강화 레벨 | 성공률 | 비용 배율 | 스탯 증가 | +|----------|--------|----------|----------| +| +1 | 90% | 1x | +5% | +| +2 | 80% | 2x | +10% | +| +3 | 70% | 3x | +15% | +| +4 | 60% | 4x | +20% | +| +5 | 50% | 5x | +30% | +| +6 | 40% | 7x | +40% | +| +7 | 30% | 10x | +50% | +| +8 | 20% | 15x | +65% | +| +9 | 10% | 20x | +80% | +| +10 | 5% | 30x | +100% | + +### 2.3 아이템 합성 + +```dart +class SynthesisSystem { + /// 동일 아이템 3개 → 상위 희귀도 1개 + Equipment? synthesize(List items) { + if (items.length != 3) return null; + if (!_isSameItem(items)) return null; + + final baseItem = items.first; + final nextRarity = _getNextRarity(baseItem.rarity); + + if (nextRarity == null) return null; // 이미 최고 희귀도 + + return baseItem.copyWith(rarity: nextRarity); + } +} +``` + +### 2.4 합성 규칙 + +``` +Common x3 → Uncommon x1 +Uncommon x3 → Rare x1 +Rare x3 → Epic x1 +Epic x3 → Legendary x1 +Legendary → 합성 불가 +``` + +### 2.5 강화/합성 UI + +``` +┌─ 대장간 ────────────────────────────┐ +│ │ +│ [강화] [합성] │ +│ │ +│ ┌───────────────────────────────┐ │ +│ │ 디버거의 검 +3 │ │ +│ │ 공격력: 45 (+15%) │ │ +│ │ 희귀도: Rare │ │ +│ └───────────────────────────────┘ │ +│ │ +│ 강화 정보: │ +│ 현재: +3 → +4 │ +│ 성공률: 60% │ +│ 비용: 2,000 골드 │ +│ 스탯 증가: +15% → +20% │ +│ │ +│ [ 강화하기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## 3. 인벤토리 관리 + +### 3.1 인벤토리 구조 + +```dart +class Inventory { + final int maxSlots; // 최대 슬롯 수 + final List items; + + int get usedSlots => items.length; + int get freeSlots => maxSlots - usedSlots; + bool get isFull => freeSlots <= 0; +} +``` + +### 3.2 인벤토리 크기 + +| 레벨 | 기본 슬롯 | 확장 가능 | +|------|----------|----------| +| 1-20 | 30 | +10 (골드) | +| 21-50 | 40 | +15 (골드) | +| 51-80 | 55 | +20 (골드) | +| 81-100 | 75 | +25 (골드) | +| 최대 | 100 | - | + +### 3.3 정렬 옵션 + +| 정렬 기준 | 설명 | +|----------|------| +| 최근 획득 | 획득 시간 내림차순 | +| 희귀도 | 전설 > 에픽 > 레어 > ... | +| 레벨 | 아이템 레벨 내림차순 | +| 이름 | 가나다/ABC 순 | +| 슬롯 | 무기 → 방어구 → 악세서리 | +| 가중치 | 높은 가중치 우선 | + +### 3.4 필터 옵션 + +| 필터 | 옵션 | +|------|------| +| 슬롯 | 전체, 무기, 방어구, 악세서리 등 | +| 희귀도 | 전체, Common ~ Legendary | +| 장착 가능 | 현재 레벨에서 장착 가능한 것만 | +| 세트 | 세트 아이템만 | + +### 3.5 자동 정리 + +```dart +class InventoryAutoClean { + /// 인벤토리 자동 정리 + void autoClean(Inventory inventory, AutoCleanSettings settings) { + if (settings.sellCommon) { + _sellByRarity(ItemRarity.common); + } + if (settings.sellBelowLevel) { + _sellBelowLevel(settings.minLevel); + } + if (settings.keepBestPerSlot) { + _keepBestPerSlot(settings.keepCount); + } + } +} +``` + +### 3.6 인벤토리 UI + +``` +┌─ 인벤토리 [45/50] ──────────────────┐ +│ │ +│ [정렬: 희귀도 ▼] [필터: 전체 ▼] │ +│ │ +│ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ │ +│ │ ★ │ │ ★ │ │ ◆ │ │ ◆ │ │ ○ │ ... │ +│ │검 │ │갑 │ │방 │ │투 │ │단 │ │ +│ └───┘ └───┘ └───┘ └───┘ └───┘ │ +│ │ +│ 선택: 디버거의 검 +3 │ +│ 공격력 +45, 크리티컬 +5% │ +│ │ +│ [장착] [판매] [강화] [분해] │ +│ │ +│ ───────────────────────────────── │ +│ [ 자동 정리 ] [ 일괄 판매 ] │ +└─────────────────────────────────────┘ +``` + +--- + +## 4. 물약/소모품 시스템 + +### 4.1 소모품 종류 + +| 카테고리 | 아이템 | 효과 | 획득 방법 | +|----------|--------|------|----------| +| **HP 물약** | 소형 HP 물약 | HP +100 | 상점, 드롭 | +| | 중형 HP 물약 | HP +300 | 상점, 드롭 | +| | 대형 HP 물약 | HP +500 | 상점, 드롭 | +| | 최상급 HP 물약 | HP 100% 회복 | 보스 드롭, 제작 | +| **MP 물약** | 소형 MP 물약 | MP +50 | 상점, 드롭 | +| | 중형 MP 물약 | MP +150 | 상점, 드롭 | +| | 대형 MP 물약 | MP +300 | 상점, 드롭 | +| | 최상급 MP 물약 | MP 100% 회복 | 보스 드롭, 제작 | +| **버프 물약** | 공격력 물약 | ATK +20%, 5분 | 상점, 제작 | +| | 방어력 물약 | DEF +20%, 5분 | 상점, 제작 | +| | 경험치 물약 | EXP +50%, 5분 | 이벤트, 퀘스트 | +| | 골드 물약 | GOLD +50%, 5분 | 이벤트, 퀘스트 | +| | 행운 물약 | 드롭률 +30%, 5분 | 희귀 드롭 | +| **특수 소모품** | 귀환 스크롤 | 마을로 즉시 이동 | 상점 | +| | 부활의 부적 | 사망 시 장비 1개 보존 | 보스 드롭 | +| | 감정 스크롤 | 미감정 아이템 감정 | 상점 | + +### 4.2 소모품 데이터 구조 + +```dart +class Consumable { + final String id; + final String name; + final ConsumableType type; // hp, mp, buff, special + final int value; // 회복량 또는 효과 수치 + final Duration? duration; // 버프 지속 시간 + final int maxStack; // 최대 중첩 수 (인벤토리) + final int buyPrice; + final int sellPrice; +} + +class ConsumableInventory { + final Map items; // id -> 수량 + + void use(String id); + void add(String id, int amount); + bool has(String id) => (items[id] ?? 0) > 0; +} +``` + +### 4.3 자동 사용 설정 + +``` +┌─ 물약 자동 사용 설정 ───────────────┐ +│ │ +│ HP 물약 자동 사용 │ +│ ● 켜기 ○ 끄기 │ +│ HP가 [30]% 이하일 때 사용 │ +│ 사용 우선순위: [소형 > 중형 > 대형]│ +│ │ +│ MP 물약 자동 사용 │ +│ ● 켜기 ○ 끄기 │ +│ MP가 [20]% 이하일 때 사용 │ +│ │ +│ 버프 물약 자동 사용 │ +│ ○ 켜기 ● 끄기 │ +│ (보스전에서만 자동 사용) │ +│ │ +└─────────────────────────────────────┘ +``` + +### 4.4 물약 쿨타임 + +| 물약 종류 | 쿨타임 | +|----------|--------| +| HP 물약 | 3초 | +| MP 물약 | 3초 | +| 버프 물약 | 60초 | +| 특수 소모품 | 없음 | + +--- diff --git a/doc/task-ext-meta-systems.md b/doc/task-ext-meta-systems.md new file mode 100644 index 0000000..6ae3c89 --- /dev/null +++ b/doc/task-ext-meta-systems.md @@ -0,0 +1,251 @@ +# 메타 시스템: 업적/도감/통계/칭호 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 업적 시스템 + +### 1.1 업적 카테고리 + +| 카테고리 | 예시 업적 | +|----------|----------| +| **전투** | 첫 번째 몬스터 처치, 100마리 처치, 1000마리 처치, 무피해 보스 처치 | +| **성장** | 레벨 10 달성, 레벨 50 달성, 레벨 100 달성 | +| **수집** | 첫 에픽 아이템, 전설 아이템 획득, 모든 슬롯 에픽 이상 장착 | +| **탐험** | 첫 퀘스트 완료, 100개 퀘스트 완료, 모든 Act 클리어 | +| **생존** | 10연전 생존, HP 1로 생존, 사망 없이 Act 1 클리어 | +| **스킬** | 첫 스킬 사용, 스킬로 100마리 처치, 모든 스킬 습득 | +| **도전** | 레벨 10 이하로 Act 1 보스 처치, 장비 없이 10마리 처치 | +| **히든** | 특정 조합 발견, 이스터에그 발견 | + +### 1.2 업적 보상 + +| 등급 | 보상 | +|------|------| +| 브론즈 | 골드 100-500 | +| 실버 | 골드 500-2000, 아이템 박스 | +| 골드 | 골드 2000-10000, 희귀 아이템 박스 | +| 플래티넘 | 전설 아이템 박스, 특별 칭호 | + +### 1.3 업적 UI + +``` +┌─ 업적 ──────────────────────────┐ +│ ★ 전투 [12/25] │ +│ ☑ 첫 번째 사냥꾼 - 몬스터 처치│ +│ ☑ 백전용사 - 100마리 처치 │ +│ ☐ 천인의 적 - 1000마리 처치 │ +│ │ +│ ★ 성장 [3/10] │ +│ ☑ 신입 개발자 - 레벨 10 │ +│ ☐ 시니어 개발자 - 레벨 50 │ +└─────────────────────────────────┘ +``` + +--- + +## 2. 도감 시스템 + +### 2.1 도감 종류 + +| 도감 | 기록 내용 | 수집 조건 | +|------|----------|----------| +| **몬스터 도감** | 이름, 레벨 범위, 드롭 아이템, 출현 지역 | 한번이라도 처치 | +| **아이템 도감** | 이름, 스탯, 희귀도, 획득 방법 | 한번이라도 획득 | +| **스킬 도감** | 이름, 효과, MP 소모, 쿨타임 | 한번이라도 습득 | +| **NPC 도감** | 이름, 역할, 등장 시네마틱 | 시네마틱에서 등장 | + +### 2.2 몬스터 도감 상세 + +```dart +class MonsterEntry { + final String id; + final String name; + final int minLevel; + final int maxLevel; + final List dropItems; + final String description; + final int killCount; // 처치 횟수 + final DateTime firstMet; // 첫 조우 시간 + final bool isDefeated; // 처치 여부 +} +``` + +### 2.3 도감 UI + +``` +┌─ 몬스터 도감 [127/200] ─────────┐ +│ │ +│ ┌──────┐ Syntax Error │ +│ │ ∧∧∧ │ Lv. 1-5 │ +│ │ \○/ │ 드롭: 오타, 구두점 │ +│ │ │ │ 처치: 47회 │ +│ └──────┘ │ +│ │ +│ ┌──────┐ Memory Leak │ +│ │ ~~~ │ Lv. 6-12 │ +│ │ ⊂⊃ │ 드롭: 누수 바이트 │ +│ │ ~~~ │ 처치: 23회 │ +│ └──────┘ │ +│ │ +│ ┌──────┐ ??? │ +│ │ ? │ 미발견 │ +│ └──────┘ │ +└─────────────────────────────────┘ +``` + +### 2.4 수집률 보상 + +| 수집률 | 보상 | +|--------|------| +| 25% | 칭호 "수집가 견습생" | +| 50% | 드롭률 +5% | +| 75% | 칭호 "마스터 수집가" | +| 100% | 전설 아이템 + 칭호 "완벽주의자" | + +--- + +## 3. 통계 화면 + +### 3.1 통계 카테고리 + +| 카테고리 | 통계 항목 | +|----------|----------| +| **시간** | 총 플레이 시간, 현재 세션 시간, 평균 세션 시간 | +| **전투** | 총 전투 횟수, 처치 몬스터 수, 총 데미지, 최고 단일 데미지, 크리티컬 횟수 | +| **생존** | 총 사망 횟수, 사망 원인 Top 5, 최장 생존 시간, 연속 전투 생존 기록 | +| **획득** | 총 획득 골드, 총 획득 아이템, 희귀도별 아이템 수, 가장 비싼 아이템 | +| **스킬** | 총 스킬 사용 횟수, 스킬별 사용 횟수, 스킬 데미지 합계, 가장 많이 쓴 스킬 | +| **탐험** | 완료 퀘스트 수, 방문 지역 수, 현재 Act, 최고 도달 레벨 | +| **효율** | 시간당 경험치, 시간당 골드, 평균 전투 시간, 승률 | + +### 3.2 통계 UI + +``` +┌─ 플레이 통계 ───────────────────┐ +│ │ +│ ⏱ 플레이 시간 │ +│ 총: 15시간 34분 │ +│ 현재 세션: 2시간 12분 │ +│ │ +│ ⚔ 전투 │ +│ 처치 몬스터: 1,247마리 │ +│ 총 데미지: 458,291 │ +│ 최고 데미지: 2,847 (크리티컬) │ +│ 크리티컬 횟수: 312회 │ +│ │ +│ 💀 사망 │ +│ 총 사망: 7회 │ +│ ┌ 사망 원인 Top 3 ┐ │ +│ │ 1. 커널 패닉 (3회)│ │ +│ │ 2. 메모리 누수 (2회)│ │ +│ │ 3. 스택 오버플로우 (2회)│ │ +│ └─────────────────┘ │ +│ │ +│ 💰 획득 │ +│ 총 골드: 124,560 │ +│ 아이템: 892개 │ +│ 전설: 3개 | 에픽: 12개 │ +└─────────────────────────────────┘ +``` + +### 3.3 통계 데이터 구조 + +```dart +class GameStatistics { + // 시간 + final Duration totalPlayTime; + final Duration currentSessionTime; + + // 전투 + final int totalBattles; + final int monstersKilled; + final int totalDamageDealt; + final int highestDamage; + final int criticalHits; + + // 생존 + final int totalDeaths; + final Map deathCauses; + final Duration longestSurvival; + + // 획득 + final int totalGoldEarned; + final int totalItemsObtained; + final Map itemsByRarity; + + // 스킬 + final int totalSkillUses; + final Map skillUseCounts; + + // 탐험 + final int questsCompleted; + final int highestLevel; + final int currentAct; +} +``` + +--- + +## 4. 칭호 시스템 + +### 4.1 칭호 구조 + +```dart +class Title { + final String id; + final String name; + final String description; + final TitleRarity rarity; // 일반, 희귀, 영웅, 전설 + final Map? statBonus; // 착용 시 보너스 + final String unlockCondition; // 해금 조건 설명 +} +``` + +### 4.2 칭호 목록 + +| 칭호 | 해금 조건 | 보너스 | 희귀도 | +|------|----------|--------|--------| +| **초보 개발자** | 게임 시작 | - | 일반 | +| **버그 헌터** | 몬스터 100마리 처치 | ATK +2 | 일반 | +| **백전용사** | 몬스터 1000마리 처치 | ATK +5 | 희귀 | +| **천인의 적** | 몬스터 10000마리 처치 | ATK +10, CRI +2% | 영웅 | +| **불사신** | 레벨 50 무사망 | HP +100, DEF +5 | 영웅 | +| **완벽주의자** | 도감 100% | 모든 스탯 +3 | 전설 | +| **글리치 슬레이어** | 글리치 신 처치 | 모든 스탯 +5 | 전설 | +| **전설의 코더** | 명예의 전당 입성 | 경험치 +10% | 전설 | +| **스피드러너** | 10시간 내 클리어 | 이동 속도 +10% | 영웅 | +| **생존주의자** | 사망 3회 이하 클리어 | HP 재생 +5% | 영웅 | +| **무자비한 디버거** | 20 콤보 달성 | CRI +5% | 희귀 | +| **행운아** | 전설 아이템 10개 획득 | 드롭률 +5% | 희귀 | + +### 4.3 칭호 UI + +``` +┌─ 칭호 ──────────────────────────────┐ +│ │ +│ 현재 칭호: [백전용사] ATK +5 │ +│ │ +│ 보유 칭호 [15/50]: │ +│ │ +│ ★★★ 전설 │ +│ ☐ 글리치 슬레이어 (미해금) │ +│ ☐ 완벽주의자 (미해금) │ +│ │ +│ ★★ 영웅 │ +│ ☑ 불사신 - HP +100, DEF +5 │ +│ ☐ 스피드러너 (미해금) │ +│ │ +│ ★ 희귀 │ +│ ☑ 백전용사 - ATK +5 [장착 중] │ +│ ☑ 무자비한 디버거 - CRI +5% │ +│ │ +│ ○ 일반 │ +│ ☑ 초보 개발자 │ +│ ☑ 버그 헌터 - ATK +2 │ +│ │ +└─────────────────────────────────────┘ +``` + +--- diff --git a/doc/task-ext-platform.md b/doc/task-ext-platform.md new file mode 100644 index 0000000..fd97dc0 --- /dev/null +++ b/doc/task-ext-platform.md @@ -0,0 +1,184 @@ +# 플랫폼/오프라인/향후 고려사항 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 오프라인/백그라운드 진행 + +### 1.1 오프라인 진행 개념 + +``` +앱 종료 시점 기록 → 재접속 시 경과 시간 계산 → 오프라인 보상 계산 → 결과 표시 +``` + +### 1.2 오프라인 보상 계산 + +```dart +class OfflineProgressCalculator { + /// 오프라인 보상 계산 + OfflineReward calculate({ + required DateTime lastPlayedAt, + required int playerLevel, + required CombatStats stats, + }) { + final duration = DateTime.now().difference(lastPlayedAt); + final cappedMinutes = min(duration.inMinutes, maxOfflineMinutes); + + // 분당 예상 전투 수 (레벨 기반) + final battlesPerMinute = 2.0; + final totalBattles = (cappedMinutes * battlesPerMinute).round(); + + // 오프라인 효율 (온라인의 50%) + final efficiency = 0.5; + + return OfflineReward( + exp: (totalBattles * expPerBattle * efficiency).round(), + gold: (totalBattles * goldPerBattle * efficiency).round(), + items: generateOfflineItems(totalBattles, efficiency), + duration: Duration(minutes: cappedMinutes), + ); + } +} +``` + +### 1.3 오프라인 제한 + +| 항목 | 제한 | +|------|------| +| 최대 오프라인 시간 | 8시간 (480분) | +| 오프라인 효율 | 온라인의 50% | +| 사망 가능성 | 없음 (오프라인 중 사망 불가) | +| 레벨업 | 가능 (최대 3레벨) | +| 퀘스트 진행 | 불가 (전투만 계산) | +| 스킬 사용 | 자동 (효율 계산에 포함) | + +### 1.4 재접속 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ 🌙 오프라인 보상 │ +│ │ +│ 부재 시간: 4시간 32분 │ +│ │ +│ ───────────────────────── │ +│ 💰 획득 골드: 2,450 │ +│ ⭐ 획득 경험치: 12,800 │ +│ 📦 획득 아이템: 3개 │ +│ ───────────────────────── │ +│ │ +│ 레벨업! Lv.23 → Lv.24 │ +│ │ +│ [ 보상 받기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +### 1.5 백그라운드 진행 (모바일) + +| 모드 | 동작 | +|------|------| +| 포그라운드 | 정상 진행 | +| 백그라운드 (5분 이내) | 실시간 진행 유지 | +| 백그라운드 (5분 초과) | 앱 일시 정지, 재진입 시 오프라인 계산 | +| 완전 종료 | 오프라인 계산 | + +### 1.6 관련 파일 + +| 파일 | 역할 | +|------|------| +| `core/service/offline_service.dart` | **신규** - 오프라인 보상 계산 | +| `core/storage/last_played_storage.dart` | **신규** - 마지막 플레이 시간 저장 | +| `features/game/widgets/offline_reward_dialog.dart` | **신규** - 보상 UI | + +--- + +## 2. 플랫폼별 고려사항 + +### 2.1 플랫폼 지원 현황 + +| 플랫폼 | 지원 | 우선순위 | 특이사항 | +|--------|------|----------|----------| +| iOS | ✓ | 상 | App Store 심사 | +| Android | ✓ | 상 | Google Play 심사 | +| Web | ✓ | 중 | 브라우저 호환성 | +| macOS | ✓ | 하 | 데스크톱 UI | +| Windows | ✓ | 하 | 데스크톱 UI | +| Linux | △ | 최하 | 테스트 제한적 | + +### 2.2 플랫폼별 기능 차이 + +| 기능 | iOS | Android | Web | Desktop | +|------|-----|---------|-----|---------| +| 진동 | ✓ | ✓ | ✗ | ✗ | +| 푸시 알림 | ✓ | ✓ | △ | △ | +| 백그라운드 | △ | ✓ | ✗ | ✓ | +| 클라우드 저장 | iCloud | Google Play | ✗ | ✗ | +| IAP | App Store | Google Play | ✗ | ✗ | +| 키보드 단축키 | ✗ | ✗ | ✓ | ✓ | + +### 2.3 화면 크기 대응 + +| 카테고리 | 화면 크기 | 레이아웃 | +|----------|----------|----------| +| 소형 모바일 | < 360dp | 단일 컬럼, 축소 UI | +| 일반 모바일 | 360-600dp | 단일 컬럼 | +| 대형 모바일/태블릿 | 600-900dp | 2단 컬럼 | +| 태블릿/데스크톱 | > 900dp | 3단 컬럼 | + +### 2.4 플랫폼별 테스트 체크리스트 + +| 항목 | iOS | Android | Web | +|------|-----|---------|-----| +| 최소 OS 버전 | iOS 12+ | Android 6+ | 최신 브라우저 | +| 기기 테스트 | iPhone SE, 15 Pro | 저사양, 고사양 | Chrome, Safari, Firefox | +| 가로/세로 | 세로 고정 | 세로 고정 | 반응형 | +| 노치/펀치홀 | SafeArea | SafeArea | N/A | +| 다크 모드 | ✓ | ✓ | ✓ | + +--- + +## 3. 향후 고려 사항 + +### 3.1 타임어택/스피드런 모드 + +| 기능 | 설명 | +|------|------| +| 타이머 표시 | 실시간 플레이 시간 표시 | +| 구간 기록 | Act별 클리어 시간 | +| 리더보드 | 최고 기록 순위 (향후 온라인) | +| 고스트 데이터 | 이전 기록과 비교 (로컬) | + +### 3.2 애널리틱스 (익명) + +| 수집 데이터 | 목적 | +|------------|------| +| 레벨별 사망률 | 밸런싱 조정 | +| 인기 스킬/장비 | 콘텐츠 밸런싱 | +| 플레이 세션 시간 | 게임 흐름 개선 | +| 이탈 지점 | 문제 구간 파악 | + +### 3.3 다국어 확장 + +| 언어 | 우선순위 | 현황 | +|------|----------|------| +| 한국어 | 완료 | ✓ | +| 영어 | 완료 | ✓ | +| 일본어 | 높음 | 계획 | +| 중국어 (간체) | 높음 | 계획 | +| 중국어 (번체) | 중간 | 계획 | +| 스페인어 | 중간 | 계획 | + +### 3.4 개발자/디버그 모드 + +| 기능 | 설명 | +|------|------| +| 레벨 조정 | 즉시 레벨 변경 | +| 아이템 지급 | 모든 아이템 획득 | +| 골드 지급 | 무제한 골드 | +| 무적 모드 | 사망 불가 | +| 스킵 | 전투/시네마틱 스킵 | +| 로그 표시 | 상세 디버그 로그 | + +--- diff --git a/doc/task-ext-save-data.md b/doc/task-ext-save-data.md new file mode 100644 index 0000000..877ef07 --- /dev/null +++ b/doc/task-ext-save-data.md @@ -0,0 +1,223 @@ +# 세이브/데이터 관리 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 멀티 세이브 슬롯 + +### 1.1 세이브 슬롯 구조 + +```dart +class SaveSlot { + final int slotIndex; // 0-4 (5개 슬롯) + final String? characterName; + final String? race; + final String? klass; + final int? level; + final Duration? playTime; + final DateTime? lastPlayedAt; + final bool isEmpty; +} +``` + +### 1.2 세이브 슬롯 UI + +``` +┌─ 세이브 슬롯 선택 ──────────────────┐ +│ │ +│ ┌─ 슬롯 1 ─────────────────────┐ │ +│ │ 🎮 CodeSlayer (Lv.45) │ │ +│ │ 버퍼 드워프 디버거 성기사 │ │ +│ │ 플레이: 8시간 22분 │ │ +│ │ 마지막: 2024.03.15 14:30 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 2 ─────────────────────┐ │ +│ │ 🎮 NullMaster (Lv.12) │ │ +│ │ 널 엘프 컴파일러 마법사 │ │ +│ │ 플레이: 1시간 05분 │ │ +│ │ 마지막: 2024.03.14 20:15 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 3 ─────────────────────┐ │ +│ │ 빈 슬롯 │ │ +│ │ [ + 새 게임 시작 ] │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 4 ─────────────────────┐ │ +│ │ 빈 슬롯 │ │ +│ └──────────────────────────────┘ │ +│ │ +│ ┌─ 슬롯 5 ─────────────────────┐ │ +│ │ 빈 슬롯 │ │ +│ └──────────────────────────────┘ │ +│ │ +└─────────────────────────────────────┘ +``` + +### 1.3 슬롯 관리 기능 + +| 기능 | 설명 | +|------|------| +| 새 게임 | 빈 슬롯에 새 캐릭터 생성 | +| 계속하기 | 해당 슬롯 캐릭터로 게임 재개 | +| 삭제 | 슬롯 데이터 삭제 (확인 필요) | +| 복사 | 다른 빈 슬롯으로 복사 | +| 내보내기 | 세이브 파일로 내보내기 | + +### 1.4 관련 파일 + +| 파일 | 역할 | +|------|------| +| `core/model/save_slot.dart` | **신규** - 세이브 슬롯 모델 | +| `core/storage/multi_save_manager.dart` | **신규** - 멀티 세이브 관리 | +| `features/save/save_slot_screen.dart` | **신규** - 슬롯 선택 화면 | + +--- + +## 2. 데이터 마이그레이션 + +### 2.1 버전별 마이그레이션 전략 + +```dart +class SaveMigrator { + /// 세이브 데이터 버전 확인 및 마이그레이션 + SaveData migrate(Map rawData) { + final version = rawData['version'] as int? ?? 1; + + var data = rawData; + + // 단계별 마이그레이션 + if (version < 2) data = _migrateV1ToV2(data); + if (version < 3) data = _migrateV2ToV3(data); + if (version < 4) data = _migrateV3ToV4(data); + // ... + + return SaveData.fromJson(data); + } +} +``` + +### 2.2 버전별 변경 사항 + +| 버전 | 변경 내용 | 마이그레이션 | +|------|----------|-------------| +| v1→v2 | CombatStats 추가 | 기본 스탯에서 파생 스탯 계산 | +| v2→v3 | ItemStats 추가 | 기존 아이템에 기본 스탯 부여 | +| v3→v4 | SkillState 추가 | 보유 스킬에 상태 초기화 | +| v4→v5 | DeathInfo 추가 | 사망 기록 초기화 | +| v5→v6 | 통계 데이터 추가 | 기존 플레이 기반 추정 | + +### 2.3 마이그레이션 안전 장치 + +```dart +class MigrationSafetyNet { + /// 마이그레이션 전 백업 생성 + Future createBackup(int slotIndex) async { + final backup = await loadRawSave(slotIndex); + await saveBackup(slotIndex, backup, DateTime.now()); + } + + /// 마이그레이션 실패 시 롤백 + Future rollback(int slotIndex) async { + final backup = await loadLatestBackup(slotIndex); + await restoreSave(slotIndex, backup); + } +} +``` + +### 2.4 마이그레이션 실패 처리 + +``` +┌─────────────────────────────────────┐ +│ │ +│ ⚠️ 세이브 데이터 업그레이드 실패 │ +│ │ +│ 이전 버전의 세이브 데이터를 │ +│ 현재 버전으로 변환하는 데 │ +│ 문제가 발생했습니다. │ +│ │ +│ [ 백업에서 복원 ] │ +│ [ 새 게임 시작 ] │ +│ [ 버그 리포트 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## 3. 세이브 파일 관리 + +### 3.1 세이브 파일 구조 + +```dart +class SaveFileManager { + /// 세이브 파일 경로 + Future getSavePath(int slotIndex); + + /// 백업 파일 경로 + Future getBackupPath(int slotIndex, DateTime timestamp); + + /// 내보내기 파일 생성 + Future exportSave(int slotIndex); + + /// 외부 파일에서 가져오기 + Future importSave(File file, int slotIndex); +} +``` + +### 3.2 자동 백업 + +| 시점 | 백업 유형 | 보관 기간 | +|------|----------|----------| +| 레벨업 시 | 자동 | 최근 5개 | +| 퀘스트 완료 시 | 자동 | 최근 5개 | +| 앱 종료 시 | 자동 | 최근 3개 | +| 수동 저장 시 | 수동 | 무제한 | +| 버전 업데이트 전 | 마이그레이션 | 영구 | + +### 3.3 내보내기/가져오기 + +``` +내보내기 형식: JSON (압축) +파일명: ascii_never_die_save_{slot}_{timestamp}.json + +내보내기 내용: +- 캐릭터 데이터 +- 인벤토리 +- 장비 +- 퀘스트 진행 +- 통계 +- 업적 +- 설정 (선택적) +``` + +### 3.4 클라우드 저장 (향후) + +| 플랫폼 | 저장 위치 | +|--------|----------| +| iOS | iCloud | +| Android | Google Play Games | +| Desktop | 로컬만 (향후 자체 서버) | + +### 3.5 세이브 파일 UI + +``` +┌─ 세이브 파일 관리 ──────────────────┐ +│ │ +│ 📁 슬롯 1: CodeSlayer │ +│ │ +│ 자동 백업 (최근 5개) │ +│ ├─ 2024-03-15 14:30 (레벨업) │ +│ ├─ 2024-03-15 14:15 (퀘스트) │ +│ ├─ 2024-03-15 13:45 (레벨업) │ +│ └─ ... │ +│ │ +│ [ 내보내기 ] [ 가져오기 ] │ +│ [ 백업에서 복원 ] [ 삭제 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- diff --git a/doc/task-ext-settings-infra.md b/doc/task-ext-settings-infra.md new file mode 100644 index 0000000..8206fba --- /dev/null +++ b/doc/task-ext-settings-infra.md @@ -0,0 +1,160 @@ +# 설정/튜토리얼/성능/테스트 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 설정 화면 + +| 설정 항목 | 옵션 | +|----------|------| +| 게임 속도 | 0.5x, 1x, 2x, 5x | +| 자동 저장 간격 | 1분, 5분, 10분 | +| SFX 볼륨 | 0-100% | +| BGM 볼륨 | 0-100% | +| 진동 | 켜기/끄기 (모바일) | +| 알림 표시 | 켜기/끄기 | +| 전투 로그 | 간략/상세/끄기 | +| 언어 | 한국어/English | + +### 1.1 데이터 관리 설정 + +| 설정 항목 | 설명 | 경고 | +|----------|------|------| +| 튜토리얼 초기화 | 튜토리얼 다시 보기 | - | +| 도움말 초기화 | 모든 도움말 팁 다시 표시 | - | +| 캐시 삭제 | 임시 파일 삭제 | - | +| 설정 초기화 | 모든 설정을 기본값으로 | 확인 필요 | +| 현재 캐릭터 삭제 | 현재 슬롯 데이터 삭제 | 2중 확인 필요 | +| 모든 데이터 삭제 | 전체 초기화 | 3중 확인 + 입력 확인 | + +### 1.2 데이터 삭제 확인 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ ⚠️ 모든 데이터 삭제 │ +│ │ +│ 이 작업은 되돌릴 수 없습니다! │ +│ │ +│ 삭제될 항목: │ +│ • 모든 캐릭터 (5개 슬롯) │ +│ • 명예의 전당 기록 │ +│ • 업적 │ +│ • 통계 │ +│ • 설정 │ +│ │ +│ 확인하려면 "삭제합니다"를 입력: │ +│ ┌───────────────────────────┐ │ +│ │ │ │ +│ └───────────────────────────┘ │ +│ │ +│ [ 취소 ] [ 삭제 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## 2. 성능 최적화 + +| 항목 | 현재 | 개선 방안 | +|------|------|----------| +| 상태 업데이트 | 매 틱마다 전체 rebuild | 변경된 부분만 업데이트 | +| 애니메이션 | Timer 기반 | AnimationController 사용 | +| 저장 | 자동 저장 빈번 | 변경 감지 후 디바운스 | + +--- + +## 3. 테스트 전략 + +| 테스트 유형 | 대상 | 도구 | +|------------|------|------| +| 유닛 테스트 | 전투 계산, 스탯 계산 | flutter_test | +| 위젯 테스트 | UI 컴포넌트 | flutter_test | +| 통합 테스트 | 전체 게임 플로우 | integration_test | +| 밸런스 테스트 | 시뮬레이션 | 커스텀 도구 | + +--- + +## 4. 튜토리얼 시스템 + +### 4.1 튜토리얼 흐름 + +``` +첫 실행 감지 → 튜토리얼 시작 → 단계별 가이드 → 완료 보상 → 본 게임 시작 +``` + +### 4.2 튜토리얼 단계 + +| 단계 | 내용 | 하이라이트 UI | 완료 조건 | +|------|------|--------------|----------| +| 1 | 게임 소개 | 전체 화면 | 탭하여 계속 | +| 2 | 캐릭터 스탯 설명 | 스탯 패널 | 스탯 패널 탭 | +| 3 | 전투 시스템 설명 | 전투 영역 | 첫 몬스터 처치 | +| 4 | 장비 시스템 설명 | 장비 패널 | 첫 장비 장착 | +| 5 | 스킬 사용 설명 | 스킬 바 | 첫 스킬 사용 | +| 6 | 경험치/레벨업 설명 | 경험치 바 | 레벨 2 달성 | +| 7 | 퀘스트 설명 | 퀘스트 패널 | 첫 퀘스트 확인 | +| 8 | 사망/부활 설명 | 안내 팝업 | 탭하여 계속 | +| 9 | 설정 및 기타 | 설정 버튼 | 설정 화면 열기 | +| 10 | 튜토리얼 완료 | 보상 팝업 | 보상 수령 | + +### 4.3 튜토리얼 UI + +``` +┌─────────────────────────────────────┐ +│ ┌─────────────────────────────┐ │ +│ │ 하이라이트된 영역 │◄───│ 이 부분을 탭해보세요! +│ └─────────────────────────────┘ │ +│ │ +│ ══════════════════════════════ │ +│ 스탯은 전투력에 직접 영향을 │ +│ 미칩니다. STR은 공격력, │ +│ CON은 HP에 영향을 줍니다. │ +│ ══════════════════════════════ │ +│ │ +│ [ 다음 ] [ 건너뛰기 ] │ +└─────────────────────────────────────┘ +``` + +### 4.4 튜토리얼 완료 보상 + +| 보상 | 수량 | +|------|------| +| 골드 | 500 | +| 초보자 무기 | 1 | +| 초보자 방어구 | 1 | +| 경험치 물약 | 1 | + +### 4.5 구현 방안 + +```dart +class TutorialService { + int currentStep = 0; + bool isCompleted = false; + + void startTutorial(); + void nextStep(); + void skipTutorial(); + void completeStep(int step); + Widget? getHighlightWidget(); + String getCurrentMessage(); +} + +class TutorialOverlay extends StatelessWidget { + final int step; + final VoidCallback onNext; + final VoidCallback onSkip; +} +``` + +### 4.6 튜토리얼 관련 파일 + +| 파일 | 역할 | +|------|------| +| `core/service/tutorial_service.dart` | **신규** - 튜토리얼 로직 | +| `features/game/widgets/tutorial_overlay.dart` | **신규** - 튜토리얼 UI | +| `data/tutorial_data.dart` | **신규** - 튜토리얼 텍스트 | + +--- diff --git a/doc/task-ext-ui-tech.md b/doc/task-ext-ui-tech.md new file mode 100644 index 0000000..058edb9 --- /dev/null +++ b/doc/task-ext-ui-tech.md @@ -0,0 +1,238 @@ +# UI 레이아웃/기술 상세 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. UI 레이아웃/네비게이션 + +### 1.1 메인 게임 화면 레이아웃 + +``` +┌─────────────────────────────────────────────────────────┐ +│ [메뉴] CodeSlayer Lv.25 💰 15,420 [알림] [설정] │ ← 헤더 +├─────────────────────────────────────────────────────────┤ +│ │ +│ ┌─ 캐릭터 ─────┐ ┌─ 전투 영역 ──────────────────┐ │ +│ │ │ │ │ │ +│ │ HP ████░░ │ │ ╔═══╗ ╔═══╗ │ │ +│ │ MP ███░░░ │ │ ║ ☺ ║ VS ║ ☠ ║ │ │ +│ │ │ │ ╚═══╝ ╚═══╝ │ │ +│ │ STR: 25 │ │ │ │ +│ │ CON: 20 │ │ Syntax Error Lv.24 │ │ +│ │ DEX: 18 │ │ HP ██████░░░░ │ │ +│ │ INT: 15 │ │ │ │ +│ │ WIS: 12 │ │ [45 데미지!] │ │ +│ │ CHA: 10 │ │ │ │ +│ └──────────────┘ └───────────────────────────────┘ │ +│ │ +│ ┌─ 장비 ───────────────────────────────────────────┐ │ +│ │ ⚔️ 디버거의 검 🛡️ 강철 갑옷 🎩 마법 투구 ... │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ +│ ┌─ 진행 상황 ──────────────────────────────────────┐ │ +│ │ 🗡️ 버그 처치 중... [일시정지] │ │ +│ │ ████████████████░░░░░░░░ 60% │ │ +│ └───────────────────────────────────────────────────┘ │ +│ │ +├─────────────────────────────────────────────────────────┤ +│ [전투] [인벤] [스킬] [퀘스트] [더보기] │ ← 탭 바 +└─────────────────────────────────────────────────────────┘ +``` + +### 1.2 화면 구성 + +| 화면 | 접근 방법 | 주요 기능 | +|------|----------|----------| +| **메인 (전투)** | 기본 화면 | 전투 진행, 스탯, 장비 | +| **인벤토리** | 탭 바 | 아이템 관리, 장착 | +| **스킬** | 탭 바 | 스킬 관리, 빌드 | +| **퀘스트** | 탭 바 | 퀘스트 목록, 진행 | +| **더보기** | 탭 바 | 도감, 업적, 통계, 상점 등 | +| **지역** | 더보기 | 월드맵, 던전 | +| **설정** | 헤더 | 게임 설정 | + +### 1.3 네비게이션 흐름 + +```mermaid +graph TD + A[앱 시작] --> B{세이브 존재?} + B -->|No| C[세이브 슬롯 선택] + B -->|Yes| D[세이브 슬롯 선택] + C --> E[캐릭터 생성] + D --> F{튜토리얼 완료?} + E --> F + F -->|No| G[튜토리얼] + F -->|Yes| H[메인 게임] + G --> H + + H --> I[인벤토리] + H --> J[스킬] + H --> K[퀘스트] + H --> L[더보기] + + L --> M[도감] + L --> N[업적] + L --> O[통계] + L --> P[상점] + L --> Q[지역] + L --> R[명예의 전당] +``` + +### 1.4 모달/오버레이 + +| 타입 | 사용 상황 | +|------|----------| +| **풀스크린 모달** | 사망 화면, 레벨업, 업적 달성 | +| **바텀 시트** | 아이템 상세, 스킬 상세, 퀵 액션 | +| **다이얼로그** | 확인, 경고, 선택 | +| **토스트** | 간단한 알림, 획득 메시지 | +| **툴팁** | 스탯 설명, 효과 설명 | + +### 1.5 반응형 레이아웃 + +```dart +class ResponsiveLayout extends StatelessWidget { + @override + Widget build(BuildContext context) { + return LayoutBuilder( + builder: (context, constraints) { + if (constraints.maxWidth < 360) { + return CompactLayout(); // 소형 모바일 + } else if (constraints.maxWidth < 600) { + return MobileLayout(); // 일반 모바일 + } else if (constraints.maxWidth < 900) { + return TabletLayout(); // 태블릿 + } else { + return DesktopLayout(); // 데스크톱 + } + }, + ); + } +} +``` + +--- + +## 2. 기술적 상세 + +### 2.1 State Management + +```dart +// Riverpod 사용 권장 +final gameStateProvider = StateNotifierProvider( + (ref) => GameStateNotifier(), +); + +class GameStateNotifier extends StateNotifier { + GameStateNotifier() : super(GameState.initial()); + + void tick() { /* 게임 틱 처리 */ } + void attack() { /* 공격 처리 */ } + void useSkill(String skillId) { /* 스킬 사용 */ } + void equip(Equipment item) { /* 장비 장착 */ } +} + +// 분리된 Provider들 +final combatProvider = ...; // 전투 상태 +final inventoryProvider = ...; // 인벤토리 상태 +final questProvider = ...; // 퀘스트 상태 +final settingsProvider = ...; // 설정 상태 +``` + +### 2.2 에러 처리 전략 + +```dart +class AppException implements Exception { + final String code; + final String message; + final dynamic originalError; + + AppException(this.code, this.message, [this.originalError]); +} + +// 에러 타입 +class SaveLoadException extends AppException { ... } +class MigrationException extends AppException { ... } +class NetworkException extends AppException { ... } // 향후 온라인용 + +// 전역 에러 핸들러 +void handleError(AppException e, StackTrace stack) { + // 1. 로깅 + Logger.error(e.code, e.message, stack); + + // 2. 사용자 알림 + showErrorDialog(e.message); + + // 3. 복구 시도 (가능한 경우) + attemptRecovery(e); +} +``` + +### 2.3 에러 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ ⚠️ 오류가 발생했습니다 │ +│ │ +│ 세이브 데이터를 불러오는 중 │ +│ 문제가 발생했습니다. │ +│ │ +│ 오류 코드: SAVE_LOAD_001 │ +│ │ +│ [ 다시 시도 ] [ 백업 복원 ] │ +│ [ 새 게임 ] [ 문의하기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +### 2.4 로깅 전략 + +```dart +class Logger { + static LogLevel currentLevel = kDebugMode + ? LogLevel.debug + : LogLevel.warning; + + static void debug(String message) { ... } + static void info(String message) { ... } + static void warning(String message) { ... } + static void error(String code, String message, StackTrace? stack) { ... } +} + +enum LogLevel { debug, info, warning, error } + +// 로그 출력 예시 +// [DEBUG] 2024-03-15 14:30:00 - Combat: Player attacks for 45 damage +// [INFO] 2024-03-15 14:30:01 - Level up: 24 -> 25 +// [WARN] 2024-03-15 14:30:02 - Low HP warning: 15% +// [ERROR] 2024-03-15 14:30:03 - SAVE_001: Failed to save game +``` + +### 2.5 성능 모니터링 + +```dart +class PerformanceMonitor { + /// FPS 측정 + double get currentFps => ...; + + /// 메모리 사용량 + int get memoryUsageMb => ...; + + /// 틱 처리 시간 + Duration get averageTickTime => ...; + + /// 성능 경고 + void checkPerformance() { + if (currentFps < 30) { + Logger.warning('Low FPS: $currentFps'); + } + if (memoryUsageMb > 500) { + Logger.warning('High memory usage: $memoryUsageMb MB'); + } + } +} +``` + +--- diff --git a/doc/task-ext-world.md b/doc/task-ext-world.md new file mode 100644 index 0000000..5ddc38c --- /dev/null +++ b/doc/task-ext-world.md @@ -0,0 +1,215 @@ +# 월드 시스템: 던전/지역/상점 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 던전/지역 시스템 + +### 1.1 월드 구조 + +``` +┌─ 코드 왕국 (세계) ─────────────────────────────────────┐ +│ │ +│ Act I: 버그 평원 │ +│ ├─ 시작 마을 (안전 지역) │ +│ ├─ 버그 초원 (Lv.1-5) │ +│ ├─ 에러 숲 (Lv.6-10) │ +│ ├─ 버그 둥지 [던전] (Lv.8-12) │ +│ └─ 문법 오류의 탑 [보스] (Lv.15) │ +│ │ +│ Act II: 손상된 네트워크 │ +│ ├─ 디버거 요새 (안전 지역) │ +│ ├─ 손상된 회로 (Lv.16-25) │ +│ ├─ 메모리 늪 (Lv.21-30) │ +│ ├─ 누수 동굴 [던전] (Lv.25-35) │ +│ └─ 히드라의 서버실 [보스] (Lv.40) │ +│ │ +│ Act III: 널 왕국 │ +│ ├─ 바이너리 신전 (안전 지역) │ +│ ├─ 널 사막 (Lv.41-50) │ +│ ├─ 포인터 미궁 (Lv.46-55) │ +│ ├─ 버퍼의 심연 [던전] (Lv.50-60) │ +│ └─ 타이탄의 성채 [보스] (Lv.60) │ +│ │ +│ Act IV: 글리치 영역 │ +│ ├─ 저항군 기지 (안전 지역) │ +│ ├─ 커널 황무지 (Lv.61-70) │ +│ ├─ 패닉 협곡 (Lv.66-80) │ +│ ├─ 시스템 감옥 [던전] (Lv.70-85) │ +│ └─ 아콘의 왕좌 [보스] (Lv.80) │ +│ │ +│ Act V: 최종 결전 │ +│ ├─ 최후의 캐시 (안전 지역) │ +│ ├─ 글리치 회랑 (Lv.81-90) │ +│ ├─ 차원의 틈 (Lv.86-95) │ +│ ├─ 신의 코어 [던전] (Lv.90-100) │ +│ └─ 글리치 신의 영역 [최종 보스] (Lv.100) │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +### 1.2 지역 타입 + +| 타입 | 설명 | 특징 | +|------|------|------| +| **안전 지역** | 마을, 요새 | 전투 없음, 상점, NPC, 회복 | +| **필드** | 일반 사냥터 | 일반 몬스터, 퀘스트 | +| **던전** | 인스턴스 지역 | 강화 몬스터, 미니보스, 보상 증가 | +| **보스 지역** | Act 보스 | 보스 몬스터, 스토리 진행 | + +### 1.3 지역 이동 (Idle 방식) + +```dart +class AreaProgress { + final String currentAreaId; + final double explorationProgress; // 0.0 ~ 1.0 + final bool isBossUnlocked; + + /// 탐험 진행 (자동) + void progressExploration(Duration elapsed) { + // 시간 경과에 따라 탐험도 증가 + // 탐험도 100% 달성 시 다음 지역/보스 해금 + } +} +``` + +### 1.4 던전 시스템 + +| 요소 | 설명 | +|------|------| +| **입장 조건** | 최소 레벨, 이전 던전 클리어 | +| **층 구조** | 3-5층, 층별 강화 몬스터 | +| **보스 층** | 마지막 층에 미니보스 | +| **보상** | 일반 필드 대비 2-3배 | +| **재입장** | 클리어 후 24시간 대기 (일일 1회) | + +### 1.5 지역 UI + +``` +┌─ 현재 위치 ─────────────────────────┐ +│ │ +│ 📍 Act II: 손상된 회로 │ +│ Lv.16-25 │ +│ │ +│ 탐험 진행도: ████████░░ 78% │ +│ 다음 지역까지: 22% │ +│ │ +│ ─────────────────────────────────── │ +│ │ +│ 🏰 디버거 요새 [방문하기] │ +│ 🌲 손상된 회로 [현재] │ +│ 🌊 메모리 늪 [해금 필요: 탐험 100%] │ +│ 🏔 누수 동굴 [해금 필요: Lv.25] │ +│ 👹 히드라 서버실 [해금 필요] │ +│ │ +└─────────────────────────────────────┘ +``` + +--- + +## 2. 상점 시스템 상세 + +### 2.1 상점 종류 + +| 상점 | 위치 | 판매 품목 | +|------|------|----------| +| **일반 상점** | 모든 마을 | 물약, 기본 장비, 소모품 | +| **대장간** | 모든 마을 | 무기, 방어구 (레벨 기반) | +| **마법 상점** | Act II 이후 | 스킬서, 마법 장비 | +| **비밀 상점** | 랜덤 등장 | 희귀 아이템, 한정품 | +| **길드 상점** | 요새 | 길드 포인트 교환 | + +### 2.2 상점 갱신 시스템 + +```dart +class Shop { + final ShopType type; + final List items; + final DateTime lastRefresh; + final Duration refreshInterval; + + /// 상점 아이템 갱신 + void refresh(int playerLevel) { + items.clear(); + items.addAll(_generateItems(playerLevel)); + lastRefresh = DateTime.now(); + } +} +``` + +| 상점 | 갱신 주기 | 갱신 조건 | +|------|----------|----------| +| 일반 상점 | 매일 자정 | 자동 | +| 대장간 | 레벨업 시 | 레벨업 | +| 마법 상점 | 매주 월요일 | 자동 | +| 비밀 상점 | 랜덤 | 5% 확률로 등장 | + +### 2.3 가격 계산 공식 + +```dart +/// 구매 가격 계산 +int calculateBuyPrice(Equipment item) { + final basePrice = item.level * 50; + final rarityMultiplier = { + ItemRarity.common: 1.0, + ItemRarity.uncommon: 2.0, + ItemRarity.rare: 5.0, + ItemRarity.epic: 15.0, + ItemRarity.legendary: 50.0, + }[item.rarity]!; + + return (basePrice * rarityMultiplier).round(); +} + +/// 판매 가격 계산 +int calculateSellPrice(Equipment item) { + return (calculateBuyPrice(item) * 0.3).round(); +} + +/// CHA 보너스 적용 +int applyCharismaDiscount(int price, int cha) { + // CHA 10당 1% 할인, 최대 20% 할인 + final discount = min(0.20, (cha - 10) * 0.01); + return (price * (1 - discount)).round(); +} +``` + +### 2.4 상점 UI + +``` +┌─ 대장간 ────────────────────────────┐ +│ │ +│ 👤 레벨: 25 💰 골드: 15,420 │ +│ 📦 인벤토리: 42/50 │ +│ │ +│ ─────────────────────────────────── │ +│ 판매 중인 아이템 (갱신까지: 2시간) │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ ⚔️ 디버거의 검 (Lv.25) │ │ +│ │ ATK +35, CRI +3% │ │ +│ │ 💰 1,250 골드 [구매] │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ ┌─────────────────────────────────┐ │ +│ │ 🛡️ 강철 갑옷 (Lv.24) │ │ +│ │ DEF +42, HP +50 │ │ +│ │ 💰 1,100 골드 [구매] │ │ +│ └─────────────────────────────────┘ │ +│ │ +│ [판매하기] [강화하기] [수리하기] │ +│ │ +└─────────────────────────────────────┘ +``` + +### 2.5 특별 거래 + +| 기능 | 설명 | +|------|------| +| **일괄 구매** | 물약 10개/50개 묶음 구매 (5% 할인) | +| **일괄 판매** | 선택한 아이템 일괄 판매 | +| **자동 구매** | 물약 부족 시 자동 구매 설정 | +| **예약 구매** | 비밀 상점 아이템 등장 시 알림 | + +--- diff --git a/doc/task-fun-design.md b/doc/task-fun-design.md new file mode 100644 index 0000000..0656668 --- /dev/null +++ b/doc/task-fun-design.md @@ -0,0 +1,292 @@ +# 재미 요소 설계 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +# 14. 재미 요소 설계 (Fun Factor Design) + +## 14.1 즉각적인 보상감 (Dopamine Hits) + +| 요소 | 설명 | 우선순위 | +|------|------|----------| +| **데미지 숫자 팝업** | 공격 시 데미지가 화면에 튀어오름 (크리티컬은 크게, 빨간색) | 상 | +| **콤보 시스템** | 연속 처치 시 "x5 COMBO!" 표시 + 보너스 경험치 (10% per combo) | 상 | +| **희귀 드롭 연출** | 전설 아이템 획득 시 화면 번쩍 + 특별 효과음 + 진동 | 상 | +| **레벨업 축하** | 레벨업 시 3초간 화려한 ASCII 이펙트 | 중 | +| **크리티컬 이펙트** | 크리티컬 히트 시 화면 흔들림 + "CRITICAL!" 텍스트 | 상 | + +### 14.1.1 데미지 팝업 구현 + +```dart +class DamagePopup { + final int damage; + final bool isCritical; + final Offset position; + final double opacity; // 1.0 → 0.0 fade out + final double offsetY; // 위로 떠오름 +} + +// 표시 예시 +// 일반: "45" (흰색, 작게) +// 크리티컬: "127!" (빨간색, 크게, 흔들림) +// 회복: "+30" (녹색) +// 스킬: "DEBUG STRIKE 250" (노란색) +``` + +### 14.1.2 콤보 시스템 + +``` +콤보 조건: 5초 내 연속 처치 +콤보 보상: +- x2: 경험치 +10% +- x3: 경험치 +15% +- x5: 경험치 +25%, 골드 +10% +- x10: 경험치 +50%, 골드 +25%, 희귀 드롭률 +5% +- x20+: "UNSTOPPABLE!" 칭호 획득 조건 +``` + +--- + +## 14.2 "한 판 더" 유발 요소 + +### 14.2.1 일일 도전 + +| 요소 | 설명 | +|------|------| +| **일일 미션** | 매일 3개의 미션 (예: "버그 30마리 처치", "크리티컬 10회") | +| **일일 보너스** | 첫 접속 시 골드/아이템 박스 | +| **연속 접속 보상** | 7일 연속 시 전설 아이템 박스 | + +``` +┌─ 일일 도전 ─────────────────────┐ +│ │ +│ ☑ 버그 30마리 처치 [30/30] │ +│ 보상: 골드 500 │ +│ │ +│ ☐ 크리티컬 10회 달성 [7/10] │ +│ 보상: 경험치 물약 │ +│ │ +│ ☐ 레벨업 1회 [0/1] │ +│ 보상: 랜덤 장비 박스 │ +│ │ +│ ───────────────────────────────│ +│ 연속 접속: 5일째 🔥 │ +│ 7일 보상까지: 2일 남음 │ +└─────────────────────────────────┘ +``` + +### 14.2.2 주간/이벤트 보스 + +| 보스 타입 | 출현 조건 | 보상 | +|----------|----------|------| +| **주간 보스** | 매주 일요일 등장 | 한정 아이템, 대량 골드 | +| **시즌 보스** | 명절/기념일 | 시즌 한정 장비, 칭호 | +| **랜덤 레이드** | 랜덤 (1% 확률) | 희귀 아이템 + 업적 | + +### 14.2.3 "거의 다 됐어" 심리 + +``` +레벨업까지 남은 경험치가 10% 이하일 때: +→ 경험치 바 색상 변경 (황금색) +→ "조금만 더!" 메시지 표시 +→ 다음 레벨 보상 미리보기 +``` + +--- + +## 14.3 플레이어 선택권 확대 + +### 14.3.1 스킬 빌드 시스템 + +```dart +class SkillBuild { + final List activeSkills; // 3개 슬롯 + final List passiveSkills; // 2개 슬롯 + final String buildName; // "공격형", "탱커형" 등 +} +``` + +| 빌드 타입 | 특징 | +|----------|------| +| **공격형** | 데미지 스킬 위주, 높은 DPS | +| **방어형** | 회복/방어 스킬, 생존력 특화 | +| **균형형** | 공격 + 회복 혼합 | +| **스피드형** | 쿨타임 감소, 연속 공격 | + +### 14.3.2 전투 스타일 전환 + +``` +[공격 모드] 🗡️ +- 공격력 +20% +- 방어력 -10% +- 크리티컬 +5% + +[방어 모드] 🛡️ +- 방어력 +30% +- 공격력 -10% +- 블록율 +10% + +[균형 모드] ⚖️ +- 기본 스탯 +- 회복량 +10% +``` + +### 14.3.3 자동/반자동 전환 + +| 모드 | 설명 | +|------|------| +| **완전 자동** | 모든 것 자동 (기본) | +| **스킬 수동** | 스킬만 수동 선택 | +| **보스전 수동** | 보스전에서만 수동 전환 | + +--- + +## 14.4 감정적 연결 + +### 14.4.1 캐릭터 성장 기록 + +``` +┌─ 나의 여정 ─────────────────────┐ +│ │ +│ 🎮 함께한 시간: 15시간 34분 │ +│ ⚔️ 처치한 버그: 1,247마리 │ +│ 💀 사망 횟수: 7회 │ +│ 🏆 획득 업적: 23개 │ +│ │ +│ 📝 기억에 남는 순간: │ +│ • 첫 레벨업 (0시간 2분) │ +│ • 첫 사망 (1시간 15분) │ +│ • 첫 전설 아이템 (8시간 22분) │ +│ • 첫 보스 처치 (5시간 47분) │ +└─────────────────────────────────┘ +``` + +### 14.4.2 상황별 메시지 (유머/위로) + +| 상황 | 메시지 예시 | +|------|------------| +| **첫 사망** | "축하합니다! 첫 번째 교훈을 얻었습니다. 버그는 누구나 만납니다." | +| **연속 사망** | "잠시 쉬어가는 건 어떨까요? 커피 한 잔의 여유..." | +| **레벨업** | "레벨 {n} 달성! 당신의 코드가 더 강해졌습니다." | +| **희귀 아이템** | "운이 좋으시네요! 이건 정말 드문 거에요!" | +| **100 연속 처치** | "무자비한 디버거! 버그들이 당신을 두려워합니다." | +| **장시간 플레이** | "3시간째 플레이 중... 물 한 잔 드세요! 💧" | + +### 14.4.3 마일스톤 축하 + +| 마일스톤 | 축하 연출 | +|----------|----------| +| 100마리 처치 | "백전용사" 칭호 + 특별 이펙트 | +| 1000마리 처치 | "천인의 적" 칭호 + 업적 팝업 | +| 10시간 플레이 | "헌신적인 개발자" 칭호 | +| 무사망 Act 클리어 | "완벽주의자" 칭호 + 보너스 골드 | + +--- + +## 14.5 예측 불가능한 재미 + +### 14.5.1 랜덤 이벤트 + +| 이벤트 | 확률 | 효과 | +|--------|------|------| +| **전설 몬스터 출현** | 5% | "갑자기 전설 몬스터가 나타났다!" - 처치 시 대량 보상 | +| **황금 몬스터** | 3% | 골드 10배 드롭 | +| **보물 상자** | 2% | 랜덤 아이템 발견 | +| **도움의 NPC** | 5% | 버프 or 회복 제공 | +| **함정** | 3% | 데미지 or 디버프 (긴장감) | +| **경험치 폭풍** | 1% | 다음 5분간 경험치 2배 | + +### 14.5.2 행운 시스템 + +```dart +class LuckEvent { + // 연속 불운 시 행운 상승 + int unluckyStreak = 0; + + double getLuckBonus() { + // 10회 연속 일반 드롭 시 희귀 드롭 확률 +50% + return unluckyStreak >= 10 ? 0.5 : 0.0; + } +} +``` + +--- + +## 14.6 사회적 요소 (향후 확장) + +### 14.6.1 현재 버전 (오프라인) + +| 기능 | 설명 | +|------|------| +| **스크린샷 공유** | 명예의 전당 달성 시 공유 버튼 | +| **기록 내보내기** | 통계를 이미지로 저장 | + +### 14.6.2 향후 버전 (아스키 아레나) + +| 기능 | 설명 | +|------|------| +| **글로벌 랭킹** | 레벨, 사망 횟수, 클리어 시간 순위 | +| **친구 비교** | 친구의 기록과 비교 | +| **PvP 아레나** | 명예의 전당 캐릭터로 대전 | +| **길드 시스템** | 협력 레이드 보스 | + +--- + +# 15. 피해야 할 요소 + +## 15.1 지루함 유발 요소 + +| 피해야 할 것 | 이유 | 대안 | +|-------------|------|------| +| **긴 대기 시간** | 아무 일도 안 일어나면 지루함 | 항상 뭔가 진행 중 표시 | +| **반복 메시지** | 같은 문구 반복은 지루함 | 30+ 가지 변형 메시지 | +| **단조로운 전투** | 항상 같은 패턴 | 랜덤 이벤트, 크리티컬, 콤보 | +| **느린 초반** | 첫 30분이 지루하면 이탈 | 초반 빠른 레벨업 + 튜토리얼 보상 | + +## 15.2 불쾌감 유발 요소 + +| 피해야 할 것 | 이유 | 대안 | +|-------------|------|------| +| **불공정한 즉사** | 예측 불가능한 사망은 스트레스 | HP 보고 대응 가능하도록 | +| **과도한 페널티** | 레벨 다운은 너무 가혹 | 장비 상실만 (레벨/인벤 유지) | +| **강제 광고** | 게임 흐름 방해 | 광고 없음 | +| **과금 유도** | 필수 과금은 불쾌 | 무과금 완전 클리어 가능 | +| **복잡한 UI** | 정보 과다는 혼란 | 핵심 정보만, 상세는 별도 탭 | + +## 15.3 혼란 유발 요소 + +| 피해야 할 것 | 이유 | 대안 | +|-------------|------|------| +| **설명 없는 시스템** | 무엇인지 모르면 답답 | 첫 등장 시 툴팁/튜토리얼 | +| **너무 많은 스탯** | 이해하기 어려움 | 핵심 6개만 강조 | +| **숨겨진 메커니즘** | 어떻게 작동하는지 모름 | 공식 공개 (도움말) | + +--- + +# 16. 핵심 재미 요약 + +``` +┌─────────────────────────────────────────────────────┐ +│ │ +│ 🎮 ASCII Never Die의 5가지 재미 │ +│ │ +│ 1. "조금만 더" - 다음 레벨업이 가까워! │ +│ → 경험치 바, 레벨업 보상 미리보기 │ +│ │ +│ 2. "오 뭐지?" - 예상 못한 전설 아이템! │ +│ → 랜덤 이벤트, 희귀 드롭 연출 │ +│ │ +│ 3. "다시 해보자" - 사망해도 다시 도전! │ +│ → 적절한 페널티, 빠른 복귀 │ +│ │ +│ 4. "나 잘하네" - 통계로 보는 내 성장! │ +│ → 상세 통계, 업적, 마일스톤 │ +│ │ +│ 5. "수집 완료!" - 도감 100% 달성! │ +│ → 몬스터/아이템 도감, 수집 보상 │ +│ │ +└─────────────────────────────────────────────────────┘ +``` + +--- diff --git a/doc/task-phase-01-combat.md b/doc/task-phase-01-combat.md new file mode 100644 index 0000000..f291ebe --- /dev/null +++ b/doc/task-phase-01-combat.md @@ -0,0 +1,122 @@ +# Phase 1: 핵심 전투 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 목표 +Stats가 전투에 실제 영향을 미치도록 전투 계산 로직을 구현한다. + +## 2. 새로운 Stats 구조 + +```dart +class CombatStats { + // 기본 스탯 (캐릭터 고유) + final int str; // 힘: 물리 공격력 보정 + final int con; // 체력: HP, 방어력 보정 + final int dex; // 민첩: 회피율, 크리티컬율, 명중률 + final int intelligence; // 지능: 마법 공격력, MP + final int wis; // 지혜: 마법 방어력, MP 회복 + final int cha; // 매력: 상점 가격, 드롭율 보정 + + // 파생 스탯 (장비 + 기본 스탯으로 계산) + final int atk; // 공격력 + final int def; // 방어력 + final int magAtk; // 마법 공격력 + final int magDef; // 마법 방어력 + final double criRate; // 크리티컬 확률 (0.0 ~ 1.0) + final double criDamage; // 크리티컬 데미지 배율 (1.5 ~ 3.0) + final double evasion; // 회피율 (0.0 ~ 0.5) + final double accuracy; // 명중률 (0.8 ~ 1.0) + final double blockRate; // 방패 방어율 (0.0 ~ 0.4) + final double parryRate; // 무기로 쳐내기 확률 (0.0 ~ 0.3) + + // 자원 + final int hpMax; + final int hpCurrent; + final int mpMax; + final int mpCurrent; +} +``` + +## 3. 전투 계산 공식 + +``` +1. 명중 판정 + 명중 = random() < (공격자.accuracy - 방어자.evasion) + +2. 방어 판정 (명중 시) + 방패 방어 = random() < 방어자.blockRate + 무기 쳐내기 = random() < 방어자.parryRate + +3. 데미지 계산 + 기본 데미지 = 공격자.atk * (1 + random() * 0.2) - 방어자.def * 0.5 + + 크리티컬 판정 = random() < 공격자.criRate + if (크리티컬) 데미지 *= 공격자.criDamage + + if (방패 방어) 데미지 *= 0.3 + if (무기 쳐내기) 데미지 *= 0.5 + + 최종 데미지 = max(1, 데미지) + +4. 전투 결과 + 방어자.hp -= 최종 데미지 + if (방어자.hp <= 0) 전투 종료 +``` + +## 4. 전투 틱 시스템 + +``` +현재: 2초 후 자동 승리 +변경: 매 틱(200ms)마다 공격 교환, HP가 0이 되면 승패 결정 + +전투 흐름: +1. 플레이어 턴 (atk 기반 공격) +2. 몬스터 턴 (몬스터 레벨 기반 공격) +3. HP 체크 +4. 반복 또는 종료 +``` + +### 4.1 공격 속도 시스템 + +```dart +class AttackSpeed { + final int baseDelayMs; // 기본 공격 딜레이 (1000ms) + final double speedModifier; // DEX 기반 속도 배율 + + int get actualDelayMs => (baseDelayMs / speedModifier).round(); +} + +// 공격 속도 계산 +double calculateSpeedModifier(int dex) { + // DEX 10 = 1.0배, DEX 20 = 1.2배, DEX 50 = 1.8배 + return 1.0 + (dex - 10) * 0.02; +} +``` + +| DEX | 공격 속도 배율 | 실제 딜레이 | +|-----|---------------|------------| +| 10 | 1.0x | 1000ms | +| 20 | 1.2x | 833ms | +| 30 | 1.4x | 714ms | +| 50 | 1.8x | 556ms | +| 100 | 2.8x | 357ms | + +**몬스터 공격 속도**: 몬스터 타입별로 고정 (빠름/보통/느림) + +## 5. 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | CombatStats 클래스 추가, Stats 구조 변경 | +| `core/engine/progress_service.dart` | 전투 틱 로직 변경 | +| `core/util/pq_logic.dart` | 전투 계산 함수 추가 | +| `core/engine/combat_calculator.dart` | **신규** - 전투 계산 전담 | + +## 6. 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~400 LOC +- 수정 코드: ~200 LOC + +--- diff --git a/doc/task-phase-02-items.md b/doc/task-phase-02-items.md new file mode 100644 index 0000000..681a979 --- /dev/null +++ b/doc/task-phase-02-items.md @@ -0,0 +1,136 @@ +# Phase 2: 아이템 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +아이템에 스탯 보정치를 부여하고, 가중치 시스템을 도입한다. + +## 아이템 스탯 구조 + +```dart +class ItemStats { + final int atk; // 공격력 보정 + final int def; // 방어력 보정 + final int magAtk; // 마법 공격력 보정 + final int magDef; // 마법 방어력 보정 + final double criRate; // 크리티컬 확률 보정 + final double evasion; // 회피율 보정 + final double blockRate; // 방패 방어율 (방패 전용) + final double parryRate; // 무기 쳐내기 (무기 전용) + + // 추가 효과 + final int hpBonus; + final int mpBonus; + final int strBonus; + final int dexBonus; + // ... 기타 스탯 보너스 +} + +class Equipment { + final String name; + final EquipmentSlot slot; + final int level; // 아이템 레벨 + final int weight; // 가중치 (높을수록 좋은 아이템) + final ItemStats stats; + final ItemRarity rarity; // Common, Uncommon, Rare, Epic, Legendary +} +``` + +## 아이템 가중치 계산 + +``` +가중치 = 기본값 + (레벨 * 10) + (희귀도 보너스) + (스탯 합계) + +희귀도 보너스: +- Common: 0 +- Uncommon: 50 +- Rare: 150 +- Epic: 400 +- Legendary: 1000 +``` + +## 자동 장착 로직 + +``` +1. 인벤토리에서 장착 가능한 아이템 필터링 +2. 슬롯별로 그룹화 +3. 각 슬롯에서 가장 높은 가중치 아이템 선택 +4. 무게 제한 체크 (총 무게 ≤ STR 기반 최대 무게) +5. 현재 장비와 비교하여 더 좋으면 교체 +``` + +### 무게 제한 시스템 + +```dart +class WeightSystem { + /// STR 기반 최대 휴대 가능 무게 + int calculateMaxWeight(int str) { + // 기본 100 + STR당 10 + return 100 + str * 10; + } + + /// 현재 장비 총 무게 + int calculateCurrentWeight(List equipped) { + return equipped.fold(0, (sum, item) => sum + item.weight); + } + + /// 장착 가능 여부 + bool canEquip(Equipment newItem, List current, int str) { + final maxWeight = calculateMaxWeight(str); + final currentWeight = calculateCurrentWeight(current); + final newWeight = currentWeight + newItem.weight; + return newWeight <= maxWeight; + } +} +``` + +| STR | 최대 무게 | 설명 | +|-----|----------|------| +| 10 | 200 | 경장비 + 일부 중장비 | +| 20 | 300 | 대부분의 장비 | +| 30 | 400 | 중장비 풀세트 | +| 50 | 600 | 최중량 장비 | + +**무게 초과 페널티**: 장착 불가 (자동 장착 시 무게 고려) + +## 아이템 생성 공식 + +```dart +/// 아이템 스탯 생성 (레벨 기반) +ItemStats generateItemStats(int level, ItemRarity rarity, EquipmentSlot slot) { + final rarityMultiplier = { + ItemRarity.common: 1.0, + ItemRarity.uncommon: 1.3, + ItemRarity.rare: 1.7, + ItemRarity.epic: 2.2, + ItemRarity.legendary: 3.0, + }[rarity]!; + + final baseValue = (level * 2 * rarityMultiplier).round(); + + // 슬롯별 주요 스탯 결정 + return switch (slot) { + EquipmentSlot.weapon => ItemStats(atk: baseValue, ...), + EquipmentSlot.shield => ItemStats(def: baseValue ~/ 2, blockRate: 0.1, ...), + EquipmentSlot.armor => ItemStats(def: baseValue, ...), + // ... + }; +} +``` + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | Equipment 구조 변경, ItemStats 추가 | +| `core/model/equipment_slot.dart` | 슬롯별 기본 스탯 정의 | +| `core/util/pq_logic.dart` | 아이템 생성 로직 변경 | +| `core/engine/item_service.dart` | **신규** - 아이템 관리 전담 | +| `data/pq_config_data.dart` | 아이템 기본 데이터 확장 | + +## 예상 작업량 +- 예상 파일 수: 5-6개 +- 신규 코드: ~500 LOC +- 수정 코드: ~300 LOC diff --git a/doc/task-phase-03-skills.md b/doc/task-phase-03-skills.md new file mode 100644 index 0000000..4d50843 --- /dev/null +++ b/doc/task-phase-03-skills.md @@ -0,0 +1,90 @@ +# Phase 3: 스킬 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +MP를 소모하여 스킬을 사용하고, 쿨타임을 관리한다. + +## 스킬 구조 + +```dart +class Skill { + final String id; + final String name; + final SkillType type; // attack, heal, buff, debuff + final int mpCost; + final int cooldownMs; // 쿨타임 (밀리초) + final int power; // 스킬 위력 + + // 효과 + final double damageMultiplier; // 공격 스킬: 데미지 배율 + final int healAmount; // 회복 스킬: 회복량 + final BuffEffect? buff; // 버프 효과 +} + +class SkillState { + final String skillId; + final int lastUsedMs; // 마지막 사용 시간 + final int rank; // 스킬 레벨 + + bool isReady(int currentMs) => + currentMs - lastUsedMs >= skill.cooldownMs; +} +``` + +## MP 시스템 + +``` +MP 회복: +- 비전투 시: 50ms당 1 회복 +- 전투 중: 회복 없음 (또는 WIS에 비례하여 느리게 회복) +- 전투 종료: 즉시 전체 회복 + +MP 소모: +- 스킬 사용 시 즉시 차감 +- MP 부족 시 스킬 사용 불가 (일반 공격으로 대체) +``` + +## 스킬 사용 로직 + +``` +자동 스킬 사용 우선순위: +1. HP < 30% → 회복 스킬 (있으면) +2. 보스전 → 가장 강력한 공격 스킬 +3. 일반 전투 → MP 효율이 좋은 스킬 +4. MP < 20% → 일반 공격만 + +수동 개입: +- 현재 버전에서는 자동만 지원 +- 향후 수동 스킬 사용 UI 추가 가능 +``` + +## 스킬 목록 예시 + +| 스킬명 | 타입 | MP | 쿨타임 | 효과 | +|--------|------|-----|--------|------| +| Debug Strike | attack | 10 | 3s | 데미지 150% | +| Memory Leak | attack | 25 | 8s | 데미지 250%, 적 방어력 -20% | +| Hot Reload | heal | 20 | 10s | HP 30% 회복 | +| Safe Mode | buff | 30 | 30s | 방어력 +50%, 10초 지속 | +| Core Dump | attack | 50 | 20s | 데미지 400% | +| Kernel Panic | attack | 100 | 60s | 데미지 800%, 자신 HP -10% | + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | SkillState 추가 | +| `core/model/skill.dart` | **신규** - 스킬 정의 | +| `core/engine/skill_service.dart` | **신규** - 스킬 사용 로직 | +| `core/engine/progress_service.dart` | MP 회복 로직, 스킬 자동 사용 | +| `data/skill_data.dart` | **신규** - 스킬 데이터 | + +## 예상 작업량 +- 예상 파일 수: 5-6개 +- 신규 코드: ~600 LOC +- 수정 코드: ~200 LOC + +--- diff --git a/doc/task-phase-04-death.md b/doc/task-phase-04-death.md new file mode 100644 index 0000000..61cb5b1 --- /dev/null +++ b/doc/task-phase-04-death.md @@ -0,0 +1,122 @@ +# Phase 4: 사망/부활 시스템 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +사망 개념을 도입하고, 페널티 및 부활 메커니즘을 구현한다. + +## 사망 조건 + +``` +사망 = HP <= 0 + +사망 시 처리: +1. 게임 루프 일시 정지 +2. 장착 중인 모든 장비 제거 (인벤토리로 이동하지 않음 - 상실) +3. 인벤토리 아이템 유지 +4. 골드 유지 +5. 경험치 유지 (레벨 다운 없음) +6. 사망 UI 표시 (부활 버튼) +``` + +## 부활 프로세스 + +``` +부활 버튼 클릭 시: +1. HP/MP 전체 회복 +2. 부활 위치로 이동 (안전 지역: 마을) +3. 자동으로 샵 이동 +4. 골드로 구매 가능한 최고 장비 자동 구매 +5. 각 슬롯에 장비 자동 장착 +6. 게임 루프 재개 (퀘스트 진행도 유지) +``` + +### 부활 위치 + +| 상황 | 부활 위치 | 설명 | +|------|----------|------| +| 일반 사망 | 마을 (시작 지점) | 안전 지역, 샵 접근 가능 | +| 보스전 사망 | 보스 던전 입구 | 보스방 직전 | +| 퀘스트 중 사망 | 퀘스트 시작 지점 | 퀘스트 진행도 유지 | + +### 부활 페널티 완화 (선택적) + +| 아이템/스킬 | 효과 | +|------------|------| +| 부활의 부적 (소모품) | 사망 시 장비 1개 보존 | +| 영혼 보호 (패시브) | 사망 시 50% 확률로 장비 1개 보존 | +| 불사 버프 | 사망 시 HP 1로 생존 (1회) | + +## 샵 시스템 + +```dart +class Shop { + /// 현재 레벨에서 구매 가능한 장비 목록 + List getAvailableItems(int playerLevel, int gold); + + /// 최적의 장비 세트 자동 구매 + PurchaseResult autoBuy(int playerLevel, int gold, List emptySlots); +} + +class PurchaseResult { + final List purchased; + final int totalCost; + final int remainingGold; +} +``` + +## 장비 가격 공식 + +``` +기본 가격 = 아이템 레벨 * 50 * 희귀도 배율 + +희귀도 배율: +- Common: 1.0 +- Uncommon: 2.0 +- Rare: 5.0 +- Epic: 15.0 +- Legendary: 50.0 + +판매 가격 = 구매 가격 * 0.3 +``` + +## 사망 UI + +``` +┌─────────────────────────────────────┐ +│ │ +│ YOU DIED │ +│ │ +│ Level 45 버그 헌터 │ +│ │ +│ 사망 원인: 커널 패닉 │ +│ │ +│ ───────────────────────── │ +│ 장비 상실: 7개 │ +│ 보유 골드: 15,420 │ +│ ───────────────────────── │ +│ │ +│ [ 부활하기 ] │ +│ │ +└─────────────────────────────────────┘ +``` + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/game_state.dart` | isDead 플래그, deathInfo 추가 | +| `core/engine/progress_service.dart` | 사망 판정 로직 | +| `core/engine/resurrection_service.dart` | **신규** - 부활 처리 | +| `core/engine/shop_service.dart` | **신규** - 샵 로직 | +| `features/game/widgets/death_overlay.dart` | **신규** - 사망 UI | +| `features/game/game_session_controller.dart` | 사망/부활 상태 관리 | + +## 예상 작업량 +- 예상 파일 수: 6-7개 +- 신규 코드: ~500 LOC +- 수정 코드: ~200 LOC + +--- diff --git a/doc/task-phase-05-race-class.md b/doc/task-phase-05-race-class.md new file mode 100644 index 0000000..88a24af --- /dev/null +++ b/doc/task-phase-05-race-class.md @@ -0,0 +1,66 @@ +# Phase 5: 종족/클래스 특화 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +종족과 클래스에 고유한 능력치 보정과 특수 능력을 부여한다. + +## 종족 특성 + +```dart +class RaceTraits { + final String raceId; + final Map statModifiers; // 스탯 보정 + final List passives; // 패시브 능력 + final double expMultiplier; // 경험치 배율 +} +``` + +| 종족 | STR | CON | DEX | INT | WIS | CHA | 특수 능력 | +|------|-----|-----|-----|-----|-----|-----|----------| +| Byte Human | 0 | 0 | 0 | 0 | 0 | +2 | 경험치 +10% | +| Null Elf | -1 | -1 | +2 | +2 | 0 | 0 | 마법 데미지 +15% | +| Buffer Dwarf | +2 | +2 | -1 | -1 | 0 | 0 | 방어력 +10% | +| Stack Goblin | -1 | -1 | +3 | 0 | 0 | +1 | 크리티컬 확률 +5% | +| Heap Troll | +3 | +3 | -2 | -2 | 0 | 0 | HP +20% | +| Pointer Fairy | -2 | -2 | +2 | +2 | +2 | 0 | MP +20% | +| Coredump Undead | +1 | +2 | -1 | 0 | 0 | -2 | 사망 시 장비 1개 유지 | + +## 클래스 특성 + +```dart +class ClassTraits { + final String classId; + final Map statModifiers; + final List startingSkills; // 시작 스킬 + final List classSkills; // 클래스 전용 스킬 + final EquipmentRestriction restrictions; // 장비 제한 +} +``` + +| 클래스 | 주요 스탯 | 장비 제한 | 특수 능력 | +|--------|----------|----------|----------| +| Bug Hunter | STR/DEX | 전체 가능 | 일반 공격 +20% | +| Debugger Paladin | STR/CON | 중갑, 방패 | 방어력 +15%, 회복력 +10% | +| Compiler Mage | INT/WIS | 경갑, 지팡이 | 마법 데미지 +25% | +| Refactor Monk | DEX/WIS | 경갑, 맨손 | 회피율 +15%, 연속 공격 | +| Pointer Assassin | DEX/STR | 경갑, 단검 | 크리티컬 +20%, 첫 공격 2배 | +| Garbage Collector | CON/STR | 중갑 | HP +30%, 전투 후 HP 10% 회복 | + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/race_traits.dart` | **신규** - 종족 특성 | +| `core/model/class_traits.dart` | **신규** - 클래스 특성 | +| `data/race_data.dart` | **신규** - 종족 데이터 | +| `data/class_data.dart` | **신규** - 클래스 데이터 | +| `core/engine/stat_calculator.dart` | **신규** - 최종 스탯 계산 | +| `features/character/character_creation.dart` | 종족/클래스 선택 UI 개선 | + +## 예상 작업량 +- 예상 파일 수: 6-7개 +- 신규 코드: ~400 LOC +- 수정 코드: ~150 LOC diff --git a/doc/task-phase-06-balance.md b/doc/task-phase-06-balance.md new file mode 100644 index 0000000..596bbe9 --- /dev/null +++ b/doc/task-phase-06-balance.md @@ -0,0 +1,119 @@ +# Phase 6: 밸런싱 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 1. 목표 +레벨 1-100 구간에서 적절한 난이도 곡선을 설계한다. + +## 2. 레벨 구간 설계 + +| 구간 | 레벨 | 특징 | 예상 플레이 시간 | +|------|------|------|-----------------| +| 초반 | 1-20 | 튜토리얼, 기본 시스템 학습 | 1-2시간 | +| 중반 | 21-50 | 본격적인 성장, 다양한 스킬 | 3-5시간 | +| 후반 | 51-80 | 고급 장비, 어려운 몬스터 | 5-8시간 | +| 엔드게임 | 81-100 | 최종 보스, 명예의 전당 | 3-5시간 | + +## 3. 경험치 곡선 + +``` +레벨업 필요 경험치 = 기본값 * (1.15 ^ 레벨) + +기본값 = 100 +레벨 10: 405 exp +레벨 50: 108,366 exp +레벨 100: 11,739,085 exp +``` + +## 4. 몬스터 스탯 스케일링 + +```dart +MonsterStats generateMonster(int level, MonsterType type) { + final baseStats = MonsterStats( + hp: 50 + level * 20 + (level * level / 5).round(), + atk: 5 + level * 3, + def: 2 + level * 2, + exp: 10 + level * 5, + gold: 5 + level * 3, + ); + + return _applyTypeModifier(baseStats, type); +} +``` + +### 4.1 몬스터 타입별 배율 + +| 타입 | HP | ATK | DEF | EXP | GOLD | +|------|-----|-----|-----|-----|------| +| 일반 | 1.0x | 1.0x | 1.0x | 1.0x | 1.0x | +| 정예 | 2.0x | 1.3x | 1.2x | 2.0x | 2.0x | +| 미니보스 | 5.0x | 1.5x | 1.5x | 5.0x | 5.0x | +| 보스 | 10.0x | 2.0x | 2.0x | 15.0x | 10.0x | +| 최종보스 | 20.0x | 2.5x | 2.5x | 50.0x | 30.0x | + +### 4.2 보스 몬스터 특수 스탯 + +```dart +class BossStats extends MonsterStats { + final List phases; + final double enrageThreshold; // 분노 HP % + final double enrageMultiplier; // 분노 시 스탯 배율 + final bool hasShield; // 보호막 여부 + final int shieldAmount; // 보호막 수치 +} +``` + +| 보스 | 특수 능력 | +|------|----------| +| Syntax Error Dragon | 페이즈 3에서 연속 공격 | +| Memory Leak Hydra | HP 30% 이하 시 회복 | +| Buffer Overflow Titan | 보호막 (일정 데미지 흡수) | +| Kernel Panic Archon | 분노 시 스턴 공격 | +| Glitch God | 5페이즈, 각 페이즈별 완전히 다른 패턴 | + +## 5. 사망 확률 목표 + +| 레벨 구간 | 목표 사망 확률 (전투당) | +|----------|----------------------| +| 1-20 | 1-3% | +| 21-50 | 3-5% | +| 51-80 | 5-10% | +| 81-100 | 10-20% | + +## 6. 밸런스 테스트 도구 + +```dart +/// 시뮬레이션으로 밸런스 검증 +class BalanceSimulator { + /// 특정 레벨 구간을 N회 시뮬레이션 + SimulationResult simulate({ + required int startLevel, + required int endLevel, + required int iterations, + }); +} + +class SimulationResult { + final double averageDeaths; + final double averageTimeMinutes; + final double survivalRate; + final List deathCauses; +} +``` + +## 7. 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/util/balance_constants.dart` | **신규** - 밸런스 상수 | +| `core/util/pq_logic.dart` | 경험치/몬스터 스케일링 | +| `data/pq_config_data.dart` | 몬스터 레벨 재조정 | +| `test/balance_test.dart` | **신규** - 밸런스 테스트 | + +## 8. 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~300 LOC +- 수정 코드: ~400 LOC +- 테스트 및 조정: 반복 작업 필요 diff --git a/doc/task-phase-07-content.md b/doc/task-phase-07-content.md new file mode 100644 index 0000000..bc88536 --- /dev/null +++ b/doc/task-phase-07-content.md @@ -0,0 +1,83 @@ +# Phase 7: 콘텐츠 확장 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 + +더 많은 몬스터, 아이템, 애니메이션을 추가한다. + +## 몬스터 확장 + +현재: ~100종 +목표: ~200종 + +추가할 몬스터 카테고리: +- 레벨 81-100 엔드게임 몬스터 (30종) +- 보스 몬스터 (10종, 각 Act 마다) +- 미니 보스 (20종) +- 특수 이벤트 몬스터 (20종) +- 퀘스트 전용 몬스터 (20종) + +## 아이템 확장 + +현재: 이름만 존재 +목표: 스탯이 있는 300+ 아이템 + +카테고리별 추가: +- 무기 (50종): 검, 도끼, 활, 지팡이, 단검 등 +- 방어구 (80종): 투구, 갑옷, 장갑, 부츠, 망토 +- 방패 (30종) +- 악세서리 (50종): 반지, 목걸이, 귀걸이 +- 소모품 (50종): 물약, 스크롤 + +## ASCII 애니메이션 확장 + +### 전투 결과별 애니메이션 + +| 상황 | 애니메이션 | +|------|----------| +| 일반 공격 | 기존 battle_mode | +| 크리티컬 히트 | 화려한 이펙트 | +| 회피 성공 | 살짝 비켜가는 모션 | +| 방패 방어 | 방패 들어올리기 | +| 스킬 사용 | 스킬별 고유 애니메이션 | +| 사망 | 쓰러지는 애니메이션 | +| 레벨업 | 빛나는 이펙트 | + +### 몬스터별 애니메이션 + +```dart +class MonsterAnimation { + final String monsterId; + final List idleFrames; + final List attackFrames; + final List hitFrames; + final List deathFrames; +} +``` + +카테고리별 기본 애니메이션: +- 버그류 (곤충 형태) +- 언데드류 (좀비, 유령) +- 드래곤류 (대형) +- 휴머노이드류 (NPC형) +- 기계류 (로봇, 바이러스) + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `data/pq_config_data.dart` | 몬스터/아이템 데이터 확장 | +| `data/ascii_animation_data.dart` | 애니메이션 프레임 추가 | +| `data/monster_animations.dart` | **신규** - 몬스터별 애니메이션 | +| `features/game/widgets/ascii_animation_card.dart` | 상황별 애니메이션 선택 | + +## 예상 작업량 + +- 예상 파일 수: 4-5개 +- 신규 코드: ~1000 LOC (대부분 데이터) +- 수정 코드: ~200 LOC + +--- diff --git a/doc/task-phase-08-ui.md b/doc/task-phase-08-ui.md new file mode 100644 index 0000000..6e7d5c2 --- /dev/null +++ b/doc/task-phase-08-ui.md @@ -0,0 +1,60 @@ +# Phase 8: UI/UX 개선 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +능력치 변화를 실시간으로 표시하고, 전반적인 UI를 개선한다. + +## 실시간 스탯 변화 표시 + +``` +┌─ Stats ─────────────────┐ +│ HP: 450/500 ████████░░ │ +│ MP: 80/120 ██████░░░░ │ +│ │ +│ ATK: 125 (+15) ▲ │ ← 장비 변경 시 변화량 표시 +│ DEF: 89 (-5) ▼ │ +│ CRI: 12.5% │ +│ EVA: 8.3% │ +└─────────────────────────┘ +``` + +## 전투 로그 + +``` +┌─ Combat Log ────────────────────┐ +│ > 문법 오류를 공격! 45 데미지 │ +│ > 문법 오류의 반격! 12 데미지 │ +│ > 크리티컬! 98 데미지 │ +│ > Debug Strike 사용! 150 데미지 │ +│ > 문법 오류 처치! +25 exp │ +└─────────────────────────────────┘ +``` + +## 알림 시스템 + +| 이벤트 | 표시 방식 | +|--------|----------| +| 레벨업 | 화면 중앙 팝업 + 사운드 | +| 장비 획득 | 우측 하단 토스트 | +| 스탭 변화 | 해당 스탯 옆 애니메이션 | +| 사망 위험 (HP < 20%) | HP 바 깜빡임 | +| 스킬 쿨타임 완료 | 스킬 아이콘 빛남 | + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `features/game/widgets/stats_panel.dart` | 스탯 변화 애니메이션 | +| `features/game/widgets/combat_log.dart` | **신규** - 전투 로그 | +| `features/game/widgets/notification_overlay.dart` | **신규** - 알림 | +| `core/service/notification_service.dart` | **신규** - 알림 관리 | + +## 예상 작업량 +- 예상 파일 수: 5-6개 +- 신규 코드: ~400 LOC +- 수정 코드: ~200 LOC + +--- diff --git a/doc/task-phase-09-story.md b/doc/task-phase-09-story.md new file mode 100644 index 0000000..57bd159 --- /dev/null +++ b/doc/task-phase-09-story.md @@ -0,0 +1,63 @@ +# Phase 9: 스토리/엔딩 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +프롤로그부터 엔딩까지 일관된 스토리를 구성한다. + +## 스토리 구조 + +``` +Act I (레벨 1-20): 각성 +- 프롤로그: 코드의 신으로부터 비전을 받음 +- 마을에서 기본 훈련 +- 첫 번째 던전: 버그 둥지 +- Act I 보스: Syntax Error Dragon + +Act II (레벨 21-40): 성장 +- 디버거 기사단 가입 +- 손상된 네트워크 탐험 +- 배신자 발견 +- Act II 보스: Memory Leak Hydra + +Act III (레벨 41-60): 시련 +- 널 왕국 진입 +- 고대 컴파일러의 시험 +- 동료의 희생 +- Act III 보스: Buffer Overflow Titan + +Act IV (레벨 61-80): 결전 +- 글리치 신의 성채 침입 +- 최후의 동맹 결성 +- Act IV 보스: Kernel Panic Archon + +Act V (레벨 81-100): 종말 +- 글리치 신과의 최종 대결 +- 다중 페이즈 보스전 +- 엔딩: 시스템 재부팅, 평화 회복 +``` + +## 시네마틱 개선 + +각 Act 전환 시: +- 전용 시네마틱 텍스트 (5-10개 단계) +- ASCII 아트 일러스트 +- 분위기에 맞는 색상 테마 + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `data/story_data.dart` | **신규** - 스토리 텍스트 | +| `data/game_text_l10n.dart` | 시네마틱 텍스트 확장 | +| `core/engine/story_service.dart` | **신규** - 스토리 진행 관리 | +| `features/game/widgets/cinematic_view.dart` | **신규** - 시네마틱 UI | + +## 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~600 LOC (대부분 텍스트) +- 수정 코드: ~100 LOC + +--- diff --git a/doc/task-phase-10-hall.md b/doc/task-phase-10-hall.md new file mode 100644 index 0000000..804047f --- /dev/null +++ b/doc/task-phase-10-hall.md @@ -0,0 +1,83 @@ +# Phase 10: 명예의 전당 + +> 메인 문서: [game-system-overhaul-index.md](game-system-overhaul-index.md) + +--- + +## 목표 +게임 클리어 시 캐릭터를 명예의 전당에 등재한다. + +## 클리어 조건 + +``` +클리어 = 레벨 100 달성 + 글리치 신 처치 +``` + +## 명예의 전당 데이터 + +```dart +class HallOfFameEntry { + final String id; + final String characterName; + final String race; + final String klass; + final int level; + final Duration totalPlayTime; + final int totalDeaths; + final int monstersKilled; + final DateTime clearedAt; + + // 향후 아스키 아레나용 + final CombatStats finalStats; + final List finalEquipment; + final List skills; +} +``` + +## 명예의 전당 UI + +``` +╔═══════════════════════════════════════════════════╗ +║ 명예의 전당 ║ +╠═══════════════════════════════════════════════════╣ +║ ║ +║ 1. 버퍼 드워프 디버거 성기사 "CodeSlayer" ║ +║ Lv.100 | 12시간 34분 | 사망 3회 ║ +║ 2024.03.15 ║ +║ ║ +║ 2. 널 엘프 컴파일러 마법사 "NullMaster" ║ +║ Lv.100 | 15시간 22분 | 사망 7회 ║ +║ 2024.03.10 ║ +║ ║ +║ 3. 스택 고블린 포인터 암살자 "StackKiller" ║ +║ Lv.100 | 18시간 05분 | 사망 12회 ║ +║ 2024.03.08 ║ +║ ║ +╚═══════════════════════════════════════════════════╝ +``` + +## 클리어 후 처리 + +``` +1. 축하 시네마틱 표시 +2. 명예의 전당 등재 +3. 통계 표시 (플레이 시간, 사망 횟수, 처치 몬스터 등) +4. "새 게임 시작" 버튼 +5. 기존 캐릭터 데이터는 명예의 전당에만 보존 +``` + +## 수정 대상 파일 + +| 파일 | 변경 내용 | +|------|----------| +| `core/model/hall_of_fame.dart` | **신규** - 명예의 전당 모델 | +| `core/storage/hall_of_fame_storage.dart` | **신규** - 저장/로드 | +| `features/hall_of_fame/hall_of_fame_screen.dart` | **신규** - UI | +| `features/game/game_session_controller.dart` | 클리어 처리 | + +## 예상 작업량 +- 예상 파일 수: 4-5개 +- 신규 코드: ~400 LOC +- 수정 코드: ~100 LOC + +---