歷史記錄 · 2026-05-28¶
重大重構里程碑¶
2026-05-28 ─ 建模參數表三輪複審（spec 細項清理 + 常數命名 + 跨檔對齊）¶
動機：二輪定案後再做一次完整 spec consistency 掃描；找到 6 個高 / 8 個中 / 3 個低優先級瑕疵，其中 3 個含使用者澄清後撤回（H3 飛越段 b-soft 沒問題、H4 roller required ❌ 是先前刻意決定）。
| 項 | 變動 | 位置 |
|---|---|---|
H1 material vs materials[] 分層釐清 |
§2 表 desc 補「material = main-mesh 主材質(always 必填) / materials[] = sub-mesh 覆寫」;單 sub-mesh / 全同材質可只填 material |
建模參數表 §2 |
| H2 場地主 material fallback | §8 開頭補註：場地沿用 §2 material（main-mesh 預設、必填）;§8.5 改成「sub-mesh 個別覆寫,未覆寫 fallback 主材質」;標題從「所有 part 通用」改「零件 + 場地共用」 |
建模參數表 §2 / §8 / §8.5 |
| H5 launch bullet 統一沿 Axis +Z | §3.7.3 補:bullet 子節點 transform 僅定發射起點,飛行方向統一 Axis +Z | 建模參數表 §3.7.3 |
| H6 weapon_mechanism general 衍生模式釐清 | §3.7 表 weapon_max_angle_deg required 改「weapon_mechanism: general + 有 Pivot 必填」;補一段說明 general 由 Pivot 存在與否衍生 rotate / push |
建模參數表 §3.7 |
| M1 K_battery_capacity 常數命名 | auto_capacity_mah 從 × 50 改 × K_battery_capacity（K 預估 50,mAh/cm³,與 K_battery_output W/cm³ 不同物理量）;跨 3 檔對齊（建模參數表 / 零件與場景 / 編輯器操作） |
建模參數表 §3.3 + 零件與場景 §6 + 編輯器操作 §3 |
| M2 conditional required 三類規範 | §1 補一段：required 表達為 ✅ / ❌ / <條件> 必填（如「active 必填」、「rain/snow 必填」）三類,「必有值」與來源無關 |
建模參數表 §1 |
| M3 chip kinetic_ratio 跨檔指向 | §3.6 skill_slots[] desc 補「kinetic_ratio = battery declared_output_w 比例」+ 指向 算式表 §2 / §5 |
建模參數表 §3.6 |
| M4 相鄰 RoutePoint 重合閾值 | §8.2 補:相鄰中心距 < 100mm 視為重合;例外:fixed + loop 時 RP1 ↔ RPn 允許重合（loop 定義）;禁止:恰 2 點時 RP1 ↔ RPn 重合（route 退化拒收） | 建模參數表 §8.2 |
| M5 motion_curve 適用範圍精確化 | §9.2 表頭「適用 entity_type」→「適用條件」;open_duration_ratio desc 補「僅 step 有停留語意」;physics 補「visual_only 僅 decoration,kinematic_* 強制 default」 |
建模參數表 §9.2 |
| M6 conveyor forward 軸定義 | §9.2 conveyor_velocity_m_s desc 補「沿 entity 自身 -Z 軸(Blender forward 慣例,與 RoutePoint forward 一致)」 |
建模參數表 §9.2 |
| M7 K_stress_burst_factor 常數命名 | §9.3 破壞行為 ultimate × 1.5 → ultimate × K_stress_burst_factor（K 預估 1.5） |
建模參數表 §9.3 |
| M8 MAX_CHAIN_SEGMENT 常數命名 | §3.7.2 + §5.3 兩處的「32 segment」改 MAX_CHAIN_SEGMENT（預估 32） |
建模參數表 §3.7.2 / §5.3 |
| L1 玩家上限公式對齊 | §8.2 從 floor(width_mm / 180) 改與 §5.4 同的 floor(RP1.width_mm / (130 + 50)) clamp 至 MAX_PLAYERS(8) |
建模參數表 §8.2 |
| L2 Stage 2 extras 設定清單簡化 | §10 流程 「玩家設 GLB extras（material / skill_slots / ...）」→「依 type 走 §2 + §3 各 part type 表」（避免羅列遺漏） | 建模參數表 §10 |
| L3 「水平面」定義 | §6.4 補「水平面 = chassis local X-Z 平面(地面接觸面慣例,不受重力方向影響)」 | 建模參數表 §6.4 |
H4 roller auto_hinge required 修正 |
二輪 C1 條原以為「roller 可能是固定滑塊」維持 ❌,使用者澄清 roller 恆轉動(與 tire 同);required ❌ → ✅,desc 同步改「同 tire,恆轉動必為 true」 | 建模參數表 §3.5 |
使用者澄清撤回的 2 項：
- H3 飛越段著陸 b-soft 邊角：依使用者裁決「空中不判、落地有路徑就可判」收斂，原提案為過度設計
- 先前對 K_battery_capacity「不能整合」的記憶（查證無此前例;motor/battery K 是相同 W/cm³ 故對稱、capacity 是不同物理量 mAh/cm³ 故獨立,但加常數名無阻礙）
反向修正：
- H4 roller required:二輪 C1 條維持 ❌ 的決定基於誤判「可能是固定滑塊」,使用者本輪澄清 roller 恆轉動,撤回該決定改 ✅(與 tire 對稱)
2026-05-28 ─ 建模參數表二輪複審（route spline + 表面貼齊 + B 系列 + 編輯器操作獨立成檔）¶
動機：第一輪 6 項定案後使用者再次逐項複審 建模參數.md，發現 2 個明確不一致 + 4 個值得討論的語意模糊 + 2 個小瑕疵；討論過程中 B3 從「幾何方向」演化到「自訂切線 + spline」再到「貼 mesh 表面」最終方案。
| 項 | 變動 | 位置 |
|---|---|---|
A1 type enum 補 track |
§2 type 欄 desc 從 8 個零件類別補 track（場地）；解決 enum 與「type === "track" 走場地解析」之間的不一致 |
建模參數表 §2 |
| A2 motor/battery auto required 標記修正 | auto_input_w / auto_capacity_mah 從 required ❌ 改 ✅（volume 必算得出 → 符合 §1 正交表的「✅✅ 一定算得出」） |
建模參數表 §3.2 / §3.3 |
| B1 width / deviation 合一 | 查證 b-soft 實際只用 deviation_mm、width_mm 的「走廊寬」空轉、auto_narrowest_path_mm 是不同概念（mesh 幾何）→ 合一為 width_mm（車道全寬），b-soft 邊界 = spline 中心線 ± width_mm / 2；移除 deviation_mm |
建模參數表 §5.4 / §8.2 + 遊戲機制 §12 + 零件與場景 §11.1 + UGC機制 §跑道結構 |
| B2 passive 武器磁源 = 場景物件模型 | active magnet 武器（weapon_mechanism: magnet）：N 極 = Axis +Z、強度 = kinetic_ratio × battery（動態）；passive 武器（無 weapon_mechanism）= 同場景靜態磁源（magnetism_role: source 材質 + magnet_source_strength_n、N 極 = sub-mesh 法向、強度固定）；passive 仍占 chip weapon 槽且填 kinetic_ratio（目前空轉，為未來「被動武器加持」機制保留欄位以免 GLB 重上鏈） |
建模參數表 §3.7 / §5.2 |
| B3 RoutePoint 自訂切線 + spline + 表面貼齊 | route 從 polyline 改為依各點 (position, forward) 插值的 Hermite spline，創作者可少量點做順曲線。RoutePoint 永遠貼 mesh 表面（±5mm）、forward 切線約束在表面切線平面（1 DOF 繞 surface normal）、up 軸自動取 surface normal（支援 banked / 翻滾管道 / 立體迴圈）。飛越段（中間無 mesh）創作者自然放不了點 → spline 浮空、b-soft 僅當車「在表面」時觸發（物理 contact + 100ms hysteresis）；空中段不檢核，重力兜底。終點正向 RP(n-1) → RPn 幾何 → RPn.forward 自訂切線（與起跑朝向對稱）。新 auto 欄位 auto_route_polyline_3d（Stage 3 等弧長預採樣，runtime b-soft 查最近點用） |
建模參數表 §5.4 / §8.2 / §8.6 + 遊戲機制 §12.1 / §12.2 + 零件與場景 §11.1 + UGC機制 §跑道結構 + 流程/UGC上傳流程 §2.1 |
| B4 lap_mode override 範圍 | edit 欄補「僅 fixed 可覆蓋；open 鎖 linear 不可覆蓋」 | 建模參數表 §8.1 |
C1 tire auto_hinge required 修正 |
tire 恆轉動必有 hinge → required ❌ 改 ✅（roller 維持 ❌，可能是固定滑塊） | 建模參數表 §3.4 |
| C2 §4 auto_* required 慣例補註 | §4 開頭補一段：幾何 / 質量類恆算得出 = ✅；可能無值者（thermal_limit / volume_estimated / inferred）= ❌；auto_feature_deviations 恆寫（可空 []）= ✅；auto_fragments Stage 3 預烘焙 = ✅ |
建模參數表 §4 |
| 編輯器操作獨立成檔 | Stage 2 編輯器互動（零件 + 場地共用、PC / Mobile 手勢、modeless 設計、相機 orbit、切線把手、材質 paint、Empty 拖放…）抽離出來成 編輯器操作.md；流程/UGC上傳流程 §2.1 縮減為純資料層狀態轉移（保留加點 / 刪點 / 刪線 + 新增「旋轉切線」op）+ link 到新檔；新檔含完整 §1 通用 + §4.1 RoutePoint，其他章節 TODO 後續逐章補 |
新建 編輯器操作.md + 流程/UGC上傳流程 §2.1 |
設計演化簡記（B3 三輪）：
- 初版（2026-05-27）：route = polyline；終點方向 =
RP(n-1) → RPn幾何；曲線靠多點折線逼近 - 中版：route = Hermite spline；每點自訂 forward 切線；曲線從幾何切線插值
- 定版：spline + RoutePoint 永遠貼 mesh 表面；切線約束在表面切線平面（1 DOF）；up 軸自動 = surface normal；飛越段 spline 浮空 + b-soft 「在表面才檢核」物理 contact 判定 + 100ms hysteresis；採業界編輯器慣例（Trackmania / Forza track maker）
動機：使用者逐項複審 建模參數.md 提出 6 個疑問，討論後定案。
| 項 | 變動 | 位置 |
|---|---|---|
| Q1 hinge 軸來源 | 補註：Mount 是帶 transform 的 Empty（非單純點），tire/roller hinge 軸 = chassis 端 mount empty 指定 local 軸（慣例 +X，auto_hinge 對應）；tire canonical 固定（檢核恆過）、roller 自訂（拖放含朝向，夾角檢核實際只對 roller 有意義） |
建模參數表 §6.4 |
Q2 track.type 改唯讀 |
edit ✏️→🔒：type 由有無走廊（編輯器有無連線）衍生（無→open / 有→fixed），非獨立選項；lap_mode 維持 ✏️ 可覆蓋（幾何啟發法可能誤判，鐵則 3） |
建模參數表 §8.1 |
| Q3 version 不在上傳擋 | loader 三分支界定為「僅載入已上鏈資產時」；Stage 1 上傳解析不走此分支（原始 GLB 尚無 marker）；open4wd_version 於上鏈寫入、GLB 既有值一律覆寫不採信（同 type 定案邏輯） |
建模參數表 §2/§8/§10 + 版本規範 §15 |
| Q4 場地起終點模型統一（廢 StartLine/FinishLine + Waypoint→RoutePoint） | 起終點 open / fixed 統一：徹底移除 StartLine / FinishLine 與 Waypoint，改用 RoutePoint_<n>（track.route[]）：RP1 = 起點、RPn = 終點（open / fixed 共用）。open vs fixed = 走廊（b-soft）關 / 開（= 編輯器無線 / 有線）；open 恰 2 點、fixed ≥ 2 點。單一規則（消掉所有 open/fixed 分支）：玩家上限 RP1.width_mm、終點方向 RP(n-1)→RPn、掉出 fallback RP1、loop RP1↔RPn < 1m；新規則「相鄰 RoutePoint 不可重合（否則方向未定義）」。type 🔒 由「有無走廊線」衍生。編輯器 3 操作（加點 / 刪點 / 刪線；加點一律連線、open 僅靠刪線達成）+ 清空（暫定可砍）寫進流程文檔 |
建模參數表 §5.4/§7.2/§8.1/§8.2/§8.6/§9 + 遊戲機制 §12.1/§12.2/§12.3 + 流程/UGC上傳流程 §2.1 + UGC機制 §9 + 零件與場景 §11 + 其他 §3 |
| Q4 命名 | Waypoint_<n> → RoutePoint_<n>、track.waypoints[] → track.route[]、WP→RP（中性名;理由:「route/way」對 open 略 over-claim 但在 fixed 走廊語境讀起來最達意，勝過純中性的 TrackPoint） |
跨 6 spec 檔 |
| Q5 天氣視覺 + 遮蔽 | 維持 3 modifier 乘子模型（查證：來自 2026-05-24 回填、有「dirt+rain 湧現」設計理由，非殘留；使用者誤記的「丟水/雪球→貼圖→依材質」實為武器 deploy 系統）。新增 patch 視覺 = 世界座標色偏（rain 壓暗/snow 提亮）對齊物理範圍、純視覺；遮蔽（屋頂/橋/隧道）物理+視覺都吃，由上鏈烘焙的確定性曝露圖 auto_exposure（沿重力反向逐 surface）決定，僅靜態幾何 |
建模參數表 §8.3/§8.6 + 算式表 §10.2 |
| Q6 零件全 sub-mesh 必有材質 | 零件未指派材質的 sub-mesh 自動預設為主 material（§11 原則）；Stage 3 斷言無 collider sub-mesh 缺材質；不允許部分指派（防以未指派 sub-mesh 規避碰撞/損壞）。與場地「至少 1 sub-mesh」不同（場地有 visual_only 無 collider mesh） |
建模參數表 §2 |
動機：使用者問「場地有 open4wd_track_version，零件是不是也要？」→「上傳/編輯/上鏈已統一，能不能 type=分類 / version=版本 統一」→ 演變成整套 UGC 資產 schema 版本系統。與既有「A 軸 client build 版本」（6 欄位 checkCompatibility）區分，新增「B 軸：每顆 GLB extras 符合哪版 schema」。
廢除欄位：open4wd_track_version（場地專屬識別 marker）→ 由統一 marker open4wd_version + type: "track" 取代（零件與場地共用）。
核心設計決策：
| 項 | 決策 |
|---|---|
| 識別 marker | open4wd_version（Root Extras，per-type 命名空間）+ type enum（8 零件 + track）；loader 三分支（無 marker 拒載 / track / 零件） |
| bump 原則 | 破壞性（增刪欄位 / 語意 / 演算法 / 必填無安全預設）→ 棄用；非破壞（純數值 / 位置）→ 只提示 |
| 生命週期 | 活躍 → 棄用（仍可用、含棄用件則該 type 全場降版本）→ unusable（picker 不出現、仍可被 fork） |
| 三升級分類 | ① 自動 / ② 需手動編輯 / ③ 無法升級 |
| 降版本運算 | 只換 per-asset「extras→物理輸入映射」、跑當前引擎、不綁 Rapier；不變式：跨資產聚合走 derive_logic（A 軸全場一致）；降版目標 = 最低非破壞相容類最高版；每破壞牆附雙向遷移（②人工有損存 pre-edit 快照） |
| 動態最低支援版 | 非靜態常數，ledger 衍生（DEPRECATED_TO_UNUSABLE_THRESHOLD=3、數「不同創作者」、單調 ratchet）；以 deriveStateAt(checkpoint) pin 進房算 |
| 共識 | 開房 pin ledger checkpoint，版本閘門對快照算、後加入 peer 須 sync、開賽前重驗 |
| 兩種提示 | 含棄用件→「降版本運算」（改物理，強）；混非破壞舊版→「數據可能有差異」（吃預設，軟） |
| 遷移流程 | schema 定於「上鏈提交時」（非編輯器開啟時）、落後先 shim；草稿 reload 後 shim；鏈式遷移可組合；版本 yank（壞版專用，唯一強推遷移） |
| 經濟 | 版本後繼升級上鏈免費（限真後繼）；版本後繼血緣（≠ fork）不新增分潤層，評分/使用次數/fork 樹位置三項在血緣節點層 aggregate |
| ledger | 新增 AssetVersionUpgradeEvent（新 CID → 舊 CID 後繼邊）；AssetVersionDerivedState（動態 min + 各 CID 版本狀態） |
| replay | 暫不實作；已知相依：未來加入需重訂舊路徑保留政策 |
改動檔案（12）：版本規範（補 B 軸 §14–26）/ 建模參數表（§2 marker + loader、§8 廢 track_version、§10 上鏈寫 version）/ 零件與場景（§11 識別 marker）/ UGC機制（新增 §10）+ 流程/UGC上傳流程（Stage 3 + 後續可改）/ 車輛組裝（§13 版本相依）/ 賽內機制（§1.6 preRaceVersionCheck + §4 開賽前無罰退出列）/ 經濟系統（§9 升級免費列 + §8.1b 血緣）/ 版權（§3.5 兩種邊 + §3.6 fork 救援）/ 資料系統（§3 事件 + §4 DerivedState）/ 程式參數表（§3 THRESHOLD + §11 動態 min 註）/ 總覽（版本規範指向）。