Codice sorgente di un gioco di minigolf: buche, fisica e percorsi 3D

Il codice sorgente di un gioco di minigolf si giudica da una sola operazione: aggiungere una buca. Chi vuole un percorso con il proprio marchio, un livello stagionale o il logo di un cliente sul green apre per prima cosa i file dei livelli, e se una buca è sepolta nel codice del motore il progetto si blocca. In Puttide, il nostro template di minigolf 3D, ogni percorso ha il proprio file di buche in JavaScript puro, e il manuale spiega come aggiungerne una.

Questa guida segue il pacchetto nell'ordine in cui lo incontra uno sviluppatore: le cartelle, le librerie, i file dei percorsi, l'ordine delle modifiche, l'hosting e la licenza. I nomi dei file vengono dalla guida per l'acquirente inclusa nel gioco.

La risposta breve per chi ha fretta: Puttide è JavaScript formattato, con Three.js per la grafica e Rapier per la fisica della pallina, entrambi inclusi. Nessun passaggio di build, nessuna CDN e nessun codice lato server.

Cosa include il codice sorgente del minigolf

Puttide è un gioco completo con 30 buche distribuite su cinque percorsi insulari: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden e Volcano Forge, sei buche ciascuno. Rampe, portali, respingenti e mulini a vento trasformano le buche in piccoli rompicapi. Ogni buca assegna tre stelle (completarla, chiuderla al par o meglio, trovare la moneta nascosta), e medaglie di bronzo, argento e oro premiano i giri migliori.

Oltre ai percorsi ci sono una sfida giornaliera con una variante (vento, green ghiacciato, pallina pesante, sponde elastiche, corsa alle monete o caccia al birdie), un Locker in cui le monete comprano palline, scie e altri elementi estetici, e partite da due a quattro giocatori a turno sullo stesso dispositivo. L'interfaccia è disponibile in 14 lingue.

• game/: la build pronta da caricare, l'unica cartella da pubblicare.
• source/: lo stesso gioco in edizione per sviluppatori, con README e package.json.
• documentation/: una guida illustrata in inglese e portoghese.
• THIRD-PARTY-LICENSES/: i testi delle licenze di librerie e font.
• Versione 1.1.0, aggiornata il 22 ottobre 2026.

Apri la scheda di Puttide: demo, manuale e prezzo

Three.js, Rapier e il resto dello stack

La pallina è simulata da Rapier 3D 0.21.0, che gira in WebAssembly, e la scena è disegnata con Three.js r186. Entrambe le librerie stanno in lib/three/ e lib/rapier/ con i rispettivi file di licenza, e index.html contiene una import map che indirizza il gioco verso di esse. Il manuale precisa che il comportamento delle librerie non è stato modificato: sono solo formattate per essere leggibili.

Questo conta per due motivi. Primo, niente viene caricato da una CDN, quindi a un portale o a un cliente con una politica di sicurezza rigida basta il tuo host. Secondo, aggiornare una libreria è un passaggio manuale e voluto: source/package.json elenca le versioni esatte, si copiano i nuovi moduli sopra la cartella lib/ corrispondente e si mantengono i percorsi della import map.

• Three.js r186: licenza MIT.
• Rapier 3D compat 0.21.0, con WebAssembly incorporato: licenza Apache-2.0.
• Font web Rubik e Fredoka: SIL Open Font License 1.1.
• Due brani musicali: music/menu.mp3 e music/play-1.mp3.

Dove stanno buche, monete e testi

I percorsi sono identici in source/ e in game/. I dati dei percorsi sono divisi per isola, così ogni file resta abbastanza corto da leggerlo tutto d'un fiato.

• src/course/courses.js: ordine dei percorsi e requisiti di sblocco.
• src/course/holes.js: le buche di Sunlit Ruins, con geometria, par e ostacoli.
• src/course/pier.js, ice.js, lava.js e sky.js: le buche degli altri quattro percorsi.
• src/sim/constants.js: la taratura della fisica.
• src/game/economy.js: palline, scie e outfit, con i relativi prezzi.
• src/ui/i18n.js e i file collegati: i dizionari delle 14 lingue, compresi nomi delle buche e suggerimenti.
• src/game/localRecords.js: i record dei percorsi salvati nel browser.
• src/audio/audio.js: effetti sonori e associazione della musica, in probeTracks.
• css/style.css: colori dell'interfaccia, font e stili responsive.

Aggiungere una buca, passo dopo passo

È la modifica che fa la maggior parte degli acquirenti, e il manuale la descrive in poche righe. Noi l'abbiamo sviluppata nell'ordine che seguiremmo noi stessi.

1. Scegli il file del percorso a cui appartiene la nuova buca, per esempio lava.js per Volcano Forge.
2. Duplica la definizione di una buca esistente simile a quella che vuoi.
3. Assegnale un id univoco. Riutilizzare un id manda in confusione i progressi salvati.
4. Imposta il par, la posizione del tee e quella della buca, poi sposta o sostituisci gli ostacoli.
5. Aggiungi la buca al suo percorso in courses.js.
6. Aggiungi nome e suggerimento nei dizionari, in tutte le lingue che pubblichi.
7. Giocala: verifica collisioni, recupero fuori campo e tutte e tre le stelle, moneta nascosta compresa.

Modifica in source/, copia i file cambiati negli stessi percorsi dentro game/ e servi la cartella via HTTP per il test. Il package.json ha uno script serve, oppure puoi lanciare python -m http.server 8765. Node.js è facoltativo e serve solo se vuoi che npm gestisca le versioni delle librerie.

Le altre modifiche, in un ordine sensato

1. Marchio e colori: logo, colori e font in css/style.css. Il white label è consentito, quindi il tuo marchio può sostituire il nostro.
2. Prezzi nel Locker: economy.js. Elementi estetici più economici rendono più accogliente un sito casual; più cari allungano una campagna lunga.
3. Testi: formulazioni e suggerimenti nei file i18n.
4. Musica: i due brani inclusi si possono sostituire con registrazioni di cui hai la licenza. Copia il file e aggiorna l'associazione esplicita in audio.js (probeTracks); la musica delle scene ripiega sul brano di gioco.
5. Fisica: constants.js, per ultima e a piccoli passi, perché ogni buca è stata tarata sui valori attuali.

Se cerchi un progetto affine, con lo stesso approccio in JavaScript puro e senza alcuna libreria 3D, il nostro template di biliardo è costruito allo stesso modo.

Velvet Pool: biliardo 8-ball in JavaScript puro e WebGL2

Sunset Rally: ping pong 3D con una campagna di nove partite

Hosting, tipi MIME e app native

Carica tutto il contenuto di game/ in una cartella come public_html/puttide/, mantieni le sottocartelle e apri l'indirizzo in HTTPS. Sul server non servono npm, PHP, database né account. Aprire index.html dal disco non funziona, perché i browser bloccano i moduli su file://.

Puttide ha un dettaglio di hosting che un gioco 2D non ha: la fisica gira in WebAssembly. Il server deve inviare i file .js con un tipo MIME JavaScript e i .wasm come application/wasm. Un host che sbaglia questa configurazione mostra una schermata vuota o un errore di modulo, quindi controllalo subito.

• Requisiti del browser: JavaScript, moduli ES, WebAssembly e WebGL2.
• In un iframe di un portale, consenti fullscreen e autoplay.
• Su touch screen: trascina per mirare e tirare, due dita per ruotare la telecamera, pizzica per lo zoom.
• Non è un'app installabile offline: ogni nuovo caricamento passa comunque dal tuo host.

I progetti di app native non sono inclusi. Se prevedi una pubblicazione negli store, metti in budget il wrapper e i test su telefoni reali, perché sui dispositivi più vecchi un gioco 3D con fisica è più pesante di un gioco di carte.

Cosa non è incluso, e la licenza

Questa è l'edizione locale per browser: niente multigiocatore o stanze online, niente classifica online, niente account cloud, niente SDK pubblicitario, niente app native e niente hosting. Record dei percorsi, progressi giornalieri e partite sullo stesso dispositivo restano nel browser del giocatore, e nessun punteggio viene inviato. I salvataggi appartengono all'origine del browser, quindi spostando il gioco su un altro dominio i giocatori ripartono da zero.

Puttide costa $39 a listino; fino al 30 novembre 2026 la promozione Black Friday lo porta a $33.15, 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 cambiare marchio, modificare codice, grafica e audio e offrire il gioco gratis o con pubblicità, ma non puoi rivendere il template o il suo codice da soli. Il supporto dura sei mesi, o dodici con l'estensione; buche personalizzate, integrazioni e hosting si quotano su richiesta.

Termini completi di licenza, supporto e rimborso

Domande frequenti

Il codice sorgente del minigolf è in TypeScript?

No. Puttide è JavaScript puro e formattato in source/src e game/src, senza file minificati o impacchettati da noi.

Posso aggiungere buche o percorsi miei?

Sì. Duplica una buca nel file del percorso, assegnale un id univoco, imposta par, tee e buca, aggiungila a courses.js e inserisci nome e suggerimento nei file delle lingue.

Three.js viene caricato da una CDN?

No. Three.js, Rapier, i font e la musica sono tutti dentro game/, quindi il gioco ha bisogno solo del tuo host.

Perché il mio host mostra una schermata vuota?

Di solito per i tipi MIME. Servi i .js come JavaScript e i .wasm come application/wasm, apri il gioco via HTTP(S) e verifica che WebGL2 sia attivo.

Si può giocare con gli amici?

Sì, da due a quattro giocatori a turno sullo stesso dispositivo. Il gioco online non fa parte di questa edizione.

È la base di minigolf giusta per te?

Puttide è adatto a un portale per famiglie o di sport, a un'agenzia che costruisce un percorso brandizzato per un cliente e a uno sviluppatore che vuole vedere come Three.js e Rapier lavorano insieme in codice leggibile. È meno adatto a un progetto che richiede partite online o una classifica condivisa fin dal primo giorno.

Gioca un percorso intero nella demo da telefono, poi leggi la sezione del manuale su come aggiungere una buca. Se ti sembra un pomeriggio di lavoro, il resto del gioco è già fatto.

Prova la demo di Puttide e acquista la licenza