Codice sorgente di un gioco di biliardo: un pacchetto HTML5 8-ball
Fisica, regole, CPU e salvataggi in file separati: cosa contiene il sorgente di Velvet Pool e cosa cambia per primo chi lo compra.
Il codice sorgente di un gioco di biliardo vale l'acquisto quando tre cose stanno in file separati e leggibili: la fisica delle bilie, le regole dell'8-ball e l'avversario controllato dal computer. Se sono intrecciate, ogni modifica al colore del panno o alla difficoltà della CPU diventa una sessione di debug. Velvet Pool, il nostro template di 8-ball, le tiene separate, e questa guida ne percorre il pacchetto file per file.
Vediamo come è organizzato il codice, cosa cambia di solito per primo chi lo compra, come ospitarlo o trasformarlo in app, cosa consente la licenza e cosa resta fuori dall'edizione. Ogni nome di file qui sotto viene dalla guida per l'acquirente inclusa nel gioco.
In breve: Velvet Pool è JavaScript puro su WebGL2, senza librerie 3D e senza fase di build. Modifichi un file, lo copi nella cartella del gioco e ricarichi la pagina.
Cosa contiene questo codice sorgente di biliardo
Velvet Pool è un gioco di 8-ball finito, non un motore né uno starter kit. Il download ha quattro cartelle: game/ è la build pronta da caricare, source/ è lo stesso gioco in edizione per sviluppatori con README, package.json e test, documentation/ contiene la guida illustrata in inglese e portoghese, e THIRD-PARTY-LICENSES/ conserva i testi delle licenze dei font.
Il gioco si gioca a 8-ball con falli, bilia in mano e piene o spezzate. Ci sono tre livelli di CPU (Easy, Medium e Hard), un tavolo di allenamento libero con annulla, posizionamento delle bilie e nuovo triangolo, e partite a due giocatori sullo stesso dispositivo. I giocatori danno effetto alto, basso o laterale alla bilia bianca, e gli obiettivi locali sbloccano cinque colori di panno e cinque stili di stecca. L'interfaccia è disponibile in 14 lingue.
- Stack: JavaScript vanilla, moduli ES e WebGL2. Nessun Three.js o altra libreria di codice.
- Codice: JavaScript semplice e formattato in source/src e game/src. Niente è minificato o impacchettato.
- Test: opzionali, con Node.js 20 o superiore. Verificano fisica, regole dell'8-ball, partite contro la CPU e chiavi di traduzione.
- Versione al momento della stesura: 1.1.0, aggiornata il 22 ottobre 2026.
Vedi la scheda di Velvet Pool, la demo e il manuale
Come sono organizzati i file
game/ e source/ hanno la stessa struttura, quindi un percorso in una cartella indica lo stesso file nell'altra. Per un gioco di biliardo la divisione che conta di più è tra src/core/ (simulazione e regole) e src/game/ (tutto ciò che il giocatore tocca).
- src/core/physics.js: simulazione delle bilie, effetti e risposta delle sponde.
- src/core/rules.js: regole dell'8-ball e decisioni sui falli.
- src/core/ai.js: come la CPU sceglie il suo colpo.
- src/game/controls.js: input di mira, forza ed effetto.
- src/game/progress.js: obiettivi, panni, stecche e punteggio delle partite.
- src/game/i18n.js: i testi in 14 lingue, elencate in LANGS.
- src/game/localRecords.js: lo storico locale dei punteggi.
- src/game/audio.js: riproduzione di effetti e musica.
- css/style.css e css/fonts.css: tema, layout responsive e dichiarazioni dei font.
- assets/: grafica, audio e font, con i file del logo in assets/logo/.
Dato che fisica, regole e CPU sono moduli separati, puoi rendere la CPU più indulgente senza toccare il movimento delle bilie, o cambiare una regola sui falli senza ritarare le sponde. Questa separazione è la prima cosa da cercare in qualsiasi codice di biliardo che compri.
Cosa cambia per primo chi lo compra
La maggior parte dei progetti segue lo stesso ordine. Si parte da ciò che i giocatori vedono, poi da ciò che sentono, e le regole si lasciano per ultime, perché sono il punto in cui è più facile introdurre un bug.
- Branding: sostituisci i file del logo in assets/logo/ e adegua le dimensioni corrispondenti nel CSS. Il white label è consentito, quindi il tuo nome o quello del tuo cliente può prendere il posto del nostro.
- Aspetto del tavolo: colori e font stanno in css/style.css. Le definizioni di panni e stecche stanno in progress.js. Mantieni stabili i loro ID, altrimenti i giocatori perdono gli oggetti estetici già sbloccati.
- Testi e lingue: ogni stringa è in i18n.js. Modifica le frasi che ti servono; l'elenco delle lingue è in LANGS.
- Difficoltà della CPU: la scelta del colpo è in ai.js. Regola un livello alla volta e gioca un'intera partita contro di esso.
- Fisica: attrito, effetti e risposta delle sponde sono in physics.js. Qui piccole modifiche hanno grandi effetti, quindi esegui i test dopo ciascuna.
- Regole: le varianti della casa vanno in rules.js. Prova falli e bilia in mano a mano oltre che con la suite di test.
Il flusso è lo stesso per tutte: modifica il file in source/, copialo allo stesso percorso in game/, servi la cartella via HTTP e ricarica. La guida per l'acquirente suggerisce di cambiare una funzione alla volta e di provare menu, una partita, la pausa, la schermata del risultato e una ricarica dopo ogni modifica.
Ospitarlo, incorporarlo o trasformarlo in app
L'hosting è la parte più semplice. Carica tutto il contenuto di game/ in una cartella come public_html/velvet-pool/, mantieni le sottocartelle e apri l'indirizzo. Lato server non servono npm, terminale, PHP, database né account. Basta un piano che serva file statici in HTTPS.
- Non aprire index.html con un doppio clic: i browser bloccano i moduli del gioco su file://. Per un test locale, esegui python -m http.server 8765 dentro game/.
- Se lo schermo resta vuoto, controlla che WebGL2 sia attivo e che i nomi dei file mantengano maiuscole e minuscole.
- Se il browser rifiuta un modulo, il server sta inviando i .js con il tipo MIME sbagliato.
- Dentro un iframe su un portale, consenti fullscreen e autoplay.
Tutto ciò che serve al gioco durante l'esecuzione sta dentro game/, quindi nulla viene caricato da una CDN o da un altro sito. Un nuovo caricamento della pagina passa comunque dal tuo hosting, quindi non è un'app offline installabile. Funziona però sui touch screen: i giocatori mirano sul tavolo e trascinano il controllo della forza.
I progetti di app native non fanno parte del pacchetto. Se vuoi il gioco su Google Play o sull'App Store, un wrapper come Capacitor, che i suoi autori descrivono come un runtime nativo multipiattaforma per creare app mobili con codice web, è una strada comune. Costruire e mantenere il progetto per lo store spetta a te, oppure è un servizio che preventiviamo a parte.
Cosa resta fuori dall'edizione
Velvet Pool è l'edizione locale per browser. Non ha multiplayer online né stanze private, nessuna classifica online, nessun account cloud e nessun SDK pubblicitario. Due persone possono giocare sullo stesso dispositivo, e i punteggi personali delle partite idonee contro la CPU vengono salvati nel browser. Allenamento e partite sullo stesso dispositivo non salvano punteggi.
Il gioco online richiede un server tuo e sviluppo dedicato. È un progetto vero, quindi mettilo a budget fin dall'inizio invece di aspettarti che il template ci arrivi da solo. Se il tuo catalogo ha bisogno di altri giochi sportivi, questi due sono venduti anch'essi come edizioni per browser pronte da ospitare.
Puttide: minigolf 3D con 30 buche, anch'esso in JavaScript puro
Golazo: calcio da tavolo con 50 nazionali
Licenza e prezzo in un paragrafo
Velvet Pool ha un prezzo di listino di 39 US$. Fino al 30 novembre 2026 una promozione Black Friday toglie il 15% a ogni template, quindi costa 33,15 US$, e gli ordini di due o più template hanno un ulteriore sconto dal 5% al 20%. Ogni acquisto è una licenza perpetua e non esclusiva per un prodotto finale, tuo o di un cliente. Puoi modificare codice, grafica e audio in quel prodotto e applicarci il tuo marchio. I giocatori possono accedervi gratis o tramite pubblicità. Non puoi rivendere il template o il suo codice da soli. Sono inclusi sei mesi di supporto, o 12 con l'estensione al checkout; lavori su misura, hosting e integrazione di SDK o portali si preventivano a parte.
Leggi i termini completi di licenza e supporto
Domande frequenti
Il codice sorgente del gioco di biliardo è leggibile o minificato?
Leggibile. Il JavaScript in source/src e game/src è semplice e formattato, senza file minificati o impacchettati.
Mi servono Node.js o una fase di build?
No. Modifichi i file in source/ e li copi in game/. Node.js 20 o superiore serve solo se vuoi eseguire i test opzionali.
Posso rendere la CPU più facile o più difficile?
Sì. La scelta del colpo della CPU sta in src/core/ai.js, separata dalla fisica, quindi puoi regolarla senza cambiare il movimento delle bilie.
Funziona sui telefoni?
Sì. Il tocco è supportato e i controlli si adattano allo schermo. Serve WebGL2 e le prestazioni dipendono dal dispositivo, quindi prova sui telefoni che usano i tuoi giocatori.
I giocatori mantengono i progressi se sposto il gioco su un nuovo dominio?
No. I salvataggi appartengono all'origine del browser, quindi cambiando dominio i giocatori ripartono da zero. Scegli l'indirizzo definitivo prima del lancio.
Posso aggiungere il multiplayer online?
Non con questa sola edizione. Servono un server tuo e sviluppo dedicato. Possiamo preventivarlo come lavoro su misura.
Per chi è adatto questo codice di biliardo
È adatto a un portale o a un sito che vuole un gioco di 8-ball nel proprio catalogo, a un'agenzia che consegna un biliardo brandizzato a un cliente e a uno sviluppatore che vuole leggere come si scrivono fisica e regole del biliardo senza una libreria 3D di mezzo. È meno adatto se il tuo piano dipende da partite online o da una classifica condivisa.
Prima di comprare, gioca la demo su un telefono e su un portatile e apri la mappa dei file del manuale. Se la divisione tra fisica, regole e CPU corrisponde al tuo modo di lavorare, il resto sono pochi pomeriggi di modifiche.