ProjectQuint

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

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

독립 테스트 실행

.NET 10 SDK가 있으면 유니티를 설치하지 않고 판정·타이밍·파서와 주요 화면 상태 테스트를 실행할 수 있습니다. macOS와 Linux에서는 저장소 루트에서 다음 명령을 실행합니다.

Tools/agentctl test
Tools/agentctl replay --notes 1000 --seed 42 --fps 30
Tools/agentctl replay --notes 1000 --seed 42 --fps 240

재생 검증에는 생성한 노트와 입력 이벤트만 사용하며 음악 파일이나 외부 채보를 읽지 않습니다. 두 재생 결과의 result.judgement는 같아야 합니다. --fps는 가상 프레임 갱신 간격이며 실제 게임의 초당 프레임 수를 측정하는 옵션은 아닙니다.

Verification/의 프로젝트는 실제 게임 소스와 테스트 파일을 직접 컴파일합니다. 검증용으로 별도의 판정 엔진을 구현하거나 유니티 API를 모방하지 않습니다. 첫 실행에는 테스트 패키지를 복원할 인터넷 연결이 필요합니다.

주요 기능과 구성

판정과 타이밍: 렌더링 프레임과 분리한 판정 엔진, BPM·STOP을 처리하는 시간 변환, 롱노트 판정 정책을 순수 C#으로 구현했습니다.
입력과 오디오: 입력 이벤트 시각과 DSP 시각을 사용하며, 키음 재생·프리믹스 캐시·동기화 보정을 분리했습니다.
라이브러리와 저장: 팩별 곡 목록, 난이도표 연결, 검색과 정렬, 플레이 결과·프로필 저장을 관리합니다.
화면 구성: UI Toolkit 화면과 프레젠터를 사용해 화면 표시와 세션 상태를 나눴습니다.

설계

프레임 갱신 빈도와 판정 결과 분리

입력을 처리한 프레임의 시각으로 판정하면 프레임 지연이 점수에 영향을 줄 수 있습니다. RhythmJudgementEngine은 전달받은 곡 시각으로 판정하고, TempoMap과 ScrollMap은 음악의 시간 변환과 화면 위치 계산을 나눠 담당합니다. 판정 테스트와 합성 입력 재생에서 서로 다른 갱신 간격의 결과를 비교합니다.

비동기 작업의 수명과 화면 상태 분리

곡 교체는 준비한 리소스를 한 묶음으로 넘기고, 취소된 후보는 해제합니다. 업데이트 알림은 UpdateSessionController가 요청 세대와 화면 상태를 관리합니다. 취소된 요청의 늦은 응답은 무시하며, 게임 중에는 알림을 표시하지 않습니다. 업데이트 상태 테스트는 중복 요청·취소 후 재요청·표시 가능한 화면·같은 응답의 중복 전달을 검증합니다.

입력 장치와 프로필 화면 상태 분리

ProfileSessionController가 탭, 난이도표별 레이팅, 수집 기록과 배지의 선택 상태를 소유합니다. 키보드와 UI 이벤트는 같은 상태 변경 메서드를 호출합니다. 표시할 데이터가 줄거나 비어도 선택 인덱스가 유효하도록 프로필 상태 테스트에서 확인합니다.

측정 결과

합성 노트 10,000개와 입력 이벤트 18,822개를 사용하는 판정 코어 측정에서, 전체 입력 재생 시간의 중앙값은 4.831 ms였습니다. 엔진 생성은 별도로 측정했으며 중앙값은 0.995 ms였습니다. 이 입력 재생 구간에서 현재 스레드의 관리 메모리 추가 할당은 20회 모두 0바이트였습니다.

이 값은 macOS ARM64·.NET 10 환경에서 측정한 코어의 기준값입니다. 유니티 플레이어의 프레임 시간, 실제 입력·오디오 지연, FMOD 메모리 사용량을 뜻하지 않습니다. 측정 조건·원자료·재현 방법을 함께 확인할 수 있습니다.

주요 경로

경로	역할
`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/Core`	유니티와 .NET에서 공유하는 코어 테스트
`Assets/ProjectQuint/Tests/EditMode`	앱 상태·유니티 통합 테스트
`Verification`	독립 테스트 실행과 합성 입력·성능 측정 도구
`Tools`	빌드·배포 도구와 테스트
`Website/projectquint-site`	프로젝트 소개 사이트

프로젝트 열기

Unity Hub에서 유니티 6000.3.20f1을 설치합니다.
이 저장소의 루트 폴더를 프로젝트로 등록합니다.
패키지 복원과 에셋 임포트가 끝난 뒤 프로젝트를 엽니다.

유니티 에디터 활성화가 필요합니다. FMOD 패키지 접근과 사용 조건은 해당 공급자의 안내를 따릅니다. BMS 음악과 채보는 포함되어 있지 않으므로, 플레이할 콘텐츠는 별도로 등록해야 합니다.

검증

독립 검증의 실행 방법과 검증 범위는 검증 안내에 정리되어 있습니다. 독립 테스트 통과만으로 유니티 화면·오디오·네이티브 연동이 검증되었다고 보지 않습니다.

유니티 Test Runner에서 EditMode 테스트를 실행합니다. 명령줄 실행 시에는 -runTests -testPlatform EditMode -testResults <결과 파일> -logFile <로그 파일>을 사용하고, 테스트 시작 전에 종료되지 않도록 -quit는 함께 전달하지 않습니다. 일부 통합 테스트는 별도로 등록한 외부 BMS 자료가 있어야 실행됩니다.

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

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

콘텐츠와 라이선스

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

6.8 KiB Raw Blame History