7.3 KiB

Raw Blame History

Agent: Arena Picker

0. 필수

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

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 커넥션 풀 생성/재사용/종료
│   ├── 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: main.js, constants.js, 개발/유지보수 공통 규칙.
[서버 및 API] context/server.md: Fastify 서버, MongoDB 연동, 방문자 및 사망 통계 API 상세.
[아레나 및 카메라] context/arena.md: ArenaScene 오케스트레이션, 지능형 카메라 추적, 미니맵 가이드라인.
[전투 엔진] context/combat.md: 전투 AI, 투사체 판정, 처치 보상 성장, 슬로우모션 연출.
[캐릭터 및 에셋] context/fighter.md: 캐릭터 공장, 동적 실루엣 생성, 종족 및 특성(Slime 등) 정의.
[매치 로직 및 UI] 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: 상세 개발 가이드 및 핵심 로직 설명 (필독)
todo.md: 작업 내역 및 잔여 이슈 관리

7.3 KiB Raw Blame History