Сорс код за миниголф игра: дупки, физика и 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: 8-топков билярд на обикновен 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.
• В iframe на портал разрешете цял екран и автоматично пускане.
• На сензорни екрани: влачене за прицелване и удар, два пръста за завъртане на камерата, събиране за мащабиране.
• Не е инсталируемо офлайн приложение: всяко ново зареждане все пак стига до вашия хостинг.

Проектите за нативни приложения не са в пакета. Ако планирате публикуване в магазин, заделете време за обвивката и тестването ѝ на реални телефони, защото 3D игра с физика е по-тежка от игра с карти на по-стари устройства.

Какво не е включено и лицензът

Това е локалното браузърно издание: без онлайн мултиплейър или онлайн стаи, без онлайн класация, без облачни акаунти, без рекламно SDK, без нативни приложения и без хостинг. Рекордите на теренете, дневният прогрес и рундовете на едно устройство остават в браузъра на играча, а никакъв резултат не се качва. Запазванията принадлежат на браузърния origin, така че преместването на друг домейн започва играчите отначало.

Puttide е на 39 USD; до 30 ноември 2026 г. промоцията Black Friday я прави 33,15 USD, а покупката на два или повече шаблона в една поръчка добавя отстъпка за пакет от 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 и купете лиценз