리듬게임 소스코드: 채보, 판정 타이밍, 곡 추가
Riffvolt가 12곡과 48개 채보를 어떻게 저장하는지, 판정과 점수가 어디서 정해지는지, 나만의 곡을 추가하려면 무엇이 필요한지 정리했습니다.
리듬게임 소스코드는 사실 두 가지로 이루어져 있습니다. 타이밍을 판정하는 코드와, 각 노트가 언제 오는지 정하는 데이터입니다. 구매자는 거의 언제나 두 번째를 바꾸고 싶어 합니다. 새 곡이 들어가야 리듬게임이 비로소 자기 것이 되기 때문입니다. 저희 4레인 록 리듬게임 템플릿 Riffvolt는 곡 목록을 매니페스트 파일 하나에, 채보는 각각 별도 파일에 두었습니다. 그래서 곡 추가는 체크리스트가 분명한 데이터 작업입니다.
이 가이드는 패키지를 차례로 살펴봅니다. 게임 구성, 판정과 점수 위치, 곡 추가 방법, 리빌드와 호스팅, 라이선스 범위, 이 에디션에서 빠진 것까지입니다. 파일 이름은 게임에 포함된 구매자 가이드를 따릅니다.
처음부터 기억해 둘 사실 하나: 저희 일부 템플릿과 달리 Riffvolt는 소스를 바꾸거나 곡을 추가한 뒤 리빌드가 필요합니다. 제공된 게임 폴더를 호스팅하는 데는 정적 웹 호스트만 있으면 됩니다.
이 리듬게임 소스코드의 구성
Riffvolt는 브라우저용으로 완성된 4레인 록 리듬게임입니다. 플레이어는 박자에 맞춰 노트를 치고, 롱노트를 끝까지 누르고, 와미로 음을 휘게 하며, ROCK 게이지를 채워 오버드라이브를 발동합니다. 오버드라이브는 점수를 더하지 않는 조명 연출이며, 한 번이라도 놓치면 끝납니다. 타이밍 정확도가 점수와 콤보를 쌓습니다.
- 풀버전 12곡, 곡마다 Easy, Normal, Hard 채보, 투어를 마치면 열리는 Rock God까지 총 48개 채보.
- 네 공연장(Garage, The road, Festival, Arena)을 도는 투어, 공연장마다 3곡. 앞 두 곡의 별로 앙코르가 열리고, 앙코르를 마치면 다음 공연장이 열리며, 스토리 장면과 트레일·프레임 같은 꾸미기 보상이 있습니다.
- 자유 플레이: 어떤 곡이든 어떤 난이도로든 플레이하고, 개인 기록은 곡별로 브라우저에 저장됩니다.
- 조작: 기본 D, F, J, K 키, 터치스크린에서는 레인 탭, 또는 게임패드. 키 설정은 설정 메뉴에 있습니다.
- 편의 기능: 블루투스 헤드폰에 도움이 되는 오디오 오프셋 보정, 움직임 줄이기, 섬광과 번개를 약하게 하는 광과민 모드.
- 인터페이스 14개 언어.
파일 구성
다운로드에는 game/(배포용 파일), source/(TypeScript 프로젝트), documentation/(영어와 포르투갈어 그림 매뉴얼), licenses/(제3자 고지)가 들어 있습니다. source/ 안에서는 곡 데이터와 게임 로직이 깔끔하게 나뉘어 있습니다.
- public/manifest.json: 곡 카탈로그. 곡마다 길이, 오디오 버전, 채보 경로.
- public/charts/: 48개 채보.
- public/audio/: 곡 녹음 파일.
- src/core/chartValidate.ts: 채보 스키마와 타이밍 검증.
- src/core/judge.ts: 타이밍 판정.
- src/core/scoring.ts: 점수와 콤보 규칙.
- src/game/campaign.ts: 투어 진행.
- src/game/session.ts: 곡 한 판의 진행 과정과 결과 계산.
- src/i18n/locales.ts: 14개 인터페이스 사전.
- src/net/localRecords.js: 로컬 개인 기록.
- src/ui/style.css: 인터페이스와 반응형 레이아웃.
판정과 점수가 별도 파일이라서, 점수 합산 방식은 건드리지 않고 판정 범위만 엄격하게 하거나 너그럽게 할 수 있고, 그 반대도 가능합니다. 어떤 리듬게임 코드를 보든 이 분리가 되어 있는지 확인하세요.
나만의 곡 추가하기, 단계별 안내
리듬게임 구매자가 가장 먼저 묻는 수정입니다. 패키지에 채보 에디터는 없으므로 채보는 데이터로 작성하며, 매뉴얼에 파일마다 필요한 항목이 정확히 나와 있습니다.
- 녹음 파일을 public/audio/에 넣습니다. 최종 제품에 쓸 권리가 있는 오디오만 사용하세요.
- public/charts/에 지원할 난이도마다 채보를 하나씩 만듭니다. 각 채보에는 일치하는 songId, difficulty, audioVersion, offset과 순서대로 정렬된 노트가 필요합니다.
- public/manifest.json에 고유 id, 길이, BPM, 테마, audioVersion, 채보 경로와 함께 곡을 추가합니다.
- chartValidate.ts의 검증기로 채보를 하나씩 확인합니다.
- 모든 난이도로 곡 전체를 플레이해 싱크를 확인합니다. 검증기는 구조와 타이밍 규칙을 확인할 뿐, 노트가 손맛이 맞는지는 확인하지 않습니다.
- 리빌드한 뒤 새 빌드를 업로드합니다.
곡 하나를 더하는 게 아니라 사운드트랙 전체를 바꾸려면 채보 단위로 계획하세요. 12곡 × 4난이도는 48개 채보이고, 출시 전에 하나하나 끝까지 플레이해 봐야 합니다.
리빌드와 그 밖의 수정
Node.js 24 LTS를 권장합니다. source/ 안에서 npm ci, 이어서 npm run typecheck와 npm run build를 실행하고 dist/의 내용만 배포하세요. npm run preview는 확인용으로 로컬 빌드를 띄웁니다. node_modules/는 업로드하지 마세요. Vite가 상대 base를 쓰므로 빌드는 하위 폴더에서도 동작합니다. 제공되는 런타임은 읽기 쉽게 정리되어 있으며, 매뉴얼은 다음 사람도 읽을 수 있도록 리빌드할 때 minify:false와 cssMinify:false를 유지하라고 안내합니다.
- 브랜드: src/ui/style.css의 색상과 레이아웃, 그리고 로고. 화이트 라벨이 허용되므로 저희 브랜드 대신 여러분의 브랜드를 넣을 수 있습니다.
- 텍스트: 배포할 언어의 src/i18n/locales.ts.
- 투어: campaign.ts의 공연장 순서와 해금 조건.
- 난이도: judge.ts의 판정 범위, 그다음 scoring.ts의 점수·콤보 규칙.
- 곡: 맨 마지막에. 새 채보마다 끝까지 플레이해 봐야 하기 때문입니다.
수정 전에 백업하고, 한 번에 기능 하나만 바꾸고, 바꿀 때마다 메뉴, 곡 하나, 일시정지, 결과 화면, 새로고침을 테스트하세요. 기존 플레이어의 기록이 유지되도록 아이템 id와 저장 키는 바꾸지 마세요.
호스팅 또는 포털에 임베드하기
game/의 내용을 HTTP(S) 호스트의 폴더에 상대 경로 그대로 올리고 주소를 여세요. PHP, 데이터베이스, 계정은 필요 없습니다. index.html을 file://로 열지 마세요. 로컬 테스트는 game/ 안에서 python -m http.server 8765를 실행하면 됩니다.
- 브라우저 요구 사항: JavaScript, ES 모듈, Canvas 2D, Web Audio.
- 브라우저는 첫 탭이나 클릭 이후에만 오디오를 허용하므로 첫 화면에서 소리가 나지 않는 것은 정상입니다.
- iframe에서는 전체 화면과 자동 재생을 허용하세요.
- .js는 JavaScript MIME 타입으로 제공하고, text/plain으로 보내면 안 됩니다.
- 런타임 에셋, 폰트, 라이브러리가 모두 빌드 안에 있습니다. 필수 CDN은 없지만 설치형 오프라인 앱은 아닙니다.
저장 데이터는 브라우저 오리진에 묶이므로 게임을 다른 도메인으로 옮기면 플레이어는 처음부터 시작합니다. 이 에디션은 저희 포털 에디션과 분리된 자체 저장 키를 씁니다. 네이티브 앱 프로젝트는 포함되지 않으며, 스토어 출시는 별도 작업입니다.
이 에디션에 포함되지 않은 것
Riffvolt는 로컬 브라우저 에디션입니다. 온라인 방이나 멀티플레이, 온라인 랭킹이나 공유 리더보드, 광고 SDK나 광고 계정, 채보 에디터, 네이티브 앱, 호스팅이 없습니다. 개인 기록과 투어 진행 상황은 플레이어의 브라우저에 남습니다.
카탈로그에 음악 게임이 어울린다면, 타이밍을 기반으로 한 저희 다른 템플릿 두 개도 함께 둘 만합니다.
Pinloop: 타깃 30개가 있는 원버튼 타이밍 아케이드
라이선스와 가격
Riffvolt의 정가는 $49입니다. 2026년 11월 30일까지 블랙 프라이데이 프로모션으로 15% 할인되어 $41.65이며, 한 주문에 템플릿을 두 개 이상 사면 5%~20% 묶음 할인이 추가됩니다. 라이선스는 영구·비독점이며 최종 제품 하나(여러분의 것 또는 고객사 하나)에 적용됩니다. 코드·아트·오디오 수정, 저희 브랜드를 여러분의 브랜드로 교체, 무료 또는 광고 포함 서비스가 가능합니다. 포함된 곡은 그 최종 제품의 일부로 사용하며, 템플릿이나 코드, 에셋을 단독으로 재판매할 수는 없습니다. 지원 6개월이 포함되며 연장 시 12개월이고, 새 곡·연동·호스팅은 별도 견적입니다.
자주 묻는 질문
리듬게임 소스코드에 제 곡을 추가할 수 있나요?
네. 오디오, 난이도별 채보 하나씩, public/manifest.json 항목을 추가하고, 채보를 검증하고 끝까지 플레이한 뒤 리빌드하면 됩니다. 채보 에디터는 포함되지 않습니다.
Riffvolt를 쓰려면 Node.js가 필요한가요?
제공된 게임 폴더를 호스팅하는 데는 필요 없습니다. Node.js 24 LTS는 TypeScript를 수정하거나 곡을 추가한 뒤 리빌드할 때만 권장됩니다.
터치스크린과 게임패드에서도 되나요?
네. 레인을 탭하거나 게임패드를 쓸 수 있고, 조작은 설정 메뉴에서 정합니다. 성능은 기기에 따라 다르니 대상 기기로 테스트하세요.
블루투스 헤드폰과 지연은 어떤가요?
설정에 오디오 오프셋을 맞추는 오디오 보정 기능이 있어 블루투스 헤드폰 사용에 도움이 됩니다.
온라인 리더보드가 있나요?
아닙니다. 개인 기록은 곡과 난이도별로 플레이어의 브라우저에 저장됩니다. 원격 상대나 공유 랭킹은 없습니다.
이런 분께 맞습니다
Riffvolt는 카탈로그에 음악 게임을 넣고 싶은 포털이나 사이트, 고객사 하나에 브랜드 리듬게임을 납품하는 스튜디오, Canvas 2D와 Web Audio 게임이 TypeScript로 타이밍을 어떻게 판정하는지 읽어 보고 싶은 개발자에게 맞습니다. 비개발자용 시각적 채보 에디터나 온라인 대전이 필요하다면 덜 맞습니다. 둘 다 맞춤 개발입니다.