Codice sorgente di giochi HTML5: cosa c'è in un pacchetto reale
Uno sguardo dentro pacchetti reali del Polar Games Marketplace: cartelle, file, fasi di build, licenze e le domande da fare prima di pagare.
Il codice sorgente di un gioco HTML5 può significare tre cose diverse: una build pronta da caricare, i file per sviluppatori che modificate, oppure un progetto che si apre solo in un particolare editor. Un template di gioco HTML5 con codice sorgente del nostro marketplace è le prime due cose insieme, come semplici file web, e questa guida apre pacchetti reali per mostrare come appare.
Vendiamo noi questi template, quindi leggete questa guida come un giro dei nostri pacchetti, non come un'indagine neutrale sul mercato. Abbiamo esaminato diverse edizioni, soprattutto Velvet Pool, Puttide e Sunset Rally, letto i loro manuali pubblici e i termini dello store, e annotato cosa c'è nella confezione, cosa serve per eseguirlo e cosa non c'è. Ogni manuale è collegato dalla pagina del suo articolo, quindi potete verificare ogni riga prima di pagare.
Che cosa può significare «codice sorgente di un gioco HTML5»
I venditori usano l'espressione codice sorgente in modo vago. Tre domande chiariscono che cosa si vende davvero.
Una build, un sorgente per sviluppatori, o entrambi?
Una build è il gioco finito come lo carica il browser: un index.html, script, immagini e file audio. Potete ospitarla così com'è. Il sorgente per sviluppatori è la versione pensata per essere modificata, con i file divisi per funzione. Un pacchetto con la sola build si può caricare ma non si cambia comodamente. Un pacchetto con il solo sorgente può richiedere degli strumenti prima ancora di girare. Le edizioni di questa guida mettono entrambi in un unico ZIP: di solito una cartella game/ da pubblicare e una cartella source/ da modificare (in Ricopop, game/ è essa stessa il sorgente).
Leggibile o minificato?
La minificazione comprime gli script in poche righe dense con nomi brevi, il che si scarica più in fretta e si legge malissimo. L'offuscamento va oltre e rimescola i nomi di proposito. Nessuno dei due danneggia un sito attivo. Entrambi danneggiano se avete comprato il codice per modificarlo. Prima di pagare, aprite uno script della demo dal vivo negli strumenti per sviluppatori del browser e vedete se riuscireste a seguirlo.
File semplici o un progetto di editor?
Alcuni template arrivano come progetto per uno specifico editor di giochi, e si possono aprire solo in quell'editor. Altri sono semplici file web che qualsiasi editor di codice apre. Le edizioni di questa guida sono del secondo tipo: HTML, CSS, JavaScript e JSON, con TypeScript in alcune di esse.
Cosa c'è in un pacchetto Polar Games
Prendiamo Velvet Pool, la nostra edizione di biliardo 8-ball. Il suo manuale descrive quattro cartelle nello ZIP:
- game/ è l'edizione pronta da caricare e l'unica cartella che pubblicate.
- source/ è lo stesso gioco come edizione modificabile per sviluppatori, con un README, un package.json e dei test.
- documentation/ contiene la guida illustrata e le sue immagini.
- THIRD-PARTY-LICENSES/ contiene i testi di licenza dei font e un riepilogo in README.txt.
Nella vostra libreria lo stesso pacchetto è offerto come due download: il pacchetto completo (sorgente e manuale) oppure solo il gioco, pronto da ospitare.
game/ e source/ condividono la stessa struttura. Per Velvet Pool il manuale dice di modificare i file in source/ e di copiare quelli cambiati nello stesso percorso in game/. In mezzo non si compila nulla.
Dentro Velvet Pool: la mappa dei file
Una mappa dei file è il modo più economico di giudicare una base di codice prima di comprarla. Questa è quella del manuale di Velvet Pool, con percorsi relativi a source/ o game/:
- src/core/physics.js: simulazione delle palle, effetto e risposta delle sponde.
- src/core/rules.js: regole dell'8-ball e decisioni sui falli.
- src/core/ai.js: come la CPU sceglie un tiro.
- src/game/controls.js: input di mira, potenza ed effetto.
- src/game/progress.js: obiettivi, panni, stecche e punteggio delle partite.
- src/game/i18n.js: i testi in 14 lingue.
- src/game/localRecords.js: la cronologia locale dei punteggi.
- src/game/audio.js: effetti sonori e riproduzione della musica.
- css/style.css e css/fonts.css: tema, layout adattivo e dichiarazioni dei font.
- assets/: grafica, audio e font, con una sottocartella logo/.
Notate la suddivisione. Regole, fisica e CPU stanno in src/core. Input, salvataggi, testi e suono stanno in src/game. Il manuale vi chiede di cambiare una funzione alla volta, e questa struttura lo rende realistico: ritoccare una sponda e correggere una traduzione toccano file diversi.
Il manuale afferma anche che il codice in source/src e game/src è JavaScript semplice e formattato, senza file minificati o impacchettati. Velvet Pool è JavaScript puro su WebGL2 e non usa alcuna libreria di codice, nemmeno Three.js. Il changelog lo conferma: la versione 1.0.1 ha suddiviso in righe leggibili le lunghe stringhe su riga singola di audio, traduzioni e shader, senza cambiare il comportamento.
Puttide: la stessa struttura, più le librerie
Puttide, la nostra edizione di minigolf 3D, usa le stesse quattro cartelle e aggiunge una cosa: due librerie di terzi di cui il gioco ha bisogno. Three.js r186 (MIT) e Rapier 3D 0.21.0 (Apache-2.0) stanno in lib/three/ e lib/rapier/, e l'import map in index.html dice al browser dove trovarle. Le FAQ di Puttide dichiarano che nulla viene caricato da una CDN, quindi il gioco ha bisogno solo del vostro hosting. Il manuale aggiunge che i file delle librerie sono formattati in modo da poter essere letti, con il comportamento non modificato.
La sua mappa dei file, sempre relativa a source/ o game/:
- src/course/courses.js: ordine dei percorsi e requisiti di sblocco.
- src/course/holes.js: geometria, par e ostacoli del percorso Ruins. pier.js, ice.js, lava.js e sky.js contengono gli altri quattro.
- src/sim/constants.js: regolazione della fisica.
- src/game/economy.js: definizioni e prezzi di palline, scie e outfit.
- src/ui/i18n.js e altri tre file di dizionario: i testi delle lingue.
- css/style.css: colori dell'interfaccia, font e stili adattivi.
- fonts/ e music/: i font web con le loro licenze e due brani musicali.
La ricetta del manuale per una nuova buca: duplicare una definizione nel file del percorso giusto, darle un id univoco, impostare par e posizioni di partenza e di buca, aggiungerla al percorso, poi aggiungere nome e suggerimento ai dizionari delle lingue. Leggete una ricetta così prima di comprare. Se vi sembra un lavoro alla vostra portata, il pacchetto fa per voi.
Quando il sorgente richiede una fase di build
«Nessuna fase di build» vale per alcune edizioni e non per altre, quindi controllate l'edizione, non lo store. Ecco cinque delle nostre affiancate, con i prezzi di listino. Il nostro store mostra attualmente il 10% di sconto sul prezzo di listino, l'offerta studio direct in ogni pagina di articolo: Velvet Pool, per esempio, mostra $35,10 invece di $39.
- Velvet Pool, prezzo di listino $39: moduli JavaScript semplici su WebGL2. Modificate source/, copiate in game/. Node.js 20+ solo per i test facoltativi.
- Puttide, $39: moduli JavaScript semplici con Three.js e Rapier in lib/. Nessuna fase di build. Node.js è facoltativo e serve solo per gestire le versioni delle librerie.
- Ricopop, $39: HTML, CSS e moduli JavaScript semplici, e game/ è esso stesso il sorgente. Strumenti facoltativi per sviluppatori (Node.js 20+): un server locale, un controllo dei livelli e dei test.
- Pinloop, $24: TypeScript con Vite. La cartella game/ contiene JavaScript e CSS leggibili. Node.js 22.12+ e npm solo per modificare e ricompilare il sorgente.
- Sunset Rally, $39: TypeScript con Three.js r184 e Vite. La cartella game/ è già compilata e non minificata. Node.js solo se ricompilate.
Per Sunset Rally il manuale raccomanda Node.js 24 LTS. Dentro source/ eseguite npm ci, npm run typecheck e npm run build, poi pubblicate solo il contenuto di dist/. Chiede anche di mantenere disattivati minify e cssMinify quando ricompilate, perché il runtime consegnato è formattato per essere letto. Caricate il risultato, mai node_modules/.
Vedete l'edizione Sunset Rally
Ospitarlo: che cosa significa «statico» in pratica
Hosting statico significa che il vostro host serve soltanto file. I manuali di Velvet Pool e Puttide descrivono l'intera installazione in tre passaggi:
- Estraete lo ZIP.
- Caricate tutto ciò che sta dentro game/ in una cartella del vostro sito, per esempio public_html/velvet-pool/, via FTP o con il file manager dell'hosting, mantenendo le sottocartelle.
- Aprite quell'indirizzo in un browser.
Non sono coinvolti npm, terminale, fase di build, PHP, database né account. Ciò che invece fa inciampare le persone, secondo gli stessi manuali:
- Non fate doppio clic su index.html. I browser bloccano i moduli del gioco su file://. Per una prova locale, eseguite python -m http.server 8765 dentro game/ e aprite http://localhost:8765/.
- Il vostro server deve inviare i file .js con un tipo MIME JavaScript e .wasm come application/wasm. Un tipo MIME sbagliato si manifesta come errore di modulo rifiutato.
- Usate HTTPS per l'hosting pubblico.
- I salvataggi appartengono all'origine del browser (protocollo, host e porta). Spostate il gioco su un altro dominio e i giocatori ripartono da zero.
- Un nuovo caricamento della pagina ha comunque bisogno del vostro hosting, quindi non è un'app offline installabile.
Dove stanno logo, colori, regole e traduzioni
Ogni manuale ha una sezione sulla personalizzazione, e ciò che copre cambia da un'edizione all'altra. Ecco cosa dice ciascuno.
Velvet Pool
- Logo e branding: sostituite i file in assets/logo/ e adattate le dimensioni corrispondenti nel CSS.
- Stili di panno e stecca: le definizioni sono in progress.js. Mantenete stabili gli ID degli oggetti perché i cosmetici salvati continuino a funzionare.
- Comportamento della CPU in ai.js, fisica in physics.js. Dopo aver cambiato regole o fisica, eseguite i test dell'8-ball.
- Traduzioni: src/game/i18n.js, con l'elenco delle lingue in LANGS.
Puttide
- Colori e font: css/style.css.
- Fisica: src/sim/constants.js. Prezzi dei cosmetici: src/game/economy.js, mantenendo gli ID esistenti.
- Musica: copiate un file con licenza in music/ e aggiornate la mappatura dei brani in src/audio/audio.js.
- Buche, par e sblocchi: i file dei percorsi descritti sopra.
Gridspark e Sunset Rally
In Gridspark, secondo le FAQ del suo articolo, i testi dell'interfaccia stanno in src/locales.js, le costanti delle regole e la tavolozza in src/config.js, e le regole del puzzle in game.js, board.js, generator.js e shapes.js. In Sunset Rally le partite della campagna e le condizioni a stelle sono in Campaign.ts, le località in Places.ts, la fisica in physics.ts e il punteggio in match.ts. Le stringhe in inglese e portoghese sono in src/i18n.ts, le altre 12 lingue in src/locales/.
Notate cosa omettono i manuali. Il manuale di Puttide copre colori, fisica, buche, prezzi e musica, ma non ha un passaggio per sostituire il logo, e il manuale di Sunset Rally non ha una sezione dedicata al branding. Se il branding è la prima cosa che cambierete, chiedete prima di comprare.
Test automatici: cosa controllano e cosa no
La cartella source/ di Velvet Pool include una suite di test. Con Node.js 20 o successivo, aprite un terminale dentro source/ ed eseguite npm test, che equivale a node tests/run.js. Non serve installare dipendenze. Secondo il manuale, la suite controlla fisica, regole dell'8-ball, partite contro la CPU e la coerenza delle chiavi di traduzione, e non sostituisce il collaudo su browser e dispositivi reali.
Un controllo sulle chiavi di traduzione è il tipo di test di cui ha bisogno un gioco con 14 lingue: aggiungete una chiave in una lingua, dimenticatene un'altra, e un essere umano può non accorgersene per settimane.
Non tutte le edizioni hanno dei test. Il manuale di Puttide non ne descrive, solo controlli manuali. Pinloop e Beep Out elencano npm test tra i comandi per sviluppatori, e gli strumenti per sviluppatori di Ricopop includono un controllo dei livelli.
Licenza, note di terzi e changelog
Secondo i termini dello store, ogni acquisto dà una licenza perpetua e non esclusiva per usare l'edizione in un prodotto finale, vostro o di un singolo cliente. Potete modificare codice, grafica e audio al suo interno, e i giocatori possono usarlo gratuitamente o tramite pubblicità. Non potete rivendere, condividere o ridistribuire il template, il suo sorgente o le sue risorse da soli, come template, kit o pacchetto di asset, né all'interno di un altro prodotto destinato agli sviluppatori. La licenza non scade quando termina l'assistenza.
Le parti di terzi mantengono le proprie licenze, e conservate le loro note insieme al vostro prodotto. In Velvet Pool significa due font, Manrope e Fraunces, sotto la SIL Open Font License 1.1, con i testi in THIRD-PARTY-LICENSES/ e accanto ai font. In Puttide l'elenco aggiunge Three.js (MIT), Rapier (Apache-2.0) e i font Rubik e Fredoka (OFL 1.1).
Il changelog mostra come viene curato un pacchetto. Velvet Pool 1.0.1 (18 ottobre 2026) ha suddiviso le stringhe lunghe in righe leggibili e raccolto le note di licenza in un'unica cartella piatta. La versione 1.1.0 (22 ottobre 2026) ha portato l'interfaccia a 14 lingue. Quelle voci sono nella pagina dell'articolo. I termini dicono che gli aggiornamenti della stessa edizione compaiono nella vostra libreria quando vengono pubblicati, senza alcuna promessa di aggiornamenti per un periodo fisso.
Come leggere in un'ora il codice di un gioco che avete comprato
Questo è un piano suggerito, non una tempistica promessa. Segue la struttura di Velvet Pool e usa solo ciò che il pacchetto fornisce.
- Minuti da 0 a 10: estraete lo ZIP, scorrete il README in source/ e la mappa dei file del manuale. Aprite index.html e vedete quali script e fogli di stile carica.
- Minuti da 10 a 20: eseguite npm test dentro source/ (Node.js 20+) per ottenere una base verde.
- Minuti da 20 a 35: leggete src/core prima di src/game. Cominciate da rules.js, poi ai.js, poi physics.js. Quello è il gioco vero e proprio. Controlli, progressi, testi e suono sono l'impianto attorno.
- Minuti da 35 a 40: annotate che gli ID degli oggetti e le chiavi di salvataggio devono restare stabili, altrimenti i giocatori perdono i cosmetici salvati.
- Minuti da 40 a 55: fate una piccola modifica, come la definizione di un panno in progress.js. Copiate il file nello stesso percorso in game/, servite game/ con python -m http.server 8765 e guardate il risultato. Non apritelo mai tramite file://.
- Minuti da 55 a 60: eseguite di nuovo i test.
I moduli ES nominano ciò di cui hanno bisogno nelle righe di import, quindi potete seguire la catena a partire dal primo script che la pagina carica. È per questo che un'edizione a file semplici si può leggere a questo ritmo.
Domande da fare prima di comprare codice sorgente
- Posso leggere il manuale e giocare una demo prima di pagare? Per le nostre edizioni, entrambi sono collegati dalla pagina dell'articolo.
- Esistono una build pronta per l'hosting e un sorgente separato per sviluppatori?
- Il codice è leggibile o minificato? Aprite uno script e guardate.
- Mi servono Node.js, npm, PHP o un database, e in quali versioni?
- Il gioco carica qualcosa da una CDN o da un altro sito?
- Quali librerie di terzi ci sono dentro e con quali licenze?
- In quanti progetti posso usarlo e posso ridistribuirlo?
- Quanto dura l'assistenza e cosa copre? La nostra è di 6 mesi, o 12 con l'estensione scelta al checkout, e copre le domande sull'installazione e sull'uso dei file e i difetti riproducibili.
- Che cosa è escluso?
- Esistono un changelog e un rilascio recente?
- Qual è la regola di rimborso? La nostra: i template sono prodotti digitali, quindi rimborsiamo solo se non avete ancora scaricato il template o se ha un difetto che non riusciamo a correggere. Si richiede scrivendo allo studio con il numero di licenza.
Cosa non includono queste edizioni
Alcune edizioni aggiungono extra facoltativi. Ricopop e Zabum includono una classifica PHP a file singolo disattivata per impostazione predefinita. È una semplice tabella condivisa e informale che salva i punteggi in un file, non una classifica a prova di imbroglio, e non è multiplayer dal vivo.
L'assistenza copre le domande sull'installazione e sull'uso dei file forniti e la correzione dei difetti riproducibili nel gioco fornito. È un confine, ed è meglio conoscerlo dal primo giorno.
FAQ
Qual è la differenza tra la cartella del gioco e la cartella del sorgente?
game/ è la build che caricate sul vostro hosting. source/ è l'edizione modificabile per sviluppatori dello stesso gioco. In Velvet Pool e Puttide condividono la stessa struttura, quindi un file che modificate in source/ si copia nello stesso percorso in game/. Nelle edizioni TypeScript come Sunset Rally, source/ è un progetto che ricompilate, e pubblicate il nuovo output.
Servono npm o Node.js per usare il gioco?
Non per ospitarlo. Node.js compare solo per i test facoltativi di Velvet Pool (20 o successivo) o per ricompilare le edizioni TypeScript come Sunset Rally (consigliato 24 LTS) e Pinloop (22.12 o successivo).
Il codice sorgente è minificato?
Non nelle edizioni trattate qui. Velvet Pool e Puttide sono JavaScript semplice e formattato, e la versione 1.0.1 di entrambi ha suddiviso in righe leggibili le lunghe stringhe su riga singola. Il runtime di Sunset Rally è consegnato formattato, con la minificazione disattivata.
Posso usare un acquisto per più progetti o clienti?
La licenza copre un prodotto finale, vostro o di un singolo cliente. Un secondo prodotto è fuori da essa.
Posso rivendere o condividere il codice sorgente?
No: non da solo, non come template, kit o pacchetto di asset, e non all'interno di un altro prodotto destinato agli sviluppatori. Potete modificare codice, grafica e audio all'interno del vostro prodotto finale.
Posso leggere il manuale prima di comprare?
Sì. Ogni pagina di articolo rimanda al suo manuale e a una demo giocabile della stessa edizione.
Aprite un pacchetto prima di comprarne uno
Scegliete un'edizione, aprite il suo manuale dalla pagina dell'articolo, giocate la demo e leggete la mappa dei file alla luce delle domande qui sopra. Se il manuale vi risponde, dovrebbe farlo anche il pacchetto. Altrimenti, scrivete allo studio prima di pagare.