diff --git a/docs/klay-calibration-experiment/00-plan.md b/docs/klay-calibration-experiment/00-plan.md new file mode 100644 index 0000000000..9fa134de2a --- /dev/null +++ b/docs/klay-calibration-experiment/00-plan.md @@ -0,0 +1,118 @@ +# Klay Calibration Baseline Experiment — Plan + +> *Version 0.2 — Draft (mac-first)* +> 본 문서는 [klay-framework](https://github.com/RataToaster/klay-framework) 리워크의 Phase 1 (Calibration Baseline)을 osu-framework 측에서 진행하기 위한 계획서이다. +> +> **업스트림(`ppy/osu-framework`) 머지 비목표. `RataToaster/osu-framework` fork 한정.** +> +> **klay-framework 1.0이 macOS 한정이므로, 본 baseline 측정도 macOS에서 1차 채집한다.** + +--- + +## 0. 맥락 + +`klay-framework/docs/00-background.md` §1.2는 osu!의 `Universal Offset` 단일 자유도가 시각-청각 비대칭 갭 `(D + Δ)`를 해소할 수 없다고 주장한다. + +본 실험은 이 주장을 정량 측정으로 입증한다. 측정 결과는 klay-framework Phase 2 (Timing Core) 설계의 baseline 데이터로 활용된다. + +--- + +## 1. 가설 + +**H1**: 같은 채보에서 X_v(visual offset)를 변화시키지 않는 한, 시각 의존 타격 시점과 청각 의존 타격 시점은 `D + Δ`만큼 분리된다. 단일 슬라이더 X(Universal Offset)를 어떤 값으로 옮겨도 두 분포 사이 거리는 변하지 않는다. + +**H2**: visual clock을 audio clock과 분리하여 X_v를 별도로 노출하면 두 분포 사이 거리를 0으로 만들 수 있다. + +--- + +## 2. 측정 환경 (mac-first) + +klay-framework 1.0이 macOS 한정이므로, 본 baseline도 macOS에서 1차 채집한다. Windows / Linux 측정은 Phase 2+ 진입 시 참고용으로만 추가. + +| 항목 | 값 | +|---|---| +| OS | macOS 13+ (Ventura 이상) | +| CPU | Apple Silicon (M-series) + Intel (대조) | +| 디스플레이 | 60Hz 외장 + ProMotion 120Hz 내장 | +| 오디오 | 내장 DAC, 유선, AirPods (AAC) | +| 마이크 | 내장 마이크 (필요 시) | + +osu-framework의 macOS 빌드가 정상 동작해야 함. M-series와 Intel 각각에서 측정 수행. + +--- + +## 3. 측정 변수 + +| 변수 | 수준 | +|---|---| +| X_v | 0, +30, +60, +100 ms | +| 입력 방식 | 청각 의존, 시각 의존, 혼합 | +| 오디오 출력 | 내장 스피커, 유선 헤드폰, AirPods (AAC) | +| 디스플레이 | 60Hz 외장, ProMotion 120Hz 내장 | +| BPM | 120, 180, 240 | +| 노트 밀도 | 단노트, 트릴, 스트림 | + +--- + +## 4. 구현 단계 + +### 4.1 Visual offset 분리 PoC + +- `FrameworkSetting` enum에 `VisualOffset` 추가 +- `FrameworkConfigManager.InitialiseDefaults`에 항목 등록 +- `FrameworkSetting.AudioOffset`은 기존 universal offset 그대로 유지 (대조군) +- visual clock 추상화 도입: + - 새 인터페이스 `IVisualClock : IClock` (시각 전용) + - 기존 audio-driven 게임플레이 클럭에서 시각 렌더링 경로를 fork +- 실험용 ruleset 또는 minimal scroll demo로 적용 + +### 4.2 hit timing 수집 + +- 모든 hit event에 wall-clock timestamp 기록 +- audio play head, visual scroll head, 입력 event timestamp 동시 기록 +- jsonl 또는 sqlite로 raw log 저장 +- 측정 메타: macOS 버전, CPU, 디스플레이 refresh rate, 오디오 디바이스 UID 함께 기록 + +### 4.3 분석 + +- 각 (X_v, 입력 방식, 오디오, 디스플레이) 조합별 hit timing 분포 (히스토그램 + KDE) +- 시각 / 청각 분포 평균 차이 ± 95% CI +- X_v 변화에 대한 평균 차이 응답 곱선 → X_v로 차이를 0에 맞출 수 있는지 확인 +- ProMotion 120Hz 환경 vs 60Hz 결과 비교 (Phase 3 predict-ahead 설계 근거) + +--- + +## 5. 산출물 + +- `docs/klay-calibration-experiment/protocol.md`: 측정 절차 상세 (macOS 디바이스 설정, 테스트 채보 목록, 플레이어 지침 포함) +- `docs/klay-calibration-experiment/results.md`: 측정 결과 + 그래프 +- `docs/klay-calibration-experiment/results.jsonl` 또는 sqlite: raw 데이터 +- PoC 코드 (이 브랜치 내) + +--- + +## 6. 비목표 + +- osu!lazer 또는 osu-framework 업스트림 머지 +- 일반 사용자에게 visual offset 슬라이더를 노출하는 사용자 향 기능 +- 본 PoC를 정식 PR로 제안 +- Windows / Linux 측정 (Phase 2+ 진입 시 별도 추가 고려) + +본 작업은 klay-framework의 macOS baseline 데이터 확보만을 목적으로 한다. + +--- + +## 7. 후속 + +본 실험 완료 후 측정 결과를 [klay-framework `docs/02-phases.md`](https://github.com/RataToaster/klay-framework/blob/claude/rework-klay-framework-Gewwr/docs/02-phases.md) Phase 1 항목에 링크하고, klay-framework Phase 2 진입을 승인한다. + +--- + +## 8. 작업 순서 (후속 세션) + +1. macOS에서 osu-framework 빌드 검증 (M-series + Intel) +2. `FrameworkSetting.VisualOffset` 추가 + 디폴트 0 +3. `IVisualClock` 인터페이스 추상화 추가 +4. 게임플레이 클럭에서 visual 경로 분기 + X_v 적용 +5. 로깅 + 측정 프로토콜 구현 (macOS 디바이스 메타 포함) +6. 실측 (60Hz, 120Hz, 유선, AirPods) + 결과 정리