🎮 Xingu - 아이스브레이킹 플랫폼

웹 기반 실시간 멀티플레이 아이스브레이킹 플랫폼

프로젝트 소개

Xingu는 동아리, 워크샵, 팀 빌딩 등에서 사용할 수 있는 웹 기반 아이스브레이킹 플랫폼입니다.

주요 특징

🌐 설치 불필요: 브라우저에서 바로 실행
👥 역할 분리: 호스트는 관리, 플레이어는 참여
⚡ 실시간 동기화: WebSocket 기반 즉각 반응 (예정)
🎮 다양한 게임: 초성, 밸런스, 라이어 등 7개 게임
📌 게임 저장 기능: 담기/바로 시작 두 가지 옵션 ⭐
🔑 카카오 로그인: 간편한 소셜 로그인

기술 스택

Frontend

Framework: Next.js 15 (App Router)
Language: TypeScript
Styling: Tailwind CSS
UI Components: Shadcn UI, Radix UI
Authentication: Next-auth v5 + Kakao OAuth
Database: Prisma + SQLite (개발), PostgreSQL (프로덕션 예정)

Backend (예정)

Real-time: Socket.io
Cache: Redis

시작하기

필수 요구사항

Node.js 18+
npm 또는 yarn

설치

# 의존성 설치
npm install

# Prisma 클라이언트 생성
npx prisma generate

# 데이터베이스 초기화
npx prisma db push

# 개발 서버 실행
npm run dev

환경 변수 설정

.env 파일을 생성하고 다음 변수를 설정하세요:

DATABASE_URL="file:./dev.db"
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-secret-here"
KAKAO_CLIENT_ID="your-kakao-client-id"
KAKAO_CLIENT_SECRET="your-kakao-client-secret"

개발 서버가 http://localhost:3000에서 실행됩니다.

주요 기능

1. 비회원도 사용 가능

PIN 코드 입력으로 즉시 게임 참여
회원가입 없이 바로 시작

2. 게임 담기 & 바로 시작 ⭐

비회원: "바로 시작" → 즉시 방 생성
로그인 회원: "담기" → 나중에 대시보드에서 재사용

3. 대시보드

저장된 게임 템플릿 관리
한 번 설정한 게임을 반복 사용
템플릿 이름 지정 (예: "MT용 초성게임")

4. 카카오 로그인

간편한 소셜 로그인
게임 저장 및 관리

현재 개발 상태

✅ 완료된 기능

🚧 진행 중

사용 가능한 게임

초성 게임 ⭐⭐ - 제시된 초성으로 단어 맞추기 (추천)
밸런스 게임 ⭐ - A vs B 양자택일 (추천)
랜덤 질문 룰렛 ⭐ - 룰렛으로 자기소개 (추천)
스피드 퀴즈 ⭐ - OX 퀴즈 또는 4지선다
라이어 게임 ⭐⭐⭐ - 라이어 찾기
공통점 찾기 ⭐⭐ - 팀원 공통점 찾기 (출시 예정)
그림 퀴즈 ⭐⭐ - 그림으로 표현하기 (베타)

프로젝트 구조

xingu/
├── app/                     # Next.js 15 App Router
│   ├── page.tsx            # 랜딩 페이지
│   ├── login/              # 로그인 페이지
│   ├── dashboard/          # 대시보드 (저장된 게임)
│   ├── create/             # 게임 선택
│   ├── api/auth/           # Next-auth API
│   └── providers.tsx       # SessionProvider
│
├── components/             # React 컴포넌트
│   ├── landing/           # PIN 입력, 닉네임 모달
│   ├── create/            # 게임 카드, 필터, 저장 모달
│   ├── shared/            # Navbar, Footer
│   └── ui/                # Shadcn UI 컴포넌트
│
├── lib/                    # 유틸리티
│   ├── games/             # 게임 메타데이터
│   ├── prisma.ts          # Prisma 클라이언트
│   └── auth.ts            # Next-auth 설정
│
├── prisma/                 # Prisma 스키마
│   └── schema.prisma      # DB 스키마
│
└── types/                  # TypeScript 타입
    ├── game.ts
    ├── room.ts
    ├── player.ts
    └── socket-events.ts

개발 명령어

# 개발 서버 실행
npm run dev

# 프로덕션 빌드
npm run build

# 프로덕션 서버 실행
npm start

# 린트 검사
npm run lint

# Prisma 스튜디오 (DB GUI)
npx prisma studio

데모

1. 랜딩 페이지

방 코드 입력: DEMO12 (개발 중 테스트용)
비회원으로 바로 사용 가능

2. 게임 선택 (`/create`)

7개의 게임 중 선택
카테고리, 난이도별 필터링
담기 또는 바로 시작 선택

3. 로그인 (`/login`)

카카오 로그인
비회원으로 계속하기 옵션

4. 대시보드 (`/dashboard`)

저장된 게임 템플릿 목록
템플릿으로 빠른 게임 시작
템플릿 관리 (삭제, 수정)

카카오 개발자 설정

Kakao Developers 접속
애플리케이션 추가
플랫폼 설정 → Web 플랫폼 추가
- 사이트 도메인: http://localhost:3000
제품 설정 → 카카오 로그인
- 활성화 설정 ON
- Redirect URI: http://localhost:3000/api/auth/callback/kakao
동의항목 설정
- 닉네임, 프로필 사진 필수 동의
REST API 키 → .env 파일에 추가

데이터베이스 스키마

model User {
  id        String   @id @default(cuid())
  email     String?  @unique
  name      String?
  image     String?
  kakaoId   String?  @unique
  templates GameTemplate[]
  rooms     Room[]
}

model GameTemplate {
  id           String   @id @default(cuid())
  userId       String
  gameId       String
  templateName String
  gameSettings String   // JSON
  maxPlayers   Int      @default(20)
  createdAt    DateTime @default(now())
}

문서

docs/PLANNING.md - 프로젝트 전체 기획
docs/HOST_GUIDE.md - 호스트 화면 상세 설계
docs/PLAYER_GUIDE.md - 플레이어 화면 상세 설계
docs/GAME_LIST.md - 게임 아이디어 목록

로드맵

Phase 1: 기반 구축 ✅

Next.js 15 프로젝트 설정
기본 UI 컴포넌트
게임 선택 시스템

Phase 1.5: 회원 시스템 ✅ (NEW!)

카카오 로그인 연동
게임 템플릿 저장
대시보드

Phase 2: 핵심 기능 (진행 중)

방 시스템 (생성/참여)
WebSocket 실시간 통신
대기실 구현

Phase 3: 게임 구현

초성 게임
밸런스 게임
결과 화면

Phase 4+: 확장

추가 게임
통계 및 분석
템플릿 공유 기능

주요 변경사항 (v0.2.0)

⭐ 새로운 기능

게임 담기/바로 시작
- 비회원: 바로 시작으로 즉시 게임
- 회원: 담기로 템플릿 저장
대시보드
- 저장된 게임 템플릿 관리
- 빠른 게임 시작
카카오 로그인
- Next-auth + Kakao OAuth
- 간편한 소셜 로그인
Prisma + SQLite
- 유저 및 템플릿 데이터 저장
- 프로덕션은 PostgreSQL 사용 예정

라이선스

개발 시작일: 2025.10.11
현재 버전: 0.2.0 (템플릿 시스템 추가)
최종 업데이트: 2025.10.11

FilesExpand file tree

README.md

Latest commit

History