Вихідний код міні-гольфу: лунки, фізика і 3D-карта поля

Вихідний код міні-гольфу тримається на одному завданні: додати лунку. Покупець, який хоче фірмове поле, сезонний рівень або логотип клієнта на зеленому, спершу відкриє файли рівнів, і якщо лунка захована в коді рушія, проєкт зупиняється. У Puttide, нашому 3D-шаблоні міні-гольфу, кожне поле має власний файл лунок на простому JavaScript, а мануал покроково пояснює, як додати одну.

Цей посібник іде за пакетом так, як його бачить розробник: папки, бібліотеки, файли полів, порядок змін, хостинг і ліцензія. Назви файлів узяті з посібника покупця, що йде з грою.

Коротка відповідь для нетерплячих: Puttide — це відформатований JavaScript з Three.js для малювання і Rapier для фізики м’яча, обидва вбудовані. Без кроку збірки, без CDN і без серверного коду.

Що входить у вихідний код міні-гольфу

Puttide — закінчена гра з 30 лунками на п’яти острівних полях: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden і Volcano Forge, по шість лунок у кожному. Пандуси, портали, бампери і вітряки перетворюють лунки на маленькі головоломки. Кожна лунка нагороджує трьома зірками (фініш, пар або краще і прихована монета), а бронзові, срібні та золоті медалі винагороджують найкращі раунди.

Окрім полів, є щоденне завдання з особливістю (вітряно, крижаний зелений, важкий м’яч, пружні стінки, Coin rush чи Birdie hunt), Locker (шафка), де монети купують м’ячі, сліди та інші косметичні речі, і раунди для двох-чотирьох гравців по черзі на одному пристрої. Інтерфейс доступний 14 мовами.

• game/: готова до завантаження збірка, єдина папка, яку ви публікуєте.
• source/: та сама гра як версія для розробника, з README і package.json.
• documentation/: один ілюстрований посібник англійською та португальською.
• THIRD-PARTY-LICENSES/: тексти ліцензій для бібліотек і шрифтів.
• Версія 1.1.0, оновлена 22 жовтня 2026 року.

Відкрити сторінку Puttide: демо, мануал і ціна

Three.js, Rapier і решта стеку

М’яч симулює Rapier 3D 0.21.0, який працює як WebAssembly, а сцену малює Three.js r186. Обидві лежать у lib/three/ і lib/rapier/ зі своїми файлами ліцензій, а index.html має import map, яка вказує грі на них. Мануал зазначає, що файли бібліотек не змінені за поведінкою, а лише відформатовані, щоб їх можна було читати.

Це важливо з двох причин. По-перше, нічого не завантажується з CDN, тож порталу чи клієнту з жорсткою політикою безпеки потрібен лише ваш хостинг. По-друге, оновлення бібліотеки — це ручний і свідомий крок: source/package.json перелічує точні версії, ви копіюєте нові модульні файли поверх відповідної папки lib/ і зберігаєте шляхи import map.

• Three.js r186: ліцензія MIT.
• Rapier 3D compat 0.21.0, WebAssembly вбудовано: ліцензія Apache-2.0.
• Веб-шрифти Rubik і Fredoka: SIL Open Font License 1.1.
• Два музичні треки: music/menu.mp3 і music/play-1.mp3.

Де лежать лунки, монети і тексти

Шляхи однакові в source/ і game/. Дані полів розділені за островами, що тримає кожен файл достатньо коротким, аби прочитати за один раз.

• src/course/courses.js: порядок полів і вимоги розблокування.
• src/course/holes.js: лунки Sunlit Ruins з геометрією, паром і перешкодами.
• src/course/pier.js, ice.js, lava.js і sky.js: лунки інших чотирьох полів.
• src/sim/constants.js: налаштування фізики.
• src/game/economy.js: м’ячі, сліди та вбрання з їхніми цінами.
• src/ui/i18n.js і супровідні файли: словники 14 мов, зокрема назви лунок і поради.
• src/game/localRecords.js: рекорди полів, які зберігаються в браузері.
• src/audio/audio.js: ефекти і відповідність музики, у probeTracks.
• css/style.css: кольори інтерфейсу, шрифти і адаптивні стилі.

Додавання лунки крок за кроком

Це найпоширеніша зміна, яку роблять покупці, і мануал описує її кількома рядками. Ми розгорнули його в порядок, якого дотрималися б самі.

1. Оберіть файл поля, якому належить нова лунка, наприклад lava.js для Volcano Forge.
2. Продублюйте наявне визначення лунки, яке виглядає близько до того, що ви хочете.
3. Дайте їй унікальний id. Повторний id плутає збережений прогрес.
4. Задайте пар, позицію старту і позицію лунки, потім перемістіть або замініть перешкоди.
5. Додайте лунку до її поля в courses.js.
6. Додайте її назву і пораду до словників мов, у кожній мові, яку поставляєте.
7. Зіграйте її: перевірте зіткнення, відновлення після виходу за межі і всі три зірки, включно з прихованою монетою.

Редагуйте в source/, копіюйте змінені файли в ті самі шляхи в game/ і віддавайте папку по HTTP для тесту. У package.json є скрипт serve, або можна запустити python -m http.server 8765. Node.js необов’язковий і потрібен лише тоді, коли ви хочете, щоб npm керував версіями бібліотек.

Інші зміни, у розумному порядку

1. Бренд і кольори: логотип, кольори і шрифти в css/style.css. White label дозволений, тож ваш бренд може замінити наш.
2. Ціни в Locker: economy.js. Дешевша косметика робить казуальний сайт привітнішим; дорожча розтягує довгу кампанію.
3. Тексти: формулювання і поради в файлах i18n.
4. Музика: два включені треки можна замінити записами, на які у вас є ліцензія. Скопіюйте файл і оновіть явну відповідність в audio.js (probeTracks); музика сцен переходить на трек гри, якщо нічого не задано.
5. Фізика: constants.js наостанок і малими кроками, бо кожна лунка була налаштована під поточні значення.

Для споріднених проєктів з таким самим підходом на простому JavaScript і без 3D-бібліотеки наш шаблон більярду побудовано так само.

Velvet Pool: більярд 8-ball на простому JavaScript і WebGL2

Sunset Rally: 3D настільний теніс з кампанією з дев’яти матчів

Хостинг, MIME-типи і обгортки застосунків

Завантажте все всередині game/ в папку на кшталт public_html/puttide/, збережіть підпапки і відкривайте адресу через HTTPS. На сервері не потрібні npm, PHP, база даних чи акаунт. Відкривання index.html з диска не працює, бо браузери блокують модулі на file://.

У Puttide є одна деталь хостингу, якої немає в 2D-грі: фізика працює як WebAssembly. Ваш сервер має віддавати файли .js з MIME-типом JavaScript, а .wasm — як application/wasm. Хостинг, який це зробить неправильно, показує порожній екран або помилку модуля, тож перевірте це першого ж дня.

• Браузеру потрібні: JavaScript, ES-модулі, WebAssembly і WebGL2.
• У вбудуванні в iframe порталу дозвольте повноекранний режим і автовідтворення.
• На сенсорних екранах: тягніть, щоб прицілитися і вдарити, двома пальцями — щоб повернути камеру, щипком — щоб наблизити.
• Це не застосунок для офлайн-встановлення: кожне нове завантаження все одно звертається до вашого хостингу.

Проєктів нативних застосунків у пакеті немає. Якщо плануєте випуск у магазині, закладіть обгортку і тестування на реальних телефонах, бо 3D-гра з фізикою важча за карткову на старих пристроях.

Чого немає і ліцензія

Це локальна браузерна версія: без онлайн-мультиплеєра чи онлайн-кімнат, без онлайн-рейтингу, без хмарних акаунтів, без рекламного SDK, без нативних застосунків і без хостингу. Рекорди полів, щоденний прогрес і раунди на одному пристрої лишаються в браузері гравця, і жоден результат не вивантажується. Збереження належать джерелу в браузері, тож перехід на інший домен починає гравців з нуля.

Puttide коштує $39; до 30 листопада 2026 року акція «Чорна п’ятниця» знижує ціну до $33,15, а купівля двох і більше шаблонів в одному замовленні додає знижку за пакет від 5% до 20%. Ліцензія безстрокова і невиключна для одного кінцевого продукту — вашого або одного клієнта. Ви можете ребрендувати її, змінювати код, графіку й аудіо, і пускати гравців безкоштовно або з рекламою, але не можна перепродавати шаблон чи його код окремо. Підтримка триває шість місяців або дванадцять з продовженням; індивідуальні лунки, інтеграції та хостинг розраховуються на запит.

Повні умови ліцензії, підтримки і повернення

Поширені запитання

Чи вихідний код міні-гольфу на TypeScript?

Ні. Puttide — це простий відформатований JavaScript у source/src і game/src, без мінімізованих або збундлених файлів нашого авторства.

Чи можна додати власні лунки чи поля?

Так. Продублюйте лунку у файлі поля, дайте їй унікальний id, задайте пар, старт і лунку, додайте її в courses.js і додайте її назву та пораду до мовних файлів.

Чи завантажує вона Three.js з CDN?

Ні. Three.js, Rapier, шрифти і музика всі лежать у game/, тож грі потрібен лише ваш хостинг.

Чому мій хостинг показує порожній екран?

Зазвичай через MIME-типи. Віддавайте .js як JavaScript, а .wasm як application/wasm, відкривайте гру через HTTP(S) і перевірте, що WebGL2 увімкнено.

Чи можуть друзі грати разом?

Так, двоє-четверо гравців ходять по черзі на одному пристрої. Онлайн-гра не входить до цієї версії.

Чи це правильна основа для міні-гольфу саме вам?

Puttide пасує сімейному чи спортивному порталу, агенції, яка будує фірмове поле для одного клієнта, і розробнику, який хоче побачити, як Three.js і Rapier працюють разом у читабельному коді. Гірше пасує проєкту, якому від першого дня потрібні онлайн-раунди або спільна таблиця лідерів.

Пройдіть повне поле в демо на телефоні, потім прочитайте розділ мануала про додавання лунки. Якщо цей розділ здається вам півднем роботи, решта гри вже побудована.

Пограйте демо Puttide і купіть ліцензію