Вихідний код ритм-гри: карти нот, таймінг і додавання пісень
Як Riffvolt зберігає 12 треків і 48 карт, де вирішуються таймінг і підрахунок очок і що потрібно, щоб додати власну пісню.
Вихідний код ритм-гри — це насправді дві речі: код, що оцінює таймінг, і дані, які кажуть, коли приходить кожна нота. Покупці майже завжди хочуть змінити друге, бо саме нові пісні роблять ритм-гру їхньою. Riffvolt, наш рок-шаблон ритм-гри з чотирма смугами, тримає список пісень в одному файлі-маніфесті, а кожну карту нот — в окремому файлі, тож додавання пісні — це робота з даними з чітким чек-листом.
Цей гайд проходить пакет: що він відтворює, де живуть таймінг і підрахунок очок, як додати пісню, як перезібрати і розмістити гру, що дозволяє ліцензія і чого не містить версія. Назви файлів беруться з посібника для покупця, що йде з грою.
Одне, що варто пам'ятати з самого початку: на відміну від деяких наших шаблонів, Riffvolt потребує перезбірки після зміни вихідного коду або додавання пісень. Розмістити наданий папку гри можна на будь-якому статичному вебхостингу.
Що відтворює цей вихідний код ритм-гри
Riffvolt — це готова рок-ритм-гра з чотирма смугами для браузера. Гравці потрапляють у ноти вчасно, утримують довгі ноти до кінця, згинають їх через whammy (важіль) і заповнюють шкалу ROCK, яка запускає overdrive (перевантаження): це світлове шоу, що не додає очок і закінчується при будь-якому промаху. Точність таймінгу накопичує очки і комбо.
- 12 повних треків, кожен із рівнями Easy (легкий), Normal (звичайний) і Hard (складний), плюс Rock God, який відкривається після туру: 48 карт нот загалом.
- Тур через чотири локації, Garage (гараж), The road (дорога), Festival (фестиваль) і Arena (арена), по три пісні в кожній. Зірки з перших двох відкривають біс (encore), а проходження бісу відкриває наступну локацію, із сюжетними сценами та косметичними винагородами, як-от сліди і рамки.
- Free play (вільна гра): будь-яка пісня на будь-якій складності з особистими рекордами, що зберігаються для кожної пісні в браузері.
- Керування: D, F, J і K за замовчуванням, натискання на смуги на сенсорному екрані або геймпад. Прив'язки клавіш — у Settings (налаштуваннях).
- Комфорт: калібрування аудіо для зсуву, що допомагає з Bluetooth-навушниками, зменшений рух і режим photosensitive (для чутливих до світла), який пом'якшує спалахи і блискавки.
- 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 використовує відносну базу, тож збірка працює в підпапці. Поставлений runtime відформатований для читання; посібник просить під час перезбірки лишати 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.
- Усі ресурси середовища виконання, шрифти й бібліотеки всередині збірки. Обов'язкового CDN немає, але це не офлайн-застосунок для встановлення.
Збереження прив'язані до джерела браузера, тож перенесення гри на інший домен почне гравців з нуля. Ця версія використовує власні ключі збереження, окремі від наших версій для порталів. Проєкти нативних застосунків не входять; випуск у магазин — окрема робота.
Чого не містить ця версія
Riffvolt — локальна браузерна версія. Вона не має онлайн-кімнат чи мультиплеєра, онлайн-рейтингу чи спільної таблиці лідерів, рекламного SDK чи акаунтів, редактора карт, нативних застосунків і хостингу. Особисті рекорди та прогрес туру зберігаються в браузері гравця.
Якщо музична гра пасує до вашого каталогу, поруч із нею можуть підійти ще два наші шаблони з таймінгом.
Pinloop: аркадна гра з одним натисканням і 30 мішенями
Ricopop: аркадна гра з рикошетами і 50 рівнями
Ліцензія і ціна
Riffvolt коштує $49 за ціною зі списку. До 30 листопада 2026 року акція Black Friday дає знижку 15%, тож він коштує $41,65, а покупка двох і більше шаблонів в одному замовленні дає пакетну знижку від 5% до 20%. Ліцензія безстрокова і невиключна, на один кінцевий продукт, ваш або одного клієнта. Ви можете змінювати код, графіку й аудіо, замінити наш бренд на свій і пропонувати гру безкоштовно або з рекламою. Вбудовані треки використовуйте як частину цього кінцевого продукту; шаблон, його код або ресурси окремо перепродавати не можна. Шість місяців підтримки входять у ціну, або дванадцять з розширенням; нові пісні, інтеграції та хостинг оцінюються окремо.
Прочитайте повні умови ліцензії
Поширені запитання
Чи можна додати власні пісні до вихідного коду ритм-гри?
Так. Додайте аудіо, одну карту на кожну складність і запис у public/manifest.json, перевірте карти, пройдіть їх і перезберіть. Редактора карт немає в пакеті.
Чи потрібен Node.js, щоб користуватися Riffvolt?
Щоб розмістити наданий папку гри — ні. Node.js 24 LTS рекомендовано лише для перезбірки після зміни TypeScript або додавання пісень.
Чи працює з сенсорними екранами і геймпадами?
Так. Гравці можуть натискати на смуги або використовувати геймпад, а керування налаштовується в Settings. Продуктивність залежить від пристрою, тож перевірте ті, на які орієнтуєтеся.
Як щодо Bluetooth-навушників і затримки?
У налаштуваннях є калібрування аудіо, яке задає зсув звуку і допомагає з Bluetooth-навушниками.
Чи є онлайн-таблиця лідерів?
Ні. Особисті рекорди зберігаються для кожної пісні та складності в браузері гравця. Віддалених суперників і спільних рейтингів немає.
Кому варто купити
Riffvolt підійде порталу чи сайту, який хоче мати музичну гру в каталозі, студії, що здає брендовану ритм-гру одному клієнту, і розробнику, який хоче прочитати, як гра на Canvas 2D і Web Audio оцінює таймінг у TypeScript. Він менш підходить, якщо потрібен візуальний редактор карт для не-розробників або онлайн-змагання; і те, і інше — індивідуальна робота.