102 lines
7.3 KiB
Markdown
102 lines
7.3 KiB
Markdown
# 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): 작업 내역 및 잔여 이슈 관리
|