sunrise/docs/superpowers/plans/2026-10-30-multiplayer.md

관악산 공동 방 구현 계획

실행: 현재 세션에서 구현하고 서버 작업은 독립 파일 범위로 병렬 진행한다. 사용자 요청에 따라 추가 승인 없이 구현한다.

Goal: 관악산 100명 방, 기존 양 캐릭터·장비 상태 공유, 서버 시각·날씨, MongoDB 접속 기록. Architecture: 단일 Node/Socket.IO 인스턴스가 gwanaksan-001을 관리한다. 장소와 방 ID를 분리하고 MongoDB에는 방문 세션만 저장한다. Tech Stack: 기존 TypeScript/Three.js + socket.io/socket.io-client + mongodb 공식 드라이버. Spec: docs/superpowers/specs/2026-10-30-multiplayer-design.md와 후속 사용자 합의. 현재 양 캐릭터/3인칭/우천 장비를 유지한다. DB는 172.16.0.7:27017, 인증은 환경변수로 설정한다.

제약 및 검토 항목

• 작업 폴더는 Git 저장소가 아니므로 worktree/commit 작업은 생략한다.
• 장비는 메모리에만 저장하고 새 세션에서는 해제한다. 서버 기록에는 장비·이동을 저장하지 않는다.
• DB 저장 대기 중 정원 예약, 중복 입장, 연결 종료 후 늦은 응답, DB 실패 시 정원 반환을 검증한다.
• 재접속/혼자 보기 전환 시 이전 소켓 상태를 제거하고 장비·시각을 초기화한다.
• 공통 형식은 src/multiplayer/protocol.ts, 상수는 src/constants/multiplayer.ts를 기준으로 한다.
• 실제 호스팅 배포 및 1만 명 확장은 범위 밖이다.

Task 1: 서버와 기록

• server/room.ts, server/app.ts, server/visits.ts, server/index.ts 및 서버 테스트를 추가한다.
• 100명 정원/101번째 거절/동시 예약/비활성 장소/입력 검증 테스트를 먼저 실행해 실패 확인 후 구현한다.
• Node HTTP 정적 파일 제공, health, Socket.IO 및 DB 연결 종료를 구현한다.
• join, player:update, player:reset, clock:sync 요청과 room:state, player:correction, weather:state 응답을 공통 타입으로 연결한다.
• 기존 보행 검증과 날씨 조회를 재사용하고 DB 기록은 입장/마지막 확인/퇴장만 수행한다.

Task 2: 클라이언트와 화면

• src/multiplayer/client.ts, remotePlayers.ts, 시간 동기화를 추가한다.
• 서버 시각 고정과 원격 캐릭터 자원 공유·해제 테스트를 먼저 작성한다.
• world.ts에 로컬 상태 읽기/보정과 원격 표시를 추가하고 기존 캐릭터 모델을 복제한다.
• main.ts, timeController.ts, index.html에 공동/혼자 보기 전환과 연결/정원 상태를 표시한다.
• 공동 모드 날짜 조작 차단, 원본 지형/프로파일은 혼자 보기로 제한한다.

Task 3: 통합과 실행

• package scripts, Vite 프록시, 환경설정 예시, README 운영 명령을 추가한다.
• 실제 Socket.IO 100명/101번째 거절/퇴장/재입장/장비 스냅샷/시각을 검증한다.
• MongoDB는 테스트 전용 DB로 기록 확인하고 실제 서비스 데이터와 분리한다.
• 기존 테스트와 빌드, 5분 부하, 가능하면 브라우저 두 화면과 99 캐릭터 렌더링을 확인한다.
• 별도 코드 리뷰 후 중요한 문제를 수정하고 검증 한계를 보고한다.

진행 기록

• 계획 작성. 기존 타입과 공유 함수 재사용을 우선한다.
• 서버/클라이언트 구현 완료. 기본 캐릭터 신규 제작 대신 기존 양 모델·장비를 재사용하고 GPU geometry/material을 공유한다.
• 서버 테스트와 프런트 상태/시간/자원 테스트 RED→GREEN 확인. 전체 103개 중 102 통과, 기존 1개 skip.
• MongoDB 임시 DB에서 입장/heartbeat/종료 기록 검증 통과. 시작 시 기존 기록 일괄 복구는 자동 승인 검토 거절로 제거했고, 임시 DB에서 기존 열린 기록 보존 RED→GREEN 확인.
• 별도 리뷰의 DB 실패 응답 지연 문제 수정: 정리 작업을 기다리기 전에 오류 응답, 재현 테스트 RED→GREEN.
• 100개 클라이언트 5분 10Hz 부하, 101번째 거절/자리 재사용 통과. 결과 artifacts/multiplayer/load-report.json.
• 두 실제 브라우저 상호 표시/이동, 공동 시각 잠금, 혼자 보기/재입장 확인. 별도 시작 화면/HUD 변경이 반영된 최신 UI에서 서버/채널 선택 후 입장도 확인.
• 99명 가상 참여자+실제 브라우저 1개로 100/100명 표시와 양·우산·비옷 렌더링 확인. 정량 GPU 프레임/모바일 성능은 미측정.
• 최종 npm test: 102 pass, 1 skip, 0 fail. npm run build: 프런트/서버 타입 검사 및 운영 빌드 통과. 기존 대형 JS 청크 경고 유지.
• 기존 미종료 기록의 자동 갱신을 제거한 결정: 강제 종료 시 leftAt은 미확정으로 남고 lastSeenAt으로 마지막 확인 시각만 알 수 있다. 장비 영구 저장/다중 인스턴스/외부 배포는 요청 범위 밖이다.