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

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

Это руководство идёт по пакету так, как его видит разработчик: папки, библиотеки, файлы полей, порядок изменений, хостинг и лицензия. Названия файлов взяты из руководства покупателя, которое идёт вместе с игрой.

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

Что входит в исходный код мини-гольфа

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

Поверх полей есть ежедневное задание с поворотом (ветер, ледяной грин, тяжёлый мяч, пружинящие стены, монетный рывок или охота на бёрди), 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: бильярд-восьмёрка на простом JavaScript и WebGL2

Sunset Rally: 3D-настольный теннис с кампанией из девяти матчей

Хостинг, MIME-типы и обёртки для приложений

Загрузите всё из game/ в папку, например public_html/puttide/, сохраните подпапки и откройте адрес по HTTPS. Для сервера не нужны npm, PHP, база данных или аккаунт. Открытие index.html с диска не работает, потому что браузеры блокируют модули на file://.

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

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

Проекты нативных приложений не входят в пакет. Если вы планируете релиз в магазине, заложите обёртку и её тестирование на реальных телефонах, потому что 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 и купите лицензию