Kod źródłowy gry rytmicznej: nuty, czas i dodawanie utworów
Jak Riffvolt przechowuje 12 utworów i 48 zapisów nut, gdzie decyduje się o czasie i punktacji oraz co trzeba, by dodać własną piosenkę.
Kod źródłowy gry rytmicznej to w gruncie rzeczy dwie rzeczy: kod, który ocenia czas, i dane, które mówią, kiedy nadchodzi każda nuta. Kupujący niemal zawsze chcą zmienić to drugie, bo nowe utwory sprawiają, że gra rytmiczna staje się ich. Riffvolt, nasz czteropasmowy szablon rockowej gry rytmicznej, trzyma listę utworów w jednym manifeście, a każdy zapis nut w osobnym pliku, więc dodanie utworu to praca na danych z jasną listą kontrolną.
Ten przewodnik przechodzi przez pakiet: co gra odtwarza, gdzie żyje czas i punktacja, jak dodać utwór, jak przebudować i hostować grę, co pozwala licencja i czego edycja nie zawiera. Nazwy plików pochodzą z przewodnika dla kupującego, który dołączony jest do gry.
Jedna rzecz do zapamiętania od początku: w przeciwieństwie do niektórych naszych szablonów Riffvolt wymaga przebudowy po zmianie źródeł lub dodaniu utworów. Hostowanie dostarczonego folderu gry wymaga tylko statycznego hosta.
Co odtwarza kod źródłowy gry rytmicznej
Riffvolt to gotowa czteropasmowa rockowa gra rytmiczna do przeglądarki. Gracze trafiają nuty w czasie, przytrzymują długie nuty do końca, wyginają je dźwignią whammy i zapełniają miernik ROCK (ROCK gauge), który uruchamia overdrive. To pokaz świateł, który nie daje punktów i kończy się przy każdym pudle. Precyzja czasu buduje wynik i combo.
- 12 pełnych utworów, każdy z poziomami Easy (łatwy), Normal (normalny) i Hard (trudny), plus Rock God (bóg rocka), który otwiera się po trasie: w sumie 48 zapisów nut.
- Trasa przez cztery miejsca koncertowe: Garage (garaż), The road (droga), Festival (festiwal) i Arena (arena), po trzy utwory w każdym. Gwiazdki z dwóch pierwszych otwierają bis, a jego ukończenie otwiera kolejne miejsce, ze scenami fabularnymi i kosmetycznymi nagrodami, takimi jak smugi i ramki.
- Wolna gra: dowolny utwór na dowolnym poziomie, z osobistymi rekordami zapisywanymi w przeglądarce dla każdego utworu.
- Sterowanie: domyślnie D, F, J i K, dotknięcie pasm na ekranie dotykowym albo pad. Przypisania klawiszy są w Ustawieniach.
- Komfort: kalibracja audio dla przesunięcia (offset), która pomaga przy słuchawkach Bluetooth, ograniczony ruch i tryb dla osób wrażliwych na światło, który przytłumia błyski i pioruny.
- 14 języków interfejsu.
Zobacz stronę Riffvolt, demo i podręczniki
Jak zorganizowane są pliki
Pobranie zawiera game/ (pliki do wgrania), source/ (projekt TypeScript), documentation/ (ilustrowane podręczniki po angielsku i portugalsku) oraz licenses/ (informacje o komponentach zewnętrznych). W source/ podział między danymi utworów a logiką gry jest czysty.
- public/manifest.json: katalog utworów z czasem trwania, wersją audio i ścieżkami do zapisów.
- public/charts/: 48 zapisów nut.
- public/audio/: nagrania utworów.
- src/core/chartValidate.ts: schemat zapisu i walidacja czasu.
- src/core/judge.ts: oceny czasu.
- src/core/scoring.ts: zasady punktów i combo.
- src/game/campaign.ts: postęp przez trasę.
- src/game/session.ts: cykl życia utworu i obliczanie wyniku.
- src/i18n/locales.ts: 14 słowników interfejsu.
- src/net/localRecords.js: lokalne osobiste rekordy.
- src/ui/style.css: interfejs i układ dla różnych ekranów.
Ponieważ sędzia i punktacja są w osobnych plikach, możesz uczynić okna czasowe surowszymi albo łagodniejszymi bez ruszania sposobu, w jaki liczą się punkty, i odwrotnie. To podział, którego warto szukać w każdym kodzie rytmicznym.
Dodawanie własnego utworu krok po kroku
To zmiana, o którą kupujący gier rytmicznych pytają najpierw. W pakiecie nie ma edytora zapisów, więc nuty pisze się jako dane, a podręcznik wymienia dokładnie, czego potrzebuje każdy plik.
- Umieść nagranie w public/audio/. Używaj tylko audio, do którego masz prawa w swoim produkcie końcowym.
- Utwórz jeden zapis na każdy obsługiwany poziom w public/charts/. Każdy zapis potrzebuje pasującego songId, difficulty, audioVersion, offset i nut w kolejności.
- Dodaj utwór do public/manifest.json z unikalnym id, czasem trwania, BPM, motywem, audioVersion i ścieżkami do zapisów.
- Sprawdź każdy zapis walidatorem w chartValidate.ts.
- Zagraj cały utwór na każdym poziomie, by potwierdzić synchronizację. Walidator sprawdza strukturę i zasady czasu, a nie to, czy nuta dobrze się czuje.
- Przebuduj i wgraj nowy build.
Jeśli chcesz całą nową ścieżkę dźwiękową, a nie jeden dodatkowy utwór, planuj pracę na zapisy: 12 utworów na czterech poziomach to 48 zapisów i każdy zasługuje na pełne przejście przed wydaniem.
Przebudowa i to, co jeszcze zmienić
Zalecany jest Node.js 24 LTS. W source/ uruchom npm ci, potem npm run typecheck i npm run build, a na hosting wgraj tylko zawartość dist/. npm run preview serwuje lokalny build do sprawdzenia. Nie wgrywaj node_modules/. Vite używa względnej ścieżki bazowej, więc build działa w podfolderze. Dostarczony kod uruchomieniowy jest sformatowany, żeby dało się go czytać; podręcznik prosi, by przy przebudowie zostawić minify:false i cssMinify:false, aby następna osoba mogła go nadal czytać.
- Marka: kolory i układ w src/ui/style.css oraz Twoje logo. White label jest dozwolona, więc Twoja marka może zastąpić naszą.
- Teksty: src/i18n/locales.ts, dla języków, które wysyłasz.
- Trasa: kolejność miejsc i to, co otwiera kolejne etapy, w campaign.ts.
- Poziom trudności: okna czasowe w judge.ts, potem zasady punktów i combo w scoring.ts.
- Utwory: na końcu, bo każdy nowy zapis wymaga pełnego przejścia.
Przed edycją zrób kopię zapasową, zmieniaj jedną funkcję naraz i po każdej zmianie sprawdź menu, utwór, pauzę, ekran wyniku i przeładowanie. Zachowuj stałe identyfikatory elementów i klucze zapisu, by obecni gracze zachowali swoje rekordy.
Hosting albo osadzenie w portalu
Wgraj zawartość game/ do folderu na swoim hostingu HTTP(S), zachowaj względne ścieżki i otwórz adres. Nie potrzeba PHP, bazy danych ani konta. Nie otwieraj index.html przez file://; do lokalnego testu uruchom python -m http.server 8765 wewnątrz game/.
- Przeglądarka potrzebuje: JavaScript, modułów ES, Canvas 2D i Web Audio.
- Przeglądarki odblokowują dźwięk dopiero po pierwszym dotknięciu lub kliknięciu, więc cichy pierwszy ekran jest normalny.
- W iframe zezwól na pełny ekran i autoodtwarzanie.
- Serwuj pliki .js z typem MIME JavaScript, nigdy jako text/plain.
- Wszystkie zasoby uruchomieniowe, czcionki i biblioteki są w buildzie. Nie ma obowiązkowego CDN, ale to nie jest aplikacja instalowalna działająca offline.
Zapisy są przypisane do adresu strony w przeglądarce, więc przeniesienie gry na inną domenę zaczyna graczy od nowa. Ta edycja używa własnych kluczy zapisu, oddzielnych od naszych edycji portalowych. Projekty aplikacji natywnych nie są w pakiecie; wydanie w sklepie to osobna praca.
Czego ta edycja nie obejmuje
Riffvolt to lokalna edycja przeglądarkowa. Nie ma pokojów online ani multiplayera, rankingu online ani wspólnej tabeli wyników, SDK reklam ani kont, edytora zapisów, aplikacji natywnych ani hostingu. Osobiste rekordy i postęp trasy zostają w przeglądarce gracza.
Jeśli gra muzyczna pasuje do Twojego katalogu, obok mogą pasować dwa inne nasze szablony oparte na czasie.
Pinloop: zręcznościowa gra czasowa jednym przyciskiem, 30 celów
Ricopop: zręcznościowa gra z rykoszetami, 50 poziomów
Licencja i cena
Riffvolt kosztuje w cenie katalogowej 49 USD. Do 30 listopada 2026 promocja Black Friday obniża cenę o 15%, więc kosztuje 41,65 USD, a zamówienie dwóch lub więcej szablonów dodaje zniżkę pakietową od 5% do 20%. Licencja jest wieczna i niewyłączna, na jeden produkt końcowy, Twój albo jednego klienta. Możesz zmieniać kod, grafikę i dźwięk, zastąpić naszą markę swoją i oferować grę za darmo albo z reklamami. Dołączonych utworów używaj jako części tego produktu końcowego; nie wolno odsprzedawać szablonu, jego kodu ani zasobów osobno. Wsparcie trwa sześć miesięcy, a dwanaście z rozszerzeniem; nowe utwory, integracje i hosting wyceniamy osobno.
Przeczytaj pełne warunki licencji
Najczęściej zadawane pytania
Czy mogę dodać własne utwory do kodu źródłowego gry rytmicznej?
Tak. Dodaj audio, jeden zapis na poziom i wpis w public/manifest.json, sprawdź zapisy, zagraj je w całości, a potem przebuduj. Edytor zapisów nie jest w pakiecie.
Czy potrzebuję Node.js, by używać Riffvolt?
Nie do hostowania dostarczonego folderu gry. Node.js 24 LTS jest zalecany tylko do przebudowy po zmianie TypeScript albo dodaniu utworów.
Czy działa na ekranach dotykowych i z padami?
Tak. Gracze mogą dotykać pasm albo używać pada, a sterowanie ustawia się w Ustawieniach. Wydajność zależy od urządzenia, więc przetestuj te, na które celujesz.
A słuchawki Bluetooth i opóźnienie?
Ustawienia zawierają kalibrację audio, która ustawia przesunięcie dźwięku i pomaga przy słuchawkach Bluetooth.
Czy jest internetowa tabela wyników?
Nie. Osobiste rekordy zapisują się w przeglądarce gracza dla każdego utworu i poziomu. Nie ma zdalnych przeciwników ani wspólnych rankingów.
Dla kogo to jest
Riffvolt pasuje do portalu lub strony, która chce mieć w katalogu grę muzyczną, do studia dostarczającego markową grę rytmiczną jednemu klientowi oraz do programisty, który chce przeczytać, jak gra na Canvas 2D i Web Audio ocenia czas w TypeScript. Słabiej pasuje, jeśli potrzebujesz wizualnego edytora zapisów dla osób nieprogramujących albo rywalizacji online; obie rzeczy to praca na zamówienie.