🎮 SpinningTop 專案開發研究報告

專案名稱：SpinningTop（殭屍陀螺對戰遊戲）
報告日期：2026-07-08
技術棧：TypeScript + Three.js r185 + Vite + React
相關文件：效能分析報告（詳細版）

一、遊戲框架與渲染技術總覽

1.1 渲染架構分層

┌─────────────────────────────────────────────────────────────┐ │ Game Layer（遊戲層） │ │ 職責：決定 what to render（什麼物件、在哪裡、什麼狀態） │ │ 產出：StateMapper → Adapter 呼叫 Renderer API │ ├─────────────────────────────────────────────────────────────┤ │ Render Layer（渲染層） │ │ 職責：how to render（怎麼高效畫出來） │ │ 產出：SpriteRenderer / InstancedMeshRenderer / Particle │ ├─────────────────────────────────────────────────────────────┤ │ Pipeline Core（管線核心） │ │ 職責：基礎設施（render loop、分層、排序、resize） │ │ 核心：WebGLRenderer + OrthographicCamera + LayerSystem │ └─────────────────────────────────────────────────────────────┘

1.2 各物件渲染方式對照表

遊戲物件	渲染技術	Adapter / Renderer	Draw Call	說明
殭屍 (Zombie) 6 種類型，最多 200 隻	GPU Instanced SkinnedMesh	ZombieAdapter + InstancedMesh2 (@three.ez/instanced-mesh)	6（每 type 1 call）	FBX 模型 + 骨骼動畫，每 instance 獨立 pose via setBonesAt()
陀螺 (Top) 玩家角色	Canvas 2D Sprite	EntityRenderer (legacy) EntitySpriteAdapter (WebGL WIP)	每隻 1 (legacy)	預生成 sprite → drawImage，每幀位置/旋轉更新
場景背景多張拼接地圖	WebGL BackgroundTechnique	ArenaAdapter + BackgroundTechnique	1-2	靜態貼圖 plane，cover/partial 顯示模式，已整合至 WebGL 管線
障礙物 (Barrel)	Canvas 2D Sprite	EntityRenderer	每個 1	炸彈桶 sprite + 警示燈 gradient
混凝土方塊	Canvas 2D Shape	EntityRenderer	每個 1	fillRect + strokeRect + 螺絲細節，靜態物件
票券 (Ticket)	Canvas 2D Shape+Text	EntityRenderer	每個 1	彩虹 gradient 背景 + 數字文字，旋轉動畫
粒子特效 8 種子型別	Canvas 2D Path	EffectRenderer	每粒子 1	電弧 / 爪痕 / 電鋸火花 / 星形爆炸等
衝擊波 (Shockwave)	Canvas 2D Arc	EffectRenderer	每個 1	動態半徑 circle stroke
斬擊線 / X斬	Canvas 2D Path	EffectRenderer	每個 1	路徑線段 stroke
投射物 (Projectile)	Canvas 2D Shape	EffectRenderer	每個 1	能量彈 / 彩虹光束
Boss 預警區域 8 種型態	Canvas 2D Shape	EntityRenderer	每個 1	衝刺通道(rect) / 炸彈圈(circle) / 地震圈 / 瞄準十字
浮動文字	Canvas 2D fillText	EffectRenderer	每個 1	傷害數字、狀態提示（TextComponent 策略已就緒）
UI（血條/計分）	HTML/CSS Overlay	UIRenderer (Canvas 2D) 未來遷移至 HTML DOM	—	不在 WebGL 場景中

1.3 渲染層排序 (Layer System)

Layer	Order	內容	Blending
background	0	場景背景圖、裝飾石頭	Opaque
entities	10	殭屍 (InstancedMesh) + 陀螺/障礙物/票券 (Sprite)	Opaque
effects	20	粒子、衝擊波、斬擊線	Transparent / Additive
UI	—	血條、文字、計時器	Canvas 2D / HTML overlay

1.4 核心技術依賴

技術 / Library	版本	用途
Three.js	r185	WebGL 渲染核心、Scene/Camera/Light
@three.ez/instanced-mesh	v0.3.15	InstancedMesh2：GPU Instancing + 骨骼動畫 per instance
Vite	—	Build tool + Dev server + HMR
React	—	UI 層（PerfPanel 等設定面板）
FBXLoader	Three.js 內建	載入 FBX 3D 模型（殭屍）
Canvas 2D	原生	Legacy 渲染路徑（除殭屍外大部分物件）

1.5 效能目標

指標	當前實際	目標值	說明
WebGL render call / 幀	1	1	✅ 已達成
Draw Calls 總計	6 (殭屍) + legacy	< 15	殭屍已優化，其餘仍在 Canvas 2D
Frame Time	25-33ms (多人時)	< 8ms	目標設備：中低階 Android
FPS（單人）	30-40	≥ 60	當前偏低
FPS（多人）	20-30	≥ 30	多位玩家加入後下降明顯

二、當前開發遇到的問題

2.1 AI 對 TypeScript 架構移植與改寫問題多

問題 A：Script 沒有按照架構整理與改寫

AI 產出的程式碼未遵循「渲染層 vs 遊戲層」的分離設計原則
遊戲特定詞彙（Zombie、Arena、Top）出現在本應通用的渲染層中
程式碼未按照設定與邏輯分離的原則，設定值寫死在程式碼中

問題 B：分階段實作，東漏西漏，產出半成品

功能拆分後，各階段之間的銜接點容易遺漏
例如：Strategy 類別已實作，但 _createStrategy 回傳 null（未接線）
介面定義完整但實作只做了 stub（空方法），導致實際運行無效果
DisplaySystem 中 SpriteComponent 與 ShapeComponent 策略存在但未接線

問題 C：產出不能用，問題定位困難

出來的東西往往不能直接使用
找問題需要大量試錯（一個小問題試 10 幾次才定位）
例如殭屍 Instanced Mesh 實作：經歷 13 個重大 bug 才成功運作（詳見 instanced-skinned-mesh-journey.md）
問題包括：Canvas 佈局破壞、Layer 不建立、模型朝向錯誤、骨骼扭曲、動畫不播放等

2.2 對引用 Library 理解不足

案例：@three.ez/instanced-mesh 處理多 Mesh FBX

我們使用 @three.ez/instanced-mesh (InstancedMesh2) 處理 SkinnedMesh 的 batch 功能
對於 FBX 具有多個 Mesh 的處理，AI 試了好幾次都解決不了
請 AI 主動上網搜尋解法也無法成功
最終丟了 ChatGPT 的範例給它才順利完成
暴露出 AI 對第三方 library 內部機制的理解深度不夠，僅能處理基本 usage

Library 版本衝突問題

three-instanced-animation 依賴 three@0.159，與專案使用的 r185 不相容
nested three module 導致 determinantAffine 方法缺失
最終放棄該 library，改用 @three.ez/instanced-mesh
@three.ez/instanced-mesh 的 import 路徑（three/addons/）需要 Vite alias 才能解析

2.3 新版本的整合困難

Google AI Studio 產出的代碼架構混亂

Google AI Studio 對遊戲的調整，將邏輯、資料、渲染都混在 script 中
導致有內容的調整就會讓渲染相關的優化很難整合進去
需要盡早整理架構並套用到當前版本中，讓 Google AI Studio 修改時能夠遵守

資料與邏輯分離的需求

主要需要把資料跟邏輯分開
例如怪物的清單、每個怪物的圖片、大小、動畫等等要獨立一份設定檔
目前架構設計已有 web/src/game/configs/enemies/ 等設定檔結構規劃，但尚未完全落實
渲染層應該只知道 Sprite / Mesh / Particle 等通用概念，不知道 Zombie / Top

2.4 當前效能與表現問題

問題 1：碰撞偵測疑似耗效能

在多個玩家加入的情況下，即使沒有多太多渲染物件，FPS 仍然下降
平常 FPS 約 3X~4X，多位玩家會降到 2X
碰撞檢測使用 checkCollision、resolveCircleBoxCollision 等方法
疑似 N² 碰撞檢測在玩家增加時指數成長

問題 2：撞到敵人時感覺卡頓

碰撞瞬間有明顯的「卡」感，但 FPS 顯示正常
可能原因：碰撞解析造成瞬間位移跳動、物理解算的位置修正過大
或是碰撞響應邏輯佔用了超過一幀的時間，造成微卡

問題 3：WebGL 渲染顏色與 Sprite 不一致

WebGL 渲染的顏色與外觀，與 bake 好的 Sprite 不太一樣
可能原因：色彩空間差異（sRGB vs Linear）、Material 設定差異
使用 MeshStandardMaterial 搭配 Three.js 內建燈光系統，與 Canvas 2D 直接貼圖的視覺效果不同
需要調整 lighting / material 設定或改用 unlit material 來匹配

問題 4：部分特效與元件仍然欠缺

34 個渲染物件中，大部分仍在 Canvas 2D legacy 路徑
WebGL 管線目前僅完成殭屍的 InstancedMesh 渲染
因為第 2.1 點提到的 AI 改寫問題，修改容易改壞其他已正常運作的功能
遷移進度：Phase 0 可立即遷移的只有 TextComponent（FloatingText、UI Timer）

三、WebGL 管線遷移進度總覽

階段	內容	狀態	備註
Pipeline Core	WebGLRenderer + LayerSystem + CameraSystem	✅ 完成	render loop / 分層 / 排序 / resize
Zombie Instanced Mesh	6 種殭屍 GPU Instancing + 骨骼動畫	✅ 完成	6 draw calls 畫完全部殭屍
DisplaySystem 框架	Sprite/Shape/Text Component + Strategy 模式	⚠️ 框架完成但未接線	_createStrategy 回傳 null
Background (WebGL)	ArenaAdapter + BackgroundTechnique	✅ 完成	背景 plane 已整合至 WebGL pipeline
Top Sprite (WebGL)	EntitySpriteAdapter 玩家陀螺	❌ 未完成	仍用 Canvas 2D
Effects (WebGL)	粒子/衝擊波/斬擊線	❌ 未完成	仍用 Canvas 2D
UI 遷移	HP bars / Timer / Score	❌ 未完成	計畫改為 HTML overlay
資料與邏輯分離	JSON 設定檔抽離（enemies / scenes / entities）	❌ 未落實	結構已設計，尚未全面套用

四、後續建議方向

短期（一週內）

1. 碰撞效能調查：Profile 碰撞系統，確認是否為 O(N²) 問題，優先加入 Spatial Hash Grid

2. 碰撞卡頓修正：檢查碰撞響應的位移修正邏輯，可能需要 lerp 過渡

3. 色彩一致性：統一 WebGL 與 Canvas 2D 的色彩空間設定

中期（兩週內）

1. 資料分離：將怪物、場景、物件設定全部抽為 JSON 設定檔

2. 完成 DisplaySystem 接線：讓 SpriteComponent / ShapeComponent 的策略生效

3. 遷移 P0 物件（Top sprite、Barrel sprite、PhantomClone、Afterimage）到 WebGL

長期（一個月）

1. 完成所有渲染物件到 WebGL 管線的遷移

2. 移除 Canvas 2D legacy 渲染路徑（UI 除外）

3. 建立架構規範文件，確保 Google AI Studio 和其他 AI 工具修改時遵守分層原則