당구 게임 소스코드: 8볼 HTML5 패키지 들여다보기
물리, 규칙, CPU, 저장이 각각 다른 파일에: Velvet Pool 소스에 무엇이 들어 있고 구매자가 무엇부터 바꾸는지.
당구 게임 소스코드는 세 가지가 서로 분리된 읽기 쉬운 파일에 들어 있을 때 살 가치가 있습니다. 공의 물리, 8볼 규칙, 그리고 컴퓨터 상대입니다. 이것들이 뒤엉켜 있으면 천 색상이나 CPU 난이도를 바꿀 때마다 디버깅을 해야 합니다. 저희 8볼 템플릿 Velvet Pool은 이 셋을 분리해 두었고, 이 가이드는 그 패키지를 파일별로 살펴봅니다.
코드 구성, 구매자가 보통 먼저 바꾸는 것, 호스팅하거나 앱으로 패키징하는 방법, 라이선스가 허용하는 것, 이 에디션에서 빠진 것을 다룹니다. 아래의 모든 파일 이름은 게임과 함께 제공되는 구매자 가이드에서 가져왔습니다.
요약하면 Velvet Pool은 WebGL2 위의 순수 JavaScript이며, 3D 라이브러리도 빌드 단계도 없습니다. 파일을 고치고, 게임 폴더에 복사하고, 페이지를 새로 고치면 됩니다.
이 당구 게임 소스코드에 들어 있는 것
Velvet Pool은 엔진이나 스타터 키트가 아니라 완성된 8볼 게임입니다. 다운로드에는 폴더 네 개가 있습니다. game/은 바로 업로드할 수 있는 빌드, source/는 README, package.json, 테스트가 포함된 개발자용 에디션의 같은 게임, documentation/은 영어와 포르투갈어로 된 그림 가이드, THIRD-PARTY-LICENSES/는 폰트 라이선스 문서를 담고 있습니다.
게임은 파울, 볼 인 핸드, 솔리드와 스트라이프 규칙이 있는 8볼입니다. CPU 난이도는 세 단계(Easy, Medium, Hard)이고, 되돌리기, 공 배치, 재배열이 되는 자유 연습 테이블과 한 기기 2인 대전이 있습니다. 플레이어는 흰 공에 밀어치기, 끌어치기, 옆 회전을 줄 수 있고, 로컬 업적으로 천 색상 다섯 가지와 큐 스타일 다섯 가지를 잠금 해제합니다. 인터페이스는 14개 언어를 지원합니다.
- 스택: 바닐라 JavaScript, ES 모듈, WebGL2. Three.js나 다른 코드 라이브러리는 없습니다.
- 코드: source/src와 game/src에 있는 평범하고 정돈된 JavaScript. 압축(minify)되거나 번들링된 것은 없습니다.
- 테스트: 선택 사항이며 Node.js 20 이상이 필요합니다. 물리, 8볼 규칙, CPU 대전, 번역 키를 검사합니다.
- 작성 시점 버전: 1.1.0, 2026년 10월 22일 업데이트.
Velvet Pool 상품 페이지, 데모, 매뉴얼 보기
파일 구성
game/과 source/는 구조가 같아서 한 폴더의 경로가 다른 폴더의 같은 파일을 가리킵니다. 당구 게임에서 가장 중요한 구분은 src/core/(시뮬레이션과 규칙)와 src/game/(플레이어가 직접 만지는 모든 것) 사이입니다.
- src/core/physics.js: 공 시뮬레이션, 회전, 쿠션 반응.
- src/core/rules.js: 8볼 규칙과 파울 판정.
- src/core/ai.js: CPU가 샷을 고르는 방식.
- src/game/controls.js: 조준, 파워, 회전 입력.
- src/game/progress.js: 업적, 천, 큐, 경기 점수.
- src/game/i18n.js: LANGS에 나열된 14개 언어의 텍스트.
- src/game/localRecords.js: 로컬 점수 기록.
- src/game/audio.js: 효과음과 음악 재생.
- css/style.css와 css/fonts.css: 테마, 반응형 레이아웃, 폰트 선언.
- assets/: 아트, 오디오, 폰트. 로고 파일은 assets/logo/에 있습니다.
물리, 규칙, CPU가 별도 모듈이기 때문에 공의 움직임을 건드리지 않고 CPU를 더 너그럽게 만들 수 있고, 쿠션을 다시 조정하지 않고 파울 규칙을 바꿀 수 있습니다. 당구 코드를 살 때 가장 먼저 확인해야 할 것이 바로 이 분리입니다.
구매자가 먼저 바꾸는 것
대부분의 프로젝트는 같은 순서를 따릅니다. 플레이어가 보는 것부터 시작해 플레이어가 느끼는 것으로 넘어가고, 규칙은 마지막에 둡니다. 버그가 가장 쉽게 생기는 곳이 규칙이기 때문입니다.
- 브랜딩: assets/logo/의 로고 파일을 교체하고 CSS에서 해당 크기를 조정하세요. 화이트 라벨이 허용되므로 저희 이름 대신 여러분이나 고객의 이름을 넣을 수 있습니다.
- 테이블 모양: 색상과 폰트는 css/style.css에 있습니다. 천과 큐 정의는 progress.js에 있습니다. ID는 바꾸지 마세요. 바꾸면 플레이어가 이미 잠금 해제한 꾸미기 아이템을 잃습니다.
- 텍스트와 언어: 모든 문자열은 i18n.js에 있습니다. 필요한 문구를 고치세요. 언어 목록은 LANGS에 있습니다.
- CPU 난이도: 샷 선택은 ai.js에 있습니다. 한 번에 한 단계씩 조정하고, 조정할 때마다 그 단계와 한 경기를 끝까지 해 보세요.
- 물리: 마찰, 회전, 쿠션 반응은 physics.js에 있습니다. 작은 변경도 효과가 크니 바꿀 때마다 테스트를 실행하세요.
- 규칙: 하우스 룰 변형은 rules.js에 넣습니다. 파울과 볼 인 핸드는 테스트 스위트와 함께 직접 플레이해서도 확인하세요.
작업 방식은 모두 같습니다. source/에서 파일을 고치고, game/의 같은 경로에 복사하고, 폴더를 HTTP로 띄운 뒤 새로 고칩니다. 구매자 가이드는 한 번에 기능 하나씩 바꾸고, 바꿀 때마다 메뉴, 경기 한 판, 일시정지, 결과 화면, 새로 고침을 테스트하라고 권합니다.
호스팅, 임베드, 또는 앱으로 패키징하기
호스팅이 가장 쉬운 부분입니다. game/ 안의 모든 것을 public_html/velvet-pool/ 같은 폴더에 올리고, 하위 폴더 구조를 유지한 채 주소를 열면 됩니다. 서버 쪽에는 npm, 터미널, PHP, 데이터베이스, 계정이 전혀 필요 없습니다. HTTPS로 정적 파일을 제공하는 요금제면 충분합니다.
- index.html을 더블클릭해서 열지 마세요. 브라우저가 file://에서 게임 모듈을 차단합니다. 로컬 테스트는 game/ 안에서 python -m http.server 8765를 실행하세요.
- 화면이 비어 있으면 WebGL2가 켜져 있는지, 파일 이름의 대소문자가 그대로인지 확인하세요.
- 브라우저가 모듈을 거부하면 서버가 .js를 잘못된 MIME 타입으로 보내고 있는 것입니다.
- 포털의 iframe 안에서는 fullscreen과 autoplay를 허용하세요.
게임 실행에 필요한 모든 것이 game/ 안에 있으므로 CDN이나 다른 사이트에서 불러오는 것은 없습니다. 다만 페이지를 새로 불러올 때는 여전히 여러분의 호스팅에 접속하므로, 설치형 오프라인 앱은 아닙니다. 터치스크린에서는 작동합니다. 플레이어가 테이블 위에서 조준하고 파워 컨트롤을 당깁니다.
네이티브 앱 프로젝트는 패키지에 포함되지 않습니다. Google Play나 App Store에 게임을 올리고 싶다면, 제작사가 웹 코드로 모바일 앱을 만드는 크로스플랫폼 네이티브 런타임이라고 소개하는 Capacitor 같은 래퍼가 흔히 쓰이는 방법입니다. 스토어용 프로젝트를 만들고 유지하는 것은 직접 하시거나, 저희가 별도 견적으로 제공하는 서비스입니다.
이 에디션에서 빠진 것
Velvet Pool은 로컬 브라우저 에디션입니다. 온라인 멀티플레이와 비공개 방, 온라인 랭킹, 클라우드 계정, 광고 SDK가 없습니다. 두 사람이 한 기기에서 플레이할 수 있고, 조건을 충족한 CPU 대전의 개인 점수는 브라우저에 저장됩니다. 연습과 한 기기 대전은 점수를 저장하지 않습니다.
온라인 플레이에는 자체 서버와 개발이 필요합니다. 제대로 된 프로젝트이니, 템플릿이 거기까지 자라 주기를 기대하기보다 처음부터 예산에 넣으세요. 카탈로그에 스포츠 게임이 더 필요하다면, 아래 두 게임도 바로 호스팅할 수 있는 브라우저 에디션으로 판매합니다.
Puttide: 30홀 3D 미니 골프, 역시 순수 JavaScript
라이선스와 가격 한눈에 보기
Velvet Pool의 정가는 $39입니다. 2026년 11월 30일까지 블랙 프라이데이 프로모션으로 모든 템플릿이 15% 할인되어 $33.15이며, 템플릿 두 개 이상을 주문하면 추가로 5~20% 할인됩니다. 구매할 때마다 최종 제품 하나에 대한 영구적이고 비독점적인 라이선스가 주어지며, 여러분의 제품이든 고객 한 곳의 제품이든 됩니다. 그 제품 안에서 코드, 아트, 오디오를 수정하고 자체 브랜드를 붙일 수 있습니다. 플레이어는 무료로 또는 광고를 통해 이용할 수 있습니다. 템플릿이나 그 코드만 따로 재판매할 수는 없습니다. 지원 6개월이 포함되며 결제 시 연장하면 12개월입니다. 맞춤 작업, 호스팅, SDK나 포털 연동은 별도로 견적을 드립니다.
자주 묻는 질문
당구 게임 소스코드는 읽기 쉬운가요, 압축되어 있나요?
읽기 쉽습니다. source/src와 game/src의 JavaScript는 평범하고 정돈되어 있으며, 압축되거나 번들링된 파일은 없습니다.
Node.js나 빌드 단계가 필요한가요?
아니요. source/의 파일을 고쳐서 game/으로 복사하면 됩니다. Node.js 20 이상은 선택형 테스트를 실행할 때만 필요합니다.
CPU를 더 쉽게 또는 더 어렵게 만들 수 있나요?
네. CPU의 샷 선택은 물리와 분리된 src/core/ai.js에 있어서, 공의 움직임을 바꾸지 않고 조정할 수 있습니다.
휴대폰에서도 되나요?
네. 터치 입력을 지원하고 조작부가 화면에 맞춰집니다. WebGL2가 필요하고 성능은 기기에 따라 다르니, 플레이어가 쓰는 휴대폰으로 테스트하세요.
게임을 새 도메인으로 옮기면 플레이어의 진행 상황이 유지되나요?
아니요. 저장 데이터는 브라우저의 오리진에 속하므로 도메인을 바꾸면 플레이어는 처음부터 시작합니다. 출시 전에 최종 주소를 정하세요.
온라인 멀티플레이를 추가할 수 있나요?
이 에디션만으로는 안 됩니다. 자체 서버와 개발이 필요합니다. 맞춤 작업으로 견적을 드릴 수 있습니다.
이 당구 코드가 맞는 곳
카탈로그에 8볼 게임을 넣고 싶은 포털이나 사이트, 고객 한 곳에 브랜딩된 당구 게임을 납품하는 에이전시, 3D 라이브러리 없이 당구 물리와 규칙이 어떻게 작성되는지 읽어 보고 싶은 개발자에게 맞습니다. 계획이 온라인 대전이나 공유 리더보드에 달려 있다면 덜 맞습니다.
구매 전에 휴대폰과 노트북에서 데모를 해 보고, 매뉴얼의 파일 구조를 열어 보세요. 물리, 규칙, CPU의 분리가 여러분의 작업 방식과 맞는다면, 나머지는 오후 몇 번이면 끝나는 수정입니다.