플레이어 입력/인식/게임 경계 문서화

[SilverSupplier]

요약

• player input을 좁은 input capture와 stroke recognition/personalization으로 나눠 문서화했습니다.
• 핵심 경계는 device input -> input capture source -> session buffer -> StrokeInputSession -> recognition/personalization -> RecognitionResult -> Game Runtime입니다.
• Input Capture는 별도 최상위 제품 계층이 아니라 Platform Apps와 Recognition Runtime 사이의 handoff boundary로 정리했습니다.
• 게임 계층은 RecognitionResult 이후의 seal 생성, overlay stack, floor goal, world effect, HUD/logging에 집중하도록 분리했습니다.
• docs/ARCHITECTURE_LAYERS.md를 추가해 Product Design, Shared Contract, Recognition Runtime, Game Runtime, Platform Apps, Research/ML, Release/QA 계층을 나눴습니다.
• docs/INPUT_LAYER_HANDOFF.md를 추가해 입력 캡처, 선/형태 인식, 사용자별 보정, 게임 handoff 경계를 정리했습니다.
• docs/RECOGNITION_CONTRACT.md를 추가해 Web과 Unity가 같은 뜻으로 써야 하는 family, overlay, status, stroke/session, quality, result, log 개념을 맞췄습니다.
• README.md와 docs/PROJECT_ROADMAP.md의 문서 진입 순서를 갱신했습니다.

병렬 개발 관점

이 PR은 특정 담당자를 지정하기보다, 서로 다른 작업자가 충돌 없이 동시에 개발할 수 있는 경계를 먼저 잡는 문서 PR입니다.

Input capture boundary는 아래 작업을 독립적으로 진행할 수 있습니다.

• 마우스, 터치, 스타일러스, synthetic replay 같은 입력 source 교체
• point sampling, min distance, buffer timeout 조정
• 여러 stroke를 하나의 주문 입력으로 묶는 session policy 개선
• raw stroke export나 survey/replay bridge 초안 설계

Stroke recognition / personalization 계층은 아래 작업을 게임 규칙과 분리해 진행할 수 있습니다.

• 입력된 선이 어떤 family/operator 후보에 가까운지 판정
• quality, confidence, threshold, dynamic policy 조정
• user profile 기반 adjusted quality 또는 model/shadow 보조 판독 연결
• invalid/incomplete를 임의로 success로 올리지 않는 personalization guardrail 유지

Game runtime 계층은 입력 구현 방식과 recognizer 내부 구현에 덜 묶인 채 아래 작업을 이어갈 수 있습니다.

• recognition result 처리
• seal 생성과 overlay stack 적용
• floor goal과 world effect 구현
• HUD, hint, gameplay logging 정리

현재 Unity는 WorldDrawingController가 입력 감지, world 좌표 변환, stroke buffering, LineRenderer 표시, SpellBuffered 전달까지 함께 들고 있고, ExamGameController가 그 결과를 바로 recognition/game 처리로 이어 갑니다. 문서에서는 이 결합을 StrokeInputSession과 RecognitionResult 경계로 끊는 방향을 제안합니다.

구현 handoff

해당 영역 담당 팀원이 맡는 구현은 "플레이어가 그린 것"을 게임 규칙이 바로 쓸 수 있는 recognition result까지 만드는 쪽입니다.

Input capture 쪽 산출물:

• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Input/StrokeInputTypes.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Input/IStrokeInputSource.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Input/StrokeSessionBuffer.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Input/WorldPointerInputSource.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Input/SyntheticStrokeInputSource.cs

Recognition / personalization 쪽 산출물:

• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Recognition/IStrokeRecognitionService.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Recognition/IBaseGestureRecognizer.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Recognition/IOverlayGestureRecognizer.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Recognition/HeuristicBaseGestureRecognizer.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Recognition/HeuristicOverlayGestureRecognizer.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Recognition/StrokeRecognitionTypes.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Personalization/IUserInputProfileService.cs
• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Personalization/IRecognitionModelPolicy.cs

Presentation 쪽 산출물:

• unity/MagicExamHall/Assets/MagicExamHall/Scripts/Presentation/WorldStrokeVisuals.cs

게임 계층으로 넘기는 값은 raw mouse event나 raw stroke list가 아니라 StrokeRecognitionResult 같은 결과 객체입니다. 이 타입은 다음 Unity 리팩터에서 BaseRecognitionResult와 OverlayRecognitionResult를 한 handoff event로 감싸기 위한 제안 wrapper이며, 이 PR에서 새 canonical schema로 확정하지는 않습니다. 확정 전까지는 docs/RECOGNITION_CONTRACT.md의 base/overlay result contract를 기준으로 합니다.

RecognitionContext가 필요할 때는 current seal, overlay stack, reference frame 같은 read-only snapshot만 넣고, recognition 계층이 seal 생성/삭제, overlay stack 수정, floor goal 완료, HUD/logging을 직접 실행하지 않게 합니다.

WorldPointerInputSource
  -> StrokeSessionBuffer
  -> StrokeInputSession completed
  -> IStrokeRecognitionService.Recognize(...)
  -> StrokeRecognitionResult
  -> Game Runtime / ExamGameController

다음 구현 PR 방향

다음 PR은 C# 구현을 작게 나누는 쪽이 좋습니다.

1. Scripts/Input/StrokeInputTypes.cs 추가
2. IStrokeInputSource 추가
3. StrokeSessionBuffer 분리
4. WorldPointerInputSource로 현재 우클릭 drawing 유지
5. Presentation/WorldStrokeVisuals로 LineRenderer 표시 분리
6. IBaseGestureRecognizer / IOverlayGestureRecognizer service boundary 추가
7. GestureRecognizer / OverlayRecognizer static 호출을 heuristic 구현체 뒤로 감싸기
8. personalization/model policy boundary 추가
9. recognition coordinator/service가 StrokeSessionCompleted를 받아 recognition result를 만들게 변경
10. ExamGameController가 raw stroke와 recognizer 내부 구현 대신 recognition result만 받게 변경
11. SyntheticStrokeInputSource 또는 테스트 helper로 mouse 없이 입력 session 주입 가능하게 만들기

장기 assembly 분리는 MagicExamHall.Contracts, MagicExamHall.Input, MagicExamHall.Recognition, MagicExamHall.Personalization, MagicExamHall.Game, MagicExamHall.Presentation, MagicExamHall.Runtime 순서로 검토합니다. 초기에는 asmdef보다 namespace와 폴더 경계를 먼저 둡니다.

이번 PR 범위

이번 PR은 일부러 문서만 포함했습니다.

포함:

• 프로젝트 계층 문서
• player input과 recognition handoff 문서
• Web/Unity recognition contract 초안
• README/roadmap 문서 진입점 갱신

제외:

• Unity C# 파일 이동
• 기존 drawing runtime 변경
• AI/fine-tuning/model adapter 구현
• raw stroke 상시 저장
• floor content나 puzzle rule 변경

검증

• C:\Users\silve\.cache\codex-runtimes\codex-primary-runtime\dependencies\node\bin\node.exe scripts\validate-doc-state.mjs
• git diff --check
• git diff --cached --check

미실행:

• 로컬 npm test / npm run build
• 이유: 현재 로컬 shell에서 npm을 찾을 수 없고 node_modules도 없습니다.