basket_utils/POV-DESIGN-REVIEW.md

# 선수 시점 재생 정책 검토

2026-09-07 · 조사 및 권장 설계. 시점 주체 분리 등 아래 후속 정책은 아직 구현된 기능이 아니다.

## 판단

기본은 사용자가 지정한 선수 한 명에게 시점을 고정한다. 동시에 움직이는 선수 수, 공 소유 변화, 단계 전환에 따라 자동으로 다른 선수에게 전환하지 않는다. 전술 전체는 작전판으로 보고, 선수 시점은 특정 역할에서 무엇을 보고 판단해야 하는지 확인하는 용도로 구분한다.

| 선택 기준 | 장점 | 문제 | 권장 용도 |
| --- | --- | --- | --- |
| 움직이는 선수 자동 선택 | 별도 선택이 적음 | 동시 이동 우선순위가 자의적이고 정지한 스크리너·수비자의 역할을 놓침 | 기본 기능에서 제외 |
| 공 소유자 자동 선택 | 공 진행을 따라감 | 패스할 때마다 관찰 위치가 바뀌고 공중 구간의 주체가 애매함 | 추후 별도 관전 모드 |
| 사용자가 지정한 선수 고정 | 역할과 공간 관계가 일관됨 | 시야 밖 사건은 별도 보조가 필요 | 기본 선수 시점 |
| 단계별 지정 선수 | 코치가 의도한 설명 순서를 구성 | 설정 부담과 전환 규칙 필요 | 추후 설명용 재생 |

## 외부 근거와 적용 범위

- [Epic 공식 리플레이 문서](https://dev.epicgames.com/documentation/fortnite/replays-feature-in-fortnite-creative?lang=en-US)는 선택한 선수를 따르는 Third Person, 해당 선수 카메라를 재생하는 Gameplay, 자유롭게 움직이는 Drone 계열을 분리한다. 시점 주체와 카메라 방식을 별도로 설계하는 참고 사례다. 농구 교육 효과를 입증하는 근거는 아니다.
- [VisionCoach 농구 패스 시각 훈련 연구](https://www.cs.ucf.edu/courses/cap6121/spr2025/readings/Liu2024.pdf)는 선수의 1인칭 관점에서 패스 기회를 찾는 훈련을 다룬다. 특정 역할의 시각적 판단을 돕는 용도에 부합한다. 이 연구는 본 웹앱의 자동 시점 전환 규칙이나 최적 화각을 검증하지 않았다.
- [Three.js PerspectiveCamera 문서](https://threejs.org/docs/pages/PerspectiveCamera.html)는 수직 FOV와 화면 종횡비로 원근 투영을 구성한다. 키와 화각은 서로 다른 변수이며, 세로 화면에서는 수직 화각 제한 때문에 가로 시야가 줄어들 수 있다.

이 문서의 구체적인 UX 및 자동 시선 우선순위는 위 사례와 현재 코드 검토를 바탕으로 한 프로젝트 설계 제안이다.

## 현재 코드의 의미와 문제

- `src/scene.js`는 `selectedPlayerId`의 위치와 시선 샘플로 POV를 계산한다. 현재도 움직이는 선수 자동 전환 방식은 아니다.
- `src/main.js`는 같은 선택값을 편집 대상에도 사용한다. 명단에서 선수를 바꾸면 재생 세션을 벗어나 편집 미리보기로 돌아가고, 패스 도구를 선택하면 공 소유자로 선택값을 바꾼다. 이 결합 때문에 시점 기준이 불명확하게 느껴질 수 있다.
- `src/domain.js`의 자동 시선은 패스·스크린 대상 선수, 슛의 림, 오프볼 공격자의 공, 대인 수비자의 매치업을 따른다. 이는 '누구의 눈인가'와 별개의 '무엇을 보는가' 규칙이다.
- 눈높이는 이미 1.75m이다. 키 180~190cm 선수를 가정한 초기 눈높이로 유지할 수 있으나 개인별 신체 계측값은 아니다. 키를 올리는 것만으로 좌우 시야가 넓어지지 않는다.

## 권장 동작

1. 편집 대상 `selectedPlayerId`와 관찰 대상 `povPlayerId`를 분리한다. 처음 선수 시점에 진입할 때 선택한 선수를 관찰 대상으로 복사하고, 이후에는 명시적인 시점 선수 선택만 이를 변경한다.
2. 상단에 `O2 시점 · 선수 고정`을 항상 표시한다. PC에서는 선수 선택 드롭다운, 모바일에서는 같은 기능의 간결한 선택 패널을 제공한다.
3. 선택 선수의 행동이 없거나 이동이 끝나도 시점은 유지한다. 정지 상태에서 공과 다른 선수의 움직임을 관찰하는 것도 전술의 일부다.
4. 재생 중 다른 시점 선수를 명시적으로 선택하면 일시정지하고 현재 재생 시간을 유지한다. 새 위치로 즉시 전환하며 짧은 페이드와 선수명으로 전환을 알린다. 선수 사이를 카메라가 날아가는 연출은 피한다. 재생 버튼으로 이어 본다.
5. 단계 전환·반복 재생·패스 완료에도 관찰 대상을 유지한다. 관찰 선수가 데이터에서 사라진 경우 조용히 대체하지 말고 정지 후 재선택을 안내한다.
6. 작전판↔선수 시점 전환은 시간과 재생/정지 상태를 보존한다. 미니맵은 이후 보조 기능으로 제공하며 자신의 위치·시야 방향·공 위치를 표시한다.

## 관찰 대상과 독립적인 시선 규칙

| 행동/상황 | 자동 시선 권장값 |
| --- | --- |
| 명시적으로 지정한 시선 | 해당 지시를 우선 적용 |
| 패스 준비·릴리스 | 패스 받을 선수 |
| 패스 수신 중 | 날아오는 공 |
| 슛 | 림 |
| 오프볼 이동 | 공을 기본으로 하되 이동 방향·특정 선수 지정 허용 |
| 공 소유 이동 | 림/전방을 기본으로 하되 전술별 명시 지정 허용 |
| 스크린 | 접근 중 이동 방향, 세팅 시 지정 수비자 등 단계별 구분을 후속 검토 |
| 대인 수비 | 매치업 기본, 공 주시는 명시 지정; 자동 양쪽 번갈아 보기는 초기 범위 제외 |

눈길과 이동 방향을 동일하게 강제하지 않는다. 공을 보며 컷하거나 옆걸음으로 수비할 수 있어야 한다. 단, 현재 앱은 실제 눈동자·머리 움직임을 측정한 재현이 아니라 지정된 시선을 시뮬레이션한다.

## 좁은 시야 개선 방향

- 코트의 물리 크기(15×14m)와 이동 거리를 늘리면 전술 자체가 달라진다. 카메라가 담는 범위와 화면 구성을 넓히는 것이 우선이다.
- 눈높이 1.75m를 기본으로 사용하고, 가로 화각을 완만하게 넓힌다. 이는 신체 키로 계산한 정답이 아니라 화면 가독성을 위한 초기 설계값이다.
- 선수의 시선 목표를 바꾸지 않으면서 화면에서 목표를 약간 위에 배치하여 바닥·주변 선수가 더 보이게 한다.
- 가까운 선수의 이름표 크기를 제한한다. 실제 가림은 유지하되 이름표 때문에 추가로 장면을 가리지 않도록 한다.
- 세로 화면에서 과도한 원근 왜곡 없이 가로 화면과 동일한 범위를 담는 데는 한계가 있다. 가로 보기와 후속 미니맵을 보조 수단으로 사용한다.

## 후속 구현 검증 기준

- O1/O2/O3가 동시에 이동해도 O2 시점 유지.
- O1→O2 패스 동안 O3 시점 유지, O3는 기존 시선 규칙에 따라 공을 관찰.
- 정지한 스크리너·수비자를 선택해도 임의 전환 없음.
- 시점 선수 변경 시 같은 타임스탬프에서 일시정지; 다른 선수 위치로 전환한 뒤 이어 재생.
- 편집용 패스 도구·선수 선택이 관찰 대상을 덮어쓰지 않음.
- 단계 전환/탐색/반복/화면 회전 후 대상과 시간 일관성 확인.
- PC·모바일 세로·가로에서 대상 가시성, 가까운 이름표, 코트 바닥 범위를 확인.

실제 코드 작업은 AGENTS.md에 따라 GPT-5.6 Luna에게 위임한다.

## 이번에 적용한 시야 개선

- 기준 가로 화각 100° → 110°. 세로 화각 상한 85° → 100°로 완화. 화면 비율에 따라 실제 가로 범위는 제한될 수 있다.
- 눈높이 1.75m 유지. 코트 물리 크기 유지.
- 투영 영역을 높이의 8%만큼 아래로 옮겨, 시선 목표를 바꾸지 않고 바닥 영역을 더 표시.
- 선수 시점 이름표 축소 및 가까운 이름표의 화면 크기 제한. 이름표가 머리와 겹치지 않도록 위치 조정.
- 시점 주체 분리는 위 권장 설계로 기록했으며 이번 시야 개선에 포함하지 않았다.
- 검증: 테스트 93개 통과, 프로덕션 빌드 성공(기존 번들 크기 경고 유지). 1440×1000 PC, 390×844 세로, 844×390 가로 화면과 POV 재생 확인. 브라우저 오류 로그 없음.