Source code game mini golf: lỗ golf, vật lý và bản đồ sân 3D
Gói Puttide lưu 30 lỗ golf ở đâu, Three.js và Rapier nằm chỗ nào, và người mua tự thêm một lỗ mới ra sao.
Một bộ source code game mini golf tốt hay không phụ thuộc vào một việc: thêm lỗ golf mới. Người mua muốn làm sân mang thương hiệu, màn chơi theo mùa hay đặt logo khách hàng lên thảm cỏ sẽ mở file màn chơi trước tiên; nếu lỗ golf bị chôn trong code engine, dự án sẽ đứng lại. Trong Puttide, mẫu game mini golf 3D của chúng tôi, mỗi sân có file lỗ golf riêng bằng JavaScript thuần, và tài liệu hướng dẫn từng bước cách thêm một lỗ.
Bài viết này đi qua gói mã nguồn theo đúng thứ tự một lập trình viên sẽ gặp: thư mục, thư viện, file sân, thứ tự chỉnh sửa, cách host và giấy phép. Tên file lấy từ tài liệu dành cho người mua đi kèm game.
Trả lời nhanh cho người vội: Puttide là JavaScript đã được định dạng dễ đọc, dùng Three.js để vẽ và Rapier cho vật lý quả bóng, cả hai đều có sẵn trong gói. Không cần bước build, không CDN và không có code phía server.
Source code game mini golf gồm những gì
Puttide là một game hoàn chỉnh với 30 lỗ trên năm sân đảo: Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden và Volcano Forge, mỗi sân sáu lỗ. Dốc, cổng dịch chuyển, vật cản nảy và cối xay gió biến mỗi lỗ thành một câu đố nhỏ. Mỗi lỗ cho ba sao (hoàn thành, đạt par hoặc tốt hơn, đồng xu ẩn), còn huy chương đồng, bạc và vàng thưởng cho những lượt chơi tốt nhất.
Ngoài các sân còn có thử thách hằng ngày với một biến tấu (gió, thảm cỏ đóng băng, bóng nặng, tường nảy, săn xu hoặc săn birdie), một Locker nơi dùng xu mua bóng, vệt bóng và vật phẩm trang trí khác, cùng chế độ hai đến bốn người chơi lần lượt trên một thiết bị. Giao diện có 14 ngôn ngữ.
- game/: bản build sẵn sàng tải lên, thư mục duy nhất bạn cần đưa lên host.
- source/: cùng game đó ở dạng bản dành cho lập trình viên, có README và package.json.
- documentation/: một tài liệu minh họa bằng tiếng Anh và tiếng Bồ Đào Nha.
- THIRD-PARTY-LICENSES/: văn bản giấy phép của thư viện và phông chữ.
- Phiên bản 1.1.0, cập nhật ngày 22/10/2026.
Mở trang Puttide: demo, tài liệu và giá
Three.js, Rapier và phần còn lại của bộ công nghệ
Quả bóng được mô phỏng bằng Rapier 3D 0.21.0, chạy dưới dạng WebAssembly, còn cảnh được vẽ bằng Three.js r186. Cả hai nằm trong lib/three/ và lib/rapier/ cùng file giấy phép, và index.html có import map trỏ game đến đó. Tài liệu ghi rõ các file thư viện không thay đổi hành vi, chỉ được định dạng lại để dễ đọc.
Điều này quan trọng vì hai lý do. Thứ nhất, không có gì tải từ CDN, nên một cổng game hay khách hàng có chính sách bảo mật chặt chỉ cần host của bạn. Thứ hai, nâng cấp thư viện là bước làm thủ công và có chủ đích: source/package.json ghi đúng phiên bản, bạn chép file module mới đè lên thư mục lib/ tương ứng và giữ nguyên đường dẫn trong import map.
- Three.js r186: giấy phép MIT.
- Rapier 3D compat 0.21.0, WebAssembly nhúng sẵn: giấy phép Apache-2.0.
- Phông chữ web Rubik và Fredoka: SIL Open Font License 1.1.
- Hai bản nhạc: music/menu.mp3 và music/play-1.mp3.
Lỗ golf, đồng xu và văn bản nằm ở đâu
Đường dẫn trong source/ và game/ giống nhau. Dữ liệu sân được chia theo đảo, nên mỗi file đủ ngắn để đọc hết trong một lần.
- src/course/courses.js: thứ tự sân và điều kiện mở khóa.
- src/course/holes.js: các lỗ của Sunlit Ruins, gồm hình học, par và chướng ngại vật.
- src/course/pier.js, ice.js, lava.js và sky.js: các lỗ của bốn sân còn lại.
- src/sim/constants.js: tinh chỉnh vật lý.
- src/game/economy.js: bóng, vệt bóng và trang phục cùng giá của chúng.
- src/ui/i18n.js và các file đi kèm: từ điển của 14 ngôn ngữ, gồm cả tên lỗ và mẹo.
- src/game/localRecords.js: kỷ lục sân lưu trong trình duyệt.
- src/audio/audio.js: hiệu ứng âm thanh và ánh xạ nhạc trong probeTracks.
- css/style.css: màu giao diện, phông chữ và style responsive.
Thêm một lỗ golf, từng bước
Đây là thay đổi mà hầu hết người mua thực hiện, và tài liệu mô tả nó trong vài dòng. Chúng tôi viết rõ hơn theo đúng thứ tự mà chính mình sẽ làm.
- Chọn file sân mà lỗ mới thuộc về, ví dụ lava.js cho Volcano Forge.
- Nhân bản một định nghĩa lỗ có sẵn gần giống với ý bạn nhất.
- Đặt cho nó một id duy nhất. Dùng lại id cũ sẽ làm rối tiến trình đã lưu.
- Đặt par, vị trí phát bóng (tee) và vị trí lỗ (cup), rồi di chuyển hoặc thay chướng ngại vật.
- Thêm lỗ vào sân của nó trong courses.js.
- Thêm tên hiển thị và mẹo vào từ điển của mọi ngôn ngữ bạn phát hành.
- Chơi thử: kiểm tra va chạm, việc đưa bóng về khi ra ngoài sân và cả ba sao, kể cả đồng xu ẩn.
Sửa trong source/, chép các file đã đổi sang cùng đường dẫn trong game/, rồi chạy thư mục qua HTTP để thử. package.json có script serve, hoặc bạn có thể chạy python -m http.server 8765. Node.js là tùy chọn, chỉ cần khi bạn muốn dùng npm quản lý phiên bản thư viện.
Các thay đổi khác, theo thứ tự hợp lý
- Thương hiệu và màu sắc: logo, màu và phông chữ trong css/style.css. Được phép white label, thương hiệu của bạn có thể thay thế của chúng tôi.
- Giá trong Locker: economy.js. Vật phẩm rẻ hơn làm một trang game giải trí thân thiện hơn; vật phẩm đắt hơn kéo dài một chiến dịch dài.
- Văn bản: câu chữ và mẹo trong các file i18n.
- Nhạc: hai bản nhạc đi kèm có thể thay bằng bản thu mà bạn có giấy phép. Chép file và cập nhật ánh xạ khai báo trong audio.js (probeTracks); nhạc của cảnh sẽ dùng bản nhạc gameplay nếu không có bản riêng.
- Vật lý: constants.js, để cuối cùng và chỉnh từng chút, vì mọi lỗ đều được cân chỉnh theo giá trị hiện tại.
Nếu bạn cần một dự án tương tự cũng viết bằng JavaScript thuần nhưng hoàn toàn không dùng thư viện 3D, mẫu game bi-a của chúng tôi được xây dựng theo cùng cách.
Velvet Pool: bi-a 8 bóng bằng JavaScript thuần và WebGL2
Sunset Rally: bóng bàn 3D với chiến dịch chín trận
Host, kiểu MIME và đóng gói thành ứng dụng
Tải toàn bộ nội dung trong game/ lên một thư mục như public_html/puttide/, giữ nguyên các thư mục con và mở địa chỉ qua HTTPS. Server không cần npm, PHP, cơ sở dữ liệu hay tài khoản. Mở index.html trực tiếp từ ổ đĩa sẽ không chạy, vì trình duyệt chặn module trên file://.
Puttide có một chi tiết khi host mà game 2D không có: phần vật lý chạy bằng WebAssembly. Server của bạn phải trả file .js với kiểu MIME JavaScript và .wasm với application/wasm. Host cấu hình sai sẽ hiện màn hình trắng hoặc lỗi module, nên hãy kiểm tra ngay ngày đầu.
- Trình duyệt cần: JavaScript, ES modules, WebAssembly và WebGL2.
- Trong iframe của cổng game, cho phép fullscreen và autoplay.
- Trên màn hình cảm ứng: kéo để ngắm và đánh, hai ngón để xoay camera, chụm ngón để phóng to.
- Không phải ứng dụng ngoại tuyến cài đặt được: mỗi lần tải mới vẫn kết nối đến host của bạn.
Gói không có dự án ứng dụng native. Nếu bạn định phát hành lên store, hãy tính chi phí cho lớp đóng gói và việc thử trên điện thoại thật, vì một game vật lý 3D nặng hơn game bài trên các máy đời cũ.
Những gì không có trong gói, và giấy phép
Đây là bản chơi cục bộ trên trình duyệt: không có chơi mạng hay phòng chơi trực tuyến, không có bảng xếp hạng trực tuyến, không có tài khoản đám mây, không có SDK quảng cáo, không có ứng dụng native và không kèm hosting. Kỷ lục sân, tiến trình hằng ngày và lượt chơi chung một thiết bị đều nằm trong trình duyệt của người chơi, không có điểm nào được gửi lên server. Dữ liệu lưu thuộc về origin của trình duyệt, nên chuyển sang tên miền khác thì người chơi bắt đầu lại từ đầu.
Puttide có giá niêm yết 39 USD; đến hết ngày 30/11/2026, khuyến mãi Black Friday giảm còn 33,15 USD, và mua từ hai mẫu trở lên trong một đơn được thêm giảm giá combo từ 5% đến 20%. Giấy phép vĩnh viễn và không độc quyền, cho một sản phẩm cuối cùng của bạn hoặc của một khách hàng. Bạn được đổi thương hiệu, sửa code, hình ảnh và âm thanh, cho người chơi chơi miễn phí hoặc có quảng cáo, nhưng không được bán lại riêng mẫu game hay code của nó. Hỗ trợ kéo dài sáu tháng, hoặc mười hai tháng khi gia hạn; lỗ golf tùy chỉnh, tích hợp và hosting được báo giá theo yêu cầu.
Toàn bộ điều khoản giấy phép, hỗ trợ và hoàn tiền
Câu hỏi thường gặp
Source code mini golf có viết bằng TypeScript không?
Không. Puttide là JavaScript thuần, đã định dạng, nằm trong source/src và game/src, không có file nén hay đóng gói nào của riêng chúng tôi.
Tôi có thể thêm lỗ hoặc sân của riêng mình không?
Có. Nhân bản một lỗ trong file sân, đặt id duy nhất, chỉnh par, tee và cup, thêm vào courses.js rồi thêm tên và mẹo vào các file ngôn ngữ.
Three.js có tải từ CDN không?
Không. Three.js, Rapier, phông chữ và nhạc đều nằm trong game/, nên game chỉ cần host của bạn.
Vì sao host của tôi hiện màn hình trắng?
Thường là do kiểu MIME. Trả .js dưới dạng JavaScript và .wasm dưới dạng application/wasm, mở game qua HTTP(S) và kiểm tra WebGL2 đã được bật.
Bạn bè có chơi cùng nhau được không?
Có, hai đến bốn người chơi lần lượt trên cùng một thiết bị. Bản này không có chơi trực tuyến.
Đây có phải nền tảng mini golf phù hợp với bạn?
Puttide hợp với cổng game gia đình hoặc thể thao, agency làm sân golf mang thương hiệu cho một khách hàng, và lập trình viên muốn xem Three.js và Rapier phối hợp với nhau trong code dễ đọc. Nó kém phù hợp hơn với dự án cần lượt chơi trực tuyến hay bảng xếp hạng chung ngay từ đầu.
Hãy chơi trọn một sân trong bản demo trên điện thoại, rồi đọc phần thêm lỗ golf trong tài liệu. Nếu phần đó trông như việc của một buổi chiều, thì phần còn lại của game đã được làm sẵn.