免下載 App！開啟手機鏡頭即可在實體書桌上大展身手的 WebAR 撞球遊戲。
支援 AI 手勢握桿推擊、精確 2.5D 連續碰撞物理、美式 8 號球正規規則 與 iPhone XR 極致流暢抗卡頓優化！
-
實景 AR 書桌撞球 (Passthrough WebAR)
- 透過後置鏡頭將迷你球桌自然融合在您的書桌、茶几或客廳地板上。
- 內建 3D 空間調校面板：支援等比縮放（0.25x ~ 1.5x）、高低升降、視角仰角、距離與 360° 水平旋轉。
-
🖐️ AI 手勢握桿與推擊體感 (MediaPipe Hands)
- 瞄準：鏡頭前移動手掌，虛擬球桿即時跟隨手腕至食指方向旋轉對準母球。
- 握桿蓄力：捏合大拇指與食指（👌）鎖定瞄準，向後拉手掌累積擊球力道（0% ~ 100%）。
- 推擊出桿：向前推桿或鬆開手指（STRIKE!!），精確將動量傳遞給母球！
- 觸控雙模相容：若不想舉手，亦可隨時使用畫面底部的「瞄準角度滑桿」與「蓄力推桿條」單指流暢遊玩。
-
🎯 雙重輔助瞄準系統
- 母球運動路徑虛線：清晰指示母球前進方向。
- 幽靈預測球 (Ghost Ball)：自動計算第一顆碰撞子球的接觸點，輔助精確走位與角度切球。
-
🎱 正規美式 8 號球規則引擎
- 標準 16 顆球（1 顆母球、1
7 號全色球、8 號決勝黑球、915 號花球條紋）。 - 標準三角架開球排列（8 號球置於第三排正中央，頂球置於腳點）。
- 完整規則判定：
- 開球局（Break shot）選定花色（Solid vs Stripe）。
- 合法擊球與犯規檢驗（先碰自身球、空桿、白球洗袋）。
- 犯規自由球（Ball in Hand）：可直接在檯面上觸控拖曳母球至任意合法位置擺放！
- 決勝黑 8 規則：清台後打進黑 8 獲勝；違規進黑 8 或黑 8 洗袋直接判負！
- 雙人同機輪流對戰（Pass & Play）。
- 標準 16 顆球（1 顆母球、1
-
🔊 Procedural Web Audio 物理合成音效
- 零外部音效檔下載、零記憶體垃圾回收負載。
- 動態球球相撞清脆撞擊聲（音量與音高依碰撞速度動態調節）、庫邊鈍擊聲、球桿擊球聲與球袋沉底聲。
針對舊款 iOS 設備（如搭載 A12 仿生晶片、3GB RAM 的 iPhone XR）容易因 WebGL 與 AI 重負載導致發燙降頻、掉幀卡頓的問題，本專案實施了關鍵架構優化：
| 優化項目 | 實作策略 | 效益 |
|---|---|---|
| MediaPipe 輕量化 | 採用 modelComplexity: 0 (Lite)，並將攝影機推論尺寸限制為 480x360 |
大幅降低 A12 神經網絡推論功耗，杜絕過熱 |
| AI 推論節流管線 | 影像推論限制在 ~22 FPS，主畫面 Three.js 以 Lerp 線性插值運行在 60 FPS |
手勢動作絲滑流暢，同時降低 60% CPU 負載 |
| 視網膜渲染限幅 | renderer.setPixelRatio(Math.min(window.devicePixelRatio, 1.5)) |
避免 iOS Safari 在 2x/3x Retina 螢幕產生龐大像素填充率負載 |
| 高頻連續碰撞 (CCD) | 自研 2.5D 連續碰撞物理引擎（每幀 4 次子步更新）替代沈重 3D 物理庫 | 徹底杜絕高速穿球/穿邊問題，且運行期間 0 物件記憶體分配（Zero GC） |
| 程序化動態紋理 | 球體貼圖於啟動時由 Canvas 一次性繪製生成（包含 Aramith 紅點與條紋） | 啟動秒開、零網路等待、免加載外部貼圖資源 |
- 點擊執行目錄下的
start.bat，或在終端機執行：python serve.py
- 在電腦瀏覽器開啟
http://localhost:8080即可測試。 - 若要使用 iPhone XR 實機測試相機：
- 由於 iOS Safari 安全規範，相機權限（
getUserMedia）必須在 HTTPS 或 GitHub Pages 環境下運作。 - 推薦使用 ngrok 或 localtunnel 建立快速安全通道：
將產生的
npx localtunnel --port 8080
https://...網址在 iPhone XR 的 Safari 中開啟即可！
- 由於 iOS Safari 安全規範，相機權限（
專案已內建 .github/workflows/deploy.yml 自動部署腳本：
- 將本專案推送至 GitHub 儲存庫（Repository）。
- 至儲存庫 Settings -> Pages，將 Source 設為 GitHub Actions。
- 推送後即會自動構建，產生的
https://<你的帳號>.github.io/<專案名>/網址即可直接在任何手機上開箱遊玩！
- AR 校準：點擊右上角
📐開啟調校面板，調整「縮放大小」與「高度」讓球桌穩固貼合桌子。 - 鏡頭翻轉：點擊右上角
📷可切換後置/前置鏡頭。 - 瞄準調整：
- AI 模式：鏡頭前移動手掌，球桿會自動跟隨手勢角度旋轉。
- 觸控模式：滑動底部「瞄準角度滑桿」。
- 擊球蓄力：
- AI 模式：大拇指與食指捏合（👌）後向後拉手累積力道，向前推桿或放開手指即出桿！
- 觸控模式：手指在底部「蓄力槽」滑動選擇力量，點擊「擊球」按鈕。
- 自由球（Ball in Hand）：對手犯規時，直接在畫面上按住白球拖曳至合適位置即可重新開球！