歷史記錄 · 2026-07-12¶

月份索引｜歷史記錄

重大重構里程碑¶

2026-07-12 ─ 公開發布合規、GLB 交接契約與可重現測試門檻¶

決策檔：D-20260712-02

公版 GLB 屬維護者最後補入的正式資產，不加入 ignore，也不得用合成／假 GLB 冒充；一般開發與 PR 在缺檔時仍可 build／test，開發資產檢查只驗目前存在檔案，獨立嚴格 release gate 則必須在清單不完整時明確失敗。維護者補齊 GLB 後，才重跑嚴格資產檢查、 production build 與完整 E2E，再推 private、持續本機優化，最終轉 public；README 與貢獻指南留到本機功能驗證後最後補。

CI／本機基線固定 Node 24 與 frozen lockfile，coverage 門檻為 lines／functions／ statements 80%、branches 75%；property、八人 in-memory mesh、determinism、fuzz 與 performance 使用固定 seed／可重播失敗，且不得觸外網。Playwright 覆蓋 Chromium、 Firefox、WebKit、Pixel 7 與 iPhone 14。設定以 SettingsService 為持久化邊界，包含可深連分類、pinning 節點管理、TURN、鍵盤／手把 binding 與 PIN gate 的原子 reset；無效 URL、衝突或 PIN 失敗不得留下部分持久化。這一階段不製作、修改、選擇或判定最終 GLB 授權，也不執行發布或 Git 寫入操作。

2026-07-12 ─ 編輯器體積分割幾何工具落地：拼接（assembly）＋切分（split，平面切＋封蓋）→ 水密 sub-solid（測試 1036）¶

決策檔：D-20260712-01

Stage 2 編輯器新增兩種體積分割幾何工具，作為在瀏覽器內產生多零件 / 多材質資產（數個水密 sub-mesh node）的手段——取代並凌駕本檔同日「材質模型統一為水密 sub-mesh」條所述「瀏覽器編輯器不提供把 fused solid 切成多材質的功能」限制（該限制隨切分工具落地作廢）。

拼接（assembly，由下而上）：匯入多個各自完整水密的 GLB → 逐一 position 定位 → 指定父 / 子關係（如把數顆 bullet 指為 launcher_body 子件）→ 合為單一資產 GLB，每個來源實體成為結果內一個水密 sub-mesh node。實作＝src/editor/pipeline/assembly.ts、UI ＝src/pages/editor-page/assembly-panel/。

切分（split，由上而下：平面切＋封蓋）：沿軸向平面（X / Y / Z + 位置）把選中的水密 mesh node 切成兩片 → 對每個開口邊界環三角化補面（處理中空 / 環狀多邊界環）→ 每片成為封閉水密實體、封閉體積正確 → 質量正確（整體 Σ 守恆）；切面沿用該片材質、每片成獨立 node。僅對水密 node 開放（非水密無法保證封蓋後體積正確）。實作＝src/editor/geometry/plane-cut.ts＋cap-triangulate.ts、UI ＝src/pages/editor-page/split-panel/。

⭐與已移除 cluster-paint 的本質區別：cluster-paint 分割的是表面（色塊 patch、open surface、無獨立體積）→ per-region 質量 / 熱無從定義 → 已移除（本檔同日「材質模型統一」條）；切分分割的是體積（切＋封蓋 → 封閉水密實體）→ 體積 / 質量 well-defined。拼接與切分兩者產物皆為水密 sub-mesh，與 canon「材質 = 水密 sub-mesh、部件質量 = Σ(sub-mesh 水密體積 × 密度)」（材質表.md §7）完全一致。

目前範圍（僅落地部分入 canon）：切分為軸向（X / Y / Z + 位置）、拼接僅 position 定位；自由朝向切面 gizmo、即時雙片預覽、拼接旋轉 / 縮放尚未建置（列為 playtest 後續精修）。

跨檔：UGC機制（§3.7 反轉「編輯器不提供切成多材質」→ 三路徑〔瀏覽器切分 / 瀏覽器拼接 / 外部工具〕＋體積 vs 表面原則；§3.8 launch 武器 route (a) 純瀏覽器經切分可行、route (c) 拼接為實功能）／編輯器操作（§2.3 blockquote 反轉「編輯器不把 fused solid 切成多材質」、新增 §2.4「幾何工具：拼接／切分」、原 §2.4 數值欄位 → §2.5、§6 對接表「sub-mesh 切割」→「切分·拼接」）／程式架構/editor.md（本檔角色＋模組結構 geometry/＋pipeline/assembly＋幾何工具段）／程式架構.md（editor 行補「幾何工具（拼接·切分）」）。未改（已一致）：材質表.md §7（水密 sub-mesh mass 模型 Σ(sub_volume × density)、整顆體積 = Σ sub-mesh 水密體積）本就吻合切分 / 拼接產物；流程/UGC上傳.md §2「多材質 sub-mesh 對應」中性不受影響。測試 1036 全綠。下一步不變＝author 24+3 GLB→首次本機測試（不 commit／push）。

2026-07-12 ─ 材質模型統一為水密 sub-mesh：移除 K-means 色域分群 / paint 塗刷工具（materials 改逐 sub-mesh 指派）¶

決策檔：D-20260712-01

移除 K-means 色域分群材質工具（src/editor/clustering/＝cielab.ts／face-colors.ts／kmeans.ts 全刪，含 CIELAB↔sRGB 互轉、CIEDE2000 全式、確定性 K-means、merge／split／repaint、connectedRegion、k 滑桿 4–12 與「預估 sub-mesh 體積」列）；材質模型統一為水密 sub-mesh（node）。取代里程碑 4b（本檔 2026-07-07 條）落地的分群工作流。

根因：色域分群產出的是表面色塊（open surface patch、無獨立體積）——per-cluster 的「預估 sub-mesh 體積」把「表面顏色群」誤當「體積 sub-mesh」，質量／熱容 per-cluster 從一開始就無定義（材質表 mass = Σ(sub_volume × density)、thermal mass-weighted 皆假設每單位是真實 solid）。統一為水密 sub-mesh 後，質量／摩擦／restitution／stress／fatigue（逐接觸 sub-mesh）／thermal（mass-weighted）／磁性（逐 sub-mesh）全部 well-defined，且零件、場地表面、場地 entity 三者一致。

新模型：多材質 = 一顆 mesh 由數個各自水密的 sub-mesh（node）組成、每個 sub-mesh 指派一種材質；單一 fused mesh（如 Tripo AI blob）= 單一材質，要多材質須先把 mesh 拆成數個水密 sub-mesh（如 Blender），瀏覽器編輯器不提供把 fused solid 切成多材質的功能。Stage 2 材質域 UI ＝主／fallback 材質選單＋逐 sub-mesh 材質下拉（每 node 一列、預設「繼承主材質」）；零件與場地共用同一 UI／模型。實作＝per-node materialOverride ＋ finalize 逐 node bake（src/editor/clustering/ → src/editor/material/）。

跨檔：UGC機制（§3.7 四階段 cluster-paint 表 → 「fused = 單一材質、多材質 = 水密 sub-mesh、Stage 2 逐 sub-mesh 指派」；§9.2 指標「切割／材質指派」→「材質處理」）／編輯器操作（§0 即時預覽去「材質 paint」、§1.6 視覺層「材質 cluster 著色」→「材質 sub-mesh 著色」、§1.7 進場去 K-means、§2.3「材質指派／paint」全面改逐 sub-mesh〔主／fallback＋per-node dropdown〕、§3.6 banner「分群提示」→「材質未指派提示」、§4.5 場地「通用 paint 流程」→「通用材質指派流程」）／程式架構.md（editor 行 K-means → 逐 sub-mesh 材質指派）／程式架構/editor.md（本檔角色、模組結構 clustering/ → material/）。未改（已一致）：材質表.md §7 早已是水密 sub-mesh mass 模型（每 sub-mesh 各自水密；整顆體積 = Σ sub-mesh 水密體積）＝無矛盾；流程/UGC上傳.md §2「多材質 sub-mesh 對應」本就中性；建模參數.md §8.5 materials[] 逐 node 覆寫模型本就正確；算式表.md 無 CIELAB／ΔE2000 formula（該公式僅存於已刪的 clustering 模組碼、非算式表）＝無移除項。grep 驗證：分群／K-?means／CIELAB／ΔE／色域／色群／塗刷／cluster-tint／預估 sub-mesh 體積 於權威檔全清；殘留僅本檔歷史（里程碑 4b／4a 條與 §1 舊里程碑索引 §9.2.1 快照）、IPFS Cluster（部署／pinning）、美術提示詞 component cluster／painted、資料系統事件 partitionKey 分群、decimate 的 vertex-clustering（皆非色域分群、保留）。下一步不變＝author 24+3 GLB→首次本機測試（不 commit／push）。

2026-07-12 ─ 觀戰 viewer flow＋重連 catch-up sync＋編輯器場地空間編輯（三組新增功能落地）¶

三組新增功能落地（皆純核心＋傳輸埠注入、可測）。

⭐觀戰 viewer flow（src/spectator/＋src/pages/watch-page/）：純核心（SpectatorSession 插值／checkElimination 淘汰／SpectatorBroadcaster open-only 廣播／evaluateSpectatorJoin 進房閘）＋signaling／WebRTC 埠注入；隨房主星狀拓撲——joinAsSpectator（向房索取推薦訂閱源→撥號取回單向入站通道→逐幀插值泵）回 SpectateHandle（渲染幀／換場／終局三路訂閱＋收攤冪等）、host 端 SpectatorServer 逐訂閱者開單向通道。watch/:id 頁掛五模式攝影機 rig（CameraMode＝follow／third-person／free／overhead／finish-line）。觀戰者不簽章、不跑物理、計時本地 ephemeral 不入帳本（spec：程式架構/spectator.md／流程/觀戰.md）。

⭐重連 catch-up sync（best-effort）：15s 重連窗（RECONNECT_TIMEOUT_MS）現驅動真正的狀態追趕——mesh 重連訊號接當前回合 rollback 引擎（currentRollback 穩定接點、回合間 null）：落後端 sync-request→對端 sync-response（saveState() 快照、每 drain 每請求者至多一筆、不轉發不改本端進度）→applyCatchUp＝loadState(snapshot)＋currentFrame 前跳＋緩衝重置＋修剪已封存舊輸入。不重播、不觸發回滾窗、不升級 desync；快照幀不新於本地即忽略（絕不倒退）（spec：程式架構/network-sync.md）。

⭐編輯器場地空間編輯（src/pages/editor-page/domains/）：route／checkpoint／killzone／respawn／entity 五域各建為編輯器元件（route-editor／checkpoint-editor／killzone-editor／respawn-editor／entity-editor，含 HTML／SCSS／spec、驗證接 editor/validation/track-rules.ts）＋逐 sub-mesh 材質指派 UI（主／fallback 選單＋per-node 下拉；材質模型見同日條）（spec：程式架構/editor.md／編輯器操作.md）。

下一步不變＝author 24+3 GLB→首次本機測試（不 commit／push）。