5.9 KiB

Raw Blame History

Agent: Arena Picker

1. 프로젝트 정의

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

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

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

├── 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: 상세 개발 가이드 및 핵심 로직 설명 (필독)
todo.md: 작업 내역 및 잔여 이슈 관리

5.9 KiB Raw Blame History