# Agent: Arena Picker

## 0. 필수

- 작업이 완료되면 작업에 관련된 모든 문서를 업데이트한다

## 1. 프로젝트 정의

**Arena Picker**는 Phaser 3 게임 엔진과 Vite 번들러를 기반으로 구축된 **대규모 팀 전투 시뮬레이션 웹 애플리케이션**입니다. 사용자가 입력한 여러 명의 참가자(닉네임)를 바탕으로 각 참가자를 하나의 팀으로 설정하고, 지정된 인원만큼의 캐릭터를 생성하여 자동 전투를 시뮬레이션합니다.

서버 런타임은 Fastify를 사용하며, MongoDB 커넥션 풀을 유지해 유니크 방문자 수와 전투 사망 통계를 기록하는 간단한 통계 API를 제공합니다.

## 2. 프로젝트 전체 구조 (Directory Tree)

```text
├── index.html              # 메인 HTML 진입점 및 UI 레이아웃
├── package.json            # 프로젝트 의존성 및 스크립트 정의 (Phaser, Vite, Fastify, MongoDB)
├── config.json             # 로컬 서버/MongoDB 설정 (git ignore)
├── config.json.sample      # 공유용 서버/MongoDB 설정 예시
├── agent.md                # 프로젝트 개요 및 기능 정의 (본 문서)
├── CONTEXT.md              # 상세 개발 가이드 및 로직 설명
├── todo.md                 # 작업 내역 및 잔여 이슈 관리
├── server/                 # Fastify API 서버 및 MongoDB 연결 관리
│   ├── index.js            # Fastify 서버 진입점, Vite 개발 미들웨어, 정적 배포 서빙
│   ├── config.js           # config.json 로드 및 MongoDB URI 조립
│   ├── db.js               # MongoClient 커넥션 풀 생성/재사용/종료
│   ├── deathStats.js       # 전투 종료 시 오늘 일자별 종족 사망 통계 누적 API
│   ├── about.js            # About 개발자정보/개인정보처리방침 기본값 시드 및 조회 API
│   └── visitors.js         # 유니크 방문자 체크 및 통계 API
├── public/                 # 정적 리소스 (게임 에셋)
│   └── assets/
│       └── characters/     # 20종 이상의 캐릭터 스킨 및 투사체 에셋
│           ├── archer/, armored-axeman/, armored-orc/, ... (중략)
│           └── wizard/     # 각 폴더 내 애니메이션 시트 및 이펙트 포함
└── src/                    # 소스 코드 root
    ├── main.js             # Phaser 게임 인스턴스 생성, 옵션 drawer/재시작/일시정지 UI 제어
    ├── constants.js        # 전역 물리/UI 상수 통합 관리 (공격력, 체력, 줌, 카메라 속도 등)
    ├── styles.css          # UI 스타일링 (인트로, 옵션 drawer, 좌측 HUD 레일, 좌측 하단 킬로그, 상단 전투 안내바)
    ├── game/               # 게임 로직 모듈 (역할별 하위 폴더 구성)
    │   ├── arena/          # 아레나 및 씬 관리
    │   │   ├── ArenaScene.js   # 메인 게임 씬 (Orchestrator, 생명주기 및 모듈 조율)
    │   │   ├── arenaRenderer.js# 경기장 바닥 및 격자 렌더링
    │   │   └── arenaSpectatorCamera.js # 지능형 관전 카메라 및 줌 로직
    │   ├── combat/         # 전투 시스템
    │   │   ├── combat.js       # 전투 AI, 투사체 및 피격 판정 핵심 엔진
    │   │   ├── combatSettings.js # 전투 속도 및 이동 배율 관리
    │   │   └── arenaFinalCombatEffects.js # 최종 교전 슬로우 모션 등 연출 효과
    │   ├── fighter/        # 캐릭터 및 에셋
    │   │   ├── fighterAssets.js # 스프라이트 로드 및 팀 실루엣 동적 생성
    │   │   ├── fighterFactory.js # 캐릭터 인스턴스화 및 HUD 동기화
    │   │   ├── fighterManifest.js # 20종 캐릭터 스탯/특성 상세 정의
    │   │   └── fighterSelection.js # 캐릭터 스킨 무작위 선택 로직
    │   └── match/          # 매치 및 진행
    │       ├── matchSetup.js   # 팀 구성 및 스폰 좌표 계산 (구역/랜덤)
    │       └── arenaMatchRuntime.js # 매치 진행 중 헬퍼 (스폰 클러스터, 팀 크기 동기화)
    └── ui/                 # UI 컴포넌트 및 API 연동
        ├── arenaKillLog.js # [New] 독립된 킬로그 DOM 조작 모듈
        ├── arenaScoreboard.js # [New] 팀 스코어 badge 업데이트 모듈
        ├── battleDeathNotice.js # [New] 상단 사망 공지 메시지 및 UI 관리
        ├── victoryCelebration.js # [New] 승리 축하 연출 (DOM/Audio) 모듈
        ├── matchForm.js    # 설정 폼 제어 및 localStorage 유지
        ├── aboutDialog.js  # About 다이얼로그, 개발자정보/개인정보처리방침 표시
        ├── deathStats.js   # 사망 통계 API 호출 래퍼
        └── visitorCounter.js # 방문자 체크 API 호출 및 표시
```

## 3. 상세 기술 가이드 (Context Routing)

토큰 절약 및 효율적인 정보 조회를 위해 상세 로직은 기능별로 분리되어 보관됩니다. 특정 모듈 작업 시 아래의 관련 문서를 먼저 읽으십시오.

- **[인프라 및 전역 설정] [context/core.md](./context/core.md)**: `main.js`, `constants.js`, 개발/유지보수 공통 규칙.
- **[서버 및 API] [context/server.md](./context/server.md)**: Fastify 서버, MongoDB 연동, 방문자 및 사망 통계 API 상세.
- **[아레나 및 카메라] [context/arena.md](./context/arena.md)**: `ArenaScene` 오케스트레이션, 지능형 카메라 추적, 미니맵 가이드라인.
- **[전투 엔진] [context/combat.md](./context/combat.md)**: 전투 AI, 투사체 판정, 처치 보상 성장, 슬로우모션 연출.
- **[캐릭터 및 에셋] [context/fighter.md](./context/fighter.md)**: 캐릭터 공장, 동적 실루엣 생성, 종족 및 특성(Slime 등) 정의.
- **[매치 로직 및 UI] [context/match-ui.md](./context/match-ui.md)**: 팀 구성 및 스폰 알고리즘, HUD 레이아웃, 킬로그, 승리 연출 UI.

## 4. 기술 사양

- **Framework**: Phaser 3.90.0 (Arcade Physics 기반)
- **Build Tool**: Vite 7.1.12
- **Server**: Fastify 5.x (`@fastify/static`, `@fastify/middie`)
- **Database**: MongoDB 7.x Node Driver
- **UI Logic**: Vanilla JS & CSS (Flexbox/Grid 활용)

## 5. 서버/API 설정

- 개발/운영 서버는 `npm run dev` 또는 `npm start`로 실행하며 기본 포트는 `config.json`의 `SERVER_PORT` 값인 `9736`입니다.
- `config.json`은 로컬 설정 파일이므로 저장소에 커밋하지 않습니다. 새 환경에서는 `config.json.sample`을 복사해 사용합니다.
- 기본 API:
  - `GET /api/health`: 서버 및 MongoDB 설정 여부 확인.
  - `POST /api/visitors/check`: 현재 브라우저 방문자를 체크하고 유니크 방문자 수를 반환.
  - `GET /api/visitors/stats`: 전체 유니크 방문자 수 조회.
  - `GET /api/about`: 데이터베이스에서 실시간으로 개발자정보와 개인정보처리방침 Markdown 조회 (캐시 없이 즉시 반영).
  - `GET /api/death-stats/today`: 오늘의 종족별 전투 사망 통계 조회.
  - `POST /api/death-stats/today`: 종료된 전투의 종족별 사망 수를 오늘 집계에 누적.

## 6. 관련 문서

- [CONTEXT.md](./CONTEXT.md): 상세 개발 가이드 및 핵심 로직 설명 (필독)
- [todo.md](./todo.md): 작업 내역 및 잔여 이슈 관리