Codice sorgente di un gioco ritmico: chart, timing e nuovi brani

Il codice sorgente di un gioco ritmico è in realtà fatto di due cose: il codice che giudica il timing e i dati che dicono quando arriva ogni nota. Gli acquirenti vogliono quasi sempre cambiare la seconda, perché sono i brani nuovi a rendere un gioco ritmico davvero loro. Riffvolt, il nostro template di rhythm game rock a quattro corsie, tiene l'elenco dei brani in un unico file manifest e ogni chart di note in un file proprio, così aggiungere un brano è un lavoro sui dati con una checklist chiara.

Questa guida percorre il pacchetto: cosa offre il gioco, dove stanno timing e punteggio, come aggiungere un brano, come fare il rebuild e pubblicarlo, cosa permette la licenza e cosa lascia fuori questa edizione. I nomi dei file vengono dalla guida per l'acquirente inclusa nel gioco.

Un fatto da tenere a mente fin dall'inizio: a differenza di alcuni nostri template, Riffvolt richiede un rebuild dopo aver modificato il sorgente o aggiunto brani. Per pubblicare la cartella del gioco fornita basta un normale hosting statico.

Cosa offre questo codice sorgente di gioco ritmico

Riffvolt è un gioco ritmico rock a quattro corsie, completo, per il browser. I giocatori colpiscono le note a tempo, tengono le note lunghe fino alla fine, le piegano con la leva whammy e riempiono un indicatore ROCK che avvia l'overdrive, uno spettacolo di luci che non aggiunge punti e finisce al primo errore. La precisione del timing costruisce punteggio e combo.

• 12 brani completi, ognuno con chart Easy, Normal e Hard, più Rock God, che si apre dopo il tour: 48 chart di note in totale.
• Un tour in quattro locali (Garage, The road, Festival e Arena), tre brani ciascuno. Le stelle dei primi due aprono il bis, e completare il bis apre il locale successivo, con scene di storia e ricompense estetiche come scie e cornici.
• Gioco libero: qualsiasi brano a qualsiasi difficoltà, con record personali salvati brano per brano nel browser.
• Comandi: D, F, J e K di default, tocco sulle corsie su touch screen, oppure gamepad. L'assegnazione dei tasti è nelle Impostazioni.
• Comfort: calibrazione audio per l'offset, utile con le cuffie Bluetooth, movimento ridotto e una modalità fotosensibile che attenua lampi e fulmini.
• 14 lingue dell'interfaccia.

Vedi la scheda di Riffvolt, la demo e i manuali

Come sono organizzati i file

Il download contiene game/ (i file da pubblicare), source/ (il progetto TypeScript), documentation/ (manuali illustrati in inglese e portoghese) e licenses/ (note di terze parti). Dentro source/, la separazione tra dati dei brani e logica di gioco è netta.

• public/manifest.json: il catalogo dei brani, con durata, versione audio e percorsi dei chart di ciascuno.
• public/charts/: i 48 chart di note.
• public/audio/: le registrazioni dei brani.
• src/core/chartValidate.ts: schema dei chart e validazione del timing.
• src/core/judge.ts: i giudizi sul timing.
• src/core/scoring.ts: regole di punteggio e combo.
• src/game/campaign.ts: la progressione del tour.
• src/game/session.ts: il ciclo di vita di un brano e il calcolo del risultato.
• src/i18n/locales.ts: i 14 dizionari dell'interfaccia.
• src/net/localRecords.js: i record personali locali.
• src/ui/style.css: interfaccia e layout responsive.

Dato che giudizio e punteggio stanno in file separati, puoi rendere le finestre di timing più severe o più tolleranti senza toccare il modo in cui si sommano i punti, e viceversa. È la separazione da cercare in qualsiasi codice di rhythm game.

Aggiungere un tuo brano, passo dopo passo

È la prima cosa che chiede chi acquista un rhythm game. Nel pacchetto non c'è un editor di chart, quindi i chart si scrivono come dati, e il manuale elenca esattamente cosa serve in ogni file.

1. Metti la registrazione in public/audio/. Usa solo audio di cui hai i diritti per il tuo prodotto finale.
2. Crea un chart per ogni difficoltà supportata in public/charts/. Ogni chart richiede songId, difficulty, audioVersion e offset corrispondenti e le note in ordine.
3. Aggiungi il brano a public/manifest.json con id univoco, durata, BPM, tema, audioVersion e percorsi dei chart.
4. Controlla ogni chart con il validatore in chartValidate.ts.
5. Suona l'intero brano a ogni difficoltà per confermare la sincronizzazione. Il validatore controlla struttura e regole di timing, non se una nota suona giusta.
6. Fai il rebuild, poi carica la nuova build.

Se vuoi una colonna sonora del tutto nuova invece di un brano in più, pianifica il lavoro per chart: 12 brani a quattro difficoltà fanno 48 chart, e ognuno merita una partita completa prima del rilascio.

Il rebuild e le altre modifiche

È consigliato Node.js 24 LTS. Dentro source/ esegui npm ci, poi npm run typecheck e npm run build, e pubblica solo il contenuto di dist/. npm run preview serve la build locale per controllarla. Non caricare node_modules/. Vite usa una base relativa, quindi la build funziona in una sottocartella. Il runtime consegnato è formattato per essere letto; il manuale chiede di mantenere minify:false e cssMinify:false quando rifai la build, così anche chi viene dopo può leggerlo.

1. Marchio: colori e layout in src/ui/style.css, più il tuo logo. Il white label è consentito, quindi il tuo marchio può sostituire il nostro.
2. Testi: src/i18n/locales.ts, per le lingue che pubblichi.
3. Tour: l'ordine dei locali e cosa sblocca cosa, in campaign.ts.
4. Difficoltà: finestre di timing in judge.ts, poi regole di punteggio e combo in scoring.ts.
5. Brani: per ultimi, perché ogni nuovo chart richiede una partita completa.

Fai un backup prima di modificare, cambia una funzione alla volta e dopo ogni modifica prova il menu, un brano, la pausa, la schermata dei risultati e un ricaricamento. Mantieni stabili gli id degli oggetti e le chiavi di salvataggio, così i giocatori esistenti conservano i loro record.

Pubblicarlo o incorporarlo in un portale

Carica il contenuto di game/ in una cartella del tuo host HTTP(S), mantieni i percorsi relativi e apri l'indirizzo. Non servono PHP, database né account. Non aprire index.html via file://; per un test locale, esegui python -m http.server 8765 dentro game/.

• Requisiti del browser: JavaScript, moduli ES, Canvas 2D e Web Audio.
• I browser sbloccano l'audio solo dopo il primo tocco o clic, quindi una prima schermata muta è normale.
• In un iframe, consenti fullscreen e autoplay.
• Servi i .js con un tipo MIME JavaScript, mai come text/plain.
• Tutti gli asset, i font e le librerie di runtime sono dentro la build. Nessuna CDN obbligatoria, ma non è un'app installabile offline.

I salvataggi appartengono all'origine del browser, quindi spostando il gioco su un altro dominio i giocatori ripartono da zero. Questa edizione usa chiavi di salvataggio proprie, separate da quelle delle edizioni del nostro portale. I progetti di app native non sono inclusi; una pubblicazione negli store è un lavoro a parte.

Cosa non include l'edizione

Riffvolt è l'edizione locale per browser. Non ha stanze online né multigiocatore, né ranking online o classifica condivisa, né SDK o account pubblicitari, né editor di chart, né app native, né hosting. Record personali e progressi del tour restano nel browser del giocatore.

Se un gioco musicale ha senso nel tuo catalogo, altri due nostri template basati sul tempismo possono stargli accanto.

Pinloop: un arcade di tempismo a un pulsante con 30 bersagli

Ricopop: un arcade a rimbalzi con 50 livelli

Licenza e prezzo

Riffvolt costa $49 a listino. Fino al 30 novembre 2026 la promozione Black Friday toglie il 15%, quindi costa $41.65, e acquistando due o più template nello stesso ordine si aggiunge uno sconto pacchetto dal 5% al 20%. La licenza è perpetua e non esclusiva, per un solo prodotto finale, tuo o di un cliente. Puoi modificare codice, grafica e audio, sostituire il nostro marchio con il tuo e offrire il gioco gratis o con pubblicità. Usa i brani inclusi come parte di quel prodotto finale; non puoi rivendere il template, il suo codice o i suoi asset da soli. Sono inclusi sei mesi di supporto, o dodici con l'estensione; nuovi brani, integrazioni e hosting si quotano a parte.

Leggi i termini completi della licenza

Domande frequenti

Posso aggiungere brani miei al codice sorgente del gioco ritmico?

Sì. Aggiungi l'audio, un chart per difficoltà e una voce in public/manifest.json, valida i chart, suonali fino in fondo e poi fai il rebuild. Un editor di chart non è incluso.

Mi serve Node.js per usare Riffvolt?

Non per pubblicare la cartella del gioco fornita. Node.js 24 LTS è consigliato solo per il rebuild dopo aver modificato il TypeScript o aggiunto brani.

Funziona con touch screen e gamepad?

Sì. I giocatori possono toccare le corsie o usare un gamepad, e i comandi si impostano nelle Impostazioni. Le prestazioni dipendono dal dispositivo, quindi prova quelli a cui ti rivolgi.

E le cuffie Bluetooth e la latenza?

Le Impostazioni includono una calibrazione audio che regola l'offset e aiuta con le cuffie Bluetooth.

C'è una classifica online?

No. I record personali si salvano per brano e difficoltà nel browser del giocatore. Non ci sono avversari remoti né classifiche condivise.

A chi conviene

Riffvolt è adatto a un portale o sito che vuole un gioco musicale nel catalogo, a uno studio che consegna un rhythm game brandizzato a un cliente e a uno sviluppatore che vuole vedere come un gioco in Canvas 2D e Web Audio giudica il timing in TypeScript. È meno adatto se ti serve un editor visuale di chart per chi non sviluppa o una competizione online: entrambi sono lavoro su misura.

Prova la demo di Riffvolt e acquista la licenza

Nuovi brani o una versione brandizzata? Chiedi un preventivo