Skull King - 실시간 멀티플레이 웹 보드게임

해적 테마의 트릭 테이킹 카드 게임 **스컬킹(Skull King)**의 웹 버전입니다.

스크린샷

┌─────────────────────────────┐
│ 🟢 Connected    💀 Skull King│
├─────────────────────────────┤
│  [Player1] [Player2] [Me]   │
│   베팅:2     베팅:1    베팅:? │
├─────────────────────────────┤
│         현재 트릭            │
│    🔵7  →  ⚫5  →  ???     │
├─────────────────────────────┤
│        내 카드 (3장)         │
│   [🟡3] [🔴8] [🏴‍☠️]        │
├─────────────────────────────┤
│  [🎮 Game]    [💬 Chat]     │
└─────────────────────────────┘

빠른 시작

# 의존성 설치
npm install

# 개발 서버 실행 (서버 + 클라이언트 동시)
npm run dev

클라이언트: http://localhost:3000
서버: http://localhost:8080
Health Check: http://localhost:8080/health

기술 스택

영역	기술
프론트엔드	React 18 + Vite + TypeScript
백엔드	Node.js + Express + WebSocket (ws)
상태관리	서버 Authoritative + React Context
스키마 검증	Zod
패키지 관리	npm workspaces (monorepo)

프로젝트 구조

skull-king/
├── package.json          # 루트 (workspaces)
├── shared/               # 공유 타입/스키마
│   └── src/
│       ├── types/        # 카드, 플레이어, 게임 상태 타입
│       └── schemas/      # Zod 스키마 (메시지 검증)
├── server/               # 백엔드
│   └── src/
│       ├── game/         # 게임 엔진 (덱, 트릭, 점수)
│       ├── store/        # 메모리 룸 저장소
│       └── websocket/    # WebSocket 핸들러
├── client/               # 프론트엔드
│   └── src/
│       ├── components/   # UI 컴포넌트
│       ├── context/      # 게임 상태 Context
│       └── hooks/        # WebSocket, LocalStorage 훅
└── docs/                 # 설계 문서
    └── rules.md          # 게임 규칙

게임 규칙 (MVP)

개요

플레이어: 2~6명
라운드: 10라운드 (라운드 N에서 N장씩 배분)
목표: 베팅한 트릭 수를 정확히 맞춰 점수 획득

카드 구성 (66장)

숫자 카드: 4색(노랑/파랑/빨강/검정) × 13장 = 52장
특수 카드: 도망(5), 해적(5), 인어(2), 스컬킹(1), 타이그레스(1) = 14장

카드 강도

💀 Skull King > 🧜 Mermaid (인어가 스컬킹을 잡음!)
🧜 Mermaid > 🏴‍☠️ Pirate (인어가 해적을 잡음!)
🏴‍☠️ Pirate > 숫자 카드
⚫ Black(트럼프) > 리드 수트 > 🏃 Escape

점수 계산

결과	점수
0 베팅 성공	+라운드번호 × 10
0 베팅 실패	-라운드번호 × 10
N 베팅 성공	+20 × N
N 베팅 실패	-10 ×

자세한 규칙은 docs/rules.md 참조.

네트워크 프로토콜

클라이언트 → 서버

타입	설명
`JOIN`	룸 입장
`CHAT_SEND`	채팅 메시지
`READY`	준비 상태
`GAME_START`	게임 시작 (방장)
`BID_SUBMIT`	베팅 제출
`CARD_PLAY`	카드 제출

서버 → 클라이언트

타입	설명
`WELCOME`	입장 완료 + 룸 스냅샷
`ROOM_SNAPSHOT`	전체 상태 업데이트
`ROUND_STARTED`	라운드 시작 + 핸드
`BID_PLACED`	베팅 완료 알림
`CARD_PLAYED`	카드 제출됨
`TRICK_ENDED`	트릭 종료 + 승자
`ROUND_ENDED`	라운드 종료 + 점수
`GAME_ENDED`	게임 종료 + 순위

개발 명령어

# 전체 의존성 설치
npm install

# 개발 서버 (서버 + 클라이언트 동시)
npm run dev

# 서버만 실행
npm run dev:server

# 클라이언트만 실행
npm run dev:client

# 공유 패키지 빌드
npm run build:shared

# 테스트
npm test

🎮 플레이 방법

npm run dev 실행 (서버: 8080포트, 클라이언트: 3000포트)
브라우저 창 2~3개로 http://localhost:3000 접속
각 창에서 다른 닉네임 입력 후 자동 입장
모든 플레이어 "준비 완료" 클릭
방장이 "게임 시작" 클릭
베팅 → 트릭 플레이 → 점수 확인 반복 (10라운드)

📱 모바일 최적화 UX

핵심 동선: "채팅하다가도 내 턴이면 바로 게임 복귀"

🎯 주요 기능

미니 게임 HUD: 채팅 화면 상단에서 게임 상태 실시간 확인
- 현재 라운드/라운드 수, 게임 페이즈, 내 점수 표시
- 내 턴일 때 강조 표시 + "내 턴!" 배지
강화 알림 시스템:
- 🔊 사운드 알림: 내 턴 시 비프음 자동 재생
- 🔔 브라우저 알림: 백그라운드에서도 푸시 알림 (권한 허용 시)
- 📋 제목 변경: 탭이 백그라운드일 때 "🔔 내 턴! - 스컬킹"으로 표시
원터치 복귀: 채팅 중 내 턴이 되면 "게임으로" 버튼 자동 표시

🖱️ 모바일 친화적 터치

44px+ 터치 영역: 모든 버튼이 모바일 터치 가이드라인 준수
고정 하단 탭: Game | Chat 탭이 하단 고정, 엄지로 쉬운 전환
스크롤 가능한 카드: 많은 카드도 가로 스크롤로 편리하게 선택
카드 피드백: 터치 시 즉각적인 시각적/햅틱 피드백

🎮 게임 플로우

📱 채팅 중 → 🔔 내 턴 알림 → 👆 원터치 게임 복귀 → 🎯 카드 선택 → ✅ 완료 후 자동으로 채팅 복귀 가능

📐 반응형 디자인

데스크톱: 와이드 레이아웃, 호버 효과
태블릿: 중간 크기 터치 영역, 카드 크기 최적화
스마트폰: 세로/가로 모드 지원, 카드 겹침 방지

접근성 개선

색상 대비 WCAG AA 준수
터치 영역 최소 44px 보장
스크린 리더 호환성
키보드 네비게이션 지원

MVP 제한사항

단일 public 룸 (프라이빗 룸 없음)
메모리 기반 (서버 재시작 시 초기화)
타임아웃 없음 (무제한 대기)
보너스 점수 없음

🚀 성능 및 호환성

지원 브라우저: Chrome 90+, Safari 14+, Firefox 88+
모바일 지원: iOS Safari, Android Chrome
네트워크: WebSocket 실시간 통신 (자동 재연결)
PWA 준비: 홈 화면 추가, 오프라인 준비

데모 체크리스트

데모 전 다음 항목들을 확인하세요:

환경 준비

Node.js 18+ 설치됨
npm install 완료
npm run dev 실행 (서버 8080, 클라이언트 3000)

기본 기능

닉네임 입력 후 자동 입장
채팅 메시지 실시간 전송/수신
모든 플레이어 "준비 완료" → 방장이 "게임 시작"
베팅 → 카드 플레이 → 트릭 결과 → 라운드 점수

안정성 (v2.0)

새로고침 후 자동 재연결 (30초 내)
재연결 시 게임 상태 유지
연결 상태 표시 (연결됨/재연결 중.../연결 끊김)
에러 메시지 Toast 표시
빠른 중복 클릭 방지

멀티플레이어 테스트

브라우저 창 2-3개 열기
각각 다른 닉네임으로 입장
한 창에서 새로고침 → 자동 재접속 확인
게임 중 한 플레이어 새로고침 → 게임 계속 가능 확인

알려진 제한사항

단일 public 룸만 지원
서버 재시작 시 모든 상태 초기화
타임아웃 없음 (플레이어 대기 무제한)

라이선스

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.claude		.claude
client		client
docs		docs
e2e		e2e
md		md
server		server
shared		shared
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
opencode.json		opencode.json
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation

Skull King - 실시간 멀티플레이 웹 보드게임

스크린샷

빠른 시작

기술 스택

프로젝트 구조

게임 규칙 (MVP)

개요

카드 구성 (66장)

카드 강도

점수 계산

네트워크 프로토콜

클라이언트 → 서버

서버 → 클라이언트

개발 명령어

🎮 플레이 방법

📱 모바일 최적화 UX

핵심 동선: "채팅하다가도 내 턴이면 바로 게임 복귀"

🎯 주요 기능

🖱️ 모바일 친화적 터치

🎮 게임 플로우

📐 반응형 디자인

접근성 개선

MVP 제한사항

🚀 성능 및 호환성

데모 체크리스트

환경 준비

기본 기능

안정성 (v2.0)

멀티플레이어 테스트

알려진 제한사항

라이선스

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages