Сорс код на ритъм игра: нотни карти, тайминг и добавяне на песни
Как Riffvolt съхранява 12 парчета и 48 карти, къде се решават таймингът и точкуването и какво е нужно, за да добавите собствена песен.
Сорс кодът на ритъм игра е всъщност две неща: кодът, който оценява тайминга, и данните, които казват кога пристига всяка нота. Купувачите почти винаги искат да променят второто, защото новите песни са това, което прави ритъм играта ваша. Riffvolt, нашият ритъм шаблон за рок с четири ленти, пази списъка с песни в един манифест, а всяка нотна карта – в собствен файл, така че добавянето на песен е работа с данни и ясен списък за проверка.
Това ръководство минава през пакета: какво се свири, къде живеят таймингът и точкуването, как се добавя песен, как се компилира и хоства, какво позволява лицензът и какво изданието не включва. Имената на файловете идват от ръководството за купувача, включено в играта.
Един факт за наум от самото начало: за разлика от някои от нашите шаблони, Riffvolt се нуждае от повторна компилация след промяна на сорс кода или добавяне на песни. Хостването на доставената папка на играта изисква само статичен уеб хостинг.
Какво свири този сорс код на ритъм игра
Riffvolt е готова рок ритъм игра с четири ленти за браузъра. Играчите удрят нотите навреме, държат дългите ноти до края, огъват ги с whammy bar (лоста за деформиране на тона) и пълнят индикатора ROCK, който стартира overdrive – светлинно шоу, което не добавя точки и приключва при всеки пропуск. Точността на тайминга натрупва резултат и комбо.
- 12 пълни парчета, всяко с карти Easy, Normal и Hard (лесно, нормално и трудно), плюс Rock God (рок бог), който се отваря след турнето: общо 48 нотни карти.
- Турне през четири места – Garage (гараж), The road (пътят), Festival (фестивал) и Arena (арена) – по три песни на място. Звездите от първите две отварят бис, а завършването на биса отваря следващото място, със сцени с история и козметични награди като следи и рамки.
- Free play (свободна игра): всяка песен на всяка трудност, с лични рекорди, записани по песен в браузъра.
- Управление: D, F, J и K по подразбиране, докосване на лентите на сензорен екран или геймпад. Клавишните настройки са в Settings (настройки).
- Удобство: калибриране на аудиото за отместването, което помага при Bluetooth слушалки, намалено движение и режим за светлочувствителност (photosensitive mode), който приглушава светкавиците и проблясъците.
- 14 езика на интерфейса.
Вижте страницата на Riffvolt, демото и ръководствата
Как са организирани файловете
Изтеглянето съдържа game/ (файловете за хостване), source/ (проектът на TypeScript), documentation/ (илюстрирани ръководства на английски и португалски) и licenses/ (бележки за трети страни). В 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: интерфейс и адаптивно оформление.
Понеже judge и scoring са отделни файлове, можете да направите прозорците за тайминг по-строги или по-снизходителни, без да докосвате начина, по който се натрупват точките, и обратно. Това е разделението, което трябва да търсите във всеки ритъм код.
Добавяне на собствена песен, стъпка по стъпка
Това е промяната, за която купувачите на ритъм игри питат първо. В пакета няма редактор на карти, затова картите се пишат като данни, а ръководството изброява точно какво изисква всеки файл.
- Сложете записа в public/audio/. Използвайте само аудио, за което имате права за крайния си продукт.
- Създайте по една карта за всяка поддържана трудност в public/charts/. Всяка карта трябва да има съвпадащите songId, difficulty, audioVersion, offset и нотите в ред.
- Добавете песента в public/manifest.json с уникално id, продължителност, BPM, тема, audioVersion и пътищата до картите.
- Проверете всяка карта с валидатора в chartValidate.ts.
- Изиграйте цялото парче на всяка трудност, за да потвърдите синхрона. Валидаторът проверява структурата и правилата за тайминг, а не дали една нота се усеща добре.
- Компилирайте отново и качете новия build.
Ако искате цял нов саундтрак, а не една допълнителна песен, планирайте работата по карти: 12 песни на четири трудности са 48 карти и всяка заслужава пълно изиграване преди излизане.
Компилиране и какво още да промените
Препоръчваме Node.js 24 LTS. В source/ пуснете npm ci, после npm run typecheck и npm run build, и публикувайте само съдържанието на dist/. npm run preview сервира локалния build за проверка. Не качвайте node_modules/. Vite използва относителна база, така че build-ът работи в подпапка. Доставената работна версия е форматирана за четене; ръководството моли при компилиране да запазвате minify:false и cssMinify:false, за да може следващият човек пак да я чете.
- Бранд: цветовете и оформлението в src/ui/style.css, плюс вашето лого. Бялата етикетировка е разрешена, така че вашата марка може да замени нашата.
- Текстове: src/i18n/locales.ts, за езиците, които пускате.
- Турне: редът на местата и какво какво отключва, в campaign.ts.
- Трудност: прозорците за тайминг в judge.ts, после правилата за резултат и комбо в scoring.ts.
- Песните – последни, защото всяка нова карта изисква пълно изиграване.
Архивирайте преди редакция, променяйте по една функция наведнъж и след всяка промяна тествайте менюто, песен, пауза, екрана с резултата и презареждане. Пазете идентификаторите на предметите и ключовете за запис стабилни, за да запазят съществуващите играчи рекордите си.
Хостване или вграждане в портал
Качете съдържанието на game/ в папка на вашия HTTP(S) хостинг, запазете относителните пътища и отворете адреса. Не са нужни PHP, база данни или акаунт. Не отваряйте index.html през file://; за локален тест пуснете python -m http.server 8765 в папката game/.
- Нужно на браузъра: JavaScript, ES модули, Canvas 2D и Web Audio.
- Браузърите пускат аудиото едва след първото докосване или клик, затова тих първи екран е нормален.
- Във iframe разрешете цял екран и автоматично пускане.
- Сервирайте .js с JavaScript MIME тип, никога като text/plain.
- Всички активи за работа, шрифтовете и библиотеките са в build-а. Няма задължителен CDN, но това не е приложение за инсталиране и работа офлайн.
Записите принадлежат на произхода на браузъра, така че преместването на играта на друг домейн започва играчите от нулата. Това издание използва собствени ключове за запис, отделни от нашите портални издания. Проекти за нативни приложения не са включени; публикуването в магазин е отделна работа.
Какво изданието не включва
Riffvolt е локалното издание за браузър. Няма онлайн стаи или мултиплейър, няма онлайн класация или общ списък с резултати, няма рекламен SDK или акаунт, няма редактор на карти, няма нативни приложения и няма хостинг. Личните рекорди и напредъкът в турнето остават в браузъра на играча.
Ако музикална игра съответства на каталога ви, две други наши шаблона с тайминг могат да стоят до нея.
Pinloop: аркадна игра с тайминг и един бутон, с 30 мишени
Ricopop: аркадна игра с рикошети и 50 нива
Лиценз и цена
Riffvolt е на каталожна цена 49 USD. До 30 ноември 2026 г. промоцията за Black Friday намалява цената с 15%, така че струва 41,65 USD, а покупката на два или повече шаблона в една поръчка добавя пакетна отстъпка от 5% до 20%. Лицензът е вечен и неексклузивен, за един краен продукт – ваш или на един ваш клиент. Можете да променяте кода, арта и звука, да замените нашата марка с вашата и да предлагате играта безплатно или с реклами. Използвайте включените парчета като част от този краен продукт; не можете да препродавате шаблона, кода му или активите му самостоятелно. Шест месеца поддръжка са включени, или дванадесет с разширението; нови песни, интеграции и хостинг се оценяват отделно.
Прочетете пълните лицензни условия
Често задавани въпроси
Мога ли да добавя свои песни към сорс кода на ритъм играта?
Да. Добавете аудиото, по една карта за всяка трудност и запис в public/manifest.json, валидирайте картите, изиграйте ги и после компилирайте отново. Редактор на карти не е включен.
Нужен ли ми е Node.js, за да използвам Riffvolt?
Не, за да хоствате доставената папка на играта. Node.js 24 LTS се препоръчва само за повторна компилация след промени в TypeScript или добавяне на песни.
Работи ли със сензорни екрани и геймпади?
Да. Играчите могат да докосват лентите или да ползват геймпад, а управлението се настройва в Settings. Производителността зависи от устройството, затова тествайте устройствата, за които се прицелвате.
А Bluetooth слушалките и закъснението?
В Settings има калибриране на аудиото, което настройва отместването на звука и помага при Bluetooth слушалки.
Има ли онлайн класация?
Не. Личните рекорди се записват по песен и трудност в браузъра на играча. Няма отдалечени съперници или общи класации.
Кой трябва да я купи
Riffvolt подхожда на портал или сайт, който иска музикална игра в каталога си, на студио, което доставя брандирана ритъм игра на един клиент, и на разработчик, който иска да прочете как игра върху Canvas 2D и Web Audio оценява тайминга в TypeScript. По-слабо подхожда, ако ви трябва визуален редактор на карти за не-разработчици или онлайн състезание; и двете са работа по поръчка.