迷你高尔夫游戏源码：球洞、物理与3D球场

一套迷你高尔夫游戏源码好不好用，关键看一件事：能不能方便地新增球洞。想做品牌球场、节日关卡，或者把客户 Logo 印在果岭上的买家，第一件事就是打开关卡文件；如果球洞埋在引擎代码里，项目就会卡住。我们的 3D 迷你高尔夫模板 Puttide 里，每个球场都有自己的球洞文件，用纯 JavaScript 编写，手册里也一步步讲了怎么新增球洞。

这篇指南按开发者拿到包后的顺序来讲：文件夹、依赖库、球场文件、修改顺序、部署和授权。文中的文件名都出自随游戏附带的买家指南。

先给赶时间的人一个简短答案：Puttide 是排版清晰的 JavaScript，用 Three.js 渲染画面，用 Rapier 计算球的物理，两者都已打包在内。不需要构建步骤，不依赖 CDN，也没有服务器端代码。

这套迷你高尔夫游戏源码包含什么

Puttide 是一款完整的游戏，共 30 个球洞，分布在五座岛屿球场：Sunlit Ruins、Lantern Pier、Frost Peaks、Cloud Garden 和 Volcano Forge，每座六洞。坡道、传送门、弹板和风车让每个球洞都像一道小谜题。每洞可拿三颗星（完成、平标准杆或更好、找到隐藏金币），最好的成绩还能换来铜牌、银牌和金牌。

除了球场，还有带变化的每日挑战（大风、结冰果岭、重球、弹力墙、金币冲刺或抓小鸟），可以用金币购买球、拖尾等装扮的 Locker（储物柜），以及 2 到 4 名玩家在同一台设备上轮流击球的模式。界面支持 14 种语言。

• game/：可直接上传的构建版本，也是唯一需要发布的文件夹。
• source/：同一款游戏的开发者版本，附 README 和 package.json。
• documentation/：一份图文指南，提供英文和葡萄牙文版本。
• THIRD-PARTY-LICENSES/：依赖库和字体的授权文本。
• 版本 1.1.0，更新于 2026 年 10 月 22 日。

打开 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. 选好新球洞所属的球场文件，例如 Volcano Forge 对应 lava.js。
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 中修改 Logo、颜色和字体。允许白标，你的品牌可以替换我们的。
2. Locker 里的价格：economy.js。装扮便宜一些，休闲网站会更友好；贵一些，则能撑起较长的活动周期。
3. 文本：在 i18n 文件中修改文案和提示。
4. 音乐：附带的两首曲目可以换成你拥有授权的录音。复制文件，并更新 audio.js 里的显式映射（probeTracks）；场景音乐会回退到游戏内曲目。
5. 物理：最后再改 constants.js，而且要小步调整，因为每个球洞都是按当前数值调好的。

如果你想看一个同样采用纯 JavaScript、完全不用 3D 库的相关项目，我们的台球模板也是这样构建的。

Velvet Pool：纯 JavaScript 和 WebGL2 编写的 8 球台球

Sunset Rally：带九场比赛战役的 3D 乒乓球

部署、MIME 类型与 App 封装

把 game/ 里的所有内容上传到一个文件夹，例如 public_html/puttide/，保留子文件夹结构，再通过 HTTPS 打开地址。服务器上不需要 npm、PHP、数据库或账号。直接从本地磁盘打开 index.html 是不行的，因为浏览器会在 file:// 下拦截模块。

Puttide 有一个 2D 游戏没有的部署细节：物理引擎以 WebAssembly 运行。服务器必须以 JavaScript MIME 类型发送 .js 文件，并以 application/wasm 发送 .wasm 文件。配置不对的主机会显示白屏或模块错误，所以第一天就要检查。

• 浏览器要求：JavaScript、ES 模块、WebAssembly 和 WebGL2。
• 嵌入游戏平台的 iframe 时，需允许 fullscreen 和 autoplay。
• 触屏操作：拖动瞄准并推杆，双指旋转镜头，捏合缩放。
• 不是可安装的离线应用：每次重新加载仍会访问你的服务器。

包里不含原生 App 工程。如果计划上架应用商店，要为封装和真机测试预留预算，因为在旧设备上，3D 物理游戏比纸牌游戏更吃性能。

不包含的内容与授权

这是本地浏览器版本：没有在线多人或在线房间，没有在线排行榜，没有云端账号，没有广告 SDK，没有原生 App，也不含托管服务。球场纪录、每日进度和同设备对局都保存在玩家的浏览器里，不会上传任何分数。存档归属于浏览器的源（origin），所以换到另一个域名后，玩家要从头开始。

Puttide 标价 39 美元；在 2026 年 11 月 30 日之前，黑色星期五促销价为 33.15 美元，一次订单购买两个及以上模板还可再享 5% 到 20% 的组合折扣。授权为永久、非独占，可用于一个最终产品，你自己的或某一位客户的。你可以更换品牌，修改代码、美术和音频，让玩家免费游玩或通过广告变现，但不能单独转售模板或其代码。技术支持为期六个月，购买延长服务则为十二个月；定制球洞、功能集成和托管需另行报价。

查看完整的授权、支持和退款条款

常见问题

这套迷你高尔夫源码是用 TypeScript 写的吗？

不是。Puttide 是 source/src 和 game/src 中排版清晰的纯 JavaScript，我们自己的代码没有压缩或打包过的文件。

我能加入自己的球洞或球场吗？

可以。在球场文件里复制一个球洞，给它唯一的 id，设置标准杆、发球点和球洞位置，加入 courses.js，再把名称和提示写进语言文件。

Three.js 是从 CDN 加载的吗？

不是。Three.js、Rapier、字体和音乐都在 game/ 里，游戏只需要你自己的服务器。

为什么我的服务器显示白屏？

通常是 MIME 类型的问题。请把 .js 以 JavaScript、.wasm 以 application/wasm 发送，通过 HTTP(S) 打开游戏，并确认 WebGL2 已启用。

朋友之间能一起玩吗？

可以，2 到 4 名玩家在同一台设备上轮流击球。此版本不包含在线对战。

它是适合你的迷你高尔夫底座吗？

Puttide 适合家庭类或体育类游戏平台、为单个客户制作品牌球场的代理公司，以及想通过可读代码了解 Three.js 与 Rapier 如何配合的开发者。如果项目从第一天起就需要在线对局或共享排行榜，它就不太合适。

先在手机上用试玩版打完一整座球场，再读手册里讲新增球洞的那一节。如果你觉得那一节只需要一个下午，那游戏的其余部分已经做好了。

试玩 Puttide 并购买授权