Modularize documentation: split CONTEXT.md into functional modules and update agent.md router
This commit is contained in:
parent
4793680831
commit
e4f542d487
160
CONTEXT.md
160
CONTEXT.md
|
|
@ -1,160 +0,0 @@
|
|||
# Context: Arena Picker 개발 가이드
|
||||
|
||||
## 1. 모듈별 상세 역할
|
||||
|
||||
### [Core Engine]
|
||||
- **`src/main.js`**: Phaser 게임의 전역 설정(Physics, Scale, Canvas Parent)을 담당하며, `ArenaScene`을 인스턴스화합니다.
|
||||
- 앱 로드 시 `trackVisitor()`를 호출해 방문자 체크 API와 연동합니다.
|
||||
- `Start` 버튼, 옵션 drawer, 전투 시작 submit 흐름을 제어하며 전투 시작 시 `#app`에 `match-live` 상태 클래스를 부여합니다.
|
||||
- 전투 중 drawer 접기/펼치기(`drawer-collapsed`), 재시작 버튼, 일시정지 버튼 상태(`match-paused`)를 DOM 클래스와 `ArenaScene` 상태에 동기화합니다.
|
||||
- **`src/constants.js`**: 게임 내 모든 튜닝 수치를 관리합니다.
|
||||
- `ATTACK_DAMAGE_MIN`, `ATTACK_DAMAGE_MAX`: 일반 공격 1회 적중 시 적용되는 랜덤 피해량 범위.
|
||||
- `FIGHTER_HITBOX_*`: 100x100 캐릭터 프레임 안에서 실제 충돌 판정이 놓이는 위치와 크기.
|
||||
- `KILL_HEALTH_RECOVERY_RATIO`, `KILL_GROWTH_MULTIPLIER`, `KILL_GROWTH_MAX_MULTIPLIER`: 처치 후 회복량, 크기/공격속도/이동속도 성장 배율, 누적 보상 상한.
|
||||
- `SELECTED_FIGHTER_OUTLINE_GAP`, `SELECTED_FIGHTER_OUTLINE_WIDTH`, `SELECTED_FIGHTER_OUTLINE_ALPHA`: 팀 색상 실루엣 마커의 캐릭터 이격 거리, 두께, 투명도.
|
||||
- `TEAM_COLORS`, `getTeamColor()`: 8팀 이하에서는 기본 팔레트를 쓰고, 9팀 이상에서는 팀 수에 맞춰 중복 없는 색상을 동적으로 생성합니다.
|
||||
- `SPECTATOR_CAMERA_LERP`: 카메라 추적의 부드러움 정도.
|
||||
- `SPECTATOR_FINAL_TEAM_TOTAL_THRESHOLD`, `SPECTATOR_RANDOM_FOCUS_INTERVAL`, `FINAL_COMBAT_SLOW_MOTION_*`: 최종교전 관전 조건, 랜덤 포커싱 간격, 슬로우모션 on/off, 배율과 속도 램프 시간.
|
||||
- `MINIMAP_VIEWPORT_SIZE`: 미니맵의 고정 픽셀 크기.
|
||||
- `ARENA_SIZE`: 경기장 전체 크기 (GRID * TILE).
|
||||
|
||||
### [Server/API - server/]
|
||||
- **`server/index.js`**:
|
||||
- Fastify 서버 진입점입니다.
|
||||
- 개발 모드에서는 `@fastify/middie`로 Vite 미들웨어를 붙이고, `/api/*` 요청은 Vite SPA fallback이 가로채지 않도록 Fastify 라우트로 통과시킵니다.
|
||||
- 운영 모드(`npm start`)에서는 `@fastify/static`으로 `dist/`를 서빙하고, HTML 요청은 `index.html`로 fallback합니다.
|
||||
- **`server/config.js`**:
|
||||
- `config.json`을 읽어 서버 포트, MongoDB host/port/db/user/pass, 쿠키 보안 옵션을 정규화합니다.
|
||||
- `MONGODB_URI`가 직접 있으면 우선 사용하고, 없으면 `MONGODB_HOST`/`MONGODB_PORT` 기반으로 URI를 조립합니다.
|
||||
- 전투 사망 통계 컬렉션(`MONGODB_DAILY_DEATH_COLLECTION`)과 집계 기준 타임존(`DEATH_STATS_TIME_ZONE`) 기본값을 제공합니다.
|
||||
- **`server/db.js`**:
|
||||
- `MongoClient`를 한 번 생성한 뒤 재사용하여 MongoDB 커넥션 풀을 유지합니다.
|
||||
- 종료 시 `closeMongoConnection()`으로 커넥션을 닫습니다.
|
||||
- **`server/deathStats.js`**:
|
||||
- `GET /api/death-stats/today`: `DEATH_STATS_TIME_ZONE` 기준 오늘 일자의 종족별 사망 집계와 총 사망 수를 반환합니다.
|
||||
- `POST /api/death-stats/today`: 전투 종료 시 전달된 `deathsBySpecies`를 오늘 일자별 누적 문서의 `deathsBySpecies`, `totalDeaths`, `battles`에 바로 더합니다.
|
||||
- 집계 대상 종족은 `human`, `orc`, `skeleton`, `slime`, `wolf`, `bear`로 제한합니다.
|
||||
- **`server/visitors.js`**:
|
||||
- `POST /api/visitors/check`: `arena_visitor_id` `HttpOnly` 쿠키를 확인하고 없으면 UUID를 발급합니다.
|
||||
- MongoDB `visitors` 컬렉션에 `_id = visitorId`로 upsert해 방문자 1명당 1개 문서를 유지합니다.
|
||||
- `GET /api/visitors/stats`: 전체 유니크 방문자 수를 반환합니다.
|
||||
|
||||
### [Game Logic - src/game/]
|
||||
#### arena/
|
||||
- **`ArenaScene.js`**: Phaser 씬의 생명주기와 전반적인 오케스트레이션을 담당합니다. `update()` 매 프레임마다 전투원 상태를 체크하고, 카메라 이동 및 UI 모듈 호출을 조율합니다.
|
||||
- **`arenaRenderer.js`**: 아레나 배경 그래픽 및 타일 렌더링을 담당합니다.
|
||||
- **`arenaSpectatorCamera.js`**: 관전 모드 시점 계산 및 카메라 포커싱 로직을 담당합니다. 생존 인원에 따른 지능형 카메라 추적 알고리즘이 구현되어 있습니다.
|
||||
|
||||
#### combat/
|
||||
- **`combat.js`**: 전투 AI, 피해 계산, 처치 보상 등 핵심 전투 로직을 담당합니다. 유닛의 이동, 공격, 투사체 발사 등을 처리합니다.
|
||||
- **`combatSettings.js`**: 전투 속도 배율 등 런타임 전투 설정을 관리합니다.
|
||||
- **`arenaFinalCombatEffects.js`**: 최종 교전 시 슬로우 모션 등 연출 효과를 담당합니다. 수학적인 이징(easing) 함수와 물리 시간 배율 계산을 포함합니다.
|
||||
|
||||
#### fighter/
|
||||
- **`fighterAssets.js`**: 캐릭터 스프라이트 로드 및 애니메이션/실루엣 생성을 담당합니다. 원본 이미지로부터 팀 색상 마커용 실루엣을 동적으로 생성합니다.
|
||||
- **`fighterFactory.js`**: 캐릭터 인스턴스화 및 HUD(이름표, 체력바) 관리를 담당합니다. Phaser Sprite와 DOM UI 사이의 가교 역할을 합니다.
|
||||
- **`fighterManifest.js`**: 모든 캐릭터 종족 및 스탯 데이터를 정의합니다. 20여 종의 캐릭터 설정이 포함되어 있습니다.
|
||||
- **`fighterSelection.js`**: 매치 참여 캐릭터를 무작위로 선택하거나 섞는 로직을 담당합니다.
|
||||
|
||||
#### match/
|
||||
- **`matchSetup.js`**: 매치 초기화, 팀 구성, 스폰 위치 계산을 담당합니다. 랜덤 배치 및 스타팅 지점 배치 알고리즘이 구현되어 있습니다.
|
||||
- **`arenaMatchRuntime.js`**: 스폰 클러스터 계산 및 팀 크기 동기화 등 매치 진행 중 필요한 헬퍼 기능을 제공합니다.
|
||||
|
||||
### [Assets & UI]
|
||||
- **`fighterAssets.js`**: 원본 캐릭터 스프라이트의 alpha 값을 읽어 흰색 실루엣 spritesheet를 런타임에 생성합니다. 원본 주변 1px은 비워두고 그 바깥 1px만 칠한 뒤, `fighterFactory.js`에서 팀 색상으로 tint 처리합니다.
|
||||
- **`fighterFactory.js`**: 캐릭터 히트박스, 이름표, 체력바, 팀 색상 마커 sprite를 생성하고 매 프레임 위치/스케일/방향을 동기화합니다. 이름표는 스프라이트 중심이 아니라 실제 히트박스 하단에 고정됩니다. 사망한 캐릭터의 HUD와 팀 색상 마커는 숨겨 전투 화면을 덜 가리게 합니다. 생성 옵션의 `hp`, `maxHp`, `canSplitOnDeath`를 통해 개별 전투원의 체력과 분열 가능 여부를 지정할 수 있습니다.
|
||||
- **`fighterManifest.js`**: 20여 종의 캐릭터 스킨 정보가 담긴 딕셔너리입니다. 각 스킨은 사망 통계용 `species`를 가지며, `combat.type` (melee/projectile/instant-spell)에 따라 전투 메커니즘이 결정됩니다. `stats`와 `traits`로 캐릭터별 기본 체력과 특수 규칙을 정의합니다.
|
||||
- **`matchForm.js`**: `index.html`의 입력을 읽어 `ArenaScene`에 매치 구성을 전달하고, 검증/결과 상태 메시지를 DOM에 반영할 수 있는 setter를 제공합니다. 팀당 인원 숫자 입력과 range 슬라이더를 같은 `1~100` 범위로 동기화하며, 참가자 닉네임, 팀당 인원, 리스폰 배치 모드는 브라우저 `localStorage`에 저장/복원합니다. 실제 전투 중 하단 안내바는 숨기고, 처치 내역은 `ArenaScene`의 좌측 하단 킬로그가 담당합니다.
|
||||
- **`deathStats.js`**: `GET /api/death-stats/today`, `POST /api/death-stats/today`를 호출하는 프론트엔드 API 래퍼입니다.
|
||||
- **`visitorCounter.js`**: `POST /api/visitors/check`를 호출하고, 응답의 `uniqueVisitors` 값을 전투 화면 우측 하단의 `#visitor-count` 배지에 표시합니다.
|
||||
|
||||
## 2. 주요 로직 구현 세부 사항
|
||||
|
||||
### 지능형 카메라 추적 (Lerp & Jittering 방지)
|
||||
카메라가 소수점 단위의 평균 좌표를 즉시 따라가면 화면이 떨려 보일 수 있습니다. 이를 방지하기 위해:
|
||||
1. 목표 좌표(`targetX, targetY`)를 `Math.round()`로 정수화합니다.
|
||||
2. 현재 카메라 위치에서 목표 지점까지 매 프레임 `0.1`의 배율로 거리를 좁혀나가는 `Lerp` 연산을 수행합니다.
|
||||
```javascript
|
||||
this.cameras.main.scrollX += (targetX - this.cameras.main.midPoint.x) * SPECTATOR_CAMERA_LERP;
|
||||
```
|
||||
|
||||
최종교전 관전은 두 단계로 나뉩니다. 생존 4명 이하에서는 `SPECTATOR_RANDOM_FOCUS_INTERVAL`마다 생존 캐릭터 중 한 명을 무작위로 포커싱합니다. 잔여 팀이 2팀이고 생존 합이 8명 이하인 구간에서는 더 적은 생존 수를 가진 팀의 중앙을 포커싱하며, 동률이면 기존 교전쌍 중심 포커싱으로 되돌아갑니다. `FINAL_COMBAT_SLOW_MOTION_ENABLED`를 켜면 최종교전 상태에서 `combat.js`가 공격 모션을 시작할 때 전역 time scale을 `FINAL_COMBAT_SLOW_MOTION_SCALE`까지 낮추고, 타격과 이동이 느린 구간에 남도록 유지한 뒤 복귀 램프로 기본 속도에 돌아갑니다.
|
||||
|
||||
### 미니맵 가이드라인
|
||||
미니맵은 전장 전체를 축소하여 보여주는 독립된 카메라입니다. 주 카메라가 비추는 영역을 계산하여 미니맵 위에 사각형(`graphics`)을 그려줍니다.
|
||||
- `camera.displayWidth / zoom` 등을 이용하여 현재 월드에서 보이는 실제 영역 크기를 계산합니다.
|
||||
- 뷰포트 사각형 좌표는 미니맵 픽셀 격자에 맞춰 반올림하고, 외곽 stroke가 겹쳐 검게 깨지지 않도록 노란 내부 선을 채운 직사각형으로 렌더링합니다.
|
||||
|
||||
### 전투 진입 UI와 HUD 레이아웃
|
||||
초기 화면은 로컬 저장 옵션과 분리된 10팀 x 팀당 5명 Phaser 프리뷰 전투와 CSS 스프라이트 프리뷰를 낮은 투명도의 배경으로 깔고, 중앙에 `Arena` 로고와 `Start` 버튼을 둡니다.
|
||||
|
||||
1. `Start` 클릭 시 `#app.options-open`이 설정되고 우측 옵션 drawer가 열립니다. 홈에서 drawer가 열린 상태에서는 `Start` 버튼을 숨기되 중앙 `Arena` 로고 위치는 유지합니다.
|
||||
2. `전투 시작` 제출 시 `#app.match-live`가 설정되며 실제 전투가 시작됩니다. drawer는 닫히지 않고 우측 compact 패널로 유지됩니다.
|
||||
3. 전투 중 drawer 우측 상단의 `옵션 접기/옵션 펼치기` 버튼으로 설정 패널을 접거나 다시 펼칩니다. 접힌 상태에서는 같은 우측 상단 위치에 토글 버튼만 남아 전투 화면을 가리지 않습니다.
|
||||
4. drawer 안의 `재시작` 버튼은 현재 입력값으로 새 매치를 시작합니다.
|
||||
5. drawer 안의 `일시정지` 버튼은 `ArenaScene.togglePause()`를 호출하고, 정지 중에는 버튼 문구를 `계속`으로 바꾸며 `#app.match-paused`를 설정합니다.
|
||||
6. 참가자 닉네임과 팀당 인원은 입력이 바뀔 때마다 `localStorage`에 저장하고 앱 로드 시 먼저 복원합니다. 팀당 인원은 숫자 입력과 range 슬라이더가 즉시 동기화되며, 복원된 값은 옵션 폼과 실제 전투에만 쓰고 최초 대기 전투 프리뷰 설정은 바꾸지 않습니다.
|
||||
7. 팀 badge는 경기장 캔버스 위가 아니라 좌측 HUD 레일에 배치합니다. 레일 폭은 CSS 변수 `--score-panel-width`, `--score-rail-width`로 계산되며 미니맵과 겹치지 않습니다.
|
||||
8. badge는 팀명, 팀 색상 구분선, 생존 인원 순서로 표기하고, 클릭 시 해당 팀 생존 전투원 중 무작위 1명으로 관전 시점을 고정합니다.
|
||||
9. 전투 중 하단 `match-status` 안내바는 숨깁니다. 처치가 발생하면 좌측 하단 `kill-log`가 처치자와 피처치자를 좌우로 나누고, 각 항목에 작은 idle 스프라이트 이미지, 팀명, `manifest.key`를 표시합니다. 중앙에는 칼 아이콘과 `처치` 텍스트를 두며, 오른쪽 피처치자 아이콘에는 빨간 X를 겹쳐 왼쪽 캐릭터가 처치했다는 관계를 명확히 보여줍니다.
|
||||
10. 실제 전투가 5초 이상 지속되면 `#battle-notice` 상단 안내바가 표시됩니다. 문구는 오늘 서버 집계와 현재 전투의 사망 수를 합산한 뒤 가장 많이 사망한 종족을 기준으로 생성하며, 전투 화면보다 넓어 보이지 않는 작은 폭으로 2초 표시 후 10초 대기하는 주기로 다음 문구를 보여줍니다.
|
||||
11. 방문자 수는 메인 화면에서는 숨기고, 실제 전투 중에만 우측 하단의 작은 `#visitor-count` 배지로 표시합니다.
|
||||
12. 승리 판정이 나면 `ArenaScene`이 기존 결과 레이어를 정리한 뒤 `.victory-celebration`을 생성합니다. `styles.css`는 중앙 결과 배너, 회전 광선, 컨페티 burst, 축소 모션 설정을 담당하고, 무승부 상태는 같은 레이아웃을 더 조용한 톤으로 재사용합니다.
|
||||
|
||||
### 상시 팀 색상 실루엣
|
||||
팀 색상 표시는 히트박스 사각형이 아니라 캐릭터 모양을 따라가는 별도 spritesheet입니다.
|
||||
|
||||
1. `fighterAssets.js`가 로드된 원본 스프라이트시트의 alpha 데이터를 캔버스에서 읽습니다.
|
||||
2. 원본 alpha 픽셀 주변 `SELECTED_FIGHTER_OUTLINE_GAP` 범위는 공백 마스크로 남깁니다.
|
||||
3. 그 바깥 `SELECTED_FIGHTER_OUTLINE_WIDTH` 범위에만 흰색 outline을 칠합니다.
|
||||
4. `fighterFactory.js`가 생존 캐릭터 뒤에 `teamMarker` sprite를 배치하고, 팀 색상으로 tint 처리합니다.
|
||||
5. `syncFighterHud()`가 현재 texture frame, flip 방향, scale, 위치를 원본 캐릭터와 동기화합니다.
|
||||
6. 사망 캐릭터는 팀 색상 마커와 HUD를 숨기며, 본체 sprite만 낮은 depth와 반투명 상태로 남깁니다.
|
||||
|
||||
이 방식은 별도 에셋 없이도 캐릭터 모양에 맞춘 팀 색상 마커를 만들 수 있으며, 캐릭터가 처치 보상으로 커져도 마커가 같은 배율로 따라갑니다. 캐릭터 클릭은 카메라 포커스 기능만 담당하고, 팀 색상 마커는 선택 여부와 관계없이 유지됩니다.
|
||||
|
||||
### 캐릭터별 특성: Slime
|
||||
Slime은 `fighterManifest.js`의 `stats`와 `traits`로 특수 규칙을 선언합니다.
|
||||
|
||||
- `stats.maxHp: 1`: 처음 배정되어 스폰되는 Slime과 분열로 생성되는 Slime 모두 최대 체력이 1입니다.
|
||||
- `traits.spawnMultiplier: 10`: Slime 스킨이 배정된 기본 스폰 슬롯 1개를 실제 Slime 10마리로 확장합니다.
|
||||
- `traits.splitOnDeath.chance: 0.5`: Slime이 사망할 때 50% 확률로 분열합니다.
|
||||
- `traits.splitOnDeath.count: 2`: 분열 성공 시 같은 팀의 Slime 2마리를 사망 위치 근처에 생성합니다.
|
||||
- `traits.splitOnDeath.childMaxHp: 1`: 분열체도 최대 체력 1로 생성됩니다.
|
||||
- `traits.splitOnDeath.childCanSplit: false`: 분열체는 다시 분열하지 않습니다.
|
||||
|
||||
처치 보상은 최대 체력을 증가시키지 않습니다. `applyKillReward()`는 현재 체력을 `maxHp` 상한 안에서 회복하고, 처치 누적 배율로 크기/공격속도/이동속도만 증가시킵니다. 배율은 `KILL_GROWTH_MAX_MULTIPLIER`로 제한되므로 Slime이 적을 처치해도 최대 체력은 1로 유지되고, 장기전에서 캐릭터 scale/속도가 무한정 커지지 않습니다.
|
||||
|
||||
### 유니크 방문자 체크
|
||||
브라우저가 직접 MongoDB에 연결하지 않고, Fastify API가 MongoDB 커넥션 풀을 유지합니다.
|
||||
|
||||
1. 프론트엔드가 앱 로드 시 `POST /api/visitors/check`를 호출합니다.
|
||||
2. 서버가 `arena_visitor_id` 쿠키를 검사합니다.
|
||||
3. 쿠키가 없거나 유효하지 않으면 `crypto.randomUUID()`로 새 방문자 ID를 만들고 `HttpOnly` 쿠키로 내려줍니다.
|
||||
4. MongoDB에는 `_id`, `firstSeenAt`, `lastSeenAt`, `visits`, `firstUserAgent`, `lastUserAgent`를 저장합니다.
|
||||
5. `countDocuments()`로 전체 유니크 방문자 수를 계산해 반환합니다.
|
||||
|
||||
방문자 체크는 인증 기능이 아니며, 브라우저/쿠키 단위의 단순 유니크 카운트입니다.
|
||||
|
||||
### 전투 사망 통계
|
||||
프리뷰 전투는 통계에서 제외하고, 사용자가 시작한 실제 전투만 저장합니다.
|
||||
|
||||
1. `fighterManifest.js`의 모든 스킨은 `species`를 가집니다. 사용 가능한 값은 `human`, `orc`, `skeleton`, `slime`, `wolf`, `bear`입니다.
|
||||
2. `combat.js`의 처치 흐름이 `ArenaScene.recordKill()`을 호출하면, `ArenaScene`은 피처치자의 `skin.species`를 현재 전투의 `battleDeathCounts`에 누적합니다.
|
||||
3. 전투가 5초 이상 이어지면 `GET /api/death-stats/today`로 가져온 오늘 집계와 현재 전투의 사망 수를 합산해 `#battle-notice`에 표시합니다.
|
||||
4. 전투 종료 시 `POST /api/death-stats/today`로 `deathsBySpecies`만 보냅니다.
|
||||
5. 서버는 별도의 매치별 문서를 만들지 않고, `daily_death_stats` 컬렉션에서 오늘 일자의 `battles`, `totalDeaths`, `deathsBySpecies.*` 값을 `$inc`로 갱신합니다.
|
||||
|
||||
## 3. 개발 및 유지보수 규칙
|
||||
- **신규 캐릭터 추가**: `public/assets/characters/`에 에셋 배치 후 `fighterManifest.js`에 정의를 추가하면 즉시 게임에 반영됩니다.
|
||||
- **종족값 유지**: 신규 스킨을 추가할 때는 사망 통계가 누락되지 않도록 `species`를 `human`, `orc`, `skeleton`, `slime`, `wolf`, `bear` 중 하나로 지정해야 합니다.
|
||||
- **물리 수치 조정**: 캐릭터의 속도나 사거리 등은 `src/constants.js` 또는 `fighterManifest.js` 내 개별 설정을 통해 변경하십시오.
|
||||
- **처치 성장 상한 조정**: 처치 보상으로 캐릭터가 커지는 최대치와 공격/이동 배율 상한은 `src/constants.js`의 `KILL_GROWTH_MAX_MULTIPLIER`를 수정합니다.
|
||||
- **공격력 조정**: 기본 피해량은 `src/constants.js`의 `ATTACK_DAMAGE_MIN`, `ATTACK_DAMAGE_MAX`를 수정합니다. 캐릭터별 특수 공격 방식은 `fighterManifest.js`의 `combat` 설정을 우선 확인합니다.
|
||||
- **캐릭터별 스탯/특성 추가**: 기본 체력은 `fighterManifest.js`의 `stats.maxHp`에 정의하고, 스폰 배율이나 사망 분열 같은 특성은 `traits`에 선언합니다. 전투 중 새 전투원을 만들 필요가 있는 특성은 `ArenaScene.js`의 생성 헬퍼를 통해 `this.fighters`와 `team.size`를 함께 갱신해야 합니다.
|
||||
- **DOM 접근**: 성능을 위해 `ArenaScene`은 좌측 HUD badge 등 필요한 시점에만 최소한으로 DOM에 접근합니다.
|
||||
- **서버 설정**: `.env` 대신 `config.json`을 사용합니다. `config.json`은 로컬 전용 파일이며, 저장소에는 `config.json.sample`만 공유합니다.
|
||||
- **패키지 락 파일**: 이 프로젝트는 `package-lock.json`을 저장소에서 제외합니다. 의존성 변경 시 `package.json`을 기준으로 관리합니다.
|
||||
- **기본 포트**: `SERVER_PORT` 기본값은 `9736`입니다.
|
||||
- **MongoDB 연결**: DB 접속 정보는 `config.json`의 `MONGODB_HOST`, `MONGODB_PORT`, `MONGODB_DB`, 선택적 `MONGODB_USER`, `MONGODB_PASS`로 관리합니다.
|
||||
- **API 변경**: `/api/*` 경로는 Fastify 라우트가 담당합니다. 개발 모드에서 Vite 미들웨어가 API 요청을 SPA HTML로 처리하지 않도록 서버 라우팅 순서를 유지해야 합니다. 전투 사망 통계 API는 MongoDB 설정이 없으면 방문자 통계와 마찬가지로 503 응답을 반환합니다.
|
||||
27
agent.md
27
agent.md
|
|
@ -62,25 +62,16 @@
|
|||
└── visitorCounter.js # 방문자 체크 API 호출 및 표시
|
||||
```
|
||||
|
||||
## 3. 핵심 기능
|
||||
## 3. 상세 기술 가이드 (Context Routing)
|
||||
|
||||
- **닉네임 기반 팀 스폰**: 입력된 각 닉네임을 독립된 팀으로 인식하고, 설정된 인원(1~100명)만큼 분신 캐릭터를 소환합니다. 리스폰 설정은 참가자별 전장 구역 안에서 시작하되 참가자별 시작 구역 배정도 매치마다 섞는 `스타팅 지점 배치`와 전장 전체에서 섞이는 `완전 랜덤 배치`를 지원합니다. 캐릭터 특성에 따라 실제 출전 수가 달라질 수 있으며, Slime은 배정된 기본 스폰 슬롯마다 10마리로 확장됩니다.
|
||||
- **전투 진입 및 제어 UI**: 최초 접속 화면은 로컬 저장 옵션과 분리된 10팀 x 팀당 5명 전투 프리뷰를 배경으로 `Arena` 로고와 `Start` 버튼을 표시합니다. `Start`를 누르면 우측 옵션 drawer가 열리고, 홈에서 drawer가 열린 동안 `Start` 버튼은 숨기되 `Arena` 로고 위치는 유지합니다. 전투 시작 후에도 drawer는 compact 패널로 유지됩니다. 패널 우측 상단의 `옵션 접기/옵션 펼치기` 버튼으로 전장 시야를 확보할 수 있으며, 패널 안에서 `재시작`과 `일시정지/계속`을 제어합니다.
|
||||
- **전투 설정 유지**: 참가자 닉네임, 숫자 입력과 슬라이더가 동기화되는 팀당 인원, 리스폰 배치 모드는 브라우저 `localStorage`에 저장되어 새로고침하거나 다시 접속해도 입력값이 유지됩니다.
|
||||
- **지능형 카메라 시스템**:
|
||||
- **자동 전투 관전**: 화면 확대 시 인접한 교전 중인 캐릭터 쌍을 찾아 부드럽게 추적(Lerp)합니다.
|
||||
- **미니맵 연동**: 줌 인 상태에서 전장 전체 상황과 현재 뷰포트 위치를 미니맵에 가이드라인으로 표시합니다.
|
||||
- **최종교전 연출**: 생존 4명 이하에서는 카메라가 생존 캐릭터를 무작위로 전환 포커싱하고, 잔여 2팀의 생존 합이 8명 이하이면 생존 수가 더 적은 팀을 포커싱합니다. `FINAL_COMBAT_SLOW_MOTION_ENABLED`를 켜면 이 최종교전 구간의 공격 시작에 진입/유지/복귀 완급이 있는 슬로우모션을 적용합니다.
|
||||
- **역동적인 전투 연출**:
|
||||
- 캐릭터별 고유 공격 방식(근접, 투사체, 마법) 및 애니메이션.
|
||||
- `ATTACK_DAMAGE_MIN/MAX`로 기본 공격력 범위를 관리하고, 치명타(Critical) 적중 시 `Critical!` 문구를 띄우며 즉시 처치 및 화면 흔들림 효과를 적용합니다.
|
||||
- 상대를 처치한 캐릭터는 체력을 현재 체력 기준 30% 회복하고, 처치 누적 배율에 따라 크기, 공격속도, 이동속도가 함께 상승합니다. 누적 보상은 `KILL_GROWTH_MAX_MULTIPLIER` 상한으로 제한해 캐릭터가 필드/히트박스를 벗어나 전투가 끝나지 않는 상황을 방지합니다.
|
||||
- 캐릭터별 종족(`human`, `orc`, `skeleton`, `slime`, `wolf`, `bear`)과 스탯/특성을 `fighterManifest.js`에서 정의할 수 있습니다. Slime은 최대 체력 1이며, 사망 시 50% 확률로 최대 체력 1인 Slime 2마리로 분열합니다. 분열체는 다시 분열하지 않습니다.
|
||||
- 사망한 캐릭터는 반투명하게 표시하고 살아있는 캐릭터보다 낮은 depth로 내려, 움직이는 전투원을 가리지 않도록 유지합니다.
|
||||
- **상시 팀 색상 표시 및 선택 관전**: 생존 캐릭터는 항상 팀 색상 실루엣 마커를 표시합니다. 캐릭터를 클릭하면 해당 캐릭터에 카메라가 고정되며, 팀 색상 마커는 선택 여부와 관계없이 유지됩니다. 좌측 팀 badge를 클릭하면 해당 팀의 생존 캐릭터 중 무작위 1명으로 시점이 고정됩니다.
|
||||
- **실시간 경기 중계 UI**: 팀 badge는 경기장 밖 좌측 HUD 레일에 고정되어 미니맵을 가리지 않습니다. 각 badge는 팀명, 구분선, 현재 생존 인원 순서로 표시되며, 클릭 가능한 관전 진입점으로 동작합니다. 전투 중 하단 안내바는 숨기고, 좌측 하단 킬로그에 처치자와 피처치자를 좌우로 나눠 작은 캐릭터 이미지, 팀명, `manifest.key`, 칼 아이콘, `처치` 표시를 목록으로 보여줍니다. 피처치자 아이콘에는 빨간 X를 겹쳐 사망 대상을 빠르게 구분합니다. 실제 전투가 5초 이상 지속되면 작은 상단 안내바에 오늘의 종족별 사망 집계를 2초 표시하고 10초 쉬는 주기로 재치 있게 보여줍니다. 승리 시 금빛 축하 배너와 컨페티, 짧은 팡파르로 결과를 알리고 무승부는 절제된 배너로 표시합니다.
|
||||
- **유니크 방문자 체크**: 접속 시 `POST /api/visitors/check`를 호출하고, 서버가 `HttpOnly` 쿠키 기반 UUID로 MongoDB에 방문자 1명당 1개 문서를 유지합니다. 방문자 수는 메인 화면이 아니라 실제 전투 화면의 우측 하단에 작은 배지로 표시합니다.
|
||||
- **전투 사망 통계**: 실제 전투에서 사망한 캐릭터를 종족별로 누적하고, 전투 종료 시 `POST /api/death-stats/today`로 오늘 일자별 집계 문서에 카운트를 더합니다. 별도의 매치별 사망 통계 문서는 저장하지 않습니다.
|
||||
토큰 절약 및 효율적인 정보 조회를 위해 상세 로직은 기능별로 분리되어 보관됩니다. 특정 모듈 작업 시 아래의 관련 문서를 먼저 읽으십시오.
|
||||
|
||||
- **[인프라 및 전역 설정] [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. 기술 사양
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,30 @@
|
|||
# Context: Arena & Scene
|
||||
|
||||
## 1. 모듈별 상세 역할 (`src/game/arena/`)
|
||||
|
||||
- **`ArenaScene.js`**: Phaser 씬의 생명주기와 전반적인 오케스트레이션을 담당합니다. `update()` 매 프레임마다 전투원 상태를 체크하고, 카메라 이동 및 UI 모듈 호출을 조율합니다.
|
||||
- **`arenaRenderer.js`**: 아레나 배경 그래픽 및 타일 렌더링을 담당합니다.
|
||||
- **`arenaSpectatorCamera.js`**: 관전 모드 시점 계산 및 카메라 포커싱 로직을 담당합니다. 생존 인원에 따른 지능형 카메라 추적 알고리즘이 구현되어 있습니다.
|
||||
|
||||
## 2. 주요 로직 구현 세부 사항
|
||||
|
||||
### 지능형 카메라 추적 (Lerp & Jittering 방지)
|
||||
카메라가 소수점 단위의 평균 좌표를 즉시 따라가면 화면이 떨려 보일 수 있습니다. 이를 방지하기 위해:
|
||||
1. 목표 좌표(`targetX, targetY`)를 `Math.round()`로 정수화합니다.
|
||||
2. 현재 카메라 위치에서 목표 지점까지 매 프레임 `0.1`의 배율로 거리를 좁혀나가는 `Lerp` 연산을 수행합니다.
|
||||
```javascript
|
||||
this.cameras.main.scrollX += (targetX - this.cameras.main.midPoint.x) * SPECTATOR_CAMERA_LERP;
|
||||
```
|
||||
|
||||
최종교전 관전은 두 단계로 나뉩니다.
|
||||
- **생존 4명 이하**: `SPECTATOR_RANDOM_FOCUS_INTERVAL`마다 생존 캐릭터 중 한 명을 무작위로 포커싱합니다.
|
||||
- **2팀 잔여 & 합계 8명 이하**: 더 적은 생존 수를 가진 팀의 중앙을 포커싱하며, 동률이면 기존 교전쌍 중심 포커싱으로 되돌아갑니다.
|
||||
|
||||
### 미니맵 가이드라인
|
||||
미니맵은 전장 전체를 축소하여 보여주는 독립된 카메라입니다. 주 카메라가 비추는 영역을 계산하여 미니맵 위에 사각형(`graphics`)을 그려줍니다.
|
||||
- `camera.displayWidth / zoom` 등을 이용하여 현재 월드에서 보이는 실제 영역 크기를 계산합니다.
|
||||
- 뷰포트 사각형 좌표는 미니맵 픽셀 격자에 맞춰 반올림하고, 외곽 stroke가 겹쳐 검게 깨지지 않도록 노란 내부 선을 채운 직사각형으로 렌더링합니다.
|
||||
|
||||
### 씬 상태 관리
|
||||
- **프리뷰 모드 (`presentationMode`)**: 최초 로드 시 조용히 실행되는 배경 전투입니다. 로컬 저장 옵션과 무관하게 10팀 x 5명 고정 규모로 동작합니다.
|
||||
- **일시정지 (`setPaused`)**: 실제 전투에서 물리, Phaser 타이머, tween, 스프라이트 애니메이션을 함께 제어합니다. 프리뷰 및 종료된 전투는 제외됩니다.
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# Context: Combat System
|
||||
|
||||
## 1. 모듈별 상세 역할 (`src/game/combat/`)
|
||||
|
||||
- **`combat.js`**: 전투 AI, 피해 계산, 처치 보상 등 핵심 전투 로직을 담당합니다. 유닛의 이동, 공격, 투사체 발사 등을 처리합니다.
|
||||
- **`combatSettings.js`**: 전투 속도 배율 등 런타임 전투 설정을 관리합니다.
|
||||
- **`arenaFinalCombatEffects.js`**: 최종 교전 시 슬로우 모션 등 연출 효과를 담당합니다. 수학적인 이징(easing) 함수와 물리 시간 배율 계산을 포함합니다.
|
||||
|
||||
## 2. 주요 로직 구현 세부 사항
|
||||
|
||||
### 전투 AI 및 유닛 동작
|
||||
- **`updateFighter()`**: 가장 가까운 적을 찾아 이동하거나 공격하는 유닛 AI의 핵심입니다.
|
||||
- **`applyHit()`**: 일반 공격 피해량은 `ATTACK_DAMAGE_MIN/MAX` 범위에서 계산하고, 치명타 적중은 `Critical!` 표기와 즉시 처치/카메라 흔들림을 처리합니다.
|
||||
- **`projectilePathHitsDefender()`**: 투사체가 대상을 스쳐 지나가지 않도록 궤적(Line)과 히트박스(Rectangle) 겹침 검사를 수행합니다.
|
||||
|
||||
### 처치 보상 및 성장
|
||||
- **`applyKillReward()`**: 처치한 캐릭터의 체력 회복(현재 체력 30%), 크기 증가, 공격속도/이동속도 배율 증가를 처리합니다. 누적 배율은 `KILL_GROWTH_MAX_MULTIPLIER`로 제한합니다.
|
||||
- **`clampFighterInsideArena()`**: 처치 성장 중 커진 캐릭터가 전장 바깥으로 나가지 않도록 위치를 보정합니다.
|
||||
|
||||
### 최종교전 슬로우모션
|
||||
`FINAL_COMBAT_SLOW_MOTION_ENABLED`가 활성화된 경우:
|
||||
- 최종교전 상태에서 공격 모션이 시작될 때 전역 time scale을 낮춥니다.
|
||||
- 진입/유지/복귀 속도 램프(Ease)를 적용합니다.
|
||||
- Arcade Physics는 timeScale 방향이 반대라 물리 이동에는 역수 배율을 적용합니다.
|
||||
|
||||
## 3. 유지보수 규칙
|
||||
- **처치 성장 상한**: `src/constants.js`의 `KILL_GROWTH_MAX_MULTIPLIER`를 수정합니다.
|
||||
- **공격력 조정**: `src/constants.js`의 `ATTACK_DAMAGE_MIN/MAX`를 수정합니다.
|
||||
- **특수 규칙**: 캐릭터별 특수 공격 방식은 `fighterManifest.js`의 `combat` 설정을 확인합니다.
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
# Context: Core & Infrastructure
|
||||
|
||||
## 1. 모듈별 상세 역할
|
||||
|
||||
- **`src/main.js`**: Phaser 게임의 전역 설정(Physics, Scale, Canvas Parent)을 담당하며, `ArenaScene`을 인스턴스화합니다.
|
||||
- 앱 로드 시 `trackVisitor()`를 호출해 방문자 체크 API와 연동합니다.
|
||||
- `Start` 버튼, 옵션 drawer, 전투 시작 submit 흐름을 제어하며 전투 시작 시 `#app`에 `match-live` 상태 클래스를 부여합니다.
|
||||
- 전투 중 drawer 접기/펼치기(`drawer-collapsed`), 재시작 버튼, 일시정지 버튼 상태(`match-paused`)를 DOM 클래스와 `ArenaScene` 상태에 동기화합니다.
|
||||
- **`src/constants.js`**: 게임 내 모든 튜닝 수치를 관리합니다.
|
||||
- `ATTACK_DAMAGE_MIN`, `ATTACK_DAMAGE_MAX`: 일반 공격 1회 적중 시 적용되는 랜덤 피해량 범위.
|
||||
- `FIGHTER_HITBOX_*`: 100x100 캐릭터 프레임 안에서 실제 충돌 판정이 놓이는 위치와 크기.
|
||||
- `KILL_HEALTH_RECOVERY_RATIO`, `KILL_GROWTH_MULTIPLIER`, `KILL_GROWTH_MAX_MULTIPLIER`: 처치 후 회복량, 크기/공격속도/이동속도 성장 배율, 누적 보상 상한.
|
||||
- `SELECTED_FIGHTER_OUTLINE_GAP`, `SELECTED_FIGHTER_OUTLINE_WIDTH`, `SELECTED_FIGHTER_OUTLINE_ALPHA`: 팀 색상 실루엣 마커의 캐릭터 이격 거리, 두께, 투명도.
|
||||
- `TEAM_COLORS`, `getTeamColor()`: 8팀 이하에서는 기본 팔레트를 쓰고, 9팀 이상에서는 팀 수에 맞춰 중복 없는 색상을 동적으로 생성합니다.
|
||||
- `SPECTATOR_CAMERA_LERP`: 카메라 추적의 부드러움 정도.
|
||||
- `SPECTATOR_FINAL_TEAM_TOTAL_THRESHOLD`, `SPECTATOR_RANDOM_FOCUS_INTERVAL`, `FINAL_COMBAT_SLOW_MOTION_*`: 최종교전 관전 조건, 랜덤 포커싱 간격, 슬로우모션 on/off, 배율과 속도 램프 시간.
|
||||
- `MINIMAP_VIEWPORT_SIZE`: 미니맵의 고정 픽셀 크기.
|
||||
- `ARENA_SIZE`: 경기장 전체 크기 (GRID * TILE).
|
||||
|
||||
## 2. 개발 및 유지보수 규칙
|
||||
|
||||
- **신규 캐릭터 추가**: `public/assets/characters/`에 에셋 배치 후 `fighterManifest.js`에 정의를 추가하면 즉시 게임에 반영됩니다.
|
||||
- **종족값 유지**: 신규 스킨을 추가할 때는 사망 통계가 누락되지 않도록 `species`를 `human`, `orc`, `skeleton`, `slime`, `wolf`, `bear` 중 하나로 지정해야 합니다.
|
||||
- **물리 수치 조정**: 캐릭터의 속도나 사거리 등은 `src/constants.js` 또는 `fighterManifest.js` 내 개별 설정을 통해 변경하십시오.
|
||||
- **처치 성장 상한 조정**: 처치 보상으로 캐릭터가 커지는 최대치와 공격/이동 배율 상한은 `src/constants.js`의 `KILL_GROWTH_MAX_MULTIPLIER`를 수정합니다.
|
||||
- **공격력 조정**: 기본 피해량은 `src/constants.js`의 `ATTACK_DAMAGE_MIN`, `ATTACK_DAMAGE_MAX`를 수정합니다. 캐릭터별 특수 공격 방식은 `fighterManifest.js`의 `combat` 설정을 우선 확인합니다.
|
||||
- **DOM 접근**: 성능을 위해 `ArenaScene`은 좌측 HUD badge 등 필요한 시점에만 최소한으로 DOM에 접근합니다.
|
||||
- **패키지 락 파일**: 이 프로젝트는 `package-lock.json`을 저장소에서 제외합니다. 의존성 변경 시 `package.json`을 기준으로 관리합니다.
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
# Context: Fighter & Assets
|
||||
|
||||
## 1. 모듈별 상세 역할 (`src/game/fighter/`)
|
||||
|
||||
- **`fighterAssets.js`**: 캐릭터 스프라이트 로드 및 애니메이션/실루엣 생성을 담당합니다. 원본 이미지로부터 팀 색상 마커용 실루엣을 동적으로 생성합니다.
|
||||
- **`fighterFactory.js`**: 캐릭터 인스턴스화 및 HUD(이름표, 체력바) 관리를 담당합니다. Phaser Sprite와 DOM UI 사이의 가교 역할을 합니다.
|
||||
- **`fighterManifest.js`**: 모든 캐릭터 종족 및 스탯 데이터를 정의합니다. 20여 종의 캐릭터 설정이 포함되어 있습니다.
|
||||
- **`fighterSelection.js`**: 매치 참여 캐릭터를 무작위로 선택하거나 섞는 로직을 담당합니다.
|
||||
|
||||
## 2. 주요 로직 구현 세부 사항
|
||||
|
||||
### 동적 팀 실루엣 생성
|
||||
팀 색상 표시는 캐릭터 모양을 정교하게 따라가는 별도 spritesheet입니다.
|
||||
1. `fighterAssets.js`가 로드된 원본 스프라이트의 alpha 데이터를 캔버스에서 읽습니다.
|
||||
2. 원본 alpha 픽셀 주변 `SELECTED_FIGHTER_OUTLINE_GAP`은 비우고, 그 바깥 `SELECTED_FIGHTER_OUTLINE_WIDTH`에만 흰색 outline을 칠합니다.
|
||||
3. `fighterFactory.js`에서 생성된 캐릭터 뒤에 배치하고 팀 색상으로 tint 처리합니다.
|
||||
4. 캐릭터가 성장하여 커져도 같은 배율로 실루엣이 유지됩니다.
|
||||
|
||||
### 캐릭터 HUD 및 상태 동기화
|
||||
- **이름표 고정**: 스프라이트 중심이 아닌 실제 히트박스 하단에 고정되어 시각적 일관성을 유지합니다.
|
||||
- **사망자 처리**: 사망 시 HUD와 팀 마커를 숨겨 화면 가독성을 높입니다. 본체 sprite만 낮은 depth와 반투명 상태로 남깁니다.
|
||||
|
||||
### 캐릭터별 특성 (예: Slime)
|
||||
- **`spawnMultiplier`**: 배정된 슬롯 1개를 지정된 수만큼 확장하여 스폰합니다.
|
||||
- **`splitOnDeath`**: 사망 시 확률적으로 지정된 수만큼 분열체를 생성합니다.
|
||||
- **스탯 상한**: 처치 보상은 현재 체력을 회복시키지만 `maxHp`를 넘을 수 없습니다. (예: Slime은 항상 1 HP)
|
||||
|
||||
## 3. 유지보수 규칙
|
||||
- **신규 캐릭터**: 에셋 배치 후 `fighterManifest.js`에 정의를 추가합니다.
|
||||
- **종족값**: 사망 통계를 위해 지정된 6개 종족 중 하나를 반드시 선택해야 합니다.
|
||||
- **캐릭터 특성**: 전투 중 새 유닛을 생성하는 특성은 `ArenaScene.js`의 생성 헬퍼를 통해 `this.fighters`와 `team.size`를 함께 갱신해야 합니다.
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
# Context: Match & UI
|
||||
|
||||
## 1. 모듈별 상세 역할
|
||||
|
||||
### 매치 로직 (`src/game/match/`)
|
||||
- **`matchSetup.js`**: 매치 초기화, 팀 구성, 스폰 위치 계산을 담당합니다.
|
||||
- **`arenaMatchRuntime.js`**: 스폰 클러스터 계산 및 팀 크기 동기화 등 매치 진행 중 헬퍼 기능을 제공합니다.
|
||||
|
||||
### UI 컴포넌트 (`src/ui/`)
|
||||
- **`matchForm.js`**: 설정 폼 제어 및 `localStorage` 설정 유지.
|
||||
- **`arenaScoreboard.js`**: 좌측 HUD 레일의 팀 badge 업데이트 및 관전 시점 전환.
|
||||
- **`arenaKillLog.js`**: 좌측 하단 킬로그 표시 및 관리.
|
||||
- **`battleDeathNotice.js`**: 상단 사망 통계 공지 UI.
|
||||
- **`victoryCelebration.js`**: 승리/무승부 축하 연출 (광선, 컨페티, 오디오).
|
||||
|
||||
## 2. 주요 로직 구현 세부 사항
|
||||
|
||||
### 매치 설정 및 스폰 배치
|
||||
- **완전 랜덤 배치**: 전장 전체 스폰 슬롯을 무작위로 섞어 배치합니다.
|
||||
- **스타팅 지점 배치**: 참가자 수에 맞춰 전장을 구역으로 나눈 뒤, 참가자별 구역 배정을 매치마다 섞고 구역 내 무작위 위치에 스폰합니다.
|
||||
- **설정 유지**: 닉네임, 인원, 배치 모드는 `localStorage`에 저장되어 재접속 시 복원됩니다.
|
||||
|
||||
### 전투 화면 레이아웃 (HUD)
|
||||
- **팀 Badge**: 좌측 HUD 레일에 배치되며, 클릭 시 해당 팀의 생존 유닛 중 무작위 1명으로 시점을 고정합니다.
|
||||
- **킬로그**: 처치자와 피처치자를 좌우로 배치하고, 피처치자 아이콘에 빨간 X를 겹쳐 사망 관계를 명확히 표시합니다.
|
||||
- **승리 연출**: 승리 시 Web Audio 기반 팡파르와 CSS 애니메이션(광선, 컨페티)을 결합해 화려하게 연출합니다. 무승부는 더 차분한 톤을 사용합니다.
|
||||
|
||||
## 3. UI 개발 규칙
|
||||
- **DOM 접근 최소화**: 성능 최적화를 위해 필요한 시점에만 최소한으로 DOM을 업데이트합니다.
|
||||
- **반응형 상태**: `#app`의 클래스(`match-live`, `options-open`, `drawer-collapsed`, `match-paused`)를 통해 전반적인 UI 상태를 제어합니다.
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# Context: Server & API
|
||||
|
||||
## 1. 모듈별 상세 역할
|
||||
|
||||
- **`server/index.js`**:
|
||||
- Fastify 서버 진입점입니다.
|
||||
- 개발 모드에서는 `@fastify/middie`로 Vite 미들웨어를 붙이고, `/api/*` 요청은 Vite SPA fallback이 가로채지 않도록 Fastify 라우트로 통과시킵니다.
|
||||
- 운영 모드(`npm start`)에서는 `@fastify/static`으로 `dist/`를 서빙하고, HTML 요청은 `index.html`로 fallback합니다.
|
||||
- **`server/config.js`**:
|
||||
- `config.json`을 읽어 서버 포트, MongoDB host/port/db/user/pass, 쿠키 보안 옵션을 정규화합니다.
|
||||
- `MONGODB_URI`가 직접 있으면 우선 사용하고, 없으면 `MONGODB_HOST`/`MONGODB_PORT` 기반으로 URI를 조립합니다.
|
||||
- 전투 사망 통계 컬렉션(`MONGODB_DAILY_DEATH_COLLECTION`)과 집계 기준 타임존(`DEATH_STATS_TIME_ZONE`) 기본값을 제공합니다.
|
||||
- **`server/db.js`**:
|
||||
- `MongoClient`를 한 번 생성한 뒤 재사용하여 MongoDB 커넥션 풀을 유지합니다.
|
||||
- 종료 시 `closeMongoConnection()`으로 커넥션을 닫습니다.
|
||||
- **`server/deathStats.js`**:
|
||||
- `GET /api/death-stats/today`: `DEATH_STATS_TIME_ZONE` 기준 오늘 일자의 종족별 사망 집계와 총 사망 수를 반환합니다.
|
||||
- `POST /api/death-stats/today`: 전투 종료 시 전달된 `deathsBySpecies`를 오늘 일자별 누적 문서의 `deathsBySpecies`, `totalDeaths`, `battles`에 바로 더합니다.
|
||||
- 집계 대상 종족은 `human`, `orc`, `skeleton`, `slime`, `wolf`, `bear`로 제한합니다.
|
||||
- **`server/visitors.js`**:
|
||||
- `POST /api/visitors/check`: `arena_visitor_id` `HttpOnly` 쿠키를 확인하고 없으면 UUID를 발급합니다.
|
||||
- MongoDB `visitors` 컬렉션에 `_id = visitorId`로 upsert해 방문자 1명당 1개 문서를 유지합니다.
|
||||
- `GET /api/visitors/stats`: 전체 유니크 방문자 수를 반환합니다.
|
||||
|
||||
## 2. 주요 로직 구현 세부 사항
|
||||
|
||||
### 유니크 방문자 체크
|
||||
브라우저가 직접 MongoDB에 연결하지 않고, Fastify API가 MongoDB 커넥션 풀을 유지합니다.
|
||||
1. 프론트엔드가 앱 로드 시 `POST /api/visitors/check`를 호출합니다.
|
||||
2. 서버가 `arena_visitor_id` 쿠키를 검사합니다.
|
||||
3. 쿠키가 없거나 유효하지 않으면 `crypto.randomUUID()`로 새 방문자 ID를 만들고 `HttpOnly` 쿠키로 내려줍니다.
|
||||
4. MongoDB에는 `_id`, `firstSeenAt`, `lastSeenAt`, `visits`, `firstUserAgent`, `lastUserAgent`를 저장합니다.
|
||||
5. `countDocuments()`로 전체 유니크 방문자 수를 계산해 반환합니다.
|
||||
|
||||
### 전투 사망 통계
|
||||
프리뷰 전투는 통계에서 제외하고, 사용자가 시작한 실제 전투만 저장합니다.
|
||||
1. `fighterManifest.js`의 모든 스킨은 `species`를 가집니다.
|
||||
2. `combat.js`의 처치 흐름이 `ArenaScene.recordKill()`을 호출하면, `ArenaScene`은 피처치자의 `skin.species`를 현재 전투의 `battleDeathCounts`에 누적합니다.
|
||||
3. 전투가 5초 이상 이어지면 `GET /api/death-stats/today`로 가져온 오늘 집계와 현재 전투의 사망 수를 합산해 `#battle-notice`에 표시합니다.
|
||||
4. 전투 종료 시 `POST /api/death-stats/today`로 `deathsBySpecies`만 보냅니다.
|
||||
5. 서버는 `daily_death_stats` 컬렉션에서 오늘 일자의 `battles`, `totalDeaths`, `deathsBySpecies.*` 값을 `$inc`로 갱신합니다.
|
||||
|
||||
## 3. 설정 규칙
|
||||
- **서버 설정**: `.env` 대신 `config.json`을 사용합니다. 로컬 전용 파일이며, 저장소에는 `config.json.sample`만 공유합니다.
|
||||
- **MongoDB 연결**: 접속 정보는 `config.json`의 `MONGODB_HOST`, `MONGODB_PORT`, `MONGODB_DB` 등으로 관리합니다.
|
||||
- **API 변경**: `/api/*` 경로는 Fastify 라우트가 담당하며, 개발 모드에서 Vite 미들웨어보다 우선순위를 가집니다.
|
||||
Loading…
Reference in New Issue