ProjectQuint/README.md

ProjectQuint

유니티와 C#으로 만든 macOS 중심의 BMS 리듬 게임 클라이언트입니다. 4·5·6·7키와 왼쪽 스크래치를 지원하며, 사용자가 등록한 외부 BMS 폴더나 ZIP 파일을 읽습니다.

프로젝트 사이트에서 사용 안내와 배포 정보를 확인할 수 있습니다.

주요 기능과 구성

• 판정과 타이밍: 렌더링 프레임과 분리한 판정 엔진, 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 자료가 있어야 실행됩니다.

배포 도구의 테스트는 프로젝트 루트에서 실행합니다.

python3 -m unittest discover -s Tools/tests -v

콘텐츠와 라이선스

이 저장소는 ProjectQuint의 게임 소스, 테스트, 빌드·배포 도구를 관리합니다. BMS 음악과 채보는 배포물에 포함하지 않으며, 사용자가 별도의 라이브러리로 등록합니다. 서드파티 구성 요소의 고지와 라이선스는 ThirdParty/에 보존되어 있습니다.