Magic Recognizer V1.5 / Magic Exam Hall

마법 문양을 직접 그려 주문을 시전하는 게임 경험을 검증하기 위한 프로젝트입니다.

현재 저장소는 Web 기반 Magic Recognizer V1.5 연구 프로토타입과 Unity 기반 Magic Exam Hall 플레이어블을 함께 유지합니다. Magic Exam Hall은 별도 입력창이 아니라 맵 위 바닥에 직접 문양을 그리고, base family와 overlay operator를 조합해 세계 상태를 바꾸는 2D top-down 마법 드로잉 퍼즐 어드벤처입니다.

현재 범위:

• 웹 캔버스 기반 recognizer 연구 프로토타입
• 기본 5문양 base family 인식
• user input profile 누적
• raw quality / adjusted quality 분리
• base seal 이후 overlay operator stack 인식
• final seal compile 결과 표시
• JSON 로그 export
• 문서 상태 동기화 검증
• Magic Exam Hall 게임 기획/로드맵 문서화
• Unity 기반 Magic Exam Hall 5층 월드 캐스팅 플레이 루프
• Unity 타이틀, 메인 메뉴, 옵션, 일시정지, codex, 엔딩 복귀 흐름
• Unity 3슬롯 저장, 층 완료 자동 저장, codex 수동 저장
• 절차 생성 SFX 12종, BGM 2종, 선 인식/실패 비주얼 피드백
• 접근성 옵션: 좌/우클릭 스왑, 이동 키 프리셋, 마우스 감도, 텍스트 크기, 색 보조, 관찰 모드

요구 사항

웹 프로토타입:

• Node.js 20.x 이상
• npm 10.x 이상

확인:

node -v
npm -v

Unity 플레이어블:

• Unity 6000.3.14f1
• 유효한 Unity Editor 라이선스

빠른 시작

처음 clone 후 가장 먼저 할 일:

git clone <repo-url>
cd magic
npm ci

개발 서버 실행:

npm run dev

Vite가 출력하는 로컬 주소를 브라우저에서 열면 됩니다. 보통은 http://localhost:5173 입니다.

Unity 플레이어블 실행:

unity/MagicExamHall

1. Unity Hub 또는 Unity Editor에서 위 프로젝트 폴더를 엽니다.
2. Assets/Scenes/MagicExamHall.unity를 엽니다.
3. Play를 누릅니다.

조작은 WASD/방향키 이동, 우클릭 hold/release 월드 드로잉입니다. 옵션에서 방향키/IJKL 이동, 좌클릭 드로잉, 텍스트 크기, 색 보조, 관찰 모드, BGM/SFX 볼륨을 바꿀 수 있습니다. 기본 플레이에서는 별도 입력 패널이나 마법 시전 버튼을 사용하지 않습니다.

제출 후보를 만들 때는 Release Checklist를 따라 Web 검증, Unity 테스트, Windows 빌드, player smoke, 수동 5층 완주, 로그/개인정보 확인을 함께 점검합니다.

초기 검증 튜토리얼

처음 받았을 때는 아래 순서로 확인하면 됩니다.

1. 문서 상태 검증

큐와 task frontmatter가 맞는지 확인합니다.

npm run validate:docs

기대 결과:

validated 0 task documents against work queue

2. 자동 테스트 실행

recognizer 코어의 기본 family 인식, 거부 케이스, 품질 벡터 동작을 확인합니다.

npm test

watch 모드가 필요하면:

npm run test:watch

3. 프로덕션 빌드 확인

TypeScript 타입 검사와 Vite 번들링을 함께 확인합니다.

npm run build

정상 종료 시 dist/가 생성됩니다.

데모 사용 방법

현재 Web UI에는 두 층이 함께 들어 있습니다.

• core recognizer 기능:
  • base family 인식
  • overlay operator stack 인식
  • raw / adjusted quality 계산
  • final seal compile
• HCI 검토용 demo 기능:
  • quality vector use on/off compare
  • clean / explain / workshop 프리셋
  • why panel
  • guided scenario
  • recent seals / quick compare

개발 서버를 띄운 뒤 브라우저에서 아래 순서로 확인합니다.

1. 가장 빠른 HCI 시연 순서

1. 상단 View Preset에서 clean을 먼저 확인합니다.
2. Guided Demo Scenario에서 빠른 불꽃 또는 느린 불꽃을 선택합니다.
3. 캔버스에 기본 문양을 그리고 Seal Base를 눌러 base family를 고정합니다.
4. 오른쪽 Outcome Compare에서 quality off / quality on을 비교합니다.
5. explain 프리셋으로 바꿔 why panel과 quick compare를 함께 확인합니다.
6. 필요하면 workshop 프리셋으로 바꿔 analysis overlay와 detail panel을 엽니다.
7. Start Overlay 이후 같은 캔버스에서 overlay operator를 덧그린 뒤 Seal Final로 compile 결과를 확인합니다.

2. HCI 검토 포인트

시연 중 아래 문구와 카드가 바로 보여야 합니다.

• same shape, same family
• quality affects execution, not family
• quality off는 canonical baseline outcome만 보여 줌
• quality on은 quality vector 기반 outcome delta만 반영
• why panel은 상태 이유와 quality 영향 설명을 짧은 문장으로 제공
• quick compare는 현재 시도와 직전 결과를 로그 없이 비교 가능하게 제공

3. 버튼과 토글 설명

프리셋:

• clean: 설명/분석을 줄이고 draw와 핵심 결과 위주로 봄
• explain: why panel과 quality compare 중심으로 봄
• workshop: analysis overlay와 세부 패널까지 함께 봄

개별 토글:

• quality vector use: outcome layer에 quality delta를 반영할지 제어
• quality compare: quality off / on compare card 표시
• why panel: 결과 이유 설명 패널 표시
• analysis overlay: axis, closure, anchor zone, ghost guide 표시
• detail panels: raw / adjusted quality, profile, 로그 같은 세부 패널 표시

버튼 설명:

• Seal Base: 현재 base 입력을 canonical family로 확정
• Start Overlay: base seal 이후 overlay 입력 단계를 시작
• Seal Final: base family와 overlay stack을 compile 결과로 고정
• Undo: 마지막 stroke 제거
• Reset: 현재 입력 초기화
• Export Logs: 누적 recognition 로그를 JSON으로 저장

브라우저에서 빠르게 확인할 최소 시나리오:

1. 빠른 불꽃 시나리오를 선택
2. clean에서 불꽃 삼각형을 그림
3. Seal Base
4. quality vector use on/off를 바꾸며 Outcome Compare 확인
5. explain으로 전환해 why panel 확인
6. Start Overlay
7. steel_brace, ice_bar, void_cut 중 하나를 덧그림
8. Seal Final
9. quick compare에서 현재와 직전 결과를 비교

Base Family

현재 recognizer의 canonical silhouette는 family마다 1개만 사용합니다.

• 바람: 3개 평행 개방선
• 땅: 하변이 더 긴 폐합 사다리꼴
• 불꽃: 상향 인상의 폐합 삼각형
• 물: 단일 원형 폐합 루프
• 생명: 줄기 + 상단 분기 rooted Y

Overlay operator:

• steel_brace
• electric_fork
• ice_bar
• soul_dot
• void_cut
• martial_axis (void_cut 이후에만 활성화)

주의:

• base family 판정은 profile이 가져가지 않습니다.
• overlay는 base seal 이후에만 해석합니다.
• base stroke는 overlay phase에서 ghost overlay로만 보조합니다.

주요 스크립트

npm run dev            # 개발 서버
npm run build          # 타입 검사 + 프로덕션 빌드
npm test               # Vitest 일괄 실행
npm run test:watch     # Vitest watch
npm run validate:docs  # docs 상태/의존성 검증

Unity 검증 명령 예시:

& 'C:\Program Files\Unity\Hub\Editor\6000.3.14f1\Editor\Unity.com' -batchmode -quit -projectPath 'C:\Users\silve\source\repos\magic\unity\MagicExamHall' -executeMethod MagicExamHall.Editor.MagicExamHallSceneBuilder.BuildAll
& 'C:\Program Files\Unity\Hub\Editor\6000.3.14f1\Editor\Unity.com' -batchmode -projectPath 'C:\Users\silve\source\repos\magic\unity\MagicExamHall' -runTests -testPlatform editmode -testResults 'C:\Users\silve\source\repos\magic\unity\MagicExamHall\TestResults.xml'
& 'C:\Program Files\Unity\Hub\Editor\6000.3.14f1\Editor\Unity.com' -batchmode -projectPath 'C:\Users\silve\source\repos\magic\unity\MagicExamHall' -runTests -testPlatform playmode -testResults 'C:\Users\silve\source\repos\magic\unity\MagicExamHall\PlayModeTestResults.xml'
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\build-windows.ps1 -BuildPath 'tmp\MagicExamHallFinalize\MagicExamHall.exe' -LogPath 'unity\MagicExamHall\unity-build-finalize.log'
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\smoke-magic-exam-hall-player.ps1 -BuildPath 'tmp\MagicExamHallFinalize\MagicExamHall.exe' -LogPath 'tmp\MagicExamHallFinalize\player-smoke.log'

디렉토리 구조

src/       웹 데모와 recognizer 코어
tests/     Vitest 테스트
scripts/   문서 검증 스크립트
docs/      방향/큐/task 문서
unity/     Unity Magic Exam Hall 플레이어블

문서 읽기 순서

문서 기준을 먼저 보고 싶다면 아래 순서가 가장 빠릅니다.

1. docs/GAME_DESIGN.md
2. docs/ARCHITECTURE_LAYERS.md
3. docs/INPUT_LAYER_HANDOFF.md (player input and recognition handoff)
4. docs/RECOGNITION_CONTRACT.md
5. docs/TEAM_DEVELOPMENT_PLAN.md
6. docs/PROJECT_ROADMAP.md
7. docs/PROJECT_OVERVIEW.md
8. docs/20_queue/work-queue.md
9. docs/30_tasks/README.md

트러블슈팅

vitest: not found 가 뜨면 의존성이 설치되지 않은 상태입니다.

npm ci

문서 검증이 실패하면 work-queue.md와 task 문서의 frontmatter 상태/의존성이 어긋난 것입니다. 현재 main 기준 task 문서는 아직 없으므로 정상 결과는 validated 0 task documents against work queue입니다. 먼저 아래를 다시 실행해 원인을 확인합니다.

npm run validate:docs

Unity batchmode에서 아래 메시지가 보이면 코드 컴파일 실패가 아니라 라이선스 초기화 문제입니다.

No valid Unity Editor license found. Please activate your license.

로그 끝의 abort_threads: Failed aborting id ... mono_thread_manage will ignore it 메시지는 Unity/Mono 종료 과정에서 남는 노이즈일 수 있습니다. 같은 로그 안에 Exception, CS#### error, Test run failed가 함께 있는지 먼저 확인하세요.