개발 연대기 #1과 함께 보는 공식 문서 시리즈 (2/3). 원본: voice-quest/docs/02_feature_spec.md · 2026-07-20 기준 스냅샷

Voice Quest — 기능 명세서

버전: 0.1 · MVP에 구현된 기능은 ✅, 로드맵은 🔜 표기

1. 조작

2. 음성 파이프라인

마이크 (버튼 토글, 연속 인식)
  → Web Speech API (ko-KR, interim 표시)
  → 최종 텍스트 분류:
     ⓪ 욕설 순화(미칭 치환) — 금칙어를 "왕자님/공자님/대협" 등으로 치환 후 분류 (§2.1)
     ① 신뢰도 < 0.5 또는 1글자 이하  → [갸웃 제스처]
     ② 명령 키워드 매칭              → [명령 실행 + 채팅 표시]
     ③ 명령조 어미(~해줘/~해봐/~하자 등)인데 미매칭 → [갸웃 제스처]
     ④ 그 외                         → [채팅 전송 (말풍선 + 로그 + 네트워크 브로드캐스트)]

• ✅ interim(중간 인식) 텍스트 실시간 표시
• ✅ no-speech 에러 → 갸웃 제스처
• 🔜 LLM 의도 분류(②③ 판정을 휴리스틱 → LLM으로 교체)
• 🔜 웨이크워드/홀드-투-커맨드 모드 옵션

2.1 욕설 순화 — 미칭(美稱) 치환 ("바른말 고운말")

거친 말을 차단하는 대신 무협 세계관의 존칭으로 바꿔 말풍선에 띄운다. "이 바보야!" → "이 왕자님야!" — 부정 경험을 유머로 승화 (기획 근거: 01 §2-5, §2-1). 아이에게는 안전한 채팅, 성인에게는 말버릇 자정 장치이며, 음성 조작 특성상 또박또박 말해야 인식되므로 발음·발화 연습 효과를 함께 노린다 (01 §2-1).

• ✅ 금칙어(욕설/비하)가 포함된 발화는 해당 단어만 "왕자님/공자님/대협/소협" 등 무작위 미칭으로 치환되어 말풍선·채팅로그·네트워크에 표시된다.
• ✅ 적용 지점 2곳:
  1. 송신 전 — handleUtterance 분류 직전 (내 말풍선/브로드캐스트 모두 순화된 텍스트 사용)
  2. 원격 채팅 표시 시 — 순화 미적용 클라이언트(구버전/원본 HTML)가 보낸 원문 방어
• ✅ 명령 분류보다 먼저 실행 — "닥쳐" 같은 욕설이 공격 명령("쳐" 키워드)으로 오분류되는 것을 방지하는 순서 보장.
• 🔜 서버 전환 시 서버측 필터로 이동(치환 연출은 유지), 금칙어 사전 확장 + AI 모더레이션

3. 어리둥절(갸웃) 제스처 — 시그니처 UX

• ✅ 발동 조건: 위 분류 ①③ + no-speech
• ✅ 연출 시퀀스 (150프레임):
  1. 카메라 고정 (camYaw 갱신 중단) — "나를 돌아본다"는 느낌의 핵심
  2. 캐릭터가 카메라 방향으로 회전 (yaw lerp 0.2)
  3. 양팔 으쓱(armL/R rotation.z ±2.3) + 고개 갸웃(head rotation.z sin) + 머리 위 "?" 스프라이트
  4. 마지막 35프레임: 원래 방향(preYaw)으로 복귀
• ✅ 말풍선: "뭐라고...? 🤔" / "음? 무슨 뜻인지 모르겠는데 🤔"
• ✅ 테스트 버튼 제공, ✅ 멀티플레이 시 다른 플레이어에게도 제스처 전파('huh' 메시지)

4. 캐릭터

• ✅ 무협풍 절차적(procedural) 휴머노이드: 뻗친 흑발+정수리 스파이크, 붉은 두건+살랑이는 리본 2가닥, V자 흰 깃 청색 도포, 허리띠, 넓은 소매, 등의 검. 목/코/입/귀/눈썹, 어깨 넓고 허리 좁은 인체 비율.
• ✅ 애니메이션(절차적): 걷기(팔다리 스윙+도포 자락+바운스), 대기(숨쉬기), 검격(오른팔 휘두름), 으쓱
• ✅ 멀티플레이 시 플레이어별 도포 색 자동 배정(id 해시), 머리 위 닉네임 태그
• ✅ 리깅 글TF + 애니메이션 클립 적용 — KayKit Adventurers 2.0 Knight (CC0, Kay Lousberg www.kaylousberg.com). Idle/Run 크로스페이드 + 검격은 Melee_1H_Attack_Slice_Diagonal 원샷 재생, 검(sword_1handed)을 오른손 슬롯(handslot.r)에 부착해 검격 중에만 표시(발도). 으쓱(갸웃)은 본 오버레이. 로딩 실패 시 절차 캐릭터 폴백. (client/src/hero/gltfHero.ts)
• 🔜 무협 전용 모델로 교체 (MODEL_URL·클립 매핑만 교체. Soldier.glb도 public/models/에 보존)
• 🔜 커스터마이징(얼굴/머리/의상), 이모트

5. 카메라

• ✅ 오버숄더 3인칭: 캐릭터 뒤 4.8유닛, 높이 2.8, 시선은 캐릭터 앞 2.2유닛
• ✅ 이동 방향으로 부드럽게 선회(lerp 0.05), 위치 lerp 0.12
• ✅ 제스처 중 카메라 고정
• 🔜 핀치 줌, 충돌 회피(벽 뒤 카메라)

6. 전투

• ✅ 사거리(1.9유닛) 내 자동 공격, 쿨다운 40프레임, 데미지 12
• ✅ 공격 시 대상을 향해 회전 + 발도 검격 + 피격 몹 넉백 + 플레이어 피격 파편
• ✅ 몹: 슬라임형, HP 40, 어그로 범위 9유닛, 접근 공격(플레이어 HP -4)
• ✅ 사망 시 HP 회복+부활 메시지 (패널티 없음 — 소셜 게임 지향)
• ✅ 처치 수 카운트 공유(멀티)
• 🔜 스킬/협공, 몹 다양화, 보스

7. 멀티플레이 (MVP: P2P)

P2P 메시지 프로토콜 (JSON)

게스트 → 호스트
  {t:'hello', name}                          입장 인사
  {t:'me', x, z, yaw, w}                     내 상태 (10Hz)
  {t:'chat', text}                           채팅
  {t:'huh'}                                  갸웃 제스처

호스트 → 게스트 (브로드캐스트)
  {t:'snap', ps:[{id,n,x,z,yaw,w}], mobs:[[x,z]], k}   전체 스냅샷 (10Hz)
  {t:'chat', id, n, text}                    채팅 중계
  {t:'huh', id}                              제스처 중계

8. 생활 콘텐츠 (전부 🔜 — 서버 전환 후)

• 운동회: 존 입장 → 게임 상태 머신(대기→카운트다운→경기→결과) → 보상 지급
• 중고시장: 좌판 엔티티, 아이템 등록/조회, 에스크로 거래, 음성 흥정
• 유대 시스템: 플레이어 쌍별 유대치 DB 저장, 단계별 해금
• 상세는 01_game_concept.md §5–6 참조

9. 비기능 요구사항

• 브라우저: Chrome/Edge (Web Speech API 필수), 모바일 Chrome 지원
• 성능: 미드레인지 모바일 30fps 목표 (drawcall 최소화, 픽셀비 상한 2)
• 음성 데이터: STT는 브라우저(구글) 처리 — 개인정보 고지 필요
• 모더레이션: 클라이언트 미칭 치환 구현됨(§2.1). 서버 전환 시 서버측 필터 필수(클라이언트 치환은 연출로 유지)