progress.md

색실 풀기 (Thread Sort) 진행 상황

최근 업데이트: 2026-02-28 (6차)

완료된 작업

• [2026-02-27] 게임 컨셉 확정: 소팅 퍼즐 (Wool Sort / Tangle 계열)

• [2026-02-27] 기술 스택 확정: React + Vite + HTML5 Canvas

• [2026-02-27] 상세 기획서 작성 완료 (v1.0)

• [2026-02-27] 시장 조사 + 레퍼런스 분석 완료

• [2026-02-27] 프로젝트 초기 세팅 완료 — Frontend Developer

  • React 19 + Vite + Zustand + Howler 의존성 설치
  • 전체 폴더 구조 생성
  • GameLoop, Renderer, InputManager, GameCanvas, HomeScreen, GameplayScreen 구현
  • Zustand 스토어, 게임 상수, utils/math, utils/tween 구현
  • Thread.js, Bobbin.js, Puzzle.js, PuzzleGenerator.js (역방향 생성 + BFS 솔버) 구현
  • git init + 첫 커밋 완료

• [2026-02-27] 코어 게임플레이 구현 완료 — Frontend Developer

  • 실(Thread) 렌더링: 큐빅 베지어 곡선, DESIGN.md 8색 팔레트, 외곽선+하이라이트 광택 레이어
  • 실 겹침 z-order: zIndex 기반 정렬 렌더링
  • Free End 마커: 펄스 애니메이션 (1.5초 주기), 넓은 히트 영역 (r=28px)
  • 실 선택 시각 피드백: 선택 실 발광+굵어짐, 비선택 실 반투명(opacity 0.4)+blur
  • 보빈 렌더링: 나무 보빈 (상/하 플랜지+Core), 실 채움 단계 시각화 (줄무늬 질감), 색상 라벨 원
  • 탭-탭 조작: 실 끝 탭 → 보빈 탭 이동, 잘못된 보빈 거부 흔들림 애니메이션
  • 실 감기 애니메이션: De Casteljau subdivision으로 베지어 경로 점진 소멸 (500ms Tween)
  • 보빈 하이라이트: 선택 실 색상에 맞는 보빈만 강조, 틀린 보빈 반투명
  • 파티클 시스템: 보빈 완성 파티클 16개 fanout, 스테이지 클리어 60개 파티클
  • 퍼즐 로직 연동: PuzzleGenerator 역방향 생성, Puzzle.move/undo/isCleared/isFailed/isDeadlocked
  • Undo: 무료 되돌리기 (Move 소모 없음)
  • Move 카운터 HUD: 잔여 5 이하 시 빨간색 pulse 경고
  • 게임 흐름: 스테이지 시작 → 퍼즐 생성 → 플레이 → 클리어/실패 → ResultScreen
  • 별점 계산: Move 50% 이내 3성, 70% 이내 2성, 초과 1성
  • 결과 화면: 별 순차 등장 애니메이션, 코인 보상 표시, 다음 스테이지/다시하기/스테이지 선택 버튼
  • 스테이지 선택 화면: 10스테이지 그리드, 별점 표시, 언락 시스템, 진행률 바
  • 메인 화면: 코인 표시, 실타래 SVG 일러스트, 스테이지 선택/바로 시작 버튼
  • 일시정지 모달: 계속하기/재시작/스테이지 선택/홈으로 버튼
  • DESIGN.md 컬러/폰트 시스템: CSS Custom Properties 전면 적용
  • 모바일+데스크톱 터치/마우스 지원 (InputManager)
  • 반응형: ResizeObserver 기반, devicePixelRatio 스케일링

• [2026-02-27] 런타임 버그 5종 수정 완료 — Frontend Developer

  • [A] CSS @import Google Fonts → index.html <link> 태그로 이전 (렌더 블로킹 제거)
  • [B] Puzzle.isCleared: spare 보빈(colorIndex=-1)을 클리어 체크에서 제외 (퍼즐 클리어 불가 버그 수정)
  • [C] PuzzleGenerator: THREAD_COLORS[i] (객체 숫자 인덱스 → undefined) → THREAD_COLOR_LIST[i] 배열로 교체, import 수정
  • [D] Renderer.resize: ctx.scale() 누적 → ctx.setTransform() 으로 교체
  • [E] GameCanvas: 마운트 직후 clientWidth/clientHeight가 0인 경우 rAF 1프레임 재시도 로직 추가
  • 빌드 및 개발 서버 동작 확인 완료 (http://localhost:5176)

• [2026-02-27] 조작 방식 변경: 2탭 → 1탭 자동 매칭 — Frontend Developer

  • GameController.js: handleTap 리팩터링 — Free End 탭 시 즉시 _attemptAutoMove 호출
  • 자동 매칭 우선순위: 같은 색 보빈(0) → 일반 빈 보빈(1) → spare 빈 보빈(2) 순 정렬
  • 거부 피드백: 이동 가능 보빈 없을 시 Free End 자체 좌우 흔들림 + 빨간 flash (_shakeFreeEnd)
  • freeEndShakeState: Controller에서 update(), Renderer에서 렌더링 분리 관리
  • GameRenderer.js: selectedBobbinId 기반 하이라이트/딤/발광 효과 전면 제거 — 모든 실 동등 렌더
  • Free End 마커: 거부 시 빨간 외곽 원 flash + 마커 색상 전환 (DANGER 색)
  • GameCanvas.jsx: 렌더 호출에서 selectedBobbinId 제거, freeEndShakeState 추가 전달
  • selectedBobbinId 상태 필드 완전 제거 (Undo, 이동 완료 후 null 처리 코드 등)
  • 빌드 에러 없음 확인 (http://localhost:5174)

• [2026-02-27] 비주얼 디자인 리스킨 완료 — Frontend Developer

  • 디자인 토큰 교체: tenqube reward-webview 두더지잡기 스타일로 전면 적용
  • 배경: 전 화면 #FFF9F0/#FFF4E6/#F5EFE6 웜톤 → #ffffff 클린 화이트
  • 주요 색상: terracotta #E8734A 계열 → 블루 #2761FF 계열 전면 교체
  • 텍스트: #2C1A0E → #20222E, 보조 #7A6A5A → #868686
  • 버튼: height 52px, border-radius 16px, font-weight 600 통일 (기존 56px/28px pill 형태에서 변경)
  • 비활성/보조 버튼: #E8EAED bg 또는 white with border 스타일
  • 진행바 fill: #C4845C → #2761FF
  • 스테이지 카드 현재 하이라이트: 오렌지 → #2761FF (glow ring rgba(39,97,255,0.12))
  • HUD/툴바: 배경 white, 보더 #E8EAED
  • 힌트 버튼: 오렌지 FAB → #2761FF 블루 pill
  • 일시정지 모달: 폰트 Noto Serif KR 제거 → system font, 버튼 #2761FF primary
  • SVG 아이콘: PauseIcon #7A6A5A → #868686, UndoIcon → #20222E
  • 캔버스 내부 게임 요소: 변경 없음 (실 색상, 보빈 비주얼 유지)
  • 대상 파일: App.jsx, HomeScreen.jsx, StageSelectScreen.jsx, GameplayScreen.jsx, ResultScreen.jsx

• [2026-02-28] 게임 시스템 전면 피벗: 보빈 기반 → 구형 실뭉치(Yarn Ball) — Frontend Developer

  • 신규 파일 생성 (6개):
    • src/utils/arc.js — 원호 유틸: normalizeAngle, angleInArc, arcsOverlap, arcMidAngle, arcSpan
    • src/game/entities/WindingThread.js — 실뭉치 위 실 하나 (id, colorIndex, color, layer, arcStart, arcEnd, windingLoops, freeEndAngle)
    • src/game/entities/YarnBall.js — 퍼즐 상태 (accessibleThreads, isAccessible, removeThread, undo, isCleared, isFailed)
    • src/game/generators/YarnBallGenerator.js — 레이어별 arc 배치 + 해결 가능성 greedy 검증
    • src/game/systems/YarnBallRenderer.js — 구체 렌더링 (드롭 섀도, 방사형 그라디언트, 레이어별 실 arc, Free End marker, 구체 하이라이트)
    • src/game/systems/YarnBallController.js — 상태 머신 (idle→unwinding→idle), 풀기 Tween 애니메이션 600ms
  • 수정 파일 (4개):
    • src/constants/game.js — YARN_BALL 상수 블록 추가 (BOBBIN_LAYOUT 보존)
    • src/constants/stages.js — 10개 스테이지 전면 교체 (threadCount/layerCount/arcDensity 파라미터)
    • src/ui/components/GameCanvas.jsx — YarnBallRenderer + YarnBallController 로 교체, puzzle→yarnBall prop
    • src/ui/screens/GameplayScreen.jsx — generateYarnBall 사용, 보빈 UI 제거
  • 빌드 성공 확인 (237kB, vite v7.3.1)
  • 구버전 파일 보존: Puzzle.js, Bobbin.js, Thread.js, PuzzleGenerator.js, GameController.js, GameRenderer.js, ThreadLayout.js

• [2026-02-28] 실뭉치 렌더링 3D 대원(great circle) 모델로 전면 교체 — Frontend Developer

  • WindingThread.js: tiltAngle + rotOffset + arcStart/arcEnd(대원 파라미터) 필드 추가, latitude/freeEndAngle 제거
  • YarnBallGenerator.js: rotOffset 균등 배치(지터 포함), tiltAngle 레이어별 범위 할당, 해결 가능성 검증 threadsOverlap 기반으로 전환
  • YarnBallRenderer.js: _drawThread 완전 재작성 — _sampleGreatCircle(기울어진 대원 3D 좌표 → Y축 회전 → 정사영), _splitFrontSegments(앞면 세그먼트 분리), 깊이 기반 굵기/밝기, 루프별 tilt 오프셋 다중 레이어 렌더
  • YarnBallRenderer.js: getFreeEndPosition — arcEnd 3D 점에서 법선 방향으로 뻗기, 뒷면이면 arcStart 사용
  • YarnBallRenderer.js: _drawTextureArcs — 배경 텍스처도 대원 곡선으로 교체
  • YarnBall.js: isAccessible — arcsOverlap 대신 threadsOverlap 사용
  • arc.js: threadsOverlap 함수 추가 (rotOffset 근접도 기반, 임계값 PI*0.4)
  • game.js: YARN_BALL에 LAYER_DELTA(5), TILT_MIN(0.52), TILT_MAX(1.40) 추가
  • 빌드 성공 확인 (238kB)
  • 결과: 실이 구체를 사선으로 가로지르는 대원 호 형태로 렌더링, 앞면만 표시(back-face culling), 깊이 음영 적용

• [2026-02-28] JavaScript → TypeScript 전면 전환 + Pretendard 폰트 적용 — Frontend Developer (팀)

  • 인프라: tsconfig.json (strict, @/* path alias), vite.config.ts (tsconfigPaths 플러그인), .prettierrc, src/vite-env.d.ts
  • 의존성 추가: typescript, vite-tsconfig-paths, prettier (devDependencies)
  • 폰트 교체: Google Fonts CDN (Noto Sans KR/Serif KR) → 로컬 Pretendard woff2-subset 9종 (100~900)
  • 타입 정의: src/types/game.ts 신규 생성 (ThreadColor, Stage, WindingThreadParams, GameStoreState 등 17+ 인터페이스)
  • 소스 전환 (31파일): .js→.ts (24개), .jsx→.tsx (7개), 전체 클래스/함수에 타입 추가
  • Zustand v5: create()() 이중 호출 패턴 적용
  • 검증: tsc --noEmit 에러 0개, prettier 포맷팅, npm run build 성공 (241KB)
  • package.json: "typecheck": "tsc --noEmit", "build": "tsc --noEmit && vite build"

현재 진행 중

• (다음 작업 배정 대기)

알려진 이슈/블로커

• 사운드 미구현 (Howler.js 설치됨, SFX 에셋 미확보)
• 힌트 버튼 UI만 있고 기능 미구현
• 광고 SDK 미연동 (Poki SDK)
• YarnBallGenerator: 생성 실패 시 forceSolvable 폴백으로 느슨하게 생성 (극단적 파라미터에서 드물게 발생 가능)