Phase 2 미구현 시스템 — 구현 계획

v1.0 | 2026-03-31

Phase 1~3 그래픽 정책: 모든 비주얼은 placeholder(텍스트 라벨 + _draw() 기본도형)로 구현. 실제 픽셀아트 에셋은 Phase 4에서 교체.

1. 포획 시스템

설계 문서: docs/game/system/capture.md 적 데이터: game/data/enemies.json (capture 블록 이미 존재)

1-1. 개요

봉인 부적 패시브 장착 → 적 처치 시 확률 포획 → 도감 등록 → 소환수 장착/발동
enemies.json에 보스 capture 데이터는 이미 존재. 일반 적 capture 필드 추가 필요

1-2. 데이터 변경

enemies.json — 일반 적에 capture 블록 추가

각 일반 적에 다음 필드 추가 (보스는 이미 있음):

"imp": {
  ... (기존 필드),
  "capture": {
    "grade": "F",
    "base_chance": 15,
    "summon_id": "imp_shield",
    "summon_effect": "shield",
    "summon_duration": 5.0,
    "summon_description": "아군 방패 (5초간 투사체 흡수)"
  }
}

전체 일반 적 capture 데이터:

적	grade	base_chance	summon_id	summon_effect	duration
imp	F	15	imp_shield	shield	5.0
dokkaebi_fire	F	12	fire_screen	screen_damage	2.0
egg_ghost	E	10	egg_vision	vision_expand	10.0
ghost_maiden	D	8	maiden_fear	fear	3.0
skeleton	D	8	skeleton_shield	shield	5.0
gangsi	C	5	gangsi_wall	invincible_wall	3.0
reaper	B	3	reaper_execute	execute	1.0
gumiho	A	2	fox_charm_small	charm	5.0
daegwi	A	2	daegwi_blast	screen_damage	2.0

game/data/capture_codex.json (신규)

도감 달성 보상 및 천장 시스템 설정 데이터:

{
  "codex": {
    "total_entries": 12,
    "rewards": {
      "30": { "threshold": 4, "effect": "capture_chance_bonus", "value": 5 },
      "50": { "threshold": 6, "effect": "summon_duration_bonus", "value": 3.0 },
      "80": { "threshold": 10, "effect": "summon_power_multiplier", "value": 1.5 },
      "100": { "threshold": 12, "effect": "unlock_gumiho_npc", "value": true }
    }
  },
  "pity": {
    "boss_pity_increment": 10,
    "boss_pity_max": 70,
    "normal_pity": false
  },
  "seal_talisman_bonus_per_level": 2,
  "seal_talisman_max_level": 5,
  "shrine_capture_bonus_per_level": 5,
  "shrine_capture_max_level": 5
}

1-3. 신규 파일 목록

파일 경로	역할
`game/src/systems/capture_system.gd`	Autoload 싱글톤. 포획 판정/도감/천장 관리
`game/src/systems/summon_system.gd`	소환수 장착/발동/쿨다운 관리
`game/data/capture_codex.json`	도감 보상 + 천장 설정 데이터
`game/src/ui/capture_popup.gd`	포획 성공/실패 팝업 UI
`game/src/ui/summon_button.gd`	HUD 소환수 발동 버튼
`game/test/systems/test_capture_system.gd`	GdUnit4 테스트
`game/test/systems/test_summon_system.gd`	GdUnit4 테스트

1-4. 기존 파일 변경

파일	변경 내용
`game/data/enemies.json`	일반 적 9종에 capture 블록 추가
`game/src/autoloads/data_manager.gd`	`_file_map`에 `"capture_codex": "capture_codex.json"` 추가 + `get_capture_codex()` 메서드
`game/src/autoloads/event_bus.gd`	시그널 추가: `enemy_captured(enemy_id, position)`, `capture_failed(enemy_id, position)`, `boss_capture_attempt(boss_id)`, `summon_activated(summon_id)`
`game/src/enemies/enemy_base.gd`	`_on_death()` 에서 봉인 부적 보유 시 `CaptureSystem.try_capture()` 호출
`game/src/systems/boss_spawn_system.gd`	보스 HP 10% 이하 시 `EventBus.boss_capture_attempt` emit
`game/src/ui/hud.gd`	소환수 버튼 영역(우하단 24x24) 추가
`project.godot`	Autoload 등록: CaptureSystem, SummonSystem

1-5. capture_system.gd 핵심 구조

CaptureSystem (Autoload)
├── var codex: Dictionary = {}          # {enemy_id: bool} 포획 여부
├── var boss_pity: Dictionary = {}      # {boss_id: int} 천장 누적
├── var seal_talisman_level: int = 0    # 봉인 부적 레벨
│
├── func try_capture(enemy_id, enemy_data, position) -> bool
│   ├── 봉인 부적 미보유 → return false
│   ├── 최종 확률 계산 (기본 + 부적레벨 + 사당 + 도감보상 + 천장)
│   ├── randf() < 확률 → 성공 → _register_codex() + emit captured
│   └── 실패 → emit failed (보스는 천장 누적)
│
├── func try_boss_capture(boss_id, boss_data, position) -> bool
│   ├── 보스 전용 연출 로직 (슬로우 등은 Coder가 구현)
│   └── 성공/실패 + 천장 업데이트
│
├── func get_codex_completion() -> float
├── func get_codex_rewards() -> Array[Dictionary]
└── func _calculate_capture_chance(base, enemy_grade) -> float

1-6. summon_system.gd 핵심 구조

SummonSystem (Autoload)
├── var equipped_summons: Array[String] = []  # 장착 소환수 ID 목록
├── var max_slots: int = 1                     # 사당 업그레이드로 최대 6
├── var used_this_run: Array[String] = []       # 이번 판 사용 여부
│
├── func equip_summon(summon_id) -> bool
├── func activate_summon(slot_index: int) -> void
│   ├── 이미 사용 → return
│   ├── 소환수 효과 발동 (효과별 분기)
│   └── used_this_run에 추가
│
├── func reset_for_new_run() -> void
└── func get_available_summons() -> Array[String]

1-7. placeholder 비주얼

요소	placeholder 구현
포획 성공 이펙트	적색 원(draw_circle) + "포획!" 텍스트 Label
포획 실패 이펙트	회색 원 + "실패..." 텍스트
보스 봉인 연출	화면 슬로우(Engine.time_scale=0.3) + "봉인!" 대형 텍스트
소환수 발동	소환수 이름 텍스트 + 효과 범위 원 표시
HUD 소환수 버튼	ColorRect(24x24, 적색) + 텍스트("召")
도감 UI	6x2 그리드 ColorRect + 적 이름/??/체크 텍스트

1-8. 구현 순서

enemies.json에 capture 블록 추가 + capture_codex.json 생성
CaptureSystem 싱글톤 (포획 판정 + 도감)
enemy_base.gd 사망 시 포획 판정 연결
보스 포획 (HP 10% 트리거 + 슬로우 연출)
SummonSystem (장착 + 발동)
HUD 소환수 버튼
포획 팝업 UI
GdUnit4 테스트

2. 저주 시스템

설계 문서: docs/game/system/curses.md 데이터: game/data/curses.json (미생성 — 신규 생성 필요)

2-1. 개요

판 시작 전 0~3개 저주 선택 → 난이도 상승 + 혼백 배율 증가
6종 저주, 판 수 기반 점진적 해금
curses.json 데이터 파일 필요

2-2. 데이터 — game/data/curses.json (신규)

{
  "_meta": {
    "version": "1.0.0",
    "description": "저주 6종 데이터. 판 시작 전 선택, 혼백 배율 곱연산."
  },
  "max_active_curses": 3,
  "base_honbaek_per_clear": 10,
  "base_honbaek_per_death": 5,
  "ilv_bonus_per_curse": 0.5,

  "curses": {
    "blood_moon": {
      "name_kr": "혈월",
      "description": "모든 적 HP +50%",
      "icon_text": "月",
      "honbaek_multiplier": 1.5,
      "difficulty_stars": 3,
      "unlock_condition": "runs_cleared",
      "unlock_value": 10,
      "effect": {
        "type": "enemy_hp_multiplier",
        "value": 1.5,
        "target": "all_enemies"
      },
      "visual_effect": "red_moon_overlay"
    },
    "ghost_eye": {
      "name_kr": "귀안",
      "description": "시야 반경 -30%",
      "icon_text": "眼",
      "honbaek_multiplier": 1.3,
      "difficulty_stars": 2,
      "unlock_condition": "runs_cleared",
      "unlock_value": 10,
      "effect": {
        "type": "vision_reduction",
        "value": 0.3,
        "target": "player"
      },
      "visual_effect": "vignette_overlay"
    },
    "seal": {
      "name_kr": "봉인",
      "description": "무기 슬롯 -1 (최대 3개)",
      "icon_text": "封",
      "honbaek_multiplier": 1.5,
      "difficulty_stars": 4,
      "unlock_condition": "runs_cleared",
      "unlock_value": 15,
      "effect": {
        "type": "weapon_slot_reduction",
        "value": 1,
        "target": "player"
      },
      "visual_effect": "weapon_slot_x"
    },
    "regression": {
      "name_kr": "역행",
      "description": "경험치 -30%",
      "icon_text": "逆",
      "honbaek_multiplier": 1.4,
      "difficulty_stars": 3,
      "unlock_condition": "runs_cleared",
      "unlock_value": 15,
      "effect": {
        "type": "xp_reduction",
        "value": 0.3,
        "target": "player_and_soul"
      },
      "visual_effect": "xp_bar_gray"
    },
    "impermanence": {
      "name_kr": "무상",
      "description": "레벨업 선택지 3->2",
      "icon_text": "無",
      "honbaek_multiplier": 1.3,
      "difficulty_stars": 2,
      "unlock_condition": "runs_cleared",
      "unlock_value": 20,
      "effect": {
        "type": "levelup_choice_reduction",
        "value": 1,
        "target": "levelup_system"
      },
      "visual_effect": "none"
    },
    "vengeful_spirit": {
      "name_kr": "원혼",
      "description": "죽은 적 30% 확률 부활 (HP 50%)",
      "icon_text": "怨",
      "honbaek_multiplier": 2.0,
      "difficulty_stars": 5,
      "unlock_condition": "all_curses_used_once",
      "unlock_value": true,
      "effect": {
        "type": "enemy_revive",
        "revive_chance": 0.3,
        "revive_hp_ratio": 0.5,
        "target": "all_enemies"
      },
      "visual_effect": "white_smoke_on_death"
    }
  },

  "hidden_reward": {
    "condition": "all_curses_unlocked_plus_3curse_clear",
    "reward": "unlock_character_amhaeng_eosa"
  }
}

2-3. 신규 파일 목록

파일 경로	역할
`game/data/curses.json`	저주 6종 데이터
`game/src/systems/curse_system.gd`	Autoload 싱글톤. 저주 해금/선택/효과 적용
`game/src/ui/curse_selection_screen.gd`	판 시작 전 저주 선택 UI
`game/test/systems/test_curse_system.gd`	GdUnit4 테스트

2-4. 기존 파일 변경

파일	변경 내용
`game/src/autoloads/data_manager.gd`	`_file_map`에 `"curses": "curses.json"` 추가 + `get_curse(id)`, `get_all_curses()` 메서드
`game/src/autoloads/event_bus.gd`	시그널 추가: `curses_selected(curse_ids: Array)`, `honbaek_earned(amount: int, multiplier: float)`
`game/src/autoloads/game_manager.gd`	`run_data["curses"]` 이미 존재. `run_data`에 `"honbaek_multiplier": 1.0` 추가
`game/src/systems/level_up_system.gd`	저주 "무상" 활성 시 선택지 3→2 반영
`game/src/enemies/enemy_base.gd`	저주 "혈월" 적용: 스폰 시 HP *= 1.5
`game/src/enemies/enemy_base.gd`	저주 "원혼" 적용: 사망 시 30% 확률 부활 (HP 50%)
`game/src/systems/game_world.gd`	저주 "귀안" 시야 축소 비네팅 오버레이
`game/src/ui/hud.gd`	우상단에 활성 저주 아이콘 표시 (최대 3개)
`project.godot`	Autoload 등록: CurseSystem

2-5. curse_system.gd 핵심 구조

CurseSystem (Autoload)
├── var unlocked_curses: Array[String] = []     # 해금된 저주 ID
├── var active_curses: Array[String] = []        # 현재 판 활성 저주
├── var curse_usage_history: Dictionary = {}     # {curse_id: int} 사용 횟수
├── var total_runs_cleared: int = 0              # 총 클리어 판 수
│
├── func check_unlocks() -> Array[String]        # 조건 만족 저주 해금
├── func select_curses(curse_ids: Array) -> void # 판 시작 전 선택
│   ├── 최대 3개 검증
│   └── active_curses 설정 + emit curses_selected
│
├── func get_honbaek_multiplier() -> float       # 곱연산 배율 반환
├── func get_ilv_bonus() -> float                # 저주 수 * 0.5
│
├── func is_curse_active(curse_id: String) -> bool
├── func apply_enemy_hp_modifier(base_hp: float) -> float  # 혈월
├── func get_levelup_choices() -> int            # 무상: 3→2
├── func get_xp_multiplier() -> float            # 역행: 0.7
├── func should_enemy_revive() -> bool           # 원혼: 30%
├── func get_weapon_slot_count() -> int          # 봉인: 4→3
└── func get_vision_reduction() -> float         # 귀안: 0.3

2-6. 저주 선택 UI (curse_selection_screen.gd)

placeholder 구현:

CanvasLayer (거점→스테이지 사이 표시)
6개 카드 (3x2 그리드, ColorRect + 텍스트)
잠금 카드: 회색 + 해금 조건 텍스트
선택 카드: 황금 테두리 + "저주 X/3" 카운터
우측: 현재 혼백 배수 텍스트
"출격!" / "저주 없이 시작" 버튼

2-7. 저주별 구현 난이도

저주	구현 복잡도	설명
혈월	낮음	enemy_base 스폰 시 HP 곱
귀안	중간	비네팅 셰이더/오버레이
봉인	낮음	무기 슬롯 상수 변경
역행	낮음	XP 획득 곱
무상	낮음	level_up_system 선택지 수 변경
원혼	중간	적 사망→부활 로직 + ICD

2-8. 구현 순서

curses.json 데이터 파일 생성
CurseSystem 싱글톤 (해금/선택/효과 조회)
curse_selection_screen.gd (저주 선택 UI)
각 저주 효과를 기존 시스템에 연결:
- 혈월 → enemy_base.gd
- 봉인 → game_manager.gd / weapon slot
- 역행 → XP 시스템
- 무상 → level_up_system.gd
- 귀안 → game_world.gd (비네팅)
- 원혼 → enemy_base.gd (부활)
HUD 저주 아이콘 표시
GdUnit4 테스트

3. NPC/거점 시스템

설계 문서: docs/game/system/npc-hub.md 기존 코드: game/src/hub/hub_screen.gd (스캐폴딩만)

3-1. 개요

현재 hub_screen.gd에는 NPC 카드 4종이 "(준비 중)" 상태로 표시. 이를 실제 상호작용 가능한 NPC 시스템으로 확장.

Phase 2 구현 범위:

할멈 (힌트 대사) — 간소화: 랜덤 대사 표시
대장장이 (장비 강화/재련) — 핵심 기능
저승사자 (도감 열람) — 포획 시스템 연동
사당 (영구 업그레이드) — 핵심 기능
구미호 (히든) — Phase 3으로 연기

3-2. 신규 파일 목록

파일 경로	역할
`game/src/hub/npc_dialog.gd`	NPC 대화 프레임 (공통)
`game/src/hub/npc_grandma.gd`	할멈 — 힌트 대사
`game/src/hub/npc_blacksmith.gd`	대장장이 — 장비 강화/재련
`game/src/hub/npc_reaper.gd`	저승사자 — 도감 열람
`game/src/hub/npc_shrine.gd`	사당 — 영구 업그레이드
`game/src/hub/stage_select_screen.gd`	스테이지 선택 화면
`game/data/shrine.json`	사당 업그레이드 11종 데이터
`game/data/npc_dialogs.json`	할멈 대사 데이터
`game/src/autoloads/save_manager.gd`	영구 데이터 저장/로드 (엽전, 혼백, 사당, 도감, 저주 해금)
`game/test/hub/test_npc_shrine.gd`	GdUnit4 테스트
`game/test/hub/test_npc_blacksmith.gd`	GdUnit4 테스트

3-3. 기존 파일 변경

파일	변경 내용
`game/src/hub/hub_screen.gd`	NPC 카드 클릭 → 각 NPC 씬/UI 진입. "(준비 중)" 제거. 하단에 엽전/혼백 표시. "스테이지 시작" → 스테이지 선택으로 변경. 영혼 선택/저주 선택 플로우 추가
`game/src/autoloads/data_manager.gd`	`_file_map`에 `"shrine": "shrine.json"`, `"npc_dialogs": "npc_dialogs.json"` 추가
`game/src/autoloads/event_bus.gd`	시그널 추가: `npc_interacted(npc_id)`, `equipment_upgraded(result)`, `shrine_upgraded(upgrade_id, new_level)`, `stage_selected(stage_id)`, `soul_selected(soul_id)`
`game/src/autoloads/game_manager.gd`	State.HUB 시 거점 데이터 로드. `run_data`에 `"selected_stage": ""` 추가
`project.godot`	Autoload 등록: SaveManager

3-4. game/data/shrine.json (신규)

{
  "_meta": { "version": "1.0.0", "description": "사당 영구 업그레이드 11종" },
  "upgrades": {
    "health":         { "name_kr": "체력",       "icon_text": "体", "max_level": 10, "effect_per_level": 5,     "unit": "HP",  "cost_formula": "20 * level" },
    "attack":         { "name_kr": "공격력",     "icon_text": "攻", "max_level": 10, "effect_per_level": 3,     "unit": "%",   "cost_formula": "25 * level" },
    "move_speed":     { "name_kr": "이동속도",   "icon_text": "速", "max_level": 10, "effect_per_level": 2,     "unit": "%",   "cost_formula": "20 * level" },
    "cooldown":       { "name_kr": "쿨다운",     "icon_text": "冷", "max_level": 10, "effect_per_level": -2,    "unit": "%",   "cost_formula": "30 * level" },
    "xp_gain":        { "name_kr": "경험치",     "icon_text": "経", "max_level": 10, "effect_per_level": 5,     "unit": "%",   "cost_formula": "15 * level" },
    "coin_gain":      { "name_kr": "엽전 획득",  "icon_text": "銭", "max_level": 10, "effect_per_level": 5,     "unit": "%",   "cost_formula": "20 * level" },
    "revive":         { "name_kr": "부활",       "icon_text": "復", "max_level": 3,  "effect_per_level": 1,     "unit": "회",  "cost_formula": "100 * level" },
    "start_weapon":   { "name_kr": "시작 무기",  "icon_text": "武", "max_level": 1,  "effect_per_level": 1,     "unit": "슬롯", "cost_formula": "500" },
    "capture_slot":   { "name_kr": "포획 용량",  "icon_text": "捕", "max_level": 5,  "effect_per_level": 1,     "unit": "슬롯", "cost_formula": "50 * level" },
    "yinyang_stable": { "name_kr": "음양 안정",  "icon_text": "陰", "max_level": 5,  "effect_per_level": -0.1,  "unit": "/초", "cost_formula": "40 * level" },
    "capture_boost":  { "name_kr": "포획 강화",  "icon_text": "封", "max_level": 5,  "effect_per_level": 5,     "unit": "%",   "cost_formula": "60 * level" }
  }
}

3-5. save_manager.gd 핵심 구조

SaveManager (Autoload)
├── const SAVE_PATH = "user://save_data.json"
├── var data: Dictionary = {}
│   ├── "coins": int              # 엽전
│   ├── "honbaek": int            # 혼백
│   ├── "shrine_levels": {}       # {upgrade_id: int}
│   ├── "codex": {}               # {enemy_id: bool}
│   ├── "boss_pity": {}           # {boss_id: int}
│   ├── "curse_unlocks": []       # 해금된 저주 ID
│   ├── "curse_usage": {}         # {curse_id: int}
│   ├── "runs_cleared": int
│   ├── "runs_total": int
│   ├── "equipped_summons": []
│   └── "character_unlocks": []
│
├── func save() -> void
├── func load_save() -> void
├── func get_coins() -> int
├── func spend_coins(amount: int) -> bool
├── func add_coins(amount: int) -> void
├── func get_honbaek() -> int
├── func add_honbaek(amount: int) -> void
├── func spend_honbaek(amount: int) -> bool
├── func get_shrine_level(id: String) -> int
├── func upgrade_shrine(id: String) -> bool
└── func reset() -> void   # 디버그용

3-6. 거점 UI 플로우 (hub_screen.gd 리팩터)

hub_screen.gd 리팩터:
1. NPC 카드 클릭 → _on_npc_clicked(npc_name)
2. npc_name에 따라 해당 NPC UI 표시:
   - "할멈" → npc_grandma.gd (대화 패널)
   - "대장장이" → npc_blacksmith.gd (강화/재련 패널)
   - "저승사자" → npc_reaper.gd (도감 패널)
   - "사당" → npc_shrine.gd (업그레이드 패널)
3. "스테이지 시작" → stage_select_screen.gd
   → 영혼 선택 (souls.json 기반)
   → 저주 선택 (curse_selection_screen.gd)
   → 인게임 진입
4. 하단 상태바: 엽전/혼백 실시간 표시

3-7. 판 종료 → 거점 플로우

1. game_over(is_victory) emit
2. settlement_screen.gd (신규 또는 기존 확장):
   - 생존시간, 처치수, 레벨, 엽전, 혼백, 포획 결과 표시
   - 장비 일괄 처리 (전부 수령/일괄 분해)
   - "거점으로" 버튼 → hub_screen 전환
3. SaveManager.save() 호출

3-8. placeholder 비주얼

요소	placeholder 구현
NPC 스프라이트	기존 텍스트 아이콘 유지 ([할멈], [대장], [사자], [사당])
NPC 대화 프레임	ColorRect(어두운 배경) + Label(대사 텍스트)
대장장이 UI	세로 리스트: 장비 이름 텍스트 + 비용 + "강화"/"재련" 버튼
사당 UI	세로 리스트: 업그레이드 이름 + 프로그레스 바(ColorRect) + 비용 텍스트
도감 UI	6x2 그리드 ColorRect + 텍스트
스테이지 선택	세로 리스트: 스테이지 이름 + 해금 상태 + iLv 표시

3-9. 구현 순서

SaveManager 싱글톤 (영구 데이터 저장/로드)
shrine.json + npc_dialogs.json 데이터 생성
hub_screen.gd 리팩터 (NPC 클릭 → UI 진입)
npc_shrine.gd (사당 — 영구 업그레이드, 가장 중요)
npc_blacksmith.gd (대장장이 — 강화/재련)
npc_reaper.gd (저승사자 — 도감)
npc_grandma.gd (할멈 — 대사)
stage_select_screen.gd (스테이지 선택)
거점→스테이지 플로우 연결 (영혼 선택 → 저주 선택 → 인게임)
판 종료 정산 화면 확장
GdUnit4 테스트

4. 추가 스테이지 2종

설계 문서: stage-02-bamboo.md, stage-03-temple.md 데이터: game/data/stages.json (bamboo_forest, abandoned_temple 스켈레톤 존재)

4-1. 개요

stages.json에 bamboo_forest와 abandoned_temple 엔트리가 이미 존재하나 obstacles.types가 비어있고 visual도 미완성. 웨이브 데이터(wave_11~wave_18)도 미생성.

4-2. 데이터 변경

stages.json — bamboo_forest 완성

"bamboo_forest": {
  "name_kr": "대나무 숲",
  "duration": 1200,
  "terrain": "mountain",
  "ilv": 2,
  "boss_times": [480, 960],
  "mid_boss": "ghost_king",
  "mid_boss_health_override": 800,
  "final_boss": "thousand_fox",
  "dawn_wave_time": 960,
  "dawn_wave_multiplier": 2.0,
  "favorable_soul": "jeon_woochi",
  "unfavorable_soul": "hwangjini",
  "unlock_condition": { "type": "stage_cleared", "stage_id": "hanyang_street" },

  "visual": {
    "ground_color": "#1A2E1A",
    "ground_color_alt": "#162A16",
    "grid_color": "#2A442A",
    "grid_dot_color": "#3A553A",
    "ambient_light": "#8BA0C0",
    "dawn_tint": "#C0D4FF"
  },

  "obstacles": {
    "density": 0.6,
    "min_spacing": 80,
    "max_per_chunk": 4,
    "spawn_exclusion_radius": 96,
    "types": [
      { "id": "bamboo_cluster", "name_kr": "대나무 군락", "size": [32, 48], "color": "#2E8B57", "weight": 30, "blocks_movement": true, "destructible": false },
      { "id": "rock_forest", "name_kr": "바위", "size": [24, 24], "color": "#555555", "weight": 20, "blocks_movement": true, "destructible": false },
      { "id": "dokkaebi_lantern", "name_kr": "도깨비 등불", "size": [16, 16], "color": "#2E86AB", "glow_radius": 32, "glow_color": "#4EC8FF", "weight": 15, "blocks_movement": false, "destructible": false },
      { "id": "old_tree", "name_kr": "고목", "size": [48, 64], "color": "#4A3728", "weight": 15, "blocks_movement": true, "destructible": false },
      { "id": "stream", "name_kr": "개울", "size": [64, 16], "color": "#3A7CA5", "weight": 20, "blocks_movement": false, "destructible": false, "special": "water_terrain" }
    ]
  },

  "special_zones": {
    "bamboo_dense": {
      "description": "대나무 밀집 구간",
      "speed_modifier": -0.2,
      "vision_modifier": -0.15,
      "spawn_chance_per_chunk": 0.3
    }
  }
}

stages.json — abandoned_temple 완성

"abandoned_temple": {
  "name_kr": "폐사찰",
  "duration": 1500,
  "terrain": "temple",
  "ilv": 3,
  "boss_times": [720, 1260],
  "mid_boss": "ghost_king",
  "mid_boss_health_override": 1500,
  "final_boss": "ghost_king",
  "final_boss_health_override": 3000,
  "dawn_wave_time": 1260,
  "dawn_wave_multiplier": 2.5,
  "favorable_soul": "jeon_woochi",
  "unfavorable_soul": "yi_sun_sin",
  "unlock_condition": { "type": "stage_cleared", "stage_id": "bamboo_forest" },

  "visual": {
    "ground_color": "#1A1A2E",
    "ground_color_alt": "#16162A",
    "grid_color": "#2A2A3E",
    "grid_dot_color": "#3A3A4E",
    "ambient_light": "#C0B8A0",
    "dawn_tint": "#F0E6D3"
  },

  "obstacles": {
    "density": 0.5,
    "min_spacing": 80,
    "max_per_chunk": 3,
    "spawn_exclusion_radius": 128,
    "types": [
      { "id": "stone_lantern", "name_kr": "석등", "size": [16, 32], "color": "#8B8B6B", "glow_radius": 64, "glow_color": "#FFE4B5", "weight": 20, "blocks_movement": true, "destructible": false, "special": "clears_fog" },
      { "id": "stone_stairs", "name_kr": "돌계단", "size": [48, 16], "color": "#6B6B5B", "weight": 15, "blocks_movement": false, "destructible": false },
      { "id": "broken_pillar", "name_kr": "무너진 기둥", "size": [32, 16], "color": "#7B7B6B", "weight": 15, "blocks_movement": true, "destructible": false },
      { "id": "budo_tower", "name_kr": "부도탑", "size": [16, 48], "color": "#9B9B7B", "weight": 10, "blocks_movement": true, "destructible": false },
      { "id": "buddha_remains", "name_kr": "불상 잔해", "size": [32, 32], "color": "#A0956B", "weight": 10, "blocks_movement": true, "destructible": false, "special": "random_buff" },
      { "id": "mossy_rock", "name_kr": "이끼 바위", "size": [24, 24], "color": "#4A6B4A", "weight": 20, "blocks_movement": true, "destructible": false }
    ]
  },

  "special_zones": {
    "fog_zone": {
      "description": "안개 구간",
      "vision_modifier": -0.4,
      "enter_delay": 3.0,
      "exit_delay": 2.0,
      "spawn_chance_per_chunk": 0.4
    }
  },

  "buddha_remains_effects": [
    { "chance": 0.4, "effect": "attack_bonus", "value": 0.10, "duration": 5.0 },
    { "chance": 0.3, "effect": "speed_bonus", "value": 0.15, "duration": 5.0 },
    { "chance": 0.2, "effect": "damage", "value": 5, "duration": 0.0 },
    { "chance": 0.1, "effect": "resonance_bonus", "value": 10, "duration": 0.0 }
  ]
}

4-3. 웨이브 데이터 — game/data/waves/

대나무 숲 (wave_11~~wave_14)과 폐사찰 (wave_15~~wave_18)은 기존 wave_01~10 형식을 따름.

대나무 숲 웨이브 (20분 = 1200초):

파일	시간대	주요 적	spawn_rate_mult
wave_11.json	0~180초	imp(3) + dokkaebi_fire(2)	1.0
wave_12.json	180~480초	dokkaebi_fire(3) + ghost_maiden(1) + egg_ghost(3)	1.3
wave_13.json	480~780초	skeleton(2) + gangsi(2) + ghost_maiden(1) + gumiho(1)	1.5
wave_14.json	780~960초	reaper(1) + daegwi(1) + gumiho(1) + 전체혼합	2.0

폐사찰 웨이브 (25분 = 1500초):

파일	시간대	주요 적	spawn_rate_mult
wave_15.json	0~240초	imp(2) + skeleton(2)	1.0
wave_16.json	240~720초	ghost_maiden(2) + gangsi(2) + egg_ghost(3)	1.4
wave_17.json	720~1260초	reaper(1) + dokkaebi_fire(3) + gumiho(1) + daegwi(1)	1.8
wave_18.json	1260~1500초	전체 혼합 (엘리트 포함)	2.5

4-4. 신규 파일 목록

파일 경로	역할
`game/data/waves/wave_11.json` ~ `wave_14.json`	대나무 숲 웨이브 4개
`game/data/waves/wave_15.json` ~ `wave_18.json`	폐사찰 웨이브 4개

4-5. 기존 파일 변경

파일	변경 내용
`game/data/stages.json`	bamboo_forest, abandoned_temple 엔트리 완성 (visual, obstacles, special_zones)
`game/src/systems/stage_manager.gd`	`mid_boss` 필드 처리 + `dawn_wave_multiplier` 지원 + `unlock_condition` 체크 + 특수 지형(안개, 대나무 밀집) 적용
`game/src/systems/chunk_manager.gd`	스테이지별 장애물 types 기반 절차적 생성. 특수 지형 존 생성. 불상 잔해 상호작용
`game/src/systems/obstacle.gd`	장애물 타입별 특수 효과 (glow, water_terrain, clears_fog, random_buff)
`game/src/systems/game_world.gd`	안개 오버레이 (폐사찰), 대나무 밀집 존 시각 효과
`game/src/enemies/spawn_manager.gd` (존재 시)	웨이브 데이터 로드 시 스테이지별 wave 파일 매핑

4-6. 스테이지 매니저 확장

stage_manager.gd 변경:
1. mid_boss 필드 처리:
   - boss_times[0] → mid_boss (있으면) 또는 final_boss 스폰
   - mid_boss_health_override 적용
2. dawn_wave_multiplier 적용:
   - is_dawn_wave 시 SpawnManager에 멀티플라이어 전달
3. unlock_condition 체크:
   - SaveManager에서 스테이지 클리어 기록 확인
4. 특수 지형 시스템:
   - 플레이어 위치 기반 존 진입/탈출 감지
   - 안개: 시야 감소 오버레이 (타이머 기반 진입/탈출)
   - 대나무 밀집: 이속 감소

4-7. placeholder 비주얼

요소	placeholder 구현
대나무 군락	녹색(#2E8B57) ColorRect 32x48 + "竹" 텍스트
고목	갈색(#4A3728) ColorRect 48x64
도깨비 등불	청색(#2E86AB) 작은 원 + glow 라인 원
개울	파랑(#3A7CA5) 가로 띠 ColorRect
석등	회색 ColorRect + 작은 노란 glow 원
불상 잔해	황토색 ColorRect + "佛" 텍스트
안개	반투명 흰색 ColorRect 오버레이 (알파 0.3)
대나무 밀집 존	반투명 녹색 ColorRect 오버레이

4-8. 구현 순서

stages.json bamboo_forest / abandoned_temple 완성
wave_11~wave_18.json 웨이브 데이터 생성
chunk_manager.gd에서 스테이지별 장애물 렌더링
obstacle.gd 특수 효과 (glow, fog clear, random buff, water)
stage_manager.gd 확장 (mid_boss, dawn_multiplier, unlock)
안개/대나무 밀집 존 시각 효과
스테이지 선택 화면에서 해금 상태 연동

구현 우선순위 (Coder 가이드)

전체 시스템 간 종속성을 고려한 권장 순서:

1. SaveManager (영구 데이터 — 모든 시스템의 전제)
2. CurseSystem + curses.json (독립적, 다른 시스템과 연결점 적음)
3. CaptureSystem + capture_codex.json + enemies.json 수정 (독립적)
4. SummonSystem (CaptureSystem 종속)
5. NPC/거점 리팩터:
   a. shrine.json + npc_shrine.gd (사당)
   b. npc_blacksmith.gd (대장장이)
   c. npc_reaper.gd (도감 — CaptureSystem 종속)
   d. npc_grandma.gd + npc_dialogs.json (할멈)
   e. stage_select_screen.gd
   f. hub_screen.gd 리팩터 (통합)
6. 스테이지 2종 (stages.json + 웨이브 + 장애물/지형)
7. 전체 플로우 연결 (거점→저주선택→스테이지→인게임→정산→거점)

EventBus 신규 시그널 요약

## -- Capture signals --
signal enemy_captured(enemy_id: String, position: Vector2)
signal capture_failed(enemy_id: String, position: Vector2)
signal boss_capture_attempt(boss_id: String)
signal summon_activated(summon_id: String)

## -- Curse signals --
signal curses_selected(curse_ids: Array)
signal honbaek_earned(amount: int, multiplier: float)

## -- Hub/NPC signals --
signal npc_interacted(npc_id: String)
signal equipment_upgraded(result: Dictionary)
signal shrine_upgraded(upgrade_id: String, new_level: int)
signal stage_selected(stage_id: String)
signal soul_selected(soul_id: String)

DataManager 신규 카테고리 요약

var _file_map: Dictionary = {
  ... (기존),
  "curses": "curses.json",
  "capture_codex": "capture_codex.json",
  "shrine": "shrine.json",
  "npc_dialogs": "npc_dialogs.json",
}

project.godot 신규 Autoload 요약

CaptureSystem = game/src/systems/capture_system.gd
SummonSystem = game/src/systems/summon_system.gd
CurseSystem = game/src/systems/curse_system.gd
SaveManager = game/src/autoloads/save_manager.gd

문서	비고
포획 시스템	포획 메커닉 상세 설계
저주 시스템	저주 6종 상세 설계
NPC/거점 시스템	NPC 4종 + 거점 상세 설계
대나무 숲	Stage 2 상세
폐사찰	Stage 3 상세
전투 시스템	무기/레벨업/보스전

목차​

1. 포획 시스템​

1-1. 개요​

1-2. 데이터 변경​

enemies.json — 일반 적에 capture 블록 추가​

game/data/capture_codex.json (신규)​

1-3. 신규 파일 목록​

1-4. 기존 파일 변경​

1-5. capture_system.gd 핵심 구조​

1-6. summon_system.gd 핵심 구조​

1-7. placeholder 비주얼​

1-8. 구현 순서​

2. 저주 시스템​

2-1. 개요​

2-2. 데이터 — game/data/curses.json (신규)​

2-3. 신규 파일 목록​

2-4. 기존 파일 변경​

2-5. curse_system.gd 핵심 구조​

2-6. 저주 선택 UI (curse_selection_screen.gd)​

2-7. 저주별 구현 난이도​

2-8. 구현 순서​

3. NPC/거점 시스템​

3-1. 개요​

3-2. 신규 파일 목록​

3-3. 기존 파일 변경​

3-4. game/data/shrine.json (신규)​

3-5. save_manager.gd 핵심 구조​

3-6. 거점 UI 플로우 (hub_screen.gd 리팩터)​

3-7. 판 종료 → 거점 플로우​

3-8. placeholder 비주얼​

3-9. 구현 순서​

4. 추가 스테이지 2종​

4-1. 개요​

4-2. 데이터 변경​

stages.json — bamboo_forest 완성​

stages.json — abandoned_temple 완성​

4-3. 웨이브 데이터 — game/data/waves/​

4-4. 신규 파일 목록​

4-5. 기존 파일 변경​

4-6. 스테이지 매니저 확장​

4-7. placeholder 비주얼​

4-8. 구현 순서​

구현 우선순위 (Coder 가이드)​

EventBus 신규 시그널 요약​

DataManager 신규 카테고리 요약​

project.godot 신규 Autoload 요약​

관련 문서​

목차