Docs: add Magic Exam Hall game design roadmap

README.md

@@ -1,17 +1,20 @@
-# Magic Recognizer V1.5
+# Magic Recognizer V1.5 / Magic Exam Hall
 
-기본 5문양 base seal recognizer를 유지하면서, 같은 캔버스에서 overlay operator를 누적하고 `final seal`로 compile 결과를 확정하는 마법진 인식체계 프로토타입입니다.
+마법 문양을 직접 그려 주문을 시전하는 게임 경험을 검증하기 위한 프로젝트입니다.
+
+현재 저장소의 중심은 Web 기반 `Magic Recognizer V1.5` 프로토타입이며, 게임 기획 기준은 `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층 월드 캐스팅 플레이 루프
 
 ## 요구 사항
@@ -78,7 +81,7 @@ npm run validate:docs
 기대 결과:
 
 ```bash
-validated 21 task documents against work queue
+validated 0 task documents against work queue
 ```
 
 ### 2. 자동 테스트 실행
@@ -231,20 +234,18 @@ src/       웹 데모와 recognizer 코어
 tests/     Vitest 테스트
 scripts/   문서 검증 스크립트
 docs/      방향/큐/task 문서
-chat/      원본 논의 보관소
 unity/     Unity Magic Exam Hall 플레이어블
 ```
 
 ## 문서 읽기 순서
 
 문서 기준을 먼저 보고 싶다면 아래 순서가 가장 빠릅니다.
 
-1. `docs/README.md`
-2. `docs/10_direction/final-direction.md`
-3. `docs/10_direction/prototype-target.md`
+1. `docs/GAME_DESIGN.md`
+2. `docs/PROJECT_ROADMAP.md`
+3. `docs/PROJECT_OVERVIEW.md`
 4. `docs/20_queue/work-queue.md`
-5. `docs/30_tasks/epic-02-symbols-and-input/task-01-base-symbol-prototypes.md`
-6. `docs/30_tasks/epic-02-symbols-and-input/task-02-input-interpretation-rules.md`
+5. `docs/30_tasks/README.md`
 
 ## 트러블슈팅
 
@@ -254,7 +255,7 @@ unity/     Unity Magic Exam Hall 플레이어블
 npm ci
 ```
 
-문서 검증이 실패하면 `work-queue.md`와 각 task 문서의 frontmatter 상태/의존성이 어긋난 것입니다. 먼저 아래를 다시 실행해 원인을 확인합니다.
+문서 검증이 실패하면 `work-queue.md`와 task 문서의 frontmatter 상태/의존성이 어긋난 것입니다. 현재 main 기준 task 문서는 아직 없으므로 정상 결과는 `validated 0 task documents against work queue`입니다. 먼저 아래를 다시 실행해 원인을 확인합니다.
 
 ```bash
 npm run validate:docs

docs/GAME_DESIGN.md

@@ -0,0 +1,332 @@
+# Magic Exam Hall Game Design
+
+이 문서는 `Magic Exam Hall`의 게임 기획 기준 문서입니다. 구현 세부 작업보다 먼저, 게임이 어떤 경험이어야 하는지와 플레이어가 무엇을 보고, 느끼고, 배워야 하는지를 기록합니다.
+
+## 1. 게임 정체성
+
+`Magic Exam Hall`은 떠 있는 마법탑의 입학 시험을 치르는 2D top-down 실시간 마법 드로잉 퍼즐 어드벤처입니다.
+
+플레이어는 별도 입력창을 열지 않습니다. 마법사는 맵 위 바닥에 직접 문양을 그리고, 그 문양은 세계 안에서 빛나다가 주문으로 발동합니다. 게임의 핵심은 정해진 레시피를 외워 맞히는 것이 아니라, 문양 언어를 실험하며 세계 상태를 바꾸고, 자기 방식으로 시험을 통과하는 것입니다.
+
+### 핵심 약속
+
+- 플레이어는 맵 위에 직접 마법진을 그린다.
+- 문양은 UI 미니게임이 아니라 세계 안의 행동이다.
+- 기본 문양은 세계를 바꾸는 동사다.
+- overlay 장식은 동사의 방식과 성질을 바꾼다.
+- 시험은 정답 주문이 아니라 목표 상태 달성으로 통과한다.
+- 실패는 처벌이 아니라 관찰과 다음 실험의 단서다.
+
+## 2. 대상 경험
+
+### 플레이어 판타지
+
+플레이어는 입학생 마법사입니다. 교관에게 정답을 받아 적는 학생이 아니라, 살아 있는 마법탑 안에서 룬의 반응을 직접 관찰하고, 손으로 그린 문양을 통해 세계를 이해하는 사람입니다.
+
+### 감정 곡선
+
+1. 낯선 탑에 들어온다.
+2. 바닥에 그린 문양이 실제로 빛나며 작동하는 것을 본다.
+3. 여러 문양이 서로 다른 방식으로 세계를 바꾼다는 것을 깨닫는다.
+4. overlay 장식이 같은 주문을 다르게 만든다는 것을 발견한다.
+5. 실패한 시도에서도 탑과 노트가 단서를 남긴다.
+6. 마지막 층에서 자신이 배운 문법을 자유롭게 조합한다.
+7. 정답을 맞힌 것이 아니라, 자기 방식으로 마법진을 복구했다고 느낀다.
+
+### 핵심 재미
+
+- 직접 시전감: 손으로 그린 선이 곧 주문이 된다.
+- 관찰과 실험: 주문이 오브젝트와 환경에 어떻게 반응하는지 본다.
+- 창의적 해결: 같은 목표를 여러 조합으로 해결할 수 있다.
+- 숙련감: 같은 문양도 더 안정적으로 그리면 효과가 좋아진다.
+
+## 3. 세계와 서사
+
+### 배경
+
+무대는 하늘에 떠 있는 오래된 마법탑입니다. 이 탑은 입학생을 평가하는 시험장이지만, 단순한 시험 시설이 아니라 스스로 반응하고 기록하는 살아 있는 장소입니다.
+
+탑은 완전히 고장난 상태는 아니지만, 오래된 입학 마법진이 불안정합니다. 플레이어는 각 층의 시험을 통과하며 탑의 문양 언어를 익히고, 마지막 층에서 대형 마법진을 복구해 입학 시험을 통과합니다.
+
+### 안내자
+
+명확하게 말하는 교관 NPC는 없습니다. 대신 플레이어에게는 말 없는 마법 노트가 있습니다.
+
+마법 노트는 정답을 알려주지 않습니다. 짧은 관찰문만 남깁니다.
+
+예시:
+
+- “번개는 갈라진 길을 좋아한다.”
+- “닫히지 않은 물은 힘을 오래 붙잡지 못한다.”
+- “절단 뒤에 축이 선다.”
+- “너무 빠른 불꽃은 멀리 번지지만 오래 머물지 않는다.”
+
+### 서사 목표
+
+플레이어의 표면 목표는 입학 시험 통과입니다. 실제 플레이 목표는 탑의 문양 언어를 이해하고, 마지막 마법진을 자기 방식으로 복구하는 것입니다.
+
+## 4. 조작과 맵 위 직접 드로잉
+
+### 기본 조작
+
+| 입력 | 행동 |
+| --- | --- |
+| WASD / 방향키 | 이동 |
+| 우클릭 hold | 마우스 위치의 바닥에 stroke를 그림 |
+| 우클릭 release | 현재 stroke 종료 |
+| 짧은 시간 안에 다시 우클릭 | 같은 주문 입력의 다음 stroke로 묶음 |
+| 입력 버퍼 종료 | 주문 판정 및 발동 |
+
+### 드로잉 원칙
+
+- 문양 입력은 별도 패널이나 별도 캔버스에서 하지 않는다.
+- 마우스가 가리키는 맵 바닥 위치에 직접 빛나는 stroke가 남는다.
+- 플레이어는 드로잉 중에도 계속 이동할 수 있다.
+- stroke는 잠깐 빛나다가 사라진다.
+- 주문 효과는 문양 전체의 중심에서 발생한다.
+- UI 위에 마우스가 있을 때는 드로잉 입력을 받지 않는다.
+
+### 다획 입력
+
+바람처럼 여러 획이 필요한 문양을 위해 짧은 입력 버퍼를 둔다.
+
+- 우클릭을 떼면 바로 주문이 확정되지 않는다.
+- 약 0.8초 안에 다음 stroke가 들어오면 같은 주문군으로 묶는다.
+- 0.8초 동안 추가 stroke가 없으면 현재 stroke 묶음을 하나의 주문으로 판정한다.
+
+이 버퍼는 플레이어에게 명시적인 “완성 버튼”을 요구하지 않으면서도 여러 획 문양을 가능하게 하기 위한 장치입니다.
+
+## 5. 마법 문법
+
+마법은 `base family`와 `overlay operator`로 구성됩니다.
+
+### Base family: 세계를 바꾸는 동사
+
+| Base | 문양 | 세계 동사 | 대표 반응 |
+| --- | --- | --- | --- |
+| Fire | 닫힌 삼각형 | 점화, 가열, 활성화 | 불씨 점화, 얼음 약화, 오래된 룬 깨움 |
+| Water | 닫힌 루프 | 정화, 냉각, 흐름 | 불 진압, 오염 씻기, 물길 생성 |
+| Wind | 평행한 열린 세 줄 | 밀기, 회전, 확산 | 기둥 이동, 바람개비 회전, 안개 흩기 |
+| Earth | 아래가 넓은 사다리꼴 | 생성, 고정, 지지 | 발판 생성, 흔들림 안정화, 벽 세우기 |
+| Life | 줄기와 갈래 Y | 성장, 연결, 회복 | 덩굴 성장, 씨앗 활성화, 끊긴 생명선 연결 |
+
+### Overlay operator: 동사의 방식을 바꾸는 장식
+
+| Overlay | 문양 성격 | 변형 역할 |
+| --- | --- | --- |
+| `steel_brace` | 열린 브레이스 | 구조 보강, 지속시간 증가, 안정화 |
+| `electric_fork` | 갈라지는 번개 | 효과 분기, 회로 전도, 연쇄 반응 |
+| `ice_bar` | 수평 막대 | 냉각, 고정, 정지 |
+| `soul_dot` | 작고 닫힌 점 | 집중, 정밀 타격, 핵심점 지정 |
+| `void_cut` | 대각 절단 | 연결 절단, 오염 분리, 흐름 차단 |
+| `martial_axis` | 축선 결합 | 힘의 방향 정렬, 후속 추진, 축 기반 강화 |
+
+### Base와 overlay 관계
+
+기본 규칙은 `base 먼저, overlay 후속`입니다.
+
+1. 플레이어가 맵 위에 base 문양을 그린다.
+2. base가 인식되면 그 위치에 짧게 유지되는 임시 seal이 생긴다.
+3. 플레이어가 같은 seal 근처에 overlay를 그리면 해당 base에 붙는다.
+4. 붙은 overlay는 주문의 성질을 바꾼다.
+5. `martial_axis`는 `void_cut`이 먼저 붙은 seal에서만 의미 있게 작동한다.
+
+### 자유도 원칙
+
+모든 base와 overlay는 처음부터 시도 가능하다. 게임은 “이 문양은 아직 해금되지 않았습니다”라고 막지 않습니다.
+
+대신 플레이어는 환경 반응을 통해 각 문양의 의미를 발견합니다. 시험은 특정 레시피를 요구하지 않고, 방의 목표 상태를 만족하면 통과됩니다.
+
+## 6. 품질 시스템
+
+문양 품질은 성공/실패만 가르는 처벌 장치가 아닙니다. 품질은 주문의 세기, 지속시간, 안정성, 범위에 영향을 줍니다.
+
+| 품질 요소 | 의미 | 게임 영향 |
+| --- | --- | --- |
+| Closure | 닫힌 문양의 끝점 완성도 | 닫힌 주문의 안정성, 유지 시간 |
+| Smoothness | 선의 매끄러움 | 흐름/물/바람 계열 효과 안정성 |
+| Tempo | 시전 속도 | 즉발성, 확산력, 불꽃의 번짐 |
+| Stability | 흔들림과 속도 변화 | 주문 실패율, 효과 떨림 |
+| Rotation Bias | 축과 방향의 편향 | 축 기반 효과와 이동 방향 |
+
+### 품질 처리 원칙
+
+- 명백히 잘못된 입력은 주문으로 발동하지 않고 흐릿한 파문만 만든다.
+- 애매하지만 읽을 수 있는 입력은 약한 효과로 발동한다.
+- 좋은 품질은 같은 주문의 범위, 지속시간, 안정성을 높인다.
+- 품질이 낮아도 플레이어의 실험을 완전히 막지 않는다.
+
+## 7. 피드백과 노트
+
+### 맵 피드백
+
+| 상황 | 피드백 |
+| --- | --- |
+| base 성공 | 바닥에 작은 원형 룬이 잠깐 고정된다. |
+| overlay 성공 | 룬 가장자리에 작은 장식 마크가 붙는다. |
+| final effect | 문양 중심에서 빛, 파동, 환경 변화가 발생한다. |
+| invalid input | 흐릿한 파문이 생기고 곧 사라진다. |
+| low quality | 약하고 불안정한 효과가 발생한다. |
+
+### 룬 라벨
+
+문양 위에는 짧은 라벨이 뜬다.
+
+예시:
+
+- `불꽃`
+- `물 + 얼음`
+- `생명 + 집중`
+- `절단 뒤 축`
+
+라벨은 플레이어가 자신의 입력이 어떻게 해석됐는지 즉시 알게 하기 위한 최소한의 UI입니다.
+
+### 마법 노트
+
+노트는 정답 안내서가 아니라 관찰 기록입니다.
+
+사용 원칙:
+
+- 새 반응을 발견하면 짧은 관찰문이 추가된다.
+- 반복 실패 시에만 더 직접적인 힌트가 열린다.
+- 노트는 플레이를 멈추게 하지 않고 화면 한쪽에 짧게 나타난다.
+- 최종 리포트에서 노트 기록이 다시 정리된다.
+
+## 8. 시험 구조
+
+첫 완성판은 5층 마법탑 구조입니다.
+
+### 1층: 발착층
+
+목표: 탑의 승강 룬을 깨운다.
+
+역할:
+
+- 모든 base 문양을 자유롭게 시도하게 한다.
+- 불씨, 물웅덩이, 돌기둥, 바람개비, 마른 덩굴이 각 base의 반응을 보여준다.
+- 최소 목표는 승강 룬 활성화지만, 모든 반응을 발견하면 노트가 더 풍부해진다.
+
+### 2층: 반응층
+
+목표: overlay가 base 주문을 바꾸는 방식을 발견한다.
+
+역할:
+
+- 6개 overlay를 강제 순서 없이 실험한다.
+- 벽화, 깨진 룬, 반응 오브젝트가 문양 단서를 준다.
+- 플레이어는 처음부터 모든 overlay를 그릴 수 있다.
+
+### 3층: 흐름층
+
+목표: 끊어진 공중 다리를 다시 연결한다.
+
+가능한 접근:
+
+- `earth + steel_brace`로 지지대 만들기
+- `wind + martial_axis`로 떠 있는 발판 정렬
+- `life + soul_dot`으로 덩굴 고리 성장
+- `water + ice_bar`로 임시 얼음 다리 만들기
+
+통과 기준은 특정 주문이 아니라 이동 가능한 경로가 만들어졌는지입니다.
+
+### 4층: 균열층
+
+목표: 불안정한 룬 폭주를 안정화한다.
+
+특징:
+
+- 환경 위험만 존재한다.
+- 번개 회로, 퍼지는 균열, 움직이는 플랫폼이 플레이어를 방해한다.
+- 위험에 닿으면 체력 감소가 아니라 가까운 안전 지점으로 리셋된다.
+- 실시간 드로잉의 긴장감을 가장 강하게 쓰는 층이다.
+
+### 5층: 성좌심
+
+목표: 실패한 대형 입학 마법진을 복구한다.
+
+특징:
+
+- 정답 레시피가 없다.
+- 대형 마법진은 여러 상태 요구치를 가진다.
+- 안정, 정화, 연결, 절단, 집중, 흐름을 어떤 조합으로든 채울 수 있다.
+- 부분 복구는 유지된다.
+- 완료 시 마법탑 전체가 밝아지고 입학 시험을 통과한다.
+
+## 9. 목표 판정 방식
+
+시험은 “정해진 주문을 썼는가”가 아니라 “세계 상태가 목표에 도달했는가”로 판정합니다.
+
+예시:
+
+| 목표 | 가능한 해결 방향 |
+| --- | --- |
+| 불을 끈다 | `water`, `wind + water`, `water + ice_bar` |
+| 회로를 연결한다 | `electric_fork`, `fire + electric_fork`, `soul_dot`으로 핵심점 활성화 |
+| 균열을 멈춘다 | `earth + steel_brace`, `ice_bar`, `void_cut` |
+| 오염을 분리한다 | `water`, `void_cut`, `soul_dot` |
+| 발판을 만든다 | `earth`, `water + ice_bar`, `life` |
+
+이 방식은 플레이어에게 자유도를 주면서도 구현과 검증을 가능하게 합니다.
+
+## 10. 실패와 위험
+
+### 실패 원칙
+
+- 실패는 즉시 처벌하지 않는다.
+- 잘못된 입력은 흐릿한 파문과 짧은 노트 반응으로 처리한다.
+- 반복 실패하면 노트가 더 구체적인 단서를 준다.
+- 플레이어가 “왜 안 됐는지”를 추측할 수 있어야 한다.
+
+### 환경 위험
+
+마법탑에는 적 전투가 없습니다. 대신 환경 위험이 있습니다.
+
+예시:
+
+- 불안정한 번개 회로
+- 퍼지는 균열
+- 흔들리는 발판
+- 밀려오는 바람
+- 닿으면 리셋되는 오염 장막
+
+위험에 닿으면 플레이어는 가까운 안전 위치로 돌아갑니다. 체력, 죽음, 마나 손실은 첫 완성판에서 사용하지 않습니다.
+
+## 11. 엔딩과 리포트
+
+마지막 마법진을 복구하면 탑이 밝아지고 입학 시험이 끝납니다.
+
+엔딩은 등급 랭크보다 성찰형 리포트로 마무리합니다.
+
+리포트 항목:
+
+- 가장 많이 사용한 base
+- 가장 많이 사용한 overlay
+- 발견한 조합 수
+- 평균 품질 경향
+- 가장 안정적으로 그린 문양
+- 가장 많이 실패한 문양
+- 노트가 기록한 대표 관찰문
+- 플레이어가 선택한 자기 평가 문항
+
+목표는 플레이어를 평가해 줄 세우는 것이 아니라, “내가 어떤 방식으로 마법을 이해했는지”를 보여주는 것입니다.
+
+## 12. 현재 구현과의 관계
+
+현재 Unity 프로토타입은 별도 입력 패널 없이 맵 위 바닥에 직접 문양을 그리는 흐름을 기본 플레이로 사용합니다. base seal을 만든 뒤 같은 seal 근처에 overlay를 붙이고, 층별 목표 오브젝트가 그 조합에 반응하는 5층 플레이 루프가 들어 있습니다.
+
+계속 유지할 설계 기준:
+
+- 플레이어 기본 경험에서는 별도 문양 입력 패널을 쓰지 않는다.
+- 맵 위 직접 드로잉이 기본 시전 방식이다.
+- base seal과 overlay stack은 세계 안에 잠깐 남는 피드백으로 보인다.
+- recognizer와 quality 분석은 계속 핵심 기술로 유지한다.
+
+## 13. 아직 열어둘 질문
+
+- 0.8초 입력 버퍼가 실제 조작감에 맞는가?
+- overlay seal 유지 시간은 몇 초가 가장 자연스러운가?
+- 한 번의 seal에 overlay를 몇 개까지 붙일 수 있어야 하는가?
+- 최종 마법진의 상태 요구치는 몇 종류가 적당한가?
+- 노트의 문장은 얼마나 시적으로, 얼마나 명확하게 써야 하는가?
+
+이 질문들은 구현 전에 프로토타입 조작감과 플레이 테스트로 결정한다.