arena/agent.md

# Agent: Arena Picker

## 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 커넥션 풀 생성/재사용/종료
│   └── visitors.js         # 유니크 방문자 체크 및 통계 API
├── public/                 # 정적 리소스 (게임 에셋)
│   └── assets/
│       └── characters/     # 20종 이상의 캐릭터 스킨 및 투사체 에셋
│           ├── archer/, armored-axeman/, armored-orc/, ... (중략)
│           └── wizard/     # 각 폴더 내 애니메이션 시트 및 이펙트 포함
└── src/                    # 소스 코드 root
    ├── main.js             # Phaser 게임 인스턴스 생성 및 초기화
    ├── constants.js        # 전역 물리/UI 상수 통합 관리 (공격력, 체력, 줌, 카메라 속도 등)
    ├── styles.css          # UI 스타일링 (스코어보드, 승리 배너 애니메이션)
    ├── game/               # 게임 로직 모듈
    │   ├── ArenaScene.js   # 핵심 게임 씬 (카메라 추적, 승리 판정, 스코어보드 제어)
    │   ├── arenaRenderer.js# 경기장 바닥 및 격자 렌더링
    │   ├── combat.js       # 전투 AI 및 피격 판정 로직
    │   ├── combatSettings.js# 전투 속도 및 이동 배율 관리
    │   ├── fighterAssets.js# 스프라이트 시트 로드, 애니메이션 및 선택 실루엣 생성
    │   ├── fighterFactory.js# 캐릭터 객체, 히트박스, HUD 및 선택 윤곽 동기화
    │   ├── fighterManifest.js# 캐릭터 스킨 데이터 정의 (20종 캐릭터 상세 설정)
    │   ├── fighterSelection.js# 무작위 캐릭터 스킨 선택 로직
    │   └── matchSetup.js   # 닉네임 기반 팀 구성 및 스폰 좌표 계산
    └── ui/
        ├── matchForm.js    # 참가자 입력 폼 및 팀 설정 UI 제어
        └── visitorCounter.js# 방문자 체크 API 호출 및 UI 갱신
```

## 3. 핵심 기능

- **닉네임 기반 팀 스폰**: 입력된 각 닉네임을 독립된 팀으로 인식하고, 설정된 인원(1~100명)만큼 분신 캐릭터를 소환합니다.
- **지능형 카메라 시스템**:
  - **자동 전투 관전**: 화면 확대 시 인접한 교전 중인 캐릭터 쌍을 찾아 부드럽게 추적(Lerp)합니다.
  - **미니맵 연동**: 줌 인 상태에서 전장 전체 상황과 현재 뷰포트 위치를 미니맵에 가이드라인으로 표시합니다.
- **역동적인 전투 연출**:
  - 캐릭터별 고유 공격 방식(근접, 투사체, 마법) 및 애니메이션.
  - `ATTACK_DAMAGE_MIN/MAX`로 기본 공격력 범위를 관리하고, 치명타(Critical) 발생 시 즉시 처치 및 화면 흔들림 효과를 적용합니다.
  - 상대를 처치한 캐릭터는 체력을 현재 체력 기준 30% 회복하고, 처치 누적 배율에 따라 크기, 공격속도, 이동속도가 함께 상승합니다.
- **캐릭터 선택 관전**: 캐릭터를 클릭하면 해당 캐릭터에 카메라가 고정되며, 원본 스프라이트 알파 마스크를 바탕으로 1px 공백을 둔 노란 실루엣 윤곽이 표시됩니다.
- **실시간 경기 중계 UI**: 상단 좌/우 영역에 팀별 현재 생존 인원을 실시간으로 표시하며, 승리 시 대형 배너로 결과를 알립니다.
- **유니크 방문자 체크**: 접속 시 `POST /api/visitors/check`를 호출하고, 서버가 `HttpOnly` 쿠키 기반 UUID로 MongoDB에 방문자 1명당 1개 문서를 유지합니다.

## 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`: 전체 유니크 방문자 수 조회.

## 6. 관련 문서

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