Исходный код ритм-игры: ноты, тайминг и добавление своих песен
Как Riffvolt хранит 12 треков и 48 чартов, где решаются тайминг и подсчёт очков и что нужно, чтобы добавить свою песню.
Исходный код ритм-игры — это, по сути, две вещи: код, который судит тайминг, и данные, которые говорят, когда приходит каждая нота. Покупатели почти всегда хотят менять вторую, потому что новые песни делают ритм-игру их собственной. Riffvolt, наш рок-ритм на четыре дорожки, хранит список песен в одном манифесте, а каждый чарт нот — в отдельном файле, поэтому добавление песни — работа с данными и понятным чек-листом.
Это руководство проходит по пакету: во что играют, где живут тайминг и подсчёт очков, как добавить песню, как пересобрать и разместить игру, что разрешает лицензия и чего нет в издании. Имена файлов взяты из руководства покупателя, которое идёт с игрой.
Один факт стоит держать в голове с самого начала: в отличие от некоторых наших шаблонов, Riffvolt нужно пересобирать после изменения исходников или добавления песен. Размещение готовой папки игры требует только статического веб-хостинга.
Во что играет этот исходный код ритм-игры
Riffvolt — готовая рок-ритм-игра на четыре дорожки для браузера. Игроки попадают по нотам в такт, удерживают длинные ноты до конца, изгибают их вамми-баром (whammy) и заполняют шкалу ROCK, которая запускает овердрайв — световое шоу без очков, заканчивающееся при любом промахе. Точность тайминга набирает очки и комбо.
- 12 полных треков; у каждого есть чарты Easy, Normal и Hard, плюс Rock God, который открывается после тура: всего 48 чартов нот.
- Тур по четырём площадкам (Гараж, Дорога, Фестиваль и Арена), по три песни на каждой. Звёзды с первых двух открывают бис, а его прохождение открывает следующую площадку, с сюжетными сценами и косметическими наградами, например следами и рамками.
- Свободная игра: любая песня на любой сложности, с личными рекордами по каждой песне в браузере.
- Управление: клавиши D, F, J и K по умолчанию, касание дорожек на сенсорном экране или геймпад. Назначение клавиш — в настройках.
- Комфорт: калибровка аудио для задержки, что помогает с Bluetooth-наушниками, режим уменьшенного движения и режим для фоточувствительных игроков, который смягчает вспышки и молнии.
- 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: интерфейс и адаптивная раскладка.
Поскольку судья и подсчёт очков — разные файлы, можно сделать окна тайминга строже или мягче, не трогая начисление очков, и наоборот. Такое разделение стоит искать в любом коде ритм-игры.
Добавление своей песни пошагово
Это первое, о чём спрашивают покупатели ритм-игр. Редактора чартов в пакете нет, поэтому чарты записываются как данные, а руководство перечисляет, что нужно каждому файлу.
- Положите запись в public/audio/. Используйте только аудио, на которое у вас есть права для вашего конечного продукта.
- Создайте один чарт на каждую поддерживаемую сложность в public/charts/. Каждому чарту нужны совпадающие songId, difficulty, audioVersion, offset и ноты по порядку.
- Добавьте песню в public/manifest.json с уникальным id, длительностью, BPM, темой, audioVersion и путями к чартам.
- Проверьте каждый чарт валидатором в chartValidate.ts.
- Пройдите весь трек на каждой сложности, чтобы убедиться в синхронизации. Валидатор проверяет структуру и правила тайминга, а не то, ощущается ли нота правильно.
- Пересоберите и загрузите новую сборку.
Если нужен целый новый саундтрек, а не одна песня, планируйте работу по чартам: 12 песен на четыре сложности — это 48 чартов, и каждый заслуживает полного прохождения перед релизом.
Пересборка и что ещё менять
Рекомендуется Node.js 24 LTS. Внутри source/ выполните npm ci, затем npm run typecheck и npm run build, и публикуйте только содержимое dist/. Команда npm run preview запускает локальную сборку для проверки. Не загружайте node_modules/. Vite использует относительный базовый путь, поэтому сборка работает в подпапке. Поставляемая среда выполнения отформатирована для чтения; руководство просит при пересборке оставить 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://; для локальной проверки запустите python -m http.server 8765 внутри game/.
- Браузеру нужны JavaScript, ES-модули, Canvas 2D и Web Audio.
- Браузеры включают звук только после первого касания или клика, поэтому тихий первый экран — норма.
- В iframe разрешите полноэкранный режим и автовоспроизведение.
- Отдавайте .js с JavaScript-MIME-типом, а не как text/plain.
- Все файлы среды выполнения, шрифты и библиотеки находятся внутри сборки. Обязательного CDN нет, но это не приложение для офлайн-установки.
Сохранения привязаны к источнику браузера, поэтому перенос игры на другой домен начнёт игру у игроков с нуля. Это издание использует собственные ключи сохранения, отдельные от наших портальных изданий. Проекты нативных приложений не входят; выпуск в магазине — отдельная работа.
Чего не включает это издание
Riffvolt — локальное браузерное издание. В нём нет онлайн-комнат и мультиплеера, онлайн-рейтинга или общей таблицы лидеров, рекламного SDK или аккаунтов, редактора чартов, нативных приложений и хостинга. Личные рекорды и прогресс тура остаются в браузере игрока.
Если музыкальная игра вписывается в ваш каталог, рядом могут подойти ещё два наших шаблона с таймингом.
Pinloop: аркада на одну кнопку с 30 мишенями
Ricopop: аркада с рикошетами и 50 уровнями
Лицензия и цена
Riffvolt стоит $49. До 30 ноября 2026 года акция «Чёрная пятница» даёт скидку 15%, поэтому он стоит $41,65, а покупка двух и более шаблонов в одном заказе добавляет скидку за комплект от 5% до 20%. Лицензия бессрочная и неэксклюзивная, на один конечный продукт — ваш или клиента. Можно менять код, графику и аудио, заменить наш бренд своим и предлагать игру бесплатно или с рекламой. Включённые треки можно использовать как часть этого конечного продукта; перепродавать шаблон, его код или ассеты отдельно нельзя. Шесть месяцев поддержки входят, или двенадцать при продлении; новые песни, интеграции и хостинг оцениваются отдельно.
Прочитать полные условия лицензии
Часто задаваемые вопросы
Можно ли добавить свои песни в исходный код ритм-игры?
Да. Добавьте аудио, по одному чарту на сложность и запись в public/manifest.json, проверьте чарты, пройдите их и пересоберите игру. Редактор чартов не входит.
Нужен ли Node.js, чтобы использовать Riffvolt?
Для размещения готовой папки игры — нет. Node.js 24 LTS рекомендуется только для пересборки после изменения TypeScript или добавления песен.
Работает ли игра с сенсорными экранами и геймпадами?
Да. Игроки могут касаться дорожек или использовать геймпад, управление настраивается в настройках. Производительность зависит от устройства, поэтому проверьте те, на которые ориентируетесь.
Как быть с Bluetooth-наушниками и задержкой?
В настройках есть калибровка аудио, которая задаёт смещение звука и помогает с Bluetooth-наушниками.
Есть ли онлайн-таблица лидеров?
Нет. Личные рекорды сохраняются по каждой песне и сложности в браузере игрока. Удалённых соперников и общих рейтингов нет.
Кому её покупать
Riffvolt подходит порталу или сайту, которые хотят музыкальную игру в каталоге; студии, которая делает брендированную ритм-игру для одного клиента; и разработчику, который хочет прочитать, как игра на Canvas 2D и Web Audio судит тайминг на TypeScript. Слабее подойдёт, если нужен визуальный редактор чартов для тех, кто не программирует, или онлайн-соревнования; и то и другое — индивидуальная работа.