Cod sursă joc mini golf: găuri, fizică și hartă 3D a terenului

Codul sursă al unui joc de mini golf stă sau cade pe o singură sarcină: adăugarea unei găuri. Un cumpărător care vrea un teren cu brand, un nivel sezonier sau logo-ul unui client pe green va deschide mai întâi fișierele nivelurilor, iar dacă o gaură este îngropată în codul motorului, proiectul se blochează. În Puttide, șablonul nostru de mini golf 3D, fiecare teren are propriul fișier de gaură în JavaScript simplu, iar manualul explică pas cu pas adăugarea uneia.

Acest ghid urmează pachetul așa cum îl întâlnește un dezvoltator: folderele, bibliotecile, fișierele terenurilor, ordinea modificărilor, găzduirea și licența. Numele fișierelor vin din ghidul pentru cumpărător care însoțește jocul.

Răspunsul scurt pentru cei grăbiți: Puttide este JavaScript formatat, cu Three.js pentru desen și Rapier pentru fizica mingii, ambele incluse. Fără pas de compilare, fără CDN și fără cod de server.

Ce include codul sursă al jocului de mini golf

Puttide este un joc finalizat cu 30 de găuri pe cinci terenuri de insulă: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden și Volcano Forge, câte șase găuri fiecare. Rampele, portalurile, amortizoarele și morile de vânt transformă găurile în mici puzzle-uri. Fiecare gaură acordă trei stele (terminarea, par-ul sau mai bine și moneda ascunsă), iar medaliile de bronz, argint și aur premiază cele mai bune runde.

Pe lângă terenuri, există o provocare zilnică cu o întorsătură (vânt, green înghețat, minge grea, pereți elastici, avalanșă de monede sau vânătoarea de birdie), un Locker (dulap) în care monedele cumpără mingi, trasee și alte cosmetice și runde pentru doi până la patru jucători, pe rând, pe un singur dispozitiv. Interfața vine în 14 limbi.

• game/: build-ul gata de încărcat, singurul folder pe care îl publici.
• source/: același joc ca ediție pentru dezvoltatori, cu un README și package.json.
• documentation/: un ghid ilustrat, în engleză și portugheză.
• THIRD-PARTY-LICENSES/: textele licențelor pentru biblioteci și fonturi.
• Versiunea 1.1.0, actualizată pe 22 octombrie 2026.

Deschide fișa Puttide: demo, manual și preț

Three.js, Rapier și restul stivei

Mingea este simulată de Rapier 3D 0.21.0, care rulează ca WebAssembly, iar scena este desenată cu Three.js r186. Amândouă se află în lib/three/ și lib/rapier/, cu fișierele lor de licență, iar index.html are o import map care îndreaptă jocul spre ele. Manualul notează că fișierele bibliotecilor nu sunt schimbate ca funcționare și sunt doar formatate ca să poată fi citite.

Asta contează din două motive. Primul: nimic nu se încarcă de pe un CDN, deci un portal sau un client cu o politică de securitate strictă are nevoie doar de gazda ta. Al doilea: actualizarea unei biblioteci este un pas manual și deliberat. source/package.json enumeră versiunile exacte, iar tu copiezi fișierele modulelor noi peste folderul lib/ corespunzător și păstrezi căile din import map.

• Three.js r186: licență MIT.
• Rapier 3D compat 0.21.0, cu WebAssembly încorporat: licență Apache-2.0.
• Fonturile web Rubik și Fredoka: SIL Open Font License 1.1.
• Două piese muzicale: music/menu.mp3 și music/play-1.mp3.

Unde stau găurile, monedele și textele

Căile sunt aceleași în source/ și în game/. Datele terenurilor sunt împărțite pe insulă, ceea ce ține fiecare fișier suficient de scurt ca să fie citit dintr-o suflare.

• src/course/courses.js: ordinea terenurilor și cerințele de deblocare.
• src/course/holes.js: găurile Sunlit Ruins, cu geometrie, par și obstacole.
• src/course/pier.js, ice.js, lava.js și sky.js: găurile celorlalte patru terenuri.
• src/sim/constants.js: reglajele fizicii.
• src/game/economy.js: mingile, traseele și ținutele, cu prețurile lor.
• src/ui/i18n.js și fișierele însoțitoare: dicționarele celor 14 limbi, inclusiv numele găurilor și sfaturile.
• src/game/localRecords.js: recordurile terenurilor, păstrate în browser.
• src/audio/audio.js: efectele și maparea muzicii, în probeTracks.
• css/style.css: culorile interfeței, fonturile și stilurile responsive.

Adăugarea unei găuri, pas cu pas

Aceasta este modificarea pe care o fac majoritatea cumpărătorilor, iar manualul o descrie în câteva rânduri. Noi am extins-o în ordinea în care am urma-o noi înșine.

1. Alege fișierul terenului căruia îi aparține noua gaură, de exemplu lava.js pentru Volcano Forge.
2. Dublează o definiție de gaură existentă, care seamănă cu ce vrei.
3. Dă-i un id unic. Refolosirea unui id încurcă progresul salvat.
4. Stabilește par-ul, poziția de start (tee) și poziția găurii (cup), apoi mută sau înlocuiește obstacolele.
5. Adaugă gaura în terenul ei, în courses.js.
6. Adaugă numele afișat și sfatul în dicționarele de limbă, în fiecare limbă pe care o livrezi.
7. Joac-o: testează coliziunile, revenirea când mingea iese din teren și toate cele trei stele, inclusiv moneda ascunsă.

Editezi în source/, copiezi fișierele modificate în aceleași căi din game/ și servești folderul prin HTTP ca să testezi. package.json are un script serve, sau poți rula python -m http.server 8765. Node.js este opțional și este necesar doar dacă vrei ca npm să gestioneze versiunile bibliotecilor.

Celelalte modificări, într-o ordine rezonabilă

1. Brandul și culorile: logo-ul, culorile și fonturile din css/style.css. White label este permis, deci brandul tău îl poate înlocui pe al nostru.
2. Prețurile din Locker: economy.js. Cosmeticele mai ieftine fac un site ocazional mai prietenos; cele mai scumpe întind o campanie lungă.
3. Textele: formularea și sfaturile din fișierele i18n.
4. Muzica: cele două piese incluse pot fi înlocuite cu înregistrări pentru care deții o licență. Copiază fișierul și actualizează maparea explicită din audio.js (probeTracks); muzica scenelor revine la piesa de joc.
5. Fizica: constants.js, la final și în pași mici, pentru că fiecare gaură a fost reglată pe valorile actuale.

Pentru un proiect înrudit, cu aceeași abordare în JavaScript simplu și fără nicio bibliotecă 3D, șablonul nostru de biliard este construit la fel.

Velvet Pool: bilard cu 8 bile în JavaScript simplu și WebGL2

Sunset Rally: tenis de masă 3D cu o campanie de nouă meciuri

Găzduire, tipuri MIME și învelișuri pentru aplicații

Încarcă tot ce este în game/ într-un folder precum public_html/puttide/, păstrează subfolderele și deschide adresa prin HTTPS. Nu este nevoie de npm, PHP, bază de date sau cont pe server. Deschiderea index.html de pe disc nu funcționează, pentru că browserele blochează modulele pe file://.

Puttide are un detaliu de găzduire pe care nu îl are un joc 2D: fizica rulează ca WebAssembly. Serverul tău trebuie să trimită fișierele .js cu un tip MIME JavaScript și .wasm ca application/wasm. O gazdă care greșește asta afișează un ecran gol sau o eroare de modul, deci verifică-o din prima zi.

• Browserul are nevoie de: JavaScript, module ES, WebAssembly și WebGL2.
• Într-un iframe de portal, permite ecranul complet și redarea automată.
• Pe ecranele tactile: glisează pentru a ținti și a lovi, două degete pentru a roti camera, ciupire pentru zoom.
• Nu este o aplicație offline instalabilă: fiecare încărcare nouă ajunge tot la gazda ta.

Proiectele de aplicații native nu sunt în pachet. Dacă planifici o lansare în magazin, alocă buget pentru învelișul și testarea pe telefoane reale, pentru că un joc cu fizică 3D este mai greu decât un joc de cărți pe dispozitive vechi.

Ce nu este inclus, și licența

Aceasta este ediția pentru browser local: fără multiplayer online sau camere online, fără clasament online, fără conturi în cloud, fără SDK de reclame, fără aplicații native și fără găzduire. Recordurile terenurilor, progresul zilnic și rundele pe același dispozitiv rămân în browserul jucătorului, iar niciun scor nu se încarcă. Salvările aparțin originii browserului, deci trecerea pe alt domeniu îi face pe jucători să pornească de la zero.

Puttide costă 39 USD; până la 30 noiembrie 2026, promoția Black Friday îl duce la 33,15 USD, iar cumpărarea a două sau mai multe șabloane dintr-o singură comandă adaugă o reducere de pachet de 5% până la 20%. Licența este perpetuă și nonexclusivă, pentru un produs final, al tău sau al unui client. Poți să îi schimbi brandul, să modifici codul, grafica și sunetul și să lași jucătorii să intre gratuit sau cu reclame, dar nu poți revinde șablonul sau codul său de sine stătător. Suportul durează șase luni, sau douăsprezece cu extensia; găurile personalizate, integrările și găzduirea se cotează la cerere.

Termenii de licență, suport și rambursare, integral

Întrebări frecvente

Codul sursă al mini golfului este în TypeScript?

Nu. Puttide este JavaScript simplu, formatat, în source/src și game/src, fără fișiere minificate sau împachetate de noi.

Pot adăuga propriile mele găuri sau terenuri?

Da. Dublează o gaură în fișierul terenului, dă-i un id unic, stabilește par-ul, start-ul și cupa, adaugă-o în courses.js și adaugă-i numele și sfatul în fișierele de limbă.

Încarcă Three.js de pe un CDN?

Nu. Three.js, Rapier, fonturile și muzica sunt toate în game/, deci jocul are nevoie doar de gazda ta.

De ce îmi arată gazda un ecran gol?

De obicei din cauza tipurilor MIME. Servește .js ca JavaScript și .wasm ca application/wasm, deschide jocul prin HTTP(S) și verifică dacă WebGL2 este activat.

Pot juca prietenii împreună?

Da, doi până la patru jucători iau pe rând pe același dispozitiv. Jocul online nu face parte din această ediție.

Este baza potrivită de mini golf pentru tine?

Puttide se potrivește unui portal de familie sau de sport, unei agenții care construiește un teren cu brand pentru un client și unui dezvoltator care vrea să vadă cum lucrează Three.js și Rapier împreună, în cod lizibil. Se potrivește mai slab unui proiect care are nevoie de runde online sau de un clasament comun din prima zi.

Joacă un teren complet în demo, pe telefon, apoi citește secțiunea din manual despre adăugarea unei găuri. Dacă ți se pare o după-amiază de muncă, restul jocului este deja construit.

Joacă demo-ul Puttide și cumpără licența