D-20260730-01|GLB 與 runtime 統一採公尺 canonical world¶
背景與驅動力¶
glTF 的線性距離以公尺表示,但現行 sanitizer、editor 與部分 runtime adapter 把 accessor 數值直接當成毫米。標準 glTF 因而可能在匯入時被誤判為退化幾何;同一世界尺寸也會因 exporter 把倍率寫進頂點或 node transform 而得到不同檢核結果。另一方面,local save、檔案匯出與上鏈 目前分別處理 marker 與壓縮,無法保證相同編輯狀態得到相同 GLB bytes。
D-20260703-04 已確立不可信 GLB 必須在 Worker 內先做結構安全 admission,但當時沒有定義 admission 前後的幾何單位邊界。本決策補上 該邊界,並把 editor、runtime 與 physics 的世界座標收斂為同一語意。
考慮過的選項¶
- 內部繼續使用毫米,只在 glTF 匯入與匯出各轉一次:每個 fork、reopen、physics loader 與 fingerprint consumer 都必須辨識轉換狀態,容易重複縮放或漏轉,棄。
- 依 AABB 大小自動猜 m/cm/mm:小型公尺模型與大型毫米模型可能具有相同數值範圍,無法 可靠判斷,棄。
- glTF、editor、runtime、physics 與所有 canonical 出口一律使用公尺;外來單位只在第一次 匯入由明確來源設定正規化(採納)。
決定¶
- 尚未發布的資產 schema 直接以唯一
open4wd_version=1起始;GLB 頂點、node transform、 editor working scene、持久化空間欄位、runtime 與 physics 世界座標一律採公尺,空間欄位 使用_m/_m2/_m3命名。畫面顯示或 spectator/network 的整數量化可以使用毫米作為 傳輸表示,但不得回流成資產或遊戲世界的第二套單位。 - 不建立舊毫米版本或 v1→v2 遷移;非當前 marker 一律不支援。無 marker 的一般 glTF預設 公尺,創作者可明確覆寫來源為 cm 或 mm。系統不得依模型大小猜來源單位。
- source admission 只處理結構、資源與有限值安全上限;單位正規化與 scene transform 解算後, canonical strict validation 才套用 AABB、退化面、貼圖、collider 與 per-type 規則。這是對 D-20260703-04 的分層細化,不改變 「不可信 GLB 首次解析必須在 Worker」的不變式。
- 尺寸修正只允許正值 uniform scale。自動適配與賽道時長建議屬 editor guidance,不進共識 protocol;所有空間資料必須原子縮放,UV、時間、角度、速度、加速度、力與材質係數不縮放。
- local save、檔案匯出與上鏈共用唯一 canonical finalizer;三者使用相同已帶 current marker、 已重算衍生量並完成 Draco/KTX2 與 strict validation 的 GLB bytes。鏈上流程只在 GLB 外增加 similarity、IPFS、費用與 ledger 操作。
後果與影響¶
標準 glTF 可直接依公尺進入編輯器;違反 glTF 單位慣例的來源仍可由創作者顯式修正。完成一次 canonicalization 後,local reopen、匯出重匯與 fork 不再重做單位或 provisional fit。
代價是 editor facts、runtime/physics interface、fingerprint 與既有測試必須同批切換;source admission 與 strict validation 也必須拆開。完整現況契約分別由 建模參數.md、UGC 上傳流程、 editor 架構、security 架構 與 physics-engine 架構 維護。