SpinningTop · 目錄結構重整 · 任務報告

檔案大歸位：Before → After

codex 助手執行的專案目錄重整（用量到頂後由專案負責人接手驗證與上傳）。純檔案搬家與改名，遊戲內容零改變——目的：資源／程式／設定各歸其位，之後多人多 AI 改東西不再擠在同一堆資料夾裡互撞。

日期 2026-07-17 · 分支 feat/codex-game-structure · commit 658505e · 已 push、待合回 main

358
總變更項
303
搬移／改名
29
修改（路徑引用/文件）
10
新增
12
刪除

五大搬移主題（Before → After）

左紅＝舊位置，右綠＝新位置；數字＝搬了幾個檔。

① 資料資產歸位 → DynamicResource/ （動畫、粒子、特效 JSON 共 ~90 檔）

ScriptableObject/prefabs/entities（20）→DynamicResource/Prefab/Entity
ScriptableObject/prefabs/effects（18）→DynamicResource/Prefab/Effect
ScriptableObject/prefabs/sub-effects（16）→DynamicResource/Prefab/SubEffect
ScriptableObject/prefabs/warnings（10）→DynamicResource/Prefab/Warning
ScriptableObject/prefabs/ui（4）→DynamicResource/Prefab/Ui
ScriptableObject/animations（10）→DynamicResource/Data/Animation
ScriptableObject/particles（8）→DynamicResource/Data/Particle
ScriptableObject/schemas（14）→Settings/Schema

為什麼：Barry 的「資料／渲染分離」把外觀定義寫成 JSON 之後，這批資料檔要有自己的家——照類型分層（Prefab＝物件外觀、Data＝動畫粒子參數、Schema＝格式定義），美術或企劃要改哪類一眼找到。檔名同步統一成大寫開頭（如 item-key.json → ItemKey.json）。

② 渲染程式集中 → Script/System/RenderSystem/ （~66 檔）

Script/RenderPipeline（23）→System/RenderSystem
Script/RenderPipeline/adapters（13）→System/RenderSystem/Adapters
Script/RenderPipeline/techniques（8）→System/RenderSystem/Techniques
System/renderers/entities（9）→RenderSystem/CanvasRenderers/Entities
System/renderers/ui（6）→RenderSystem/CanvasRenderers/Ui
System/mappers（6）＋ sprites（5）＋ overlay（5）→RenderSystem/{Mappers, Sprite, Overlay}

為什麼：原本「畫東西的程式」散在三個地方（RenderPipeline／renderers／散檔）；現在 WebGL 與 Canvas 渲染統一住進 RenderSystem，找「畫面問題」只需要看一個目錄。

③ 遊戲玩法邏輯歸位 → Script/System/SpinningTopSystem/ （~44 檔）

System/（散檔 17）→System/SpinningTopSystem/
System/update（10）→SpinningTopSystem/GameLoop
System/systems（9）→SpinningTopSystem/Systems
System/zombies（8）→SpinningTopSystem/Zombie

為什麼：「這個遊戲特有的玩法」（碰撞、殭屍 AI、遊戲迴圈）跟「通用系統」分開住——之後做第二款遊戲時，SpinningTopSystem 整包是可替換的。

④ 引擎工具化 → Script/Tools/IGSWebEngine/ （~23 檔）

Script/Engine（9）→Tools/IGSWebEngine
Script/Engine/painters（14）→Tools/IGSWebEngine/Painters

為什麼：PrefabRenderer 這套「通用繪圖引擎」定位是跨專案工具，不屬於單一遊戲——搬進 Tools 明確標示它的邊界（也呼應審查發現的「引擎不該反向依賴遊戲」分層原則）。

⑤ UI 與媒體素材歸位 （~35 檔）

UI/components/screens（13）→Stage/Fight/FightUi/Components/Screens
UI/components/ui（8）→Stage/Fight/FightUi/Components/Ui
Media/Images/backgrounds（6）→Media/Environment/Background
Media/Images（陀螺貼圖 3）→Media/Character/SpinningTop/Texture
ScriptableObject/scenes（3）→Stage/Fight/Scene
editor-integration（2）／constants→Script/Editor ／ Script/Info

為什麼：UI 元件按「哪個場景在用」歸進 Stage/Fight；圖片素材按「角色／環境／共用」分類——FZGUN 專案的成熟結構慣例。

新增與刪除

  • 新增 10：新目錄的 README 說明檔（DynamicResource／Shader／AutoGen）＋搬移後的轉接檔（EntityRenderer / UIRenderer / StateMapper 等在原架構位置的新殼）＋ wiki/systems/current-architecture-and-data-wiring.md（新版架構說明——回應「文件真相分裂」審查發現的收斂第一步）
  • 刪除 12：舊位置的殼檔（搬家後不再需要）＋ 5 個舊 BGM .ogg（音效重製後的遺留清理）＋一個一次性搬遷腳本
  • 修改 29：vite 設定／HMR 插件的資源路徑、wiki 全站路徑同步（11 頁）、.kiro skill 與 steering 文件同步（10 份）——就是把「文件說的路徑」跟上「檔案實際位置」

驗證結果（接手後執行，四道關卡全過）

  • ✅ 型別檢查：303 個檔搬家、零 import 斷裂（TS2307 掃描 = 0）；剩餘 55 個型別警告為遷移前既有老帳，與本次無關
  • ✅ 正式 build：vite build 通過（7.04 秒），資源打包完整
  • ✅ 真機 60 秒遊玩（RTX 3060 + headless Chrome）：殭屍正常生成（20→31 隻）、玩家正常得分、引擎時間正常推進、零 runtime 錯誤、零資源 404（僅慣有的 favicon 404，與本次無關）
  • ✅ 畫面截圖檢查：場地／殭屍／陀螺材質齊全，無破圖、無缺貼圖色塊
  • ✅ 密鑰掃描：乾淨（一次檔名誤報已排除）
合併建議：這個結構分支是「地基」，建議先合回 main；其他進行中的分支（軌跡掃掠修復 feat/swept-collision、GameEngine 拆檔）再 rebase 上來，避免大家對舊路徑做工。合併順序等蔡拍板。