FunGame (실시간 멀티플레이어 게임 플랫폼)
FunGame은 사용자들이 실시간으로 방을 만들고 입장하여 다양한 게임을 즐길 수 있는 멀티플레이어 게임 플랫폼입니다. 실시간 데이터 동기화와 원활한 게임 경험을 위한 안정적인 세션 관리를 목표로 합니다.
🚀 주요 기능
1. 실시간 대기실 및 게임 세션 관리
- 방 생성 및 입장: 사용자가 새로운 게임 방을 생성하거나 목록에서 선택하여 입장할 수 있습니다.
- 준비(Ready) 시스템: 공정한 게임 시작을 위해 모든 플레이어의 준비 상태를 실시간으로 관리하며, 방장은 모든 인원이 준비된 후 게임을 시작할 수 있습니다.
- 실시간 동기화: WebSocket(STOMP)을 사용하여 플레이어 간 상태 변화 및 게임 데이터를 실시간으로 동기화합니다.
2. 세션 유지 및 복구 (Re-entry)
- 네트워크 대응: 불안정한 네트워크 연결이나 재접속 시에도 기존 점수와 세션을 유지할 수 있도록 설계되었습니다.
- 유연한 세션 관리: 짧은 접속 끊김(15초) 동안 플레이어를 퇴장시키지 않고 상태를 유지하여 '이어하기'가 가능합니다.
3. 게임 엔진 및 동기화 로직
- 서버측 타이머 관리: 서버에서 게임 라운드 및 진행 시간을 정밀하게 기록하여 모든 클라이언트가 동일한 시점에 동기화되도록 합니다.
- 동적 피드백: 정답 처리 시 단순 채팅 외에도 시각적 효과를 위한 풍부한 데이터를 전송합니다.
🛠 기술 스택
Backend
- Language: Java 21
- Framework: Spring Boot
- Build Tool: Gradle
- Database: MySQL 8.0, Redis (로컬은 H2)
- API Docs: Spring Rest Docs +
api/*.md
- Messaging: Spring WebSocket (STOMP)
Frontend
- Framework: React 19 (Vite)
- Language: TypeScript
- Styling: Tailwind CSS 4
- Test Tool: Vitest
📂 프로젝트 구조
FunGame/
├── backend/ # Spring Boot 기반 백엔드 (Java)
├── frontend/ # React 기반 프론트엔드 (TypeScript)
├── api/ # REST · WebSocket 명세 (Markdown)
├── docs/ # 설계 문서와 실행 계획
├── infra/ # 배포 · 모니터링 설정
├── scripts/ # E2E 등 보조 스크립트
└── CLAUDE.md # AI 협업 및 작업 규칙
🏃 실행 방법
백엔드 실행 (Backend)
cd backend
./gradlew bootRun
프론트엔드 실행 (Frontend)
cd frontend
npm install
npm run dev
로컬 단독 실행 (external DB 없이)
인메모리 H2 로 백엔드를 띄우고 프론트를 거기에 붙이는 조합입니다.
DB 나 공용 개발 서버 없이 혼자 기능을 확인할 때 쓰세요.
백엔드 (local 프로파일: H2 + 시드 데이터 + localhost CORS + Secure 쿠키 해제):
./gradlew :backend:core:core-api:bootRun --args='--spring.profiles.active=local'
프론트엔드 (localdev 모드: http://localhost:8080 을 바라보고 5199 포트로 기동):
npm run dev:local --prefix frontend
시드는 backend/core/core-api/src/main/resources/db/local/R__local_seed.sql 에 있습니다.
CS 퀴즈 5문제가 들어 있어 CS 퀴즈는 바로 플레이할 수 있습니다.
방 번호 채번용 카운터는 시드가 아니라 마이그레이션(V21)이 모든 환경에 넣습니다.
음악 퀴즈는 유튜브 링크가 필요하므로 관리자 화면에서 곡을 등록한 뒤 사용하세요.
📜 개발 가이드라인
본 프로젝트는 특정 협업 규칙과 코드 스타일을 준수합니다. 상세 내용은 다음 문서를 참고하세요:
