프로젝트 소스 공개

README.md

@@ -0,0 +1,55 @@
+# ProjectQuint
+
+유니티와 C#으로 만든 macOS 중심의 BMS 리듬 게임 클라이언트입니다.
+4·5·6·7키와 왼쪽 스크래치를 지원하며, 사용자가 등록한 외부 BMS 폴더나 ZIP 파일을 읽습니다.
+
+[프로젝트 사이트](https://projectquint.duckdns.org/)에서 사용 안내와 배포 정보를 확인할 수 있습니다.
+
+## 주요 기능과 구성
+
+- **판정과 타이밍**: 렌더링 프레임과 분리한 판정 엔진, BPM·STOP을 처리하는 시간 변환,
+  롱노트 판정 정책을 순수 C#으로 구현했습니다.
+- **입력과 오디오**: 입력 이벤트 시각과 DSP 시각을 사용하며, 키음 재생·프리믹스 캐시·동기화 보정을 분리했습니다.
+- **라이브러리와 저장**: 팩별 곡 목록, 난이도표 연결, 검색과 정렬, 플레이 결과·프로필 저장을 관리합니다.
+- **화면 구성**: UI Toolkit 화면과 프레젠터를 사용해 화면 표시와 세션 상태를 나눴습니다.
+
+## 주요 경로
+
+| 경로 | 역할 |
+| --- | --- |
+| `Assets/ProjectQuint/Runtime/Core` | 채보 파싱, 타이밍, 판정, 게이지와 성장 계산 |
+| `Assets/ProjectQuint/Runtime/Unity/Features` | 앱 흐름과 게임플레이·라이브러리 세션 |
+| `Assets/ProjectQuint/Runtime/Unity/Audio` | 오디오 백엔드와 재생·캐시 |
+| `Assets/ProjectQuint/Runtime/Unity/Persistence` | 플레이 결과와 프로필 저장 |
+| `Assets/ProjectQuint/Runtime/Unity/UI` | 화면 프레젠터와 UI 리소스 |
+| `Assets/ProjectQuint/Tests/EditMode` | 유니티 편집 모드 테스트 |
+| `Tools` | 빌드·배포 도구와 테스트 |
+| `Website/projectquint-site` | 프로젝트 소개 사이트 |
+
+## 프로젝트 열기
+
+1. Unity Hub에서 유니티 `6000.3.20f1`을 설치합니다.
+2. 이 저장소의 루트 폴더를 프로젝트로 등록합니다.
+3. 패키지 복원과 에셋 임포트가 끝난 뒤 프로젝트를 엽니다.
+
+유니티 에디터 활성화가 필요합니다. FMOD 패키지 접근과 사용 조건은 해당 공급자의 안내를 따릅니다.
+BMS 음악과 채보는 포함되어 있지 않으므로, 플레이할 콘텐츠는 별도로 등록해야 합니다.
+
+## 검증
+
+유니티 Test Runner에서 `EditMode` 테스트를 실행합니다. 명령줄 실행 시에는
+`-runTests -testPlatform EditMode -testResults <결과 파일> -logFile <로그 파일>`을 사용하고,
+테스트 시작 전에 종료되지 않도록 `-quit`는 함께 전달하지 않습니다.
+일부 통합 테스트는 별도로 등록한 외부 BMS 자료가 있어야 실행됩니다.
+
+배포 도구의 테스트는 프로젝트 루트에서 실행합니다.
+
+```bash
+python3 -m unittest discover -s Tools/tests -v
+```
+
+## 콘텐츠와 라이선스
+
+이 저장소는 ProjectQuint의 게임 소스, 테스트, 빌드·배포 도구를 관리합니다.
+BMS 음악과 채보는 배포물에 포함하지 않으며, 사용자가 별도의 라이브러리로 등록합니다.
+서드파티 구성 요소의 고지와 라이선스는 `ThirdParty/`에 보존되어 있습니다.