미니골프 게임 소스코드: 홀, 물리, 3D 코스 구조
Puttide 패키지가 30개 홀을 어떻게 저장하는지, Three.js와 Rapier가 어디에 있는지, 구매자가 자신만의 홀을 어떻게 추가하는지 정리했습니다.
미니골프 게임 소스코드의 가치는 한 가지 작업으로 판가름 납니다. 바로 홀 추가입니다. 자체 브랜드 코스, 시즌 한정 레벨, 그린 위의 고객사 로고를 원하는 구매자는 레벨 파일부터 엽니다. 홀이 엔진 코드 깊숙이 묻혀 있으면 프로젝트는 거기서 멈춥니다. 저희 3D 미니골프 템플릿 Puttide는 코스마다 순수 JavaScript로 된 홀 파일이 따로 있고, 매뉴얼에서 홀을 추가하는 방법을 안내합니다.
이 가이드는 개발자가 패키지를 처음 접하는 순서대로 따라갑니다. 폴더, 라이브러리, 코스 파일, 수정 순서, 호스팅, 라이선스 순입니다. 파일 이름은 게임에 포함된 구매자 가이드를 그대로 따릅니다.
급한 분을 위한 짧은 답: Puttide는 정리된(formatted) JavaScript이며, 렌더링은 Three.js, 공 물리는 Rapier가 담당하고 둘 다 패키지에 포함되어 있습니다. 빌드 단계도, CDN도, 서버 코드도 없습니다.
미니골프 게임 소스코드에 포함된 것
Puttide는 다섯 개의 섬 코스(Sunlit Ruins, Lantern Pier, Frost Peaks, Cloud Garden, Volcano Forge)에 각 6개씩, 총 30개 홀로 구성된 완성형 게임입니다. 경사로, 포털, 범퍼, 풍차가 홀을 작은 퍼즐로 만듭니다. 홀마다 별 3개(완주, 파 이하 기록, 숨겨진 코인)를 주고, 좋은 라운드에는 동·은·금 메달이 주어집니다.
코스 외에도 변형 규칙이 붙는 데일리 챌린지(바람, 얼어붙은 그린, 무거운 공, 탄력 있는 벽, 코인 러시, 버디 헌트), 코인으로 공·트레일 등 꾸미기 아이템을 사는 Locker, 한 기기에서 2~4명이 번갈아 치는 라운드가 있습니다. 인터페이스는 14개 언어를 지원합니다.
- game/: 바로 업로드할 수 있는 빌드. 공개하는 폴더는 이것 하나뿐입니다.
- source/: 같은 게임의 개발자용 버전. README와 package.json 포함.
- documentation/: 영어와 포르투갈어로 된 그림 가이드 한 권.
- THIRD-PARTY-LICENSES/: 라이브러리와 폰트의 라이선스 원문.
- 버전 1.1.0, 2026년 10월 22일 업데이트.
Puttide 상세 페이지 보기: 데모, 매뉴얼, 가격
Three.js, Rapier, 그리고 나머지 기술 스택
공은 WebAssembly로 동작하는 Rapier 3D 0.21.0이 시뮬레이션하고, 장면은 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.
- 음악 2곡: 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: 인터페이스 색상, 폰트, 반응형 스타일.
홀 추가하기, 단계별 안내
대부분의 구매자가 가장 먼저 하는 수정이며, 매뉴얼에는 몇 줄로 설명되어 있습니다. 저희가 실제로 작업할 순서대로 풀어 썼습니다.
- 새 홀이 들어갈 코스 파일을 고릅니다. 예: Volcano Forge라면 lava.js.
- 만들려는 홀과 비슷한 기존 홀 정의를 복제합니다.
- 고유한 id를 붙입니다. id를 재사용하면 저장된 진행 상황이 꼬입니다.
- 파, 티 위치, 컵 위치를 정한 뒤 장애물을 옮기거나 교체합니다.
- courses.js에서 해당 코스에 홀을 추가합니다.
- 배포하는 모든 언어의 사전에 홀 이름과 팁을 추가합니다.
- 직접 플레이합니다. 충돌, 코스 이탈 후 복귀, 숨겨진 코인을 포함한 별 3개를 모두 확인하세요.
source/에서 수정하고, 바뀐 파일을 game/의 같은 경로에 복사한 다음, 폴더를 HTTP로 띄워 테스트합니다. package.json에 serve 스크립트가 있고, python -m http.server 8765를 실행해도 됩니다. Node.js는 선택 사항이며, npm으로 라이브러리 버전을 관리하고 싶을 때만 필요합니다.
나머지 수정, 합리적인 순서로
- 브랜드와 색상: css/style.css의 로고, 색상, 폰트. 화이트 라벨이 허용되므로 저희 브랜드 대신 여러분의 브랜드를 넣을 수 있습니다.
- Locker 가격: economy.js. 꾸미기 아이템이 저렴하면 캐주얼 사이트가 친근해지고, 비싸면 긴 캠페인을 오래 끌고 갈 수 있습니다.
- 텍스트: i18n 파일의 문구와 팁.
- 음악: 포함된 두 곡은 라이선스를 보유한 녹음으로 교체할 수 있습니다. 파일을 복사하고 audio.js(probeTracks)의 명시적 매핑을 수정하세요. 장면 음악은 게임플레이 곡으로 대체됩니다.
- 물리: constants.js는 맨 마지막에, 조금씩 바꾸세요. 모든 홀이 현재 값에 맞춰 조정되어 있습니다.
같은 순수 JavaScript 방식이면서 3D 라이브러리를 아예 쓰지 않는 비슷한 프로젝트를 찾는다면, 저희 당구 템플릿도 같은 구조로 만들어져 있습니다.
Velvet Pool: 순수 JavaScript와 WebGL2로 만든 8볼 당구
Sunset Rally: 9경기 캠페인이 있는 3D 탁구
호스팅, MIME 타입, 앱 래퍼
game/ 안의 모든 파일을 public_html/puttide/ 같은 폴더에 하위 폴더 구조 그대로 올리고, HTTPS 주소로 여세요. 서버에 npm, PHP, 데이터베이스, 계정은 필요 없습니다. 브라우저가 file:// 에서 모듈을 차단하므로 디스크에서 index.html을 직접 열면 동작하지 않습니다.
Puttide에는 2D 게임에 없는 호스팅 포인트가 하나 있습니다. 물리가 WebAssembly로 돌아간다는 점입니다. 서버는 .js 파일을 JavaScript MIME 타입으로, .wasm 파일을 application/wasm으로 보내야 합니다. 설정이 틀린 호스트에서는 빈 화면이나 모듈 오류가 나므로 첫날 바로 확인하세요.
- 브라우저 요구 사항: JavaScript, ES 모듈, WebAssembly, WebGL2.
- 포털 iframe에서는 전체 화면과 자동 재생을 허용하세요.
- 터치스크린: 드래그로 조준하고 퍼팅, 두 손가락으로 카메라 회전, 핀치로 확대·축소.
- 설치형 오프라인 앱이 아닙니다. 새로 불러올 때마다 여러분의 호스트에 접속합니다.
네이티브 앱 프로젝트는 패키지에 없습니다. 스토어 출시를 계획한다면 래퍼 작업과 실제 휴대폰 테스트 비용을 잡아 두세요. 오래된 기기에서는 3D 물리 게임이 카드 게임보다 무겁습니다.
포함되지 않은 것과 라이선스
이 버전은 로컬 브라우저 에디션입니다. 온라인 멀티플레이나 온라인 방, 온라인 리더보드, 클라우드 계정, 광고 SDK, 네이티브 앱, 호스팅은 포함되지 않습니다. 코스 기록, 데일리 진행 상황, 같은 기기 라운드는 플레이어의 브라우저에 남고 점수는 어디에도 업로드되지 않습니다. 저장 데이터는 브라우저 오리진에 묶이므로 다른 도메인으로 옮기면 플레이어는 처음부터 시작합니다.
Puttide의 정가는 $39이며, 2026년 11월 30일까지 블랙 프라이데이 프로모션으로 $33.15입니다. 한 주문에 템플릿을 두 개 이상 사면 5%~20% 묶음 할인이 추가됩니다. 라이선스는 영구·비독점이며 최종 제품 하나(여러분의 것 또는 고객사 하나)에 적용됩니다. 브랜드 교체, 코드·아트·오디오 수정, 무료 또는 광고 포함 서비스가 가능하지만, 템플릿이나 코드 자체를 단독으로 재판매할 수는 없습니다. 지원 기간은 6개월, 연장 시 12개월이며, 맞춤 홀·연동·호스팅은 요청 시 견적을 드립니다.
자주 묻는 질문
미니골프 소스코드는 TypeScript인가요?
아닙니다. Puttide는 source/src와 game/src에 있는 정리된 순수 JavaScript이며, 저희가 압축(minify)하거나 번들링한 파일은 없습니다.
제 홀이나 코스를 추가할 수 있나요?
네. 코스 파일에서 홀을 복제해 고유 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가 어떻게 함께 동작하는지 보고 싶은 개발자에게 잘 맞습니다. 첫날부터 온라인 라운드나 공유 리더보드가 필요한 프로젝트에는 덜 맞습니다.
휴대폰으로 데모에서 코스 하나를 끝까지 플레이한 뒤, 매뉴얼의 홀 추가 섹션을 읽어 보세요. 그 작업이 오후 한나절 정도로 보인다면, 나머지는 이미 다 만들어져 있습니다.