HUD Telemetry Cards

HUD Telemetry Cards

Telemetry Cards 是所有 HUD 可共用的中央遙測 cluster。它不是某個 style 的私有畫面，而是由 launcher host 初始化一次，再隨 canonical telemetry 更新。使用者操作請看 HUD Overlay 總覽；若要改卡片資料或版面，先閱讀 HUD Shared Core 的事件與單位規則。

架構與掛載

flowchart TB
    Host[hud_overlay/index.html] --> Mount[#teleCardsMount]
    Mount --> Manager[TelemetryCardsManager]
    Manager --> Template[template.js]
    Manager --> Radar[g-radar.js]
    Manager --> Corners[corner-card.js]
    Manager --> Pedal[pedal-wave.js]
    Manager --> Power[power-torque.js]
    Manager --> Map[live-map.js]
    Manager --> Utils[utils.js]
    Frame[hud:frame] --> Manager
    Config[hud:config + elements] --> Manager

Loading

入口 shared/telemetry-cards.js 重新 export manager、template、各 renderer 和 utils，並將 singleton 掛到 window.TelemetryCardsManager。launcher 會在 host 的 #teleCardsMount 初始化；多數 HUD 只需要讓 host 顯示/隱藏卡片，不要在 iframe 再建立第二份 cluster。

只有完全獨立的 HUD 頁面需要自己的 cards 時，才建立掛載點並使用：

import { createTelemetryCardsManager } from '../shared/telemetry-cards/manager.js';

var manager = createTelemetryCardsManager();
manager.init(document.getElementById('teleCardsMount'));
manager.update(data, config);
// 切換/關閉頁面時
manager.destroy();

卡片功能

卡片	顯示內容	主要輸入	實作方式
G-Force radar	橫向/縱向 G、車輛動態點、歷史軌跡與 marker	accel_x、accel_y	中央 Canvas/DOM 混合
四角 cards	FL/FR/RL/RR 懸吊行程、歷史波形、四輪 slip angle/ratio、胎溫	susp_*、slip_*、slip_angle_*、TireTemp	每輪子卡片、Canvas wave/radar、溫度色階
Pedal wave	油門與煞車隨時間的波形	throttle、brake	edge chart Canvas，top/bottom 可換位
Power/Torque	馬力、扭力與 RPM 歷史曲線	power、torque、rpm	edge chart Canvas，top/bottom 可換位
Live Map	玩家位置、移動方向、航向、道路背景、POI	pos_x、pos_z、heading_deg	Canvas + live_map_bg.png + POI JSON

四角卡的顯示順序固定是 FL、FR、RL、RR。懸吊與輪胎子區塊可以分開關閉；只關閉 slip 或 temp 時，外層 corner 仍可能保留其他可見子卡片。

顯示開關

元素 map 由 Overlay 控制頁保存，manager 將 master switch 與個別開關合併：

Element	影響
showTeleMaster	所有共用 cards 的總開關
showTeleAttitude	G-Force radar
showTeleSuspension	四角懸吊行程與波形
showTeleTires	四角胎溫/輪胎相關卡片的總開關
showTeleTiresSlip	四輪 slip 子卡片
showTeleTiresTemp	四輪胎溫子卡片
showTelePedals	油門/煞車波形
showPowerTorque	馬力/扭力圖
showLiveMap	Live Map
showTeleCenterAnchor	中央對齊框/anchor
showTeleGridLines	對齊輔助格線
showTeleSideBySideCharts	踏板與 Power/Torque 並排
showTeleCornerEdgeSnap	四角卡靠近螢幕邊緣的 anchor 模式

showTeleMaster 關閉時，子卡片不會繼續更新。新增 element 時要同步 config 型別、控制頁、manager visibility logic、文件和測試；只在模板新增 DOM 而沒有開關會造成設定表面上可用但實際無效。

尺度、透明度與位置設定

設定	預設	作用
telemetryOpacity	0.65	cluster 與 edge chart 的整體透明度；manager 也會保存到 localStorage
telemetryCardFontScale	1.0	共用文字，manager 會限制在 0.5 到 2.0
telemetryGRadarScale	1.0	G-Force radar
telemetryCornersScale	1.0	四角 cards
telemetryPedalScale	1.0	非並排時的 pedal chart
telemetryPowerTorqueScale	1.0	非並排時的 Power/Torque chart
telemetryMergedChartsScale	1.0	並排 chart 的群組
telemetryLiveMapScale	1.0	Live Map
telemetryLiveMapOpacity	1.0	Live Map 自身透明度
telemetryCornerOffsetX/Y	0	四角 cards 的共同位移
telemetryPedalOffsetX	0	非並排 pedal chart 位移
telemetryPowerTorqueOffsetX	0	非並排 Power/Torque 位移
telemetryMergedChartsOffsetX	0	並排 chart 群組位移
telemetryLiveMapOffsetX/Y	0	Live Map 位移
telemetryPedalPosition	bottom	pedal chart 放在 top 或 bottom edge
telemetryPowerTorquePosition	top	Power/Torque chart 放在 top 或 bottom edge
telemetryMergedChartsPosition	bottom	並排 chart 放在哪個 edge
telemetrySideBySideCharts	true	是否將兩個 edge chart 佈置為半寬並排

CSS 變數由 manager 寫入：--tc-font-scale、--tc-corners-scale、--tc-gradar-scale、--tc-corner-offset-x、--tc-corner-offset-y、--tc-live-map-scale、--tc-live-map-opacity 及對應 Live Map offset。--tc-gradar-scale 的拼法是現有程式的相容名稱，修改時不可只改 CSS 而漏掉 manager。

共用 palette 使用 useDefaultColors、customColor 推導 --card-primary 和 --card-contrast。卡片需要與 style 主儀表保持相同色彩，但警示色、溫度色階不應被品牌色完全覆蓋。

資料與計算原則

G-Force

G-Force card 由 coordinator 提供 accel_x/y，renderer 依物理方向轉成畫面座標，再保留 gHist 歷史點。新增顯示時應沿用相同軸向與 clamp，不要在不同 HUD 中各自定義「左/右」或「前/後」。

四角輪胎與懸吊

renderCorners() 同時接受四輪 history、懸吊 min/max 和目前的顯示開關。懸吊 bar 是目前 normalized travel；波形是時間歷史；slip radar 使用 slip angle/ratio；胎溫色彩透過 utils.js 的溫度 helper。缺少某一輪資料時要保留固定四輪結構並使用安全預設，不要把陣列縮短造成 FL/FR 對錯位置。

動力/扭力與踏板

兩個 edge chart 都是歷史型視覺，onFrame 每次只加入新 sample 並由 renderer 繪製。換車後 coordinator 會重置 sessionMaxima；卡片不應把前一台車的峰值當作新車 scale。卡片 disconnected/paused 超過約 1.5 秒時，manager 會清空 history，恢復後從新 sample 開始。

Live Map 與校準

Live Map 讀取 shared/live_map_bg.png 與 shared/japan_pois.json，依 pos_x/pos_z 映射到 Canvas；live-map.js 會載入可用的背景/POI 資料並支援 map calibration 的 scaleX/scaleZ。heading_deg 用於方向箭頭；位置未移動時不要假設航向一定改變。若要新增 POI 或地圖資產，應同時確認 asset load failure 的 fallback 和座標校準，不要把遊戲世界座標硬編碼到某個 HUD style。

共用 renderer 的修改方式

1. 先確認需求是資料契約、卡片計算、模板 DOM 或 manager layout；不要在 style 內以 workaround 修補 shared bug。
2. 修改 template.js 的 ID/class 後，搜尋 manager.js 與所有 renderer 的 getElementById，確保 cache 仍完整。
3. 修改 config 時，從 frontend/src/features/overlay_control/hudConfig.ts 開始，接著檢查 Overlay control、launcher、manager 和 CSS variable。
4. 修改 renderer 時，維持固定 60Hz frame path：不要建立大量 DOM；Canvas context/元素應 cache；陣列 history 要有上限和斷線清理。
5. 新增資料欄位時，先在 HUD Shared Core 定義 canonical meaning/unit，再讓 card 使用。
6. 若卡片是 host-level singleton，切換 style 不應重新初始化一份；若是獨立 manager，必須明確呼叫 destroy()。

除錯與驗收

• 只看不到一張卡：檢查對應 element flag、template ID、manager DOM cache 和 renderer 是否在 show* false 時被跳過。
• 卡片全不見：檢查 showTeleMaster、telemetryOpacity、#teleCardsMount 是否存在，以及 host 是否收到 hud:frame。
• 方向或單位錯：檢查 coordinator 的 canonical field 和 displayUnits，不要先改 renderer 的常數。
• 圖表重疊：檢查 position、side-by-side、scale、offset 的 combination，並確認不是同時套用兩種 layout transform。
• Live Map 偏移：確認背景/POI 資產載入、scaleX/scaleZ 校準、pos_x/pos_z 方向與 heading；不同地圖不能共用未驗證的校準值。
• 效能下降：檢查 history 是否無上限、是否每 frame querySelector、是否重複 init manager 或產生第二個 animation loop。

驗收至少要包含：啟用/關閉每個 card、切換 top/bottom/side-by-side、縮放/offset/opacity、單位切換、無 telemetry、斷線超過 1.5 秒後恢復、切換車輛重置 maxima、Live Map 資產失敗與多次 Launch/Destroy。

來源檔案

• shared/telemetry-cards.js
• shared/telemetry-cards/manager.js
• shared/telemetry-cards/template.js
• shared/telemetry-cards/g-radar.js
• shared/telemetry-cards/corner-card.js
• shared/telemetry-cards/pedal-wave.js
• shared/telemetry-cards/power-torque.js
• shared/telemetry-cards/live-map.js
• frontend/src/features/overlay_control/hudConfig.ts

English

Telemetry Cards are a host-level shared cluster containing G-Force, four-corner suspension/tire cards, pedal and power/torque charts, and Live Map. The manager owns visibility, scale, opacity, positions, history cleanup, and rendering dispatch. Reuse canonical fields from Shared Core, keep DOM/canvas references cached, and destroy independent managers explicitly.

日本語

Telemetry Cards は host レベルの共有クラスターで、G-Force、4 輪のサスペンション/タイヤ、ペダル、パワー/トルク、Live Map を提供します。manager は表示切替、拡大率、透明度、位置、履歴の消去、描画の振り分けを担当します。Shared Core の canonical field を使用し、DOM/Canvas の参照を cache し、独立した manager は明示的に destroy() してください。