Y2K 하이틴 변신 인터랙티브 웹 게임
너드 → 퀸카 → 친구를 돕는 존재로. 선택이 5축 성향 점수로 쌓여 5종 멀티 엔딩으로 이어진다.

---

✨ 소개

미국 하이틴 영화 무드의 학교를 배경으로, 4명의 너드 캐릭터 중 하나를 골라 마법으로 자신을 변화시키고(Stage 1) 그 힘으로 친구를 돕는(Stage 2) 여정을 따라간다. 탐색·수집·조합·변신·선택이 모두 5개 성향 축에 누적되어, 마지막엔 플레이 데이터를 종합한 성향 진단 카드로 마무리된다.

상세 스펙은 docs/PRD.md를 단일 진실 소스(SSOT) 로 참조한다.

🎮 플레이 흐름

시작 게이트(탭하여 시작) → 인트로 → 메인 메뉴 → 캐릭터 선택
   → Stage 1 (4장소 재료 수집 → 물약 제작 → 변신)
   → Stage 2 (복도에서 친구 택1 → 고민 해결 → 선택)
   → 엔딩 집계(5축) → 결과 카드 → 공유 / 다시하기

🏫 무대 — Stage 1: Become The Queen

📚 Library · 블랙 매직 북	🤸 Gym · 리본
🌸 Garden · 꽃	🎤 Auditorium · 반짝이

👑 캐릭터

루나 공부벌레

미오 예술가

제로 게임 덕후

삐삐 소심 패셔니스타

🧩 핵심 시스템

• Phase 상태머신 — 모든 화면 전환은 appStore의 phase 전이로만(직접 라우팅 없음).
• 콘텐츠 외부화 — 대사·선택지·점수 가중치를 src/data/*.json으로 분리(기획자가 코드 없이 수정).
• 5축 점수 엔딩 — LEADERSHIP / TREND / CREATE / DREAM / SUPPORT 누적 → lib/scoring.ts 순수함수로 5종 엔딩 산출(동점 우선순위 룰 포함, 단위 테스트 보유).
• 세이브 / 이어하기 — 진행마다 localStorage 자동 저장, schemaVersion 검증, 재방문 시 전 슬라이스 복원.
• 연출(GSAP) — Split Open · 아이템 수집 fly · 변신 파티클 · 물약 보글거림 · 5축 게이지 · 엔딩 카드. prefers-reduced-motion 폴백.
• 오디오 — Howler.js BGM, 시작 게이트 탭에서 자동재생 차단 없이 음악·인트로 싱크.

🛠 기술 스택

영역	선택
프레임워크	Vite + React 19 + TypeScript (strict)
상태관리	Zustand (슬라이스 분리)
스타일	Tailwind CSS v4 (+ 디자인 토큰 @theme)
연출	GSAP (타임라인 / 파티클 / motion)
사운드	Howler.js (로열티프리 SFX·BGM)
저장	localStorage (+ schemaVersion)
배포	Vercel

🚀 시작하기

요구사항: Node 20+ / npm

npm install
npm run dev      # 개발 서버 (http://localhost:5173)
npm run build    # 타입체크(tsc) + 프로덕션 빌드
npm run preview  # 빌드 결과 로컬 미리보기
npm test         # 단위 테스트 (scoring / save)

📦 배포 (Vercel)

정적 SPA라 Vercel이 Vite를 자동 감지한다(별도 설정 불필요).

1. GitHub 저장소를 Vercel에 import
2. Framework Preset: Vite (자동), Build: npm run build, Output: dist
3. Deploy → main 브랜치 push마다 자동 배포

배포 후 index.html의 og:image를 실제 도메인 절대 URL로 바꾸면 공유 카드 미리보기가 안정적이다(docs/KNOWN_ISSUES.md 참조).

🗂 프로젝트 구조

src/
  state/        # Zustand 슬라이스 (app/game/quest/inventory/score/ending)
  data/         # 콘텐츠 JSON + 타입드 로더 — 코드와 분리
  types/        # TS 인터페이스 (PRD 10장)
  scenes/       # phase별 화면 + PhaseRouter
  components/
    ui/         # 공용 프리미티브 (Button/Modal/GameIcon …)
    shell/      # 4분할 셸 (Header/CharacterPanel/Inventory)
  lib/          # scoring · save · audio · fx(연출) · 훅
  styles/       # 디자인 토큰(@theme) + 글로벌/씬 CSS
public/asset/   # 캐릭터·씬·아이콘·로고 등 실제 에셋
docs/PRD.md             # 제품 요구사항 (SSOT)
docs/KNOWN_ISSUES.md    # 점검 결과 / 남은 이슈 / 출시 전 QA 체크리스트
CLAUDE.md               # 작업 규칙

📐 아키텍처 원칙

• 화면 전환은 Phase 상태머신으로만. 직접 라우팅 금지.
• 모든 콘텐츠는 src/data/*.json으로 외부화.
• 디자인은 토큰을 통해서만(컬러/폰트 하드코딩 금지).
• 엔딩 산출은 lib/scoring.ts 순수함수로(테스트 가능).

🧪 개발 도구 (DEV 전용)

개발 모드에서만 동작하며 프로덕션 빌드엔 포함되지 않는다(import.meta.env.DEV 게이트).

• 화면 하단 Phase 점프 바로 phase 즉시 전환.
• 콘솔: __BM__.setPhase('STAGE1') · __BM__.seedDemo() · __BM__.resetGame() · __BM__.getState()

📄 문서

• docs/PRD.md — 제품 요구사항 (SSOT)
• docs/KNOWN_ISSUES.md — 점검 결과 · 남은 이슈 · 출시 전 QA
• CLAUDE.md — 작업 규칙

⚠️ 저작권

본 게임은 Little Mix "Black Magic"의 무드를 재해석한 오리지널 2차 창작이다. 가사 원문·음원·MV 영상·실제 인물 외형은 코드/에셋에 사용하지 않는다. 모든 캐릭터·배경은 오리지널 디자인이며, 특정 아티스트·레이블·곡과 무관하다.