場地¶

本檔是建模參數的分冊 authority；穩定總入口與既有章節錨點見建模參數.md。

8. 場地 GLB Root Extras¶

識別 marker：場地與零件共用統一 marker open4wd_version + type: "track"（見 §2 與版本規範.md §15）。場地無專屬識別欄位，由 type === "track" 走場地解析分支；載入已上鏈資產時沒有 open4wd_version 的 GLB 拒絕載入（上傳解析不適用，見 §2）。

主材質 material 沿用 §2：場地與零件統一在 §2 表填 Root Extras material（main-mesh 預設材質、必填、fallback 用），本節不重複；sub-mesh 個別覆寫見 §8.5 materials[]。未在 materials[] 出現的 sub-mesh fallback 到 material（避免漏指派 sub-mesh 無材質）。

〔TRACK-R-001〕 場地的 route／checkpoint／empty 關聯、lap mode、重力／磁源、天氣、材質、 entity／destructible／kinematic、AABB 與資源預算等正式限制，必須由 canonical finalizer 與首次 ledger content admission 對實際 GLB 呼叫同一套純 canonical validator；只有 reject findings 是協定拒收，編輯器 warn findings 不得升格。首次 admission 還必須重建完整 typed TrackPhysicsManifest、核對 CID 所指 bytes 內的 version／digest／schema，並成功持久化精確 (CID, version, digest) receipt；receipt 寫入失敗即 fail closed。race runtime 只接受 ledger record、 embedded manifest reference 與本機 receipt 完全相符的 typed AdmittedTrackAsset，不得重跑幾何、回讀 raw extras 或以六欄 track PhysicsFingerprint 代替 manifest 權威。

8.1 跑道結構（`track` 區塊，必填）¶

field	desc	required	auto	edit
`track.type`	`open`（走廊關：全場地自由跑）/ `fixed`（走廊開：b-soft 約束）	✅ 必填	✅ 由有無走廊（編輯器有無連線）決定	🔒 不可編輯（type 是走廊有無的衍生結果，非獨立選項）
`track.lap_mode`	`linear` / `loop`；Stage 2 自動推斷（`RP1 ↔ RPn` 中心距 < `LAP_MODE_LOOP_DISTANCE_M`（1m）且 route ≥ 3 點 → `loop`，否則 `linear`；恰 2 點無法構成迴圈幾何、一律 `linear`；`open` 強制 `linear`）	✅	✅ Stage 2 推斷	✏️ UI 可覆蓋（僅 `fixed` 且 route ≥ 3 點；幾何啟發法可能誤判，例如起終點相近但實為直線衝刺）；`open` 鎖 `linear` 不可覆蓋
`track.route[]`	有序點序列（open 恰 2 點 / fixed ≥ 2 點）；RP1 = 起點、RPn = 終點；陣列順序 = route 順序（權威；empty 名稱僅為識別子），見 §8.2	✅ 必填	❌	✏️ Stage 2
`track.checkpoints[]`	有序 Checkpoint 名單（empty node 名稱陣列）；陣列順序 = 通過順序（權威；名稱僅為識別子，慣例 `Checkpoint_<n>`）；與場上 Checkpoint empty 1:1（Stage 3 檢核，缺對應或孤兒皆拒收，見 §5.4）	❌（無 checkpoint 可省）	Stage 2 編輯器增刪 / 排序自動維護	✏️ Stage 2

lap_count（圈數）非場地 GLB 屬性，為房間設定（1–10，預設 3；見賽內機制.md §1.5）；場地只決定 lap_mode（幾何，由 RP1 ↔ RPn 距離推斷）。

8.2 `track.route[]` 結構（open / fixed 共用）¶

"route": [
  {
    "name": "RoutePoint_1",    // 對應 GLB 內同名 Empty Node（順序首尾 = 起終點；切線從 empty rotation 取得，見下方幾何模型）
    "width_m": 1.5             // 該點車道全寬（RP1 決定玩家上限；fixed 為 b-soft 走廊全寬，沿 spline 弧長線性插值到下一點）
  },
  { "name": "RoutePoint_2", "width_m": 1.5 },
  ...
]

寬度支援沿途變化（窄段、加寬段）；b-soft 邊界 = route spline 中心線 ± width_m / 2（僅 fixed 生效）。

幾何模型（spline + 表面貼齊）：

RoutePoint = position（貼 mesh 表面 ±0.005m，ROUTEPOINT_SURFACE_TOLERANCE_M，Stage 3 檢核）+ 自訂 forward 切線
forward 來源：empty 的 -Z 軸（Blender 慣例）；切線限制在該點 surface 切線平面內（編輯器在表面平面內讓玩家旋轉，1 DOF 繞 surface normal）
route 為依各點 (position, forward) 的 Hermite 三次 spline；切線長度約定 = 該段弦長 × 1/3（deterministic）
局部 frame 的 up 軸 = surface normal（自動，無需創作者設定 → 自動支援 banked turn / 翻滾管道 / 立體迴圈內側）
加點預設 forward = 沿弦投影到 surface 切線平面（不主動旋轉時退化為折線手感）

飛越段（兩 RoutePoint 中間無 mesh）：

創作者自然無法在無 mesh 處放點 → spline 兩端點貼面、中段曲線浮空（編輯器視覺呈現「線飄越坑洞」，業界編輯器慣例）
b-soft 僅當車「在表面」時觸發（物理 contact + 100ms hysteresis；見遊戲機制.md §12.2）；空中段完全不檢核（重力會把車拉回地面），落地後恢復
spline 中段空中曲線形狀不必等同物理拋物線（純視覺，不影響玩法）

起終點與方向（open / fixed 共用）：

RP1 = 起點、RPn = 終點（序列首尾，無獨立起終點 Empty）
玩家上限：floor(RP1.width_m / START_GRID_CELL_WIDTH_M) clamp 至 TRACK_MAX_PLAYERS_HARDCAP（同 §5.4；常數與滿員需求寬度見 protocol.md §3）
起跑格：RP1 position + RP1.width_m + RP1.forward（自訂切線）鋪車
終點正向：chassis COM previous→current 對 RPn 定向平面由負側掃掠至正側；交點須在 RPn 左右寬度內，不使用步末速度
lap_mode：RP1 ↔ RPn 中心距 < LAP_MODE_LOOP_DISTANCE_M（1m，protocol.md §3）且 route ≥ 3 點 → loop（起 = 終），否則 linear（恰 2 點一律 linear，無法構成迴圈幾何）
open = 恰 2 點（走廊關、自由跑）/ fixed = ≥ 2 點（走廊開、b-soft）；恰 2 點 + 自訂切線 + 走廊開 = 直線或單段彎曲走廊
相鄰 RoutePoint 不可重合（spline 段退化 → Stage 3 拒收）：相鄰中心距 < 0.1m（ROUTEPOINT_MIN_SPACING_M）即視為重合；例外：fixed + lap_mode: loop（route ≥ 3 點）時 RP1 ↔ RPn 允許重合（這正是 loop 的定義，見 lap_mode 規則）。特別禁止：恰 2 點時（open 或 fixed 直線），RP1 ↔ RPn 重合會讓整條 route 退化 → 一律 Stage 3 拒收

8.3 天氣（`weather` 區塊，必填可給預設）¶

field	desc	required	預設
`weather.type`	`normal` / `rain` / `snow`	✅ 必填	`normal`
`weather.temperature`	環境溫度（°C，場地創作者可調，各天氣型有範圍與預設）；= runtime `T_air` 的唯一來源（算式表.md §6.1–§6.2）；burn／freeze deploy 先轉為 W 後進同一 heat ledger，不直接改溫度或 `T_air`（算式表.md §6.4）	❌	normal=20 / rain=15 / snow=-5
`weather.wind_speed_mps`	風速（m/s），0–30（`WIND_SPEED_MPS_MAX`），獨立於 type	❌	0
`weather.wind_direction_deg`	風向角（deg）：水平 X-Z 面內繞 +Y 軸、俯視逆時針（0 = +X、90 = −Z）；語義 = 風的吹向（力的方向，算式表.md §10.3）	❌	0
`weather.patch.spawn_rate_per_min`	rain/snow 動態 patch 生成率（0–30）	rain/snow 必填	5
`weather.patch.lifetime_ms`	patch 生命週期（30000–60000）	rain/snow 必填	45000
`weather.patch.radius_m`	patch 半徑（0.2–1.0 m）	rain/snow 必填	0.5
`weather.patch.friction_modifier`	patch 內地表摩擦下降係數（0.3–0.9）	rain/snow 必填	rain=0.65 / snow=0.5
`weather.patch.rolling_modifier`	patch 內滾動阻力上升係數（1.0–2.5；>1 = 拖感變重）	rain/snow 必填	rain=1.5 / snow=2.0

三天氣溫度範圍：normal -20~+40°C / rain +2~+35°C / snow -30~+2°C（重疊 +2°C 給雨夾雪）。

weather.type: normal 時 patch.* 全部不可填（Stage 3 拒收；比照 §9.2 open_duration_ratio「不適用欄位不可填」慣例）。

雨/雪 patch seed 由 matchId + roundIndex + track manifest digest 派生；整數 accumulator、固定最多 8 次候選與穩定 ordinal 見算式表.md §10。物理只修改 tire／roller 對靜態 solid 的 friction 與 rolling resistance；不修改 restitution。

patch 視覺：patch 在地表呈現世界座標色偏（rain 壓暗 / snow 提亮 base albedo），對齊物理 patch 的位置 / radius_m → 確保「看到的影響區 = 實際影響區」（純視覺、不影響物理，無 determinism 顧慮）。貼圖樣式美術自由；環境氛圍 VFX（落雨雪粒子 / 天色）不在功能 spec 規範。

遮蔽（物理 + 視覺一致）：finalizer 沿重力方向只保留每格第一個合格靜態 solid 表面，形成 typed exposure grid；因此橋面／屋頂本身可生成，其下方與隧道不生成。admission 獨立重建並核對；runtime、renderer 與 editor preview 共用 scheduler／descriptors，不讀 raw extras 或各自抽樣。動態遮擋不改 exposure。

8.4 物理環境（`physics` 區塊，必填可給預設）¶

field	desc	required	預設 / 範圍
`physics.gravity_direction`	重力方向單位向量（解析時 normalize）	✅ 必填	`[0, -1, 0]`（GLB 標準 +Y up，「下」= -Y）
`physics.gravity_strength_m_s2`	重力強度（m/s²）	✅ 必填	`9.81`，範圍 1.6–25（月球感 1.6 / 地球 9.81 / 高重力 15）

支援低重力、反重力、橫向重力、斜向重力等創意場地。重力方向影響「掉出場地」三層處理 fallback 方向（見遊戲機制.md § 場地系統）。

8.5 材質指派（`materials[]` 區塊，sub-mesh 覆寫）¶

"materials": [
  { "mesh_node": "TrackSurface_Asphalt", "material": "asphalt" },
  { "mesh_node": "OffRoad_Sand",         "material": "sand" }
]

materials[] = sub-mesh 個別覆寫（單材質場地可留空）。任何 sub-mesh 未在此陣列出現 → fallback 到 §2 Root Extras material（main-mesh 主材質）。場景檢核由 material 的 forbidden_scopes 自動處理（材質表.md §2）。至少 1 個 sub-mesh 對應材質後即可進 Stage 3（含 fallback：若所有 sub-mesh 都未在 materials[] 出現，主 material 即所有 sub-mesh 共用材質、合法）。entity node 不得列入 materials[]（entity 材質為 node-level extras 權威，雙重宣告 Stage 3 拒收，見 §2 優先序）。

8.6 系統自動算出（auto_*，Stage 2 寫入）¶

field	desc
`auto_track_aabb_m`	場地 AABB `[x, y, z]`（檢核 `TRACK_AABB_MAX_M`：x / z ≤ 500 m、y（高）≤ 100 m）
`auto_visual_tris`	visual 三角形數
`auto_collider_tris`	collider 三角形數
`auto_player_max`	由 `RP1.width_m` 推（§5.4 / §8.2）；Stage 3 檢核 `PLAYERS_PER_RACE_MIN`（2）≤ 此值 ≤ `TRACK_MAX_PLAYERS_HARDCAP`（8）——下限不足 = 永遠開不了房、拒收（UGC機制.md §9.3）
`auto_route_polyline_3d`	route spline 的等弧長預採樣折線（3D 點序列）；runtime b-soft 查最近點用，免於 spline 解析閉式解
`auto_narrowest_path_m`	BVH 沿 `auto_route_polyline_3d` 掃描最窄寬度（賽前場地相容性檢查用：車輛 AABB.x + `NARROWEST_PATH_MARGIN_M`（0.05）≤ 此值，警告不阻擋，見比賽進行.md）
`auto_density_warning`	視覺密度 < 5 tri/m² 時為 true
`auto_exposure`	authored cache；canonical current PhysicsManifest 保存 typed grid（resolution、重力平面 origin／cell、up、每格第一靜態 solid 高度或 null），admission 由實際幾何重建。runtime 不讀 raw 本欄，見 §8.3
`auto_magnet_sources`	靜態磁源清單 `[{ node, pos, strength_n, n_pole }]`（`pos` / `n_pole` 皆 `[x, y, z]`）；每個材質 `magnetism_role: source` 的 mesh node（自身 `magnet_source_strength_n > 0`）一項——`pos` = mesh 幾何質心、`n_pole` = 面積加權平均法向（退化 → node +Z）、`strength_n` = node extras 值；runtime 免掃 mesh 直接消費（算式表.md §5.1）

9. 場地 Entity（GLB 子節點物件）¶

Entity = 場地 GLB 內帶 entity_type extras 標記的子節點。場地僅一個 GLB 檔，所有可破壞物件 / 動態物件 / 純裝飾物件皆為其子節點。RoutePoint（起終點）/ Checkpoint 不是 entity，而是場地設定（Empty Node，見 §5.4）。

9.1 Entity 3 類¶

類別	physics	用途
`decoration`	`visual_only` / `default`	純裝飾或可破壞物件（靜態 collider）
`kinematic_move`	`default`	動態位移（旋轉門 / 推板 / 升降平台 / 兩階段瞬移）
`kinematic_conveyor`	`default`	輸送帶（表面速度推動接觸物）

磁場物件實現：「任意 entity + magnetism_role: source 材質 sub-mesh + Root Extras magnet_source_strength_n」即構成磁鐵物件。詳見 §9.4 與材質表.md §8.2。

9.2 Entity Node-level Extras¶

每個 entity 對應一個獨立 mesh node，extras 包含：

field	desc	適用條件
`entity_type`	3 選 1 enum	全部
`material`	統一材質表 enum	全部
`physics`	`default` / `visual_only`（visual_only 僅 `decoration`）	全部（kinematic_* 強制 `default`）
`destructible`	通用參數（任何 type 皆可設）；僅 `physics: default` 時生效	全部
`motion_curve`	`sin`（連續往返）/ `step`（兩階段瞬移）/ `linear`（等速三角波）	`kinematic_move`
`period_ms`	週期（ms，≥ `KINEMATIC_PERIOD_MS_MIN`（500，protocol.md §3））	`kinematic_move`
`phase_offset_ms`	相位偏移（ms）	`kinematic_move`
`amplitude_m`	位移向量 `[x, y, z]`（m；entity local frame，entity 旋轉時位移方向隨之）；向量長度 ≤ `KINEMATIC_AMPLITUDE_M_MAX`（20 m）	`kinematic_move`（與旋轉模式至少填一、可並用）
`rotation_axis`	旋轉軸單位向量 `[x, y, z]`（entity local、過 node 原點；解析時 normalize，同 §8.4 `gravity_direction` 慣例）	`kinematic_move` 旋轉模式（與 `rotation_amplitude_deg` 成對）
`rotation_amplitude_deg`	1–360：360 = 連續旋轉（等角速度、`period_ms` = 一圈、`motion_curve` 不適用）/ < 360 = 往返揮動（依 `motion_curve`）；語義比照 §3.7 `weapon_max_angle_deg`	`kinematic_move` 旋轉模式
`open_duration_ratio`	period 中位於位移 / 旋轉終點的比例（0–1）；僅 `step` 有「停留」語意，`sin` / `linear` 為連續運動無此欄位	`kinematic_move` + `motion_curve: step`（其他 motion_curve 不可填）
`conveyor_velocity_m_s`	表面速度（沿 entity 自身 -Z 軸，Blender forward 慣例，與 §5.4 RoutePoint forward 一致），m/s；絕對值 ≤ `CONVEYOR_VELOCITY_M_S_MAX`（10）、負值反向	`kinematic_conveyor`
`auto_fragments`	Stage 3 預烘焙 `{version,count,method,total_volume_loss_pct,fragments[{fragment_index,seed_m,volume_m3}]}`；canonical current PhysicsManifest 保存同一完整純視覺 descriptor，不含 fragment mass／collider／pose／velocity。runtime 只讀 typed manifest，不讀 raw extras。	`destructible: true` 的 entity（僅這些 entity 烘焙）

Kinematic 固定幀驅動：finalizer 把 period_ms／phase_offset_ms 正規化為 60Hz 整數 frame，runtime 以 state(frame) = f(frame, periodFrames, phaseOffsetFrames, amplitude / rotation, motion_curve) 推導，禁止 wall clock；sin／旋轉使用版本固定 deterministic 近似。運動模式：平移（amplitude_m）與旋轉（rotation_axis + rotation_amplitude_deg）至少填一、可並用（並用 = 螺旋運動，如旋轉升降平台）；皆沿 entity local frame。

9.3 destructible 通用參數¶

name	field	desc	required	auto	edit
可破壞	`destructible`	任何 entity_type 都可加；僅 `physics: "default"` 時生效；mass / 破壞閾值由材質自動算	❌（預設 false）	❌	✏️ Stage 2 checkbox；visual_only 時灰掉

破壞行為（fatigue ≥ 1.0 或單次 stress > ultimate × K_STRESS_BURST_FACTOR，K 預估 1.5，見程式參數.md / 算式表.md §7）：

立即停止 kinematic 驅動（kinematic_move 停止往返、kinematic_conveyor 表面速度歸零、磁源 sub-mesh 失效）
停用 intact body／colliders／完整 visual；不得把 intact body 改成 Dynamic
不建立、啟用或保留 fragment body／collider／sensor；碎片不參與物理、傷害或路障
presentation 由 entityIndex + breakFrame + descriptor/presentation version 重建，不保存逐片 pose／velocity
車輛與場地碎片共用 VISUAL_FRAGMENT_LIFETIME_MS（5000ms）與 VISUAL_FRAGMENT_FADE_MS（1000ms）；逾期不生成

可破壞性決策見材質表.md §10；耐受度因子族算式見算式表.md §7。

9.4 磁源強度共用欄位¶

name	field	scope	desc	required	auto	edit
磁源強度	`magnet_source_strength_n`	零件 = Root Extras / 場地 entity = node-level extras	主動磁源強度（牛頓）；正常僅場地 entity / 地板（`magnet_floor`）使用——車輛部件（含 passive 武器）正常無 `source` 材質、異常出現即設定錯誤的 fallback 防護（材質表.md §8.2）；僅當該物件含 `magnetism_role: source` 材質 sub-mesh 時生效；未宣告 = 0（等於有磁源材質但未磁化）	❌（預設 0）	❌	✏️ Stage 2 數值欄位，範圍 0–10（`MAGNET_SOURCE_STRENGTH_N_MAX`）

物件「是磁鐵」條件（兩者缺一無效）：

至少一個 sub-mesh 的材質 magnetism_role: source
magnet_source_strength_n > 0

N 極方向：sub-mesh 面積加權平均法向（pre-bake 入 extras、多 sub-mesh 各自一向量；退化 fallback node +Z，材質表.md §8.3）。

互動算式詳見材質表.md §8.4 + 算式表.md §5。

場地¶