撞球遊戲原始碼：拆解一套 HTML5 八號球套件
物理、規則、電腦對手和存檔分放在不同檔案：Velvet Pool 原始碼裡有什麼，買家通常先改哪裡。
撞球遊戲原始碼值不值得買，要看三樣東西是否放在獨立、好讀的檔案裡：球的物理、八號球規則和電腦對手。如果它們全纏在一起，改個檯布顏色或電腦難度都會變成一場除錯。我們的八號球範本 Velvet Pool 把它們分開，這篇指南會逐一檔案帶你看它的套件。
我們會介紹程式碼怎麼組織、買家通常先改什麼、怎麼架設或包成 App、授權允許什麼，以及這個版本沒有包含什麼。以下所有檔名都來自遊戲附帶的買家指南。
簡單講：Velvet Pool 是在 WebGL2 上執行的純 JavaScript，沒有 3D 函式庫，也不需要建置。改一個檔案，複製到遊戲資料夾，重新整理頁面就好。
這套撞球遊戲原始碼包含什麼
Velvet Pool 是一款完成的八號球遊戲，不是引擎，也不是入門套件。下載內容有四個資料夾：game/ 是可直接上傳的建置版本；source/ 是同一款遊戲的開發者版本，附 README、package.json 和測試；documentation/ 是英文和葡萄牙文的圖解指南；THIRD-PARTY-LICENSES/ 放字型授權文字。
遊戲本身是八號球玩法，包含犯規、自由球，以及實心球或條紋球。電腦對手有三種難度（Easy、Medium 和 Hard），另有可復原、可擺球、可重新排球的自由練習檯，以及同一台裝置的雙人對戰。玩家可以讓母球加上推桿、拉桿或側旋，本機成就可解鎖五種檯布顏色和五種球桿樣式。介面提供 14 種語言。
- 技術架構：原生 JavaScript、ES 模組和 WebGL2。沒有 Three.js 或其他程式庫。
- 程式碼：source/src 和 game/src 裡是排版整齊的純 JavaScript，沒有壓縮（minify）也沒有打包。
- 測試：選用，需要 Node.js 20 以上版本。測試涵蓋物理、八號球規則、電腦對局和翻譯鍵。
- 撰文時的版本：1.1.0，更新於 2026 年 10 月 22 日。
檔案怎麼組織
game/ 和 source/ 的結構相同，所以一個資料夾裡的路徑，在另一個資料夾裡也指向同一個檔案。對撞球遊戲來說，最關鍵的分界是 src/core/（模擬與規則）和 src/game/（玩家碰得到的一切）。
- src/core/physics.js：球的模擬、旋轉和球檯邊的反彈。
- src/core/rules.js：八號球規則和犯規判定。
- src/core/ai.js：電腦怎麼選擇擊球。
- src/game/controls.js：瞄準、力道和旋轉的輸入。
- src/game/progress.js：成就、檯布、球桿和比賽計分。
- src/game/i18n.js：14 種語言的文字，列在 LANGS。
- src/game/localRecords.js：本機分數紀錄。
- src/game/audio.js：音效和音樂播放。
- css/style.css 和 css/fonts.css：主題、響應式版面和字型宣告。
- assets/：美術、音效和字型，標誌檔案在 assets/logo/。
因為物理、規則和電腦對手是各自獨立的模組，你可以讓電腦手下留情一點而不影響球的運動，也可以改一條犯規規則而不必重調球檯邊。買任何撞球程式碼時，這種分離是最該檢查的地方。
買家會先改什麼
大多數專案都照同樣的順序。先改玩家看得到的，再改玩家感受得到的，規則留到最後，因為規則最容易藏進 bug。
- 品牌：替換 assets/logo/ 裡的標誌檔案，並在 CSS 調整對應尺寸。授權允許白牌，所以可以用你或客戶的名字取代我們的。
- 球檯外觀：顏色和字型在 css/style.css。檯布和球桿的定義在 progress.js。請維持它們的 ID 不變，否則玩家會失去已解鎖的外觀。
- 文字和語言：所有字串都在 i18n.js。修改你需要的用字；語言清單在 LANGS。
- 電腦難度：擊球選擇在 ai.js。一次調一種難度，並跟它打完一整局。
- 物理：摩擦、旋轉和球檯邊反彈在 physics.js。這裡改一點點影響就很大，每改一次都要跑測試。
- 規則：自訂的地方規則放在 rules.js。犯規和自由球除了跑測試套件，也要親手測一遍。
每一項修改的流程都一樣：在 source/ 編輯檔案，複製到 game/ 的相同路徑，透過 HTTP 提供這個資料夾，然後重新整理。買家指南建議一次只改一項功能，每次改完都測試選單、一場比賽、暫停、結算畫面和重新整理。
架設、嵌入或包成 App
架設是最簡單的部分。把 game/ 裡的所有內容上傳到像 public_html/velvet-pool/ 這樣的資料夾，保留子資料夾，然後開啟網址。伺服器端不需要 npm、終端機、PHP、資料庫或帳號。只要是能透過 HTTPS 提供靜態檔案的方案就夠了。
- 不要點兩下開啟 index.html：瀏覽器會在 file:// 下封鎖遊戲模組。本機測試時，在 game/ 裡執行 python -m http.server 8765。
- 如果畫面一直空白，請確認 WebGL2 已啟用，以及檔名的大小寫維持原樣。
- 如果瀏覽器拒絕載入某個模組，表示你的伺服器送出 .js 時用了錯誤的 MIME 類型。
- 放進入口網站的 iframe 時，要允許全螢幕和自動播放。
遊戲執行時需要的一切都在 game/ 裡，不會從 CDN 或其他網站載入任何東西。不過每次重新開啟頁面仍會連到你的主機，所以它不是可安裝的離線 App。它可以在觸控螢幕上玩：玩家在球檯上瞄準，拉動力道控制。
套件不包含原生 App 專案。如果想把遊戲上架 Google Play 或 App Store，常見做法是用 Capacitor 這類包裝工具，它的開發者形容它是用網頁程式碼打造行動 App 的跨平台原生執行環境。建置和維護商店專案是你的工作，或由我們另外報價提供服務。
這個版本沒有包含什麼
Velvet Pool 是本機瀏覽器版本。沒有線上多人或私人房間，沒有線上排行榜，沒有雲端帳號，也沒有廣告 SDK。兩個人可以在同一台裝置上對戰，符合條件的電腦對局個人分數會存在瀏覽器裡。練習和同裝置對戰不會儲存分數。
線上對戰需要你自己的伺服器和開發。那是一個真正的專案，所以從一開始就要編列預算，別指望範本會慢慢長成那樣。如果你的遊戲目錄需要更多運動遊戲，以下兩款也以可直接架設的瀏覽器版本販售。
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 以上版本。
可以把電腦調簡單或調難嗎？
可以。電腦的擊球選擇在 src/core/ai.js，跟物理分開，所以調整它不會改變球的運動。
可以在手機上玩嗎？
可以。支援觸控輸入，控制項會依螢幕調整。需要 WebGL2，效能取決於裝置，所以請在玩家實際使用的手機上測試。
把遊戲搬到新網域，玩家的進度還會在嗎？
不會。存檔屬於瀏覽器的來源，換網域後玩家會從頭開始。請在上線前決定最終網址。
可以加入線上多人嗎？
光靠這個版本沒辦法。需要你自己的伺服器和開發。我們可以當作客製工作報價。
這套撞球程式碼適合誰
它適合想在遊戲目錄裡加入一款八號球遊戲的入口網站或網站、要為一位客戶交付品牌撞球遊戲的代理商，以及想在沒有 3D 函式庫干擾下，讀懂撞球物理和規則怎麼寫的開發者。如果你的計畫仰賴線上對戰或共用排行榜，它就不太適合。
購買前，在手機和筆電上都玩一下試玩版，並打開手冊的檔案地圖。如果物理、規則和電腦對手的分工符合你的工作方式，剩下的就是幾個下午的修改。