Kod źródłowy gry mini golf: dołki, fizyka i mapa kursu 3D

Kod źródłowy gry mini golf zależy od jednego zadania: dodania dołka. Kupujący, który chce markowego pola, sezonowego poziomu albo logo klienta na zielonym, najpierw otworzy pliki poziomów, a jeśli dołek jest zakopany w kodzie silnika, projekt stanie. W Puttide, naszym szablonie mini golfa 3D, każdy kurs ma własny plik dołków w czystym JavaScript, a instrukcja opisuje, jak dodać jeden.

Ten przewodnik idzie za pakietem tak, jak spotyka go programista: foldery, biblioteki, pliki kursów, kolejność zmian, hosting i licencja. Nazwy plików pochodzą z przewodnika dla kupującego, który dołączony jest do gry.

Krótka odpowiedź dla niecierpliwych: Puttide to sformatowany JavaScript z Three.js do rysowania i Rapier do fizyki piłki, obie biblioteki są w pakiecie. Nie ma kroku kompilacji, CDN ani kodu serwerowego.

Co zawiera kod źródłowy gry mini golf

Puttide to gotowa gra z 30 dołkami na pięciu wyspowych kursach: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden i Volcano Forge, po sześć dołków na kurs. Rampy, portale, odbijacze i wiatraki zamieniają dołki w małe łamigłówki. Każdy dołek przyznaje trzy gwiazdki (ukończenie, par lub lepiej, ukryta moneta), a brązowe, srebrne i złote medale nagradzają najlepsze rundy.

Oprócz kursów jest wyzwanie dnia z zwrotem (windy, icy green, heavy ball, bouncy walls, coin rush albo birdie hunt, czyli nazwy wyzwań w grze: wiatr, lodowy green, ciężka piłka, odbijające ściany, pogoń za monetami i łowy na birdie), Locker (Szafka), w którym monety kupują piłki, ślady i inne kosmetyki, oraz rundy dla dwóch do czterech graczy na zmianę na jednym urządzeniu. Interfejs jest w 14 językach.

• game/: gotowa do wgrania wersja, jedyny folder, który publikujesz.
• source/: ta sama gra jako edycja dla programistów, z README i package.json.
• documentation/: jeden ilustrowany przewodnik po angielsku i portugalsku.
• THIRD-PARTY-LICENSES/: teksty licencji bibliotek i czcionek.
• Wersja 1.1.0, zaktualizowana 22 października 2026 roku.

Otwórz stronę Puttide: demo, instrukcja i cena

Three.js, Rapier i reszta stosu

Piłkę symuluje Rapier 3D 0.21.0, działający jako WebAssembly, a scenę rysuje Three.js r186. Obie biblioteki leżą w lib/three/ i lib/rapier/ z plikami licencji, a index.html ma import map, który wskazuje na nie grę. Instrukcja zaznacza, że pliki bibliotek nie zmieniły zachowania i zostały tylko sformatowane, żeby dało się je czytać.

Ma to dwa powody. Po pierwsze nic nie ładuje się z CDN, więc portal albo klient z surową polityką bezpieczeństwa potrzebuje tylko Twojego hostingu. Po drugie aktualizacja biblioteki to ręczny, świadomy krok: source/package.json podaje dokładne wersje, a nowe pliki modułów kopiujesz nad odpowiedni folder lib/ i zachowujesz ścieżki w import map.

• Three.js r186: licencja MIT.
• Rapier 3D compat 0.21.0, WebAssembly osadzony: licencja Apache-2.0.
• Czcionki Rubik i Fredoka: SIL Open Font License 1.1.
• Dwa utwory muzyczne: music/menu.mp3 i music/play-1.mp3.

Gdzie leżą dołki, monety i teksty

Ścieżki są takie same w source/ i game/. Dane kursów są podzielone według wyspy, co utrzymuje każdy plik na tyle krótkim, że można go przeczytać za jednym posiedzeniem.

• src/course/courses.js: kolejność kursów i wymagania odblokowania.
• src/course/holes.js: dołki Sunlit Ruins, z geometrią, parem i przeszkodami.
• src/course/pier.js, ice.js, lava.js i sky.js: dołki pozostałych czterech kursów.
• src/sim/constants.js: strojenie fizyki.
• src/game/economy.js: piłki, ślady i stroje wraz z cenami.
• src/ui/i18n.js i powiązane pliki: słowniki 14 języków, w tym nazwy dołków i podpowiedzi.
• src/game/localRecords.js: rekordy kursów trzymane w przeglądarce.
• src/audio/audio.js: efekty i mapowanie muzyki w probeTracks.
• css/style.css: kolory interfejsu, czcionki i style responsywne.

Dodawanie dołka krok po kroku

To zmiana, którą robi większość kupujących, a instrukcja opisuje ją w kilku linijkach. Rozpisaliśmy ją w kolejności, którą sami byśmy przeszli.

1. Wybierz plik kursu, do którego należy nowy dołek, na przykład lava.js dla Volcano Forge.
2. Zduplikuj istniejącą definicję dołka, która wygląda podobnie do tego, czego chcesz.
3. Nadaj mu unikalne id. Ponowne użycie id miesza zapisany postęp.
4. Ustaw par, pozycję startu i pozycję dołka, a potem przesuń albo zastąp przeszkody.
5. Dodaj dołek do jego kursu w courses.js.
6. Dodaj jego nazwę wyświetlaną i podpowiedź do słowników językowych, we wszystkich językach, które wysyłasz.
7. Zagraj: sprawdź kolizje, odzyskiwanie po wyjściu poza boisko i wszystkie trzy gwiazdki, w tym ukrytą monetę.

Edytujesz w source/, kopiujesz zmienione pliki do tych samych ścieżek w game/ i serwujesz folder przez HTTP do testów. package.json ma skrypt serve, albo możesz uruchomić python -m http.server 8765. Node.js jest opcjonalny i potrzebny tylko wtedy, gdy chcesz, żeby npm zarządzał wersjami bibliotek.

Pozostałe zmiany, w rozsądnej kolejności

1. Marka i kolory: logo, kolory i czcionki w css/style.css. White label jest dozwolony, więc Twoja marka może zastąpić naszą.
2. Ceny w Locker: economy.js. Tańsze kosmetyki sprawiają, że casualowa strona jest przyjazna; droższe przedłużają długą kampanię.
3. Teksty: sformułowania i podpowiedzi w plikach i18n.
4. Muzyka: dwa dołączone utwory można zastąpić nagraniami, do których masz licencję. Skopiuj plik i zaktualizuj jawne mapowanie w audio.js (probeTracks); muzyka sceny wraca do utworu z rozgrywki.
5. Fizyka: constants.js na końcu i małymi krokami, bo każdy dołek został dostrojony do obecnych wartości.

Dla powiązanego projektu o tym samym podejściu, czystym JavaScript i bez żadnej biblioteki 3D, nasz szablon bilardu jest zbudowany tak samo.

Velvet Pool: bilard 8-bilowy w czystym JavaScript i WebGL2

Sunset Rally: tenis stołowy 3D z kampanią dziewięciu meczów

Hosting, typy MIME i opakowania w aplikację

Wgraj wszystko z game/ do folderu, na przykład public_html/puttide/, zachowaj podfoldery i otwórz adres przez HTTPS. Na serwerze nie potrzeba npm, PHP, bazy danych ani konta. Otwieranie index.html z dysku nie działa, bo przeglądarki blokują moduły na file://.

Puttide ma jeden szczegół hostingu, którego nie ma gra 2D: fizyka działa jako WebAssembly. Serwer musi wysyłać pliki .js z typem MIME JavaScript, a .wasm jako application/wasm. Host, który to robi źle, pokazuje pusty ekran albo błąd modułu, więc sprawdź to pierwszego dnia.

• Przeglądarka potrzebuje: JavaScript, modułów ES, WebAssembly i WebGL2.
• W ramce (iframe) portalu zezwól na pełny ekran i autoodtwarzanie.
• Na ekranach dotykowych: przeciągnij, żeby celować i uderzać, dwoma palcami obracaj kamerę, szczypnij, żeby przybliżyć.
• To nie jest zainstalowalna aplikacja offline: każde świeże wczytanie nadal sięga do Twojego hostingu.

Projektów aplikacji natywnych nie ma w pakiecie. Jeśli planujesz wydanie w sklepie, zaplanuj opakowanie i testy na prawdziwych telefonach, bo gra z fizyką 3D jest cięższa niż gra karciana na starszych urządzeniach.

Czego nie ma w pakiecie i licencja

To lokalna edycja przeglądarkowa: bez gry online dla wielu graczy i pokojów online, bez rankingu online, bez kont w chmurze, bez SDK reklamowego, bez aplikacji natywnych i bez hostingu. Rekordy kursów, dzienny postęp i rundy na jednym urządzeniu zostają w przeglądarce gracza, a żaden wynik nie jest wysyłany. Zapisy należą do originu przeglądarki, więc przeniesienie na inną domenę zaczyna graczy od zera.

Puttide kosztuje 39 USD; do 30 listopada 2026 roku promocja Black Friday obniża cenę do 33,15 USD, a kupując dwa lub więcej szablonów w jednym zamówieniu, dostajesz rabat pakietowy od 5% do 20%. Licencja jest bezterminowa i niewyłączna na jeden produkt końcowy, Twój albo jednego klienta. Możesz zmienić markę, kod, grafikę i dźwięk, a graczy wpuścić za darmo lub z reklamami, ale nie możesz odsprzedać samego szablonu ani jego kodu. Wsparcie trwa sześć miesięcy albo dwanaście z przedłużeniem; własne dołki, integracje i hosting wyceniamy na zapytanie.

Pełne warunki licencji, wsparcia i zwrotów

Najczęściej zadawane pytania

Czy kod źródłowy mini golfa jest w TypeScript?

Nie. Puttide to sformatowany, czysty JavaScript w source/src i game/src, bez zminifikowanych ani spakowanych plików naszego autorstwa.

Czy mogę dodać własne dołki albo kursy?

Tak. Zduplikuj dołek w pliku kursu, nadaj mu unikalne id, ustaw par, start i dołek, dodaj go do courses.js i dopisz jego nazwę oraz podpowiedź do plików językowych.

Czy gra ładuje Three.js z CDN?

Nie. Three.js, Rapier, czcionki i muzyka są w game/, więc gra potrzebuje tylko Twojego hostingu.

Dlaczego mój hosting pokazuje pusty ekran?

Zwykle chodzi o typy MIME. Serwuj .js jako JavaScript, a .wasm jako application/wasm, otwórz grę przez HTTP(S) i sprawdź, czy WebGL2 jest włączony.

Czy znajomi mogą grać razem?

Tak, dwie do czterech osób grają na zmianę na tym samym urządzeniu. Gra online nie wchodzi w skład tej edycji.

Czy to właściwa baza do mini golfa?

Puttide pasuje do portalu rodzinnego lub sportowego, do agencji budującej markowy kurs dla jednego klienta i do programisty, który chce zobaczyć, jak Three.js i Rapier współpracują w czytelnym kodzie. Słabiej pasuje do projektu, który od pierwszego dnia potrzebuje rund online albo wspólnego rankingu.

Zagraj w pełny kurs w demo na telefonie, a potem przeczytaj w instrukcji sekcję o dodawaniu dołka. Jeśli ta sekcja wygląda na Ciebie jak popołudnie pracy, reszta gry jest już zbudowana.

Zagraj w demo Puttide i kup licencję