BEYBLADE X 戰鬥陀螺模擬對戰（非官方）

以 TAKARA TOMY《BEYBLADE X 戰鬥陀螺》為題材的非官方擬真模擬對戰遊戲。 繁體中文介面的網頁遊戲（手機瀏覽器即可遊玩），目前為開發者自用測試版。

目錄

• 專案簡介
• 功能特色
• 快速開始
• 遊戲玩法
• 系統架構
• 專案結構
• 伺服器與部署
• 安裝到手機
• 開發文件
• 聲明與致謝

專案簡介

本專案模擬 BEYBLADE X 的實體對戰：完整官方零件庫自由組裝、自製決定論物理引擎、 官方賽制積分規則（含各種變體選項）、錦標賽與快速對戰模式、可個別設定技術等級與 性格的電腦對手，並以「手持發射器拉繩發射」與「感測器空間定位戰鬥盤」重現臨場感。

功能特色

• 完整官方零件庫 — 鋼鐵戰刃、固鎖輪盤、軸心，以及 CX 系統的紋章鎖／主要戰刃／ 輔助戰刃／金屬戰刃／超越戰刃；同名零件的官方強化版本（如金屬塗層）獨立收錄。
• 零件庫自由組裝 — 逐零件挑選、即時能力值與重量統計、命名儲存自訂配置。
• 決定論物理引擎 — 固定時步 240 Hz、無原生三角函數（自製多項式）、種子化亂數； 相同輸入在任何裝置皆產生完全相同的對戰，線上對戰即以「交換發射參數＋本地模擬」 實現鎖步同步。物理模型：碗面重力、軸心摩擦與花瓣軌跡、剛體碰撞與爆裂齒扣、 X 衝擊線齒軌加速、四種決勝判定。
• 官方賽制 — 迴轉勝利 1 分／擊飛勝利 2 分／爆裂勝利 2 分／極限勝利 3 分， 先得 4 分獲勝；自滅、發射失誤懲罰、3on3 禁重複零件等規則皆實作， 並提供 WBO 等變體與自訂選項。
• 戰鬥盤模擬 — BX-10 X戰鬥盤與 BX-32 寬型X戰鬥盤（齒軌、擊飛區域、極限區域、 發射位置皆依實品配置），亦提供無齒軌的傳統戰鬥盤。
• 模式 — 快速對戰（人類/電腦任意組合、同機輪流、線上連線）、 錦標賽（單淘汰含季軍賽或循環賽）、零件庫、對戰紀錄。
• 線上人數＝加入房間的手機數 — 房主等大家都進房後按「開始」，不必預設人數。 線上快速對戰兩台手機打標準 1v1；三台以上自動改打大亂鬥（free-for-all）： 每回合所有人同時發射進同一個戰鬥盤、全場混戰，最後存活者拿下該回合， 率先三勝獲得優勝（非官方玩法）。線上錦標賽則以「加入的手機數＋房主設定的 電腦選手數」組成籤表。
• 發射體驗 — 3・2・1 GO SHOOT 倒數中顯示半透明發射器與拉繩指示， 拉動速度累積發射力道（SP），發射瞬間陀螺脫離發射器、鏡頭拉開呈現戰場。 可選拉條／拉繩／強化握把發射器。
• 體感視角（預設開啟） — 校正時手機平放桌面、螢幕朝上，戰鬥盤即固定於手機 上緣正前方的桌面上；拿起手機朝該處觀看即可環繞觀戰，並提供「重新校正」。
• 依實物尺寸建模 — 每個零件都照真實數據建構（詳見 docs/MODELING.md）： 戰刃直徑直接取自資料庫的實測值（45–52.5 mm），固鎖輪盤的編號本身就是幾何 （3-60 ＝ 3 個爪、6.0 mm 高），軸心依代號還原實際形狀（平／球／針／尖／ 錐／橡膠），帶齒輪環的 G 系列軸心真的有咬合齒。戰鬥盤依官方尺寸：BX-10 440×455×155 mm、龍捲脊 ⌀210 mm、白色本體＋綠色 X 線；BX-32 寬型 600×440 mm 三人盤。發射器為三種真實型號（拉條／拉繩／強化握把），並以有掌、指節、 拇指的雙手握持。所有模型皆為高多邊形（單一零件掃掠達數萬面）。
• 擬真渲染與光線行進 — PBR 物理材質（壓鑄鋅合金的各向異性高光、ABS 的 橘皮紋、POM 的半透光、橡膠、聚碳酸酯外罩、皮膚次表面感）、程序化法線貼圖、 程序化攝影棚環境光照（IBL）。瀏覽器沒有硬體光線追蹤，因此改以自訂像素 著色器對深度緩衝進行光線行進：螢幕空間反射（金屬戰刃會映出戰鬥盤與 對手）、接觸陰影、環境遮蔽；並依實際幀時自動調整品質。
• 音效與音樂 — 全程序化 Web Audio 合成：轉速連動旋轉聲、碰撞、齒扣、 X 衝擊、爆裂等音效，以及可切換的氣氛音樂（預設開啟）。
• 帳號與訪客模式 — 以 Google 登入註冊／登入（不需另設密碼，也不需 電子郵件驗證），另保留電子郵件＋密碼作為備援，或只輸入暱稱以訪客身分 立即遊玩（訪客資料不會保存到伺服器）。登入後在明確登出前都保持登入。 ※ Google 僅接受 HTTPS 網域作為登入來源，因此純 HTTP／IP 位址的伺服器層 無法使用 Google 登入（會自動隱藏按鈕）。設定方式見 docs/PROTOCOL.md。
• 伺服器資料庫 — 玩家偏好、選手戰績、對戰紀錄與自訂配置儲存於伺服器 文件資料庫（LWW 合併；仍支援與對等伺服器同步，目前僅部署單一層）。
• 重播與分享 — 每場對戰都以決定論參數（種子＋發射參數）保存，可從 對戰紀錄重播，或複製連結分享給他人觀看。

快速開始

# 1. 抓取並正規化零件資料（本倉庫不內含第三方資料，需自行產生）
node tools/fetch-parts.mjs
node tools/normalize-parts.mjs

# 2. 開發模式
cd app
npm install
npm run dev        # http://localhost:5173

# 3. 測試與建置
npm test           # 物理決定論、規則引擎、平衡度測試
npm run build

本機同時測試線上對戰與資料庫時，另開一個終端執行伺服器：

cd server/relay
go run . -listen 127.0.0.1:8080

遊戲玩法

1. 於主選單選擇模式；每位玩家可設定為具名人類或電腦（技術等級： 新手／見習／高手／達人／冠軍；性格：猛攻／鐵壁／持久／均衡／詭道）。
2. 選擇規則預設（官方標準／官方 3on3／WBO）、獲勝分數、戰鬥盤與發射器， 並以官方配置或自訂配置組裝陀螺。上述偏好會自動保存。
3. 倒數「3・2・1 GO SHOOT!」時向下拉動拉繩——拉得越快力道越大； 過早、過晚或力道不足視為發射失誤，單回合兩次失誤對手得 1 分。
4. 對戰全程由物理引擎決定：碰撞、爆裂、擊飛、極限衝擊、迴轉耗盡。 先達到目標分數者獲勝。

系統架構

┌────────────── 用戶端（TypeScript + Three.js + Vite）──────────────┐
│ core/     決定論物理模擬（不依賴渲染，可無頭執行與測試）            │
│ game/     規則引擎、電腦對手、錦標賽、持久化                        │
│ render/   PBR 場景、程序化戰鬥盤與陀螺模型、著色器特效              │
│ input/    拉繩發射手勢     sensors/ 陀螺儀空間定位                  │
│ net/      房間連線與鎖步對戰   ui/ 繁中畫面   audio/ 合成音效       │
└──────────────────────────────┬────────────────────────────────────┘
                               │ WebSocket + REST
┌──────────────────────────────┴────────────────────────────────────┐
│ server/relay（Go，單一執行檔）                                      │
│  • 靜態網站託管（內嵌打包後的遊戲）                                  │
│  • /game/{room}/ws 房間中繼（不含遊戲邏輯，純轉送）                  │
│  • /game/db 文件資料庫（LWW 合併）＋ 對等層自動同步                  │
│  • 可反向代理既有服務、支援子路徑與各種主機環境                       │
└───────────────────────────────────────────────────────────────────┘

線上對戰原理：戰鬥陀螺發射後即無操作介入，因此雙方只需交換發射參數與種子， 各自在本地執行決定論模擬即可得到完全一致的結果（附狀態雜湊驗證）。

專案結構

app/            用戶端（Vite + TypeScript + Three.js；PWA）
server/relay/   Go 伺服器：靜態託管＋房間中繼＋文件資料庫＋層間同步
tools/          零件資料抓取與正規化（Node，無相依套件）
build/          建置與部署腳本（PowerShell）
docs/           計畫、規則、物理、通訊協定、資料管線文件

伺服器與部署

build\build-relay.ps1 會建置網頁版並內嵌進 Windows / Linux 兩種單一執行檔。 正式部署為 Azure App Service（HTTPS / WSS）單一伺服器，另可純本機執行。 詳見 docs/PROTOCOL.md 與 build\deploy-azure.ps1 （伺服器位址屬個人設定，不隨倉庫提供）。

為什麼只剩一層：Google 登入只接受 HTTPS 網域作為來源，純 HTTP／IP 位址 的伺服器無法登入，因此原本的 OCI Always Free VM 備援層已停止部署。

安裝到手機

以 HTTPS 開啟遊戲網址後選擇「加入主畫面」即可（PWA，含離線快取）。 本專案不再提供原生 App 打包 —— 網頁版在 iOS Safari 與 Android Chrome 上 功能完整（含體感視角與震動回饋）。

開發文件

文件	內容
docs/PLAN.md	專案計畫、技術選型、里程碑
docs/RULES.md	官方與 WBO 賽制研究、規則選項對照
docs/PHYSICS.md	物理模型與決定論規範
docs/PROTOCOL.md	伺服器、鎖步協定、資料庫與部署
docs/DATA.md	零件資料管線與授權注意事項

聲明與致謝

本專案為粉絲自製、非商業之模擬器，與 TAKARA TOMY 無任何關聯，亦未獲其授權。 「BEYBLADE X」「戰鬥陀螺」及所有零件名稱之商標與著作權均屬原權利人所有。

• 零件數據參考 BEYBLADE X 戰鬥陀螺瀏覽器 （phstudy 製作之非官方資料庫）。本倉庫不包含其資料與圖片； 資料由使用者執行 tools/ 腳本自行取得，僅供個人研究使用。
• 規則參考官方規則書與 World Beyblade Organization。
• 所有 3D 模型、材質、音效、音樂皆為程序化生成，不含任何第三方素材。