Izvorni kod mini golf igre: rupe, fizika i 3D karta staze

Izvorni kod mini golf igre stoji ili pada na jednom zadatku: dodavanju rupe. Kupac koji želi brendiranu stazu, sezonsku razinu ili logotip klijenta na zelenoj površini prvo će otvoriti datoteke razina, a ako je rupa zakopana u kodu motora, projekt zapinje. U Puttideu, našem 3D minigolf predlošku, svaka staza ima vlastitu datoteku rupa u običnom JavaScriptu, a priručnik prolazi kroz dodavanje jedne.

Ovaj vodič prati paket onako kako ga programer doživljava: mape, biblioteke, datoteke staza, redoslijed izmjena, hosting i licencu. Nazivi datoteka dolaze iz vodiča za kupca koji ide uz igru.

Kratak odgovor za one koji žure: Puttide je formatiran JavaScript s Three.js za crtanje i Rapierom za fiziku lopte, oba uključena u paket. Nema koraka izgradnje, nema CDN-a i nema serverskog koda.

Što uključuje izvorni kod mini golf igre

Puttide je gotova igra s 30 rupa na pet otočkih staza: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden i Volcano Forge, po šest rupa. Rampe, portali, odbojnici i vjetrenjače pretvaraju rupe u male zagonetke. Svaka rupa dodjeljuje tri zvjezdice (završetak, par ili bolje i skriveni novčić), a brončana, srebrna i zlatna medalja nagrađuju najbolje runde.

Uz staze postoji dnevni izazov s preokretom (vjetrovito, ledni green, teška lopta, elastični zidovi, nalet novčića ili lov na birdie), Locker (ormarić) gdje novčići kupuju lopte, staze i druge kozmetičke predmete, te runde za dva do četiri igrača koji se izmjenjuju na jednom uređaju. Sučelje dolazi na 14 jezika.

• game/: gotova verzija za učitavanje, jedina mapa koju objavljujete.
• source/: ista igra kao razvojno izdanje, s README i package.json.
• documentation/: jedan ilustrirani vodič na engleskom i portugalskom.
• THIRD-PARTY-LICENSES/: tekstovi licenci za biblioteke i fontove.
• Verzija 1.1.0, ažurirana 22. listopada 2026.

Otvorite stranicu Puttidea: demo, priručnik i cijena

Three.js, Rapier i ostatak tehnologije

Loptu simulira Rapier 3D 0.21.0, koji radi kao WebAssembly, a scena se crta s Three.js r186. Oba su u lib/three/ i lib/rapier/ sa svojim datotekama licenci, a index.html ima import mapu koja igru usmjerava na njih. Priručnik navodi da se datoteke biblioteka ponašaju nepromijenjeno i da su samo oblikovane radi čitljivosti.

To je važno iz dva razloga. Prvo, ništa se ne učitava s CDN-a, pa portalu ili klijentu sa strogom sigurnosnom politikom treba samo vaš hosting. Drugo, nadogradnja biblioteke je ručni, namjerni korak: source/package.json navodi točne verzije, a nove modulne datoteke kopirate preko odgovarajuće mape lib/ i zadržite putanje u import mapi.

• Three.js r186: MIT licenca.
• Rapier 3D compat 0.21.0, WebAssembly ugrađen: licenca Apache-2.0.
• Rubik i Fredoka web fontovi: SIL Open Font License 1.1.
• Dvije glazbene pjesme: music/menu.mp3 i music/play-1.mp3.

Gdje žive rupe, novčići i tekstovi

Putanje su iste u source/ i game/. Podaci o stazama podijeljeni su po otoku, što drži svaku datoteku dovoljno kratkom da se pročita u jednom sjedenju.

• src/course/courses.js: redoslijed staza i uvjeti otključavanja.
• src/course/holes.js: rupe Sunlit Ruinsa, s geometrijom, parom i preprekama.
• src/course/pier.js, ice.js, lava.js i sky.js: rupe ostale četiri staze.
• src/sim/constants.js: podešavanje fizike.
• src/game/economy.js: lopte, staze i odjeće, s njihovim cijenama.
• src/ui/i18n.js i pomoćne datoteke: rječnici za 14 jezika, uključujući nazive rupa i savjete.
• src/game/localRecords.js: rekordi staza pohranjeni u pregledniku.
• src/audio/audio.js: efekti i raspored glazbe, u probeTracks.
• css/style.css: boje sučelja, fontovi i responzivni stilovi.

Dodavanje rupe, korak po korak

To je promjena koju većina kupaca radi, a priručnik je opisuje u nekoliko redaka. Proširili smo je u redoslijed kojim bismo mi sami išli.

1. Izaberite datoteku staze kojoj nova rupa pripada, na primjer lava.js za Volcano Forge.
2. Duplicirajte postojeću definiciju rupe koja izgleda blizu onome što želite.
3. Dajte joj jedinstveni id. Ponovna upotreba ida zbunjuje spremljeni napredak.
4. Postavite par, položaj starta i položaj rupe, zatim pomaknite ili zamijenite prepreke.
5. Dodajte rupu njezinoj stazi u courses.js.
6. Dodajte njezin prikazni naziv i savjet u rječnike jezika, u svakom jeziku koji isporučujete.
7. Odigrajte je: testirajte sudare, povrat kad lopta izađe iz terena i sve tri zvjezdice, uključujući skriveni novčić.

Uređujte u source/, kopirajte promijenjene datoteke na iste putanje u game/ i poslužite mapu preko HTTP-a za testiranje. package.json ima skriptu serve, ili možete pokrenuti python -m http.server 8765. Node.js je opcionalan i potreban je samo ako želite da npm upravlja verzijama biblioteka.

Ostale izmjene, razumnim redom

1. Brend i boje: logotip, boje i fontovi u css/style.css. White label je dopušten, pa vaš brend može zamijeniti naš.
2. Cijene u Lockeru: economy.js. Jeftinija kozmetika čini casual stranicu prijateljskijom; skuplja produljuje dugu kampanju.
3. Tekstovi: formulacije i savjeti u i18n datotekama.
4. Glazba: dvije uključene pjesme mogu se zamijeniti snimkama za koje imate licencu. Kopirajte datoteku i ažurirajte eksplicitno mapiranje u audio.js (probeTracks); glazba scene vraća se na pjesmu za igru.
5. Fizika: constants.js, zadnje i u malim koracima, jer je svaka rupa podešena prema trenutnim vrijednostima.

Za srodan projekt s istim pristupom običnog JavaScripta i bez ikakve 3D biblioteke, naš predložak za bilijar izrađen je na isti način.

Velvet Pool: 8-ball bilijar u običnom JavaScriptu i WebGL2

Sunset Rally: 3D stolni tenis s kampanjom od devet utakmica

Hosting, MIME tipovi i omotači aplikacija

Učitajte sve iz game/ u mapu poput public_html/puttide/, zadržite podmape i otvorite adresu preko HTTPS-a. Na poslužitelju nisu potrebni npm, PHP, baza podataka ni račun. Otvaranje index.html s diska ne radi, jer preglednici blokiraju module na file://.

Puttide ima jedan detalj hostinga koji 2D igra nema: fizika radi kao WebAssembly. Vaš poslužitelj mora slati .js datoteke s JavaScript MIME tipom, a .wasm kao application/wasm. Host koji ovo pogriješi prikazuje prazan ekran ili grešku modula, pa provjerite to prvog dana.

• Preglednik treba: JavaScript, ES module, WebAssembly i WebGL2.
• U portal iframeu dopustite cijeli ekran i automatsko pokretanje.
• Na ekranima osjetljivim na dodir: povucite za nišanjenje i udarac, dva prsta za rotaciju kamere, stisnite za zumiranje.
• Nije instalabilna aplikacija za rad bez mreže: svako svježe učitavanje i dalje ide na vaš hosting.

Projekti nativnih aplikacija nisu u paketu. Ako planirate objavu u trgovini, računajte na omotač i testiranje na pravim telefonima, jer je 3D igra s fizikom teža od kartaške igre na starijim uređajima.

Što nije uključeno i licenca

Ovo je lokalno izdanje za preglednik: nema višekorisničke igre na mreži ni online soba, nema online ljestvice, nema računa u oblaku, nema SDK-a za oglase, nema nativnih aplikacija i nema hostinga. Rekordi staza, dnevni napredak i runde na istom uređaju ostaju u pregledniku igrača, a nijedan rezultat se ne šalje na mrežu. Spremanja pripadaju izvoru preglednika, pa prelazak na drugu domenu igrače vraća na početak.

Puttide košta 39 USD; do 30. studenoga 2026. promocija Black Friday ga spušta na 33,15 USD, a kupnja dva ili više predložaka u jednoj narudžbi donosi popust za skup od 5 % do 20 %. Licenca je doživotna i nekskluzivna za jedan krajnji proizvod, vaš ili jednog klijenta. Smijete ga brendirati, mijenjati kod, grafiku i zvuk te pustiti igrače besplatno ili uz oglase, ali ne smijete preprodavati predložak ili njegov kod samostalno. Podrška traje šest mjeseci, ili dvanaest uz produženje; prilagođene rupe, integracije i hosting nude se na upit.

Licenca, podrška i uvjeti povrata u cijelosti

Često postavljana pitanja

Je li izvorni kod mini golfa u TypeScriptu?

Ne. Puttide je običan, formatiran JavaScript u source/src i game/src, bez minificiranih ili spakiranih datoteka naše izrade.

Mogu li dodati vlastite rupe ili staze?

Da. Duplicirajte rupu u datoteci staze, dajte joj jedinstveni id, postavite par, start i rupu, dodajte je u courses.js i dodajte njezin naziv i savjet u jezične datoteke.

Učitava li Three.js s CDN-a?

Ne. Three.js, Rapier, fontovi i glazba nalaze se unutar game/, pa igra treba samo vaš hosting.

Zašto moj hosting prikazuje prazan ekran?

Obično zbog MIME tipova. Poslužujte .js kao JavaScript, a .wasm kao application/wasm, otvorite igru preko HTTP(S) i provjerite je li WebGL2 uključen.

Mogu li prijatelji igrati zajedno?

Da, dva do četiri igrača izmjenjuju se na istom uređaju. Igra na mreži nije dio ovog izdanja.

Je li to pravi mini golf temelj za vas?

Puttide odgovara obiteljskom ili sportskom portalu, agenciji koja gradi brendiranu stazu za jednog klijenta i programeru koji želi vidjeti kako Three.js i Rapier rade zajedno u čitljivom kodu. Slabije odgovara projektu kojem od prvog dana trebaju runde na mreži ili zajednička ljestvica.

Odigrajte cijelu stazu u demo verziji na telefonu, zatim pročitajte odjeljak priručnika o dodavanju rupe. Ako vam se taj odjeljak čini kao popodne rada, ostatak igre je već izgrađen.

Odigrajte demo Puttidea i kupite licencu