Zdrojový kód minigolfu: jamky, fyzika a 3D mapa ihriska

Zdrojový kód minigolfu stojí a padá na jednej úlohe: pridať jamku. Kupujúci, ktorý chce značkové ihrisko, sezónny level alebo logo klienta na zelenej ploche, otvorí najprv súbory levelov, a ak je jamka zakopaná v kóde enginu, projekt stojí. V Puttide, našej 3D minigolfovej šablóne, má každé ihrisko vlastný súbor jamky v čistom JavaScripte a návod prechádza krok za krokom, ako jednu pridať.

Tento návod ide balíkom tak, ako ho vidí vývojár: priečinky, knižnice, súbory ihrísk, poradie zmien, hosting a licencia. Názvy súborov pochádzajú z návodu pre kupujúcich, ktorý ide s hrou.

Krátka odpoveď pre netrpezlivých: Puttide je formátovaný JavaScript s Three.js na kreslenie a Rapier na fyziku lopty, obe zabalené. Žiadny krok zostavenia, žiadne CDN a žiadny serverový kód.

Čo obsahuje zdrojový kód minigolfu

Puttide je hotová hra s 30 jamkami na piatich ostrovných ihriskách: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden a Volcano Forge, každé so šiestimi jamkami. Rampy, portály, nárazníky a veterníky premieňajú jamky na malé hlavolamy. Každá jamka dáva tri hviezdičky (dokončenie, par alebo lepšie, skrytá minca) a bronzová, strieborná a zlatá medaila odmeňuje najlepšie kolá.

Okrem ihrísk je tu denná výzva s obmenou (veter, ľadový green, ťažká loptička, odrazové steny, horúčka mincí alebo lov birdie), Locker (skrinka), kde mince kupujú loptičky, stopy a iné kozmetické položky, a kolá pre dvoch až štyroch hráčov, ktorí sa striedajú na jednom zariadení. Rozhranie je v 14 jazykoch.

• game/: hotové zostavenie na nahratie, jediný priečinok, ktorý zverejňujete.
• source/: tá istá hra ako vývojárske vydanie, s README a package.json.
• documentation/: jeden ilustrovaný návod v angličtine a portugalčine.
• THIRD-PARTY-LICENSES/: texty licencií pre knižnice a fonty.
• Verzia 1.1.0, aktualizovaná 22. októbra 2026.

Otvoriť stránku Puttide: demo, návod a cena

Three.js, Rapier a zvyšok balíka

Loptičku simuluje Rapier 3D 0.21.0, ktorý beží ako WebAssembly, a scénu kreslí Three.js r186. Obe sú v lib/three/ a lib/rapier/ so svojimi licenčnými súbormi a index.html má import map, ktorá ukazuje hre na ne. Návod uvádza, že súbory knižníc sa správaním nemenia a boli upravené len formátovaním, aby sa dali čítať.

To je dôležité z dvoch dôvodov. Po prvé, nič sa nenačítava z CDN, takže portál alebo klient s prísnou bezpečnostnou politikou potrebuje len váš hosting. Po druhé, aktualizácia knižnice je ručný, zámerný krok: source/package.json uvádza presné verzie a nové modulové súbory skopírujete na zodpovedajúce miesto v lib/ a ponecháte cesty v import map.

• Three.js r186: licencia MIT.
• Rapier 3D compat 0.21.0, WebAssembly vložené: licencia Apache-2.0.
• Písma Rubik a Fredoka: SIL Open Font License 1.1.
• Dve hudobné stopy: music/menu.mp3 a music/play-1.mp3.

Kde sú jamky, mince a texty

Cesty sú rovnaké v source/ aj game/. Dáta ihrísk sú rozdelené podľa ostrova, čo drží každý súbor dostatočne krátky na prečítanie naraz.

• src/course/courses.js: poradie ihrísk a požiadavky na odomknutie.
• src/course/holes.js: jamky Sunlit Ruins, s geometriou, parom a prekážkami.
• src/course/pier.js, ice.js, lava.js a sky.js: jamky ostatných štyroch ihrísk.
• src/sim/constants.js: ladenie fyziky.
• src/game/economy.js: loptičky, stopy a výbavy s ich cenami.
• src/ui/i18n.js a jeho sprievodné súbory: 14 jazykových slovníkov vrátane názvov jamiek a tipov.
• src/game/localRecords.js: rekordy ihrísk uložené v prehliadači.
• src/audio/audio.js: zvukové efekty a mapovanie hudby v probeTracks.
• css/style.css: farby rozhrania, fonty a responzívne štýly.

Pridanie jamky krok za krokom

Toto je zmena, ktorú robí väčšina kupujúcich, a návod ju opisuje v niekoľkých riadkoch. Rozpísali sme ju do poradia, ktorým by sme išli my sami.

1. Vyberte súbor ihriska, ku ktorému nová jamka patrí, napríklad lava.js pre Volcano Forge.
2. Skopírujte existujúcu definíciu jamky, ktorá sa podobá tomu, čo chcete.
3. Dajte jej jedinečné id. Opätovné použitie id zmätie uložený postup.
4. Nastavte par, pozíciu odpalu a pozíciu jamky, potom posuňte alebo nahraďte prekážky.
5. Pridajte jamku do jej ihriska v courses.js.
6. Pridajte jej zobrazovaný názov a tip do jazykových slovníkov, v každom jazyku, ktorý dodávate.
7. Zahrajte si ju: otestujte kolízie, návrat z mimo ihriska a všetky tri hviezdičky, vrátane skrytej mince.

Upravujte v source/, skopírujte zmenené súbory na tie isté cesty v game/ a na testovanie podávajte priečinok cez HTTP. Súbor package.json má skript serve, alebo môžete spustiť python -m http.server 8765. Node.js je voliteľný a potrebný len vtedy, ak chcete, aby npm spravoval verzie knižníc.

Ostatné zmeny v rozumnom poradí

1. Značka a farby: logo, farby a fonty v css/style.css. White label je povolený, takže vaša značka môže nahradiť našu.
2. Ceny v Lockeri: economy.js. Lacnejšia kozmetika robí casual stránku priateľskejšou; drahšia predlžuje dlhú kampaň.
3. Texty: formulácie a tipy v súboroch i18n.
4. Hudba: dve dodané stopy možno nahradiť nahrávkami, na ktoré máte licenciu. Skopírujte súbor a aktualizujte explicitné mapovanie v audio.js (probeTracks); hudba scény sa vracia k hernej stope.
5. Fyzika: constants.js, ako poslednú a po malých krokoch, lebo každá jamka bola doladená podľa aktuálnych hodnôt.

Pre príbuzný projekt s rovnakým prístupom v čistom JavaScripte a bez 3D knižnice je naša šablóna pool postavená rovnako.

Velvet Pool: pool s osemkou v čistom JavaScripte a WebGL2

Sunset Rally: 3D stolný tenis s kampaňou deviatich zápasov

Hosting, typy MIME a obaly aplikácií

Nahrajte všetko v game/ do priečinka, napríklad public_html/puttide/, zachovajte podpriečinky a otvorte adresu cez HTTPS. Na serveri nie je potrebné npm, PHP, databáza ani účet. Otvorenie index.html z disku nefunguje, lebo prehliadače blokujú moduly na file://.

Puttide má jeden detail hostingu, ktorý 2D hra nemá: fyzika beží ako WebAssembly. Váš server musí posielať súbory .js s typom JavaScript a .wasm ako application/wasm. Hosting, ktorý to nastaví zle, ukáže prázdnu obrazovku alebo chybu modulu, takže to skontrolujte už prvý deň.

• Prehliadač potrebuje: JavaScript, ES moduly, WebAssembly a WebGL2.
• V iframe portálu povoľte celú obrazovku a automatické prehrávanie.
• Na dotykových obrazovkách: potiahnutím mieriť a zasiahnuť, dvoma prstami otáčať kameru, štipnutím priblížiť.
• Nie je to inštalovateľná offline aplikácia: každé nové načítanie stále ide na váš hosting.

Projekty natívnych aplikácií nie sú v balíku. Ak plánujete vydanie v obchode, rátajte s obalom a jeho testovaním na skutočných telefónoch, lebo 3D fyzikálna hra je na starších zariadeniach ťažšia než kartová hra.

Čo nie je zahrnuté a licencia

Toto je lokálne prehliadačové vydanie: žiadny online multiplayer ani online miestnosti, žiadny online rebríček, žiadne cloudové účty, žiadne reklamné SDK, žiadne natívne aplikácie a žiadny hosting. Rekordy ihrísk, denný postup a kolá na jednom zariadení zostávajú v prehliadači hráča a žiadne skóre sa neodosiela. Uloženia patria k originu prehliadača, takže presun na inú doménu začne hráčov odznova.

Puttide stojí 39 USD; do 30. novembra 2026 ho akcia Black Friday znižuje na 33,15 USD a kúpa dvoch alebo viacerých šablón v jednej objednávke pridá zľavu za balík 5 až 20 %. Licencia je trvalá a nevýhradná pre jeden koncový produkt, váš alebo jedného klienta. Môžete ho prebrandovať, meniť jeho kód, grafiku a zvuk a pustiť hráčov dnu zadarmo alebo s reklamou, ale samotnú šablónu ani jej kód nesmiete ďalej predávať. Podpora trvá šesť mesiacov, alebo dvanásť s predĺžením; vlastné jamky, integrácie a hosting sa ocenia na požiadanie.

Licencia, podpora a podmienky vrátenia v plnom znení

Často kladené otázky

Je zdrojový kód minigolfu v TypeScripte?

Nie. Puttide je čistý, formátovaný JavaScript v source/src a game/src, bez minifikovaných alebo zbalených súborov našich vlastných.

Môžem pridať vlastné jamky alebo ihriská?

Áno. Duplikujte jamku v súbore ihriska, dajte jej jedinečné id, nastavte par, odpal a jamku, pridajte ju do courses.js a pridajte jej názov a tip do jazykových súborov.

Načítava Three.js z CDN?

Nie. Three.js, Rapier, fonty a hudba sú všetko v game/, takže hra potrebuje len váš hosting.

Prečo mi hosting ukazuje prázdnu obrazovku?

Zvyčajne kvôli typom MIME. Podávajte .js ako JavaScript a .wasm ako application/wasm, otvorte hru cez HTTP(S) a skontrolujte, či je WebGL2 zapnuté.

Môžu hrať kamaráti spolu?

Áno, dvaja až štyria hráči sa striedajú na tom istom zariadení. Online hra nie je súčasťou tohto vydania.

Je to správny základ minigolfu pre vás?

Puttide sa hodí na rodinný alebo športový portál, agentúru, ktorá buduje značkové ihrisko pre jedného klienta, a vývojára, ktorý chce vidieť, ako Three.js a Rapier spolu fungujú v čitateľnom kóde. Je menej vhodný pre projekt, ktorý od prvého dňa potrebuje online kolá alebo spoločný rebríček.

Odohrajte celé ihrisko v demo na telefóne a potom si prečítajte časť návodu o pridávaní jamky. Ak vám tá časť pripadá ako popoludnie práce, zvyšok hry je už postavený.

Vyskúšajte demo Puttide a kúpte licenciu