跳轉到

D-20260807-03｜輪組 Revolute 接觸驅動

2026-08-11 關聯追補：正式 part collider 已由 D-20260811-04 修訂為逐 sub-mesh deterministic convex proxies；Mount frame 的 hinge anchor／axis 規則仍有效。

背景與驅動力

車輛 collider 掛載位姿與公版輪軸修正後，runtime 仍把所有零件固定在單一 dynamic body， tire／roller 也只是 cuboid。這個近似沒有輪胎自轉、輪地牽引或導輪貼牆滾動，因此正式車輛 只能由直接 chassis impulse 前進，碰牆時也會以固定盒體鎖住。它與既有 auto_hinge: true、 Mount +X 軸及無玩家方向控制的賽事模型不一致。

同時，創作者可提交任意複合旋轉與刻意不對稱、特殊造型的輪組。公版資產的薄軸方向可作為 builtin 品質閘，不能被提升為所有 UGC 的 runtime 幾何假設。

考慮過的選項

  • 保留直接 chassis impulse，只增加自由轉動的視覺 wheel joint：能改善畫面與部分牆面接觸， 但推進仍繞過輪胎摩擦、損壞與地表 grip，物理語意分裂，否決。
  • 遇牆時加入 tangent force、轉向或 teleport wall-follow correction：可讓既有案例繼續前進， 但屬隱藏導引，會掩蓋場地與碰撞問題，且無法由正常接觸解釋，否決。
  • primary body 加每顆 tire／roller auxiliary body，以完整 Mount frame 建 Revolute joint，並讓 馬達輸出經 tire contact 傳到場地（採納）。

決定

  • chassis 與非 hinge 零件保留一個 primary dynamic body；每顆 tire／roller 依原始 part index 建立獨立 auxiliary dynamic body、圓柱 collider 與 contact-disabled Revolute joint。各 collider 使用該 part 烘焙質量，總和仍須等於整車質量。
  • hinge anchor 只取 chassis-side Mount position，axis 只取其 local +X；attachment 固定為 chassisMount × inverse(partMount)。runtime 不從 AABB 最短軸、mesh、builtin 姿態或圓盤外觀 推斷軸向。合法的任意 part-side Mount 旋轉與非對稱／特殊幾何均保留。
  • AABB 只保留為縮減測試 fixture；hinge anchor／axis 仍由完整 Mount frame 決定。
  • 既有 drive_impulse_ns 是單幀最大前向動量預算。對 n 顆未損壞 tire，先取 requested_share=drive_impulse_ns/n，再以實際 contact manifold 的 normal impulse 與接觸 材質合成摩擦鉗制；無接觸可空轉但不產生 primary 線性推力。輪軸角速度達 surface_top_speed_mps/radius 後不再追加驅動。
  • tire friction 與實際 surface friction 採 Rapier Average；同輪多接觸與獨立 rolling resistance 由 D-20260811-04 修訂。tire／roller restitution固定採 Min，避免 高回彈輪組把正常落地變成反覆彈跳。roller 永遠被動；損壞 tire 不分配驅動，全部損壞時 推進為 0。
  • 正常 vehicle 宣告 tire／roller 卻缺完整 hinge descriptor 時 fail closed。只有刻意不含 tire part 的縮減 physics fixture 保留 direct-primary compatibility fallback。
  • scale、freeze、teleport、owner／damage、接觸與 part world-position 都涵蓋 primary 與所有 auxiliary bodies。snapshot／rollback 驗證 joint 數量、parent、type、anchor、axis／frame、 contacts、limit 與 motor immutable state；所有 body 的 tire spin 進入 state hash。

後果與影響

輪胎推進、材質 grip、輪胎損壞與導輪牆面接觸改由同一套可觀察物理成立，不再需要隱藏轉向 或脫困 teleport。代價是每車增加四個 tire body、零至六個 roller body 及同數 impulse joints， world operations、rollback topology 與效能門檻都必須涵蓋完整 assembly。

本決策部分修訂 D-20260524-03 的單一 world／snapshot 實作邊界、D-20260524-04 的 Mount frame 使用範圍、D-20260612-01 的軸向慣例與 D-20260807-02 的 box 期直接推進。現行算式與 runtime 結構分別見 算式表.md 第 2 節 與 physics-engine.md 第 2.2 節。場地 route／checkpoint／surface 校準仍由 issue 000250 處理；正式 weapon actuator／payload／projectile 拓樸仍由 issue 000251 處理，兩者 不得以本決策的輪組測試替代。