🎮 g5se 브라우저 던전 크롤러 - 클릭 RPG 어드벤처

g5se가 설치된 디렉터리(루트에 `index.php`·`app/`이 있는 곳)에서 작업을 시작합니다. (g5se 설치는 https://github.com/gnuboard/g5se 참고)

## Step 1: 프로젝트 골격 & DB 스키마 생성

`app/modules/dungeon/index.php` 파일을 생성하고 다음 구조로 작성하세요:

1. **modern shell 골격 적용**
   - `_common.php` 인클루드
   - `_head.inc.php`, `_nav.inc.php`, `_footer.inc.php`, `tail.sub.php` 포함
   - `<main class="m-container">` 안에 게임 UI 배치

2. **SQLite DB 초기화**
   - DB 경로: `G5_DATA_PATH.'/modules/dungeon.sqlite'`
   - 디렉터리가 없으면 `@mkdir(G5_DATA_PATH.'/modules', 0707, true);`로 생성
   - 3개 테이블 생성:
     - `characters`: id(INTEGER PRIMARY KEY), nickname(TEXT), level(INTEGER DEFAULT 1), exp(INTEGER DEFAULT 0), hp(INTEGER DEFAULT 100), max_hp(INTEGER DEFAULT 100), mp(INTEGER DEFAULT 50), max_mp(INTEGER DEFAULT 50), atk(INTEGER DEFAULT 10), def(INTEGER DEFAULT 5), gold(INTEGER DEFAULT 100), created_at(TEXT)
     - `inventory`: id(INTEGER PRIMARY KEY), character_id(INTEGER), item_type(TEXT), item_name(TEXT), item_stats(TEXT), equipped(INTEGER DEFAULT 0), acquired_at(TEXT)
     - `monsters`: id(INTEGER PRIMARY KEY), name(TEXT), level(INTEGER), hp(INTEGER), atk(INTEGER), def(INTEGER), exp_reward(INTEGER), gold_reward(INTEGER), drop_items(TEXT)

3. **몬스터 시드 데이터 삽입**
   - 초급 던전: 슬라임(Lv1, HP30, ATK5, DEF2), 고블린(Lv2, HP50, ATK8, DEF3)
   - 중급 던전: 오크(Lv5, HP120, ATK15, DEF8), 다크엘프(Lv7, HP150, ATK20, DEF10)
   - 고급 던전: 드래곤(Lv10, HP300, ATK35, DEF20), 데몬로드(Lv15, HP500, ATK50, DEF30)
   - drop_items는 JSON 형식으로 저장 (예: `["철검", "가죽갑옷"]`)

4. **기본 UI 구조**
   - 페이지 타이틀: "🎮 브라우저 던전 크롤러"
   - 두 개 섹션:
     - 왼쪽: 캐릭터 정보 카드 (닉네임, 레벨, HP/MP 바, 스탯)
     - 오른쪽: 던전 선택 & 전투 영역
   - CSS 변수 사용: `background: var(--m-surface);`, `color: var(--m-text);`

5. **쿠키 체크 로직**
   - `$_COOKIE['dungeon_character_id']` 확인
   - 있으면 DB에서 캐릭터 로드, 없으면 "새 게임 시작" 폼 표시

DB 초기화와 몬스터 시드는 페이지 로드 시 자동으로 실행되도록 하되, `CREATE TABLE IF NOT EXISTS`와 `INSERT OR IGNORE`로 중복 방지하세요.

## Step 2: 캐릭터 생성 & 스탯 시스템 구현

1. **캐릭터 생성 폼 처리**
   - POST 요청으로 닉네임 받기 (`$_POST['nickname']`)
   - 닉네임 검증: 2~10자, 특수문자 제거 (`htmlspecialchars()`)
   - DB에 새 캐릭터 INSERT (기본 스탯: Lv1, HP100, MP50, ATK10, DEF5, GOLD100)
   - 생성 후 `character_id`를 쿠키에 저장 (유효기간 30일)
   - 페이지 리다이렉트로 새로고침

2. **캐릭터 정보 카드 UI**
   - 닉네임 & 레벨 표시 (큰 글씨)
   - HP/MP 프로그레스바:
     - `<div class="stat-bar"><div class="stat-fill" style="width: {현재HP/최대HP*100}%"></div></div>`
     - HP는 빨간색, MP는 파란색 그라데이션
   - 스탯 목록:
     - 공격력: ⚔️ {atk}
     - 방어력: 🛡️ {def}
     - 골드: 💰 {gold}G
   - 경험치 바: "Lv{level} ({exp}/{다음레벨필요경험치})"

3. **레벨업 시스템 로직**
   - 필요 경험치 공식: `level * 100`
   - 경험치가 충분하면 레벨업:
     - level +1
     - max_hp +20, max_mp +10, atk +3, def +2
     - 현재 HP/MP를 최대치로 회복
     - 초과 경험치는 다음 레벨로 이월
   - 레벨업 시 화면에 "🎉 레벨업! Lv{new_level}" 토스트 메시지 표시

4. **"새 게임 시작" 버튼**
   - 현재 캐릭터 데이터 삭제 (characters 테이블에서 DELETE)
   - 관련 인벤토리 아이템도 삭제 (inventory 테이블에서 character_id로 DELETE)
   - 쿠키 삭제 후 페이지 리다이렉트

5. **CSS 스타일링**
   - 캐릭터 카드: `border-radius: var(--m-radius-lg);`, `box-shadow: var(--m-shadow);`
   - 프로그레스바 애니메이션: `transition: width 0.5s ease;`
   - 스탯 아이콘 정렬: flexbox로 아이콘+텍스트 수평 배치

모든 DB 쿼리는 prepared statement로 작성하고, 레벨업 로직은 함수로 분리하여 재사용 가능하게 하세요.

## Step 3: 던전 선택 & 몬스터 인카운터

1. **던전 선택 UI**
   - 3개 던전 버튼:
     - 🌱 초급 던전 (권장 Lv1~3)
     - ⚔️ 중급 던전 (권장 Lv4~8)
     - 🔥 고급 던전 (권장 Lv9+)
   - 각 버튼에 배경색 그라데이션 (초급: 연두, 중급: 주황, 고급: 빨강)
   - 던전별 "탐험하기" 버튼 (클릭 시 AJAX 요청)

2. **몬스터 랜덤 인카운터 (AJAX)**
   - 엔드포인트: `?action=encounter&dungeon={level}`
   - 던전 레벨에 맞는 몬스터를 DB에서 랜덤 선택:
     - 초급: level 1~2 몬스터
     - 중급: level 5~7 몬스터
     - 고급: level 10~15 몬스터
   - 선택된 몬스터 정보를 JSON으로 반환:
     ```json
     {
       "monster_id": 1,
       "name": "슬라임",
       "level": 1,
       "hp": 30,
       "max_hp": 30,
       "atk": 5,
       "def": 2,
       "emoji": "🟢"
     }
     ```

3. **전투 화면 전환**
   - AJAX 응답을 받으면 던전 선택 UI를 숨기고 전투 UI를 표시
   - 전투 UI 구성:
     - 상단: 몬스터 정보 카드 (이름, 레벨, HP바, 이모지)
     - 중단: 전투 로그 영역 (스크롤 가능한 텍스트 박스)
     - 하단: 행동 버튼 (일반 공격 / 스킬 / 포션 / 도망)

4. **몬스터 정보 표시**
   - 몬스터 이름 & 레벨: "🟢 슬라임 Lv1"
   - HP 바: 빨간색 프로그레스바 (플레이어와 동일한 스타일)
   - 몬스터별 이모지 매핑:
     - 슬라임: 🟢, 고블린: 👺, 오크: 🐗, 다크엘프: 🧝, 드래곤: 🐉, 데몬로드: 😈

5. **전투 로그 초기화**
   - 인카운터 시 첫 메시지: "야생의 {몬스터 이름}이(가) 나타났다!"
   - 로그는 아래에서 위로 쌓이는 방식 (최신 메시지가 맨 아래)
   - 스크롤은 자동으로 맨 아래로 이동

6. **전투 상태 저장 (세션)**
   - 현재 전투 중인 몬스터 정보를 PHP 세션에 저장:
     ```php
     $_SESSION['current_battle'] = [
       'monster_id' => $monster['id'],
       'monster_hp' => $monster['hp'],
       'monster_max_hp' => $monster['hp']
     ];
     ```
   - 이후 전투 액션에서 세션 데이터를 참조

CSS로 전투 화면 전환 시 페이드인 애니메이션을 추가하고, 몬스터 카드에 살짝 흔들리는 효과를 주세요 (`@keyframes shake`).

## Step 4: 턴제 전투 시스템 구현

1. **일반 공격 로직 (AJAX)**
   - 엔드포인트: `?action=attack`
   - 플레이어 턴:
     - 데미지 계산: `max(1, $player_atk - $monster_def + rand(0, 5))`
     - 몬스터 HP 감소 & 세션 업데이트
     - 로그 추가: "당신은 {몬스터}에게 {데미지}의 피해를 입혔습니다!"
   - 몬스터 턴 (몬스터 HP > 0인 경우):
     - 데미지 계산: `max(1, $monster_atk - $player_def + rand(0, 5))`
     - 플레이어 HP 감소 & DB 업데이트
     - 로그 추가: "{몬스터}의 공격! {데미지}의 피해를 받았습니다!"
   - JSON 응답:
     ```json
     {
       "player_hp": 85,
       "monster_hp": 15,
       "logs": [
         "당신은 슬라임에게 15의 피해를 입혔습니다!",
         "슬라임의 공격! 5의 피해를 받았습니다!"
       ],
       "battle_end": false
     }
     ```

2. **전투 종료 조건**
   - 몬스터 HP ≤ 0: 승리
     - 경험치 & 골드 획득
     - 랜덤 아이템 드롭 (30% 확률)
     - 레벨업 체크 (경험치가 충분하면 자동 레벨업)
     - 로그: "🎉 승리! {exp}EXP, {gold}G 획득!"
     - 아이템 드롭 시: "🎁 {아이템 이름}을(를) 획득했습니다!"
   - 플레이어 HP ≤ 0: 패배
     - 경험치 10% 손실 (최소 0)
     - 골드 손실 없음 (초보자 배려)
     - HP/MP 최대치로 회복 (마을 귀환)
     - 로그: "💀 패배했습니다... 마을로 돌아갑니다."
   - 전투 종료 시 세션 클리어 & "던전으로 돌아가기" 버튼 표시

3. **스킬 사용 (AJAX)**
   - 엔드포인트: `?action=skill`
   - 스킬 "파워 어택": MP 20 소모, 데미지 2배
   - MP 부족 시 에러 메시지: "MP가 부족합니다!"
   - 성공 시 일반 공격과 동일한 턴 진행
   - 로그: "⚡ 파워 어택 발동! {데미지}의 강력한 피해!"

4. **포션 사용 (AJAX)**
   - 엔드포인트: `?action=use_potion&type={hp|mp}`
   - 인벤토리에서 포션 체크 (inventory 테이블에서 item_type='potion' & item_name='{type}_potion')
   - 없으면 에러: "포션이 없습니다!"
   - HP 포션: HP +50 (최대치 초과 불가)
   - MP 포션: MP +30 (최대치 초과 불가)
   - 사용 후 인벤토리에서 DELETE
   - 로그: "💊 {포션 이름} 사용! {회복량} 회복!"
   - 몬스터 턴은 정상 진행

5. **도망 (AJAX)**
   - 엔드포인트: `?action=flee`
   - 50% 확률로 성공
   - 성공 시: 전투 종료, 세션 클리어, 로그: "🏃 무사히 도망쳤습니다!"
   - 실패 시: 몬스터 턴만 진행, 로그: "❌ 도망 실패! 몬스터의 공격!"

6. **UI 업데이트**
   - AJAX 응답을 받아 화면 갱신:
     - 플레이어 HP/MP 바 애니메이션
     - 몬스터 HP 바 애니메이션
     - 로그 추가 (자동 스크롤)
     - 전투 종료 시 행동 버튼 숨기고 "던전으로 돌아가기" 버튼 표시

모든 전투 액션은 서버 사이드에서 검증하고, 클라이언트는 결과만 받아서 UI를 업데이트하세요. 버튼 클릭 시 0.5초 쿨타임을 적용하여 중복 클릭을 방지하세요.

## Step 5: 인벤토리 & 장비 시스템

1. **인벤토리 UI**
   - 캐릭터 정보 카드 하단에 "🎒 인벤토리" 탭 추가
   - 클릭 시 모달 또는 슬라이드 패널로 아이템 목록 표시
   - 아이템 카테고리:
     - 무기 (⚔️): 공격력 보너스
     - 방어구 (🛡️): 방어력 보너스
     - 포션 (💊): HP/MP 회복
   - 각 아이템 카드:
     - 아이템 이름 & 이모지
     - 스탯 정보 (예: "공격력 +5")
     - 장착/해제 버튼 (무기/방어구만)
     - 판매 버튼 (가격의 50%)

2. **아이템 드롭 시스템**
   - 몬스터 처치 시 30% 확률로 아이템 드롭
   - 드롭 아이템은 몬스터 데이터의 `drop_items` JSON에서 랜덤 선택
   - 아이템 스탯은 몬스터 레벨 기반으로 생성:
     - 무기: 공격력 + (몬스터 레벨 * 2)
     - 방어구: 방어력 + (몬스터 레벨 * 1)
   - 인벤토리에 INSERT:
     ```php
     $stmt = $pdo->prepare("INSERT INTO inventory (character_id, item_type, item_name, item_stats, acquired_at) VALUES (?, ?, ?, ?, ?)");
     $stmt->execute([$char_id, 'weapon', '철검', json_encode(['atk' => 5]), date('Y-m-d H:i:s')]);
     ```

3. **장비 장착/해제 (AJAX)**
   - 엔드포인트: `?action=equip&item_id={id}`
   - 같은 타입의 기존 장착 아이템을 먼저 해제 (equipped=0)
   - 선택한 아이템을 장착 (equipped=1)
   - 캐릭터 스탯 재계산:
     - 장착된 모든 아이템의 스탯을 합산
     - 기본 스탯 + 장비 보너스
   - DB 업데이트 후 화면 갱신
   - 로그: "⚔️ {아이템 이름}을(를) 장착했습니다! 공격력 +{보너스}"

4. **아이템 판매 (AJAX)**
   - 엔드포인트: `?action=sell&item_id={id}`
   - 판매 가격 계산:
     - 무기/방어구: 스탯 보너스 * 10 * 0.5
     - 포션: 고정 가격 (HP 포션 25G, MP 포션 15G)
   - 골드 증가 & 아이템 DELETE
   - 장착 중인 아이템은 판매 불가 (에러 메시지)
   - 로그: "💰 {아이템 이름}을(를) {가격}G에 판매했습니다!"

5. **상점 시스템**
   - 인벤토리 모달에 "🏪 상점" 탭 추가
   - 구매 가능 아이템:
     - HP 포션 (50G)
     - MP 포션 (30G)
   - 구매 버튼 클릭 시 (AJAX):
     - 골드 부족 체크
     - 골드 차감 & 인벤토리에 포션 추가
     - 로그: "🛒 {아이템}을(를) 구매했습니다!"

6. **UI 개선**
   - 인벤토리 모달: 배경 블러 처리 (`backdrop-filter: blur(5px);`)
   - 아이템 카드: 호버 시 확대 효과 (`transform: scale(1.05);`)
   - 장착 중인 아이템: 테두리 강조 (`border: 2px solid gold;`)
   - 빈 인벤토리: "아직 획득한 아이템이 없습니다" 안내 메시지

모든 아이템 액션은 prepared statement로 처리하고, 스탯 재계산 로직은 함수로 분리하여 장착/해제 시 재사용하세요.

## Step 6: 최종 다듬기 & 보너스 기능

1. **레벨업 애니메이션 강화**
   - 레벨업 시 화면 전체에 "🎉 LEVEL UP!" 오버레이 표시
   - 1초간 금색 빛 효과 (`@keyframes glow`)
   - 새로운 스탯을 애니메이션으로 표시 (숫자 카운트업 효과)

2. **전투 효과음 (선택)**
   - Web Audio API로 간단한 효과음 생성:
     - 공격: 짧은 "펑" 소리 (주파수 200Hz, 0.1초)
     - 레벨업: 상승 멜로디 (주파수 400→600Hz, 0.5초)
     - 아이템 획득: "딩" 소리 (주파수 800Hz, 0.2초)
   - 음소거 토글 버튼 추가 (localStorage에 설정 저장)

3. **업적 시스템 (선택)**
   - 업적 데이터를 DB에 저장 (achievements 테이블):
     - id, character_id, achievement_name, unlocked_at
   - 조건 체크:
     - "첫 승리": 몬스터 1마리 처치
     - "슬라임 헌터": 슬라임 10마리 처치
     - "레벨 마스터": 레벨 5 달성
     - "부자": 골드 1000G 보유
   - 업적 달성 시 토스트 알림 & 보상 (골드 100G)
   - 인벤토리 모달에 "🏆 업적" 탭 추가

4. **랭킹 시스템 (선택)**
   - 전체 플레이어 순위:
     - 레벨 기준 (동점 시 경험치)
     - 골드 기준
   - 던전 페이지 상단에 "🏆 랭킹" 버튼 추가
   - 클릭 시 모달로 TOP 10 표시
   - 본인 순위 강조 (배경색 변경)

5. **반응형 디자인**
   - 모바일 화면 (768px 이하):
     - 캐릭터 카드와 던전 영역을 세로 배치
     - 버튼 크기 확대 (터치 친화적)
     - 전투 로그 높이 축소
   - 다크모드 대응 재확인:
     - 모든 색상이 CSS 변수 사용
     - 하드코딩된 색상이 있다면 변수로 교체

6. **성능 최적화**
   - DB 쿼리 최소화:
     - 캐릭터 정보는 한 번만 로드하고 JS 변수에 캐싱
     - 전투 중 불필요한 SELECT 제거
   - AJAX 요청 중복 방지:
     - 버튼 클릭 시 즉시 비활성화
     - 응답 후 재활성화
   - 로그 메시지 개수 제한 (최대 50개, 초과 시 오래된 것 삭제)

7. **에러 핸들링**
   - DB 연결 실패 시 사용자 친화적 메시지
   - AJAX 요청 실패 시 재시도 버튼 표시
   - 세션 만료 시 자동 로그아웃 & 재로그인 유도

8. **최종 테스트**
   - 시나리오 테스트:
     1. 캐릭터 생성 → 초급 던전 탐험 → 슬라임 처치 → 레벨업
     2. 아이템 획득 → 장착 → 스탯 증가 확인
     3. 중급 던전 도전 → 패배 → 경험치 손실 확인
     4. 포션 구매 → 사용 → HP 회복 확인
     5. 고급 던전 도전 → 드래곤 처치 → 업적 달성
   - 다크모드 전환 시 모든 UI 요소 정상 작동 확인
   - 모바일 화면에서 터치 인터랙션 테스트

모든 기능이 완성되면 README.md를 작성하여 게임 설명, 조작법, 시스템 요구사항을 정리하세요.