horoli
/
arena
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
arena/agent.md

9.6 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/
│       ├── effects/        # 공통 전투/월드 이펙트 스프라이트시트
│       │   ├── heal/       # 처치 회복 연출
│       │   ├── world_Effect.png # 화염 메테오 7프레임 이미지
│       │   └── world_Effect_2.png # 냉기 메테오 7프레임 이미지
│       └── 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 # 최종 교전 슬로우 모션 등 연출 효과
    │   │   └── worldEffects.js # 주기적 메테오/냉각지대 및 냉기 동결 효과
    │   ├── fighter/        # 캐릭터 및 에셋
    │   │   ├── fighterAssets.js # 스프라이트 로드 및 팀 실루엣 동적 생성
    │   │   ├── fighterFactory.js # 캐릭터 인스턴스화 및 HUD 동기화
    │   │   ├── fighterManifest.js # 20종 캐릭터 스탯/특성 상세 정의
    │   │   ├── fighterStats.js # 근접/원거리/마법 프로필 판별 및 스탯 해석
    │   │   └── fighterSelection.js # 캐릭터 스킨 무작위 선택 로직
    ├── match/          # 매치 및 진행
    │   ├── matchSetup.js   # 팀 구성(닉네임 배수 파싱 포함) 및 스폰 좌표 계산 (스타팅 영역/랜덤)
    │   └── arenaMatchRuntime.js # 매치 진행 중 헬퍼 (스폰 클러스터, 팀 크기 동기화)
    ...
    ## 7. 주요 기능 상세 (New)

    ### 7.1 닉네임 배수 시스템 (Multi-Spawn)
    - 사용자가 닉네임 뒤에 `*N` (예: `홍길동*2`)을 입력하면 해당 팀은 기본 팀 인원의 N배만큼 생성됩니다.
    - 스타팅 존 모드에서 배수만큼의 독립된 스폰 지점이 할당되어 전략적인 분산 배치가 이루어집니다.
    - 닉네임 표시 시 `*N` 접미사는 자동으로 제거되어 깔끔한 UI를 유지합니다.

    ### 7.2 서든 데스 (Sudden Death) 시스템
    - 매치 시작 후 일정 시간(기본 8초)이 경과하면 전장의 환경이 극도로 위험해지는 서든 데스 상태에 진입합니다.
    - 메테오 생성 주기가 비약적으로 단축(기본 1초)되며, 빙결 효과를 가진 냉기 메테오가 집중 투하됩니다.
    - `constants.js`를 통해 활성화 여부, 시작 시간, 주기 등을 간편하게 조정할 수 있습니다.

    ### 7.3 구매 배수 기반 월드 이펙트 표적 가중치
    - `닉네임*N`으로 구매한 추가 병력의 수치와 수량은 낮추지 않고 그대로 유지합니다.
    - 월드 이펙트는 생존 중인 팀의 구매 배수 지분보다 생존 지분이 높아진 경우에만 해당 팀의 표적 확률을 추가로 높여, 결제 이점은 보존하면서 독주만 랜덤 요소로 견제합니다.
    - `WORLD_EFFECT.DOMINANCE_TARGETING_MULTIPLIER`가 `0`이면 기존 생존 유닛 비례 표적 선택이며, 기본값 `1`은 초과 생존 지분에 따른 추가 가중치를 그대로 적용합니다.

    └── 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.
  • [스타일 및 디자인] context/style.md: CSS 모듈 구조, 디자인 변수, 반응형 및 애니메이션 가이드.

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: 작업 내역 및 잔여 이슈 관리