HUD Style Reference

HUD 樣式參考

目前 main 內建 10 個 HUD package。選單不是靠固定清單，而是由 /api/hud/styles 動態掃描有效的 index.html；本頁的 Style ID 是 package/discovery 名稱。共用啟動、元素、縮放、音訊/媒體與 package 部署方式請看 HUD Overlay 總覽 和 HUD 開發指引。

快速選擇

Style ID	顯示名稱	主要定位	特別設定/注意
advanced	Advanced Racing Arc	高資訊密度競賽弧形錶	動態 redline、lockup、power/torque、boost
drift	Drift HUD	漂移角度、流暢度與風險	固定 Drift layout；沒有解析度 preset
fm4ui	Forza Motorsport 4	原作風格數位弧錶	目錄 ID 與內部 registry ID 不同
gt7	Gran Turismo 7	底部寬幅 telemetry cluster	依賴圖片資產，適合寬螢幕底部
mw2005	NFS Most Wanted 2005	類比轉速、NOS/Boost	依賴多個 gauge/needle/flash 資產
nfs15	Need for Speed 2015	資產序列驅動的數位弧錶	大量 RPM/redline frame，需完整預載
s650_hmi	Ford Mustang HMI	多主題 Mustang cluster	s650Theme、s650CenterWidget、s650HmiOffsetY
shift_tacho	Need for Speed Shift	高對比類比轉速與 shift light	ABS/TCS 圖示目前是 placeholder
simple	Simple Gauge	簡潔圓錶、速度/檔位清楚	custom color、motion、共用 cards
vfd	Retro VFD	VFD 數字、音訊 visualizer、媒體	vfdVuOffset 有效；vfdAudioOffset 尚未接通

所有 style 都共用 scale、unit/effectiveUnits、elements、glowIntensity、customColor、useDefaultColors、enableSmoothing 和共用 Telemetry Cards 開關。下列 scaleMultiplier 是程式內的基準，不是使用者設定值；使用者最後看到的大小仍受 Overlay scale、viewport 和 style container 影響。

advanced — Advanced Racing Arc

功能

高效能競賽弧形轉速表，包含速度、檔位、RPM、換檔區、Boost、馬力/扭力、四輪 lockup indicator 與 motion effect。適合需要主儀表與車況警示同時可見的競賽畫面。

技術解析

使用 advCanvasStatic 與 advCanvas 兩張約 1450x750 Canvas。靜態層負責刻度、palette 和幾何；動態層負責指針/讀值、redline、power/torque、boost、lockup dot 和 motion。弧線使用 superellipse 幾何，HUDCore registry ID 為 advanced，scaleMultiplier 為 0.5。redline 優先使用 payload.redlineRpm，lockup 使用 coordinator 的 payload.lockup。

使用與設定

在 Displays/Performance 開啟或關閉 gauge、RPM、speed、gear、power/torque、boost、wheel lockup、motion effect。調整 glowIntensity 和 custom color 時，主錶與 DOM readout 應同步。沒有額外 style-specific 設定；若想隱藏中央 cluster，使用共用 Telemetry Cards 開關。

維護注意

修改靜態 palette、最大刻度或 redline 幾何時要設 dirty flag；不要把靜態背景每幀重畫。onFrame 不應重新建立 Canvas 或 deep-copy telemetry。

drift — Drift HUD

功能

以漂移角度、方向盤 counter-steer、油門/煞車、速度與轉速為核心，另有 Style Meter：FLOW、HOLD、RISK、EVENT 等狀態，適合漂移練習和動態回饋。

技術解析

頁面 Canvas 是 1920x1080，邏輯 Drift layout 約 1680x640，以 viewport transform、bottom-right/center-bottom anchor 適應 fullscreen。HUDCore registry ID 為 drift，scaleMultiplier/globalScaleFactor 都是 1.0。onFrame 解析 canonical telemetry，獨立 requestAnimationFrame render loop 負責繪圖；style meter DOM 更新有約 80ms 節流。

漂移數學會從速度平面推導 drift angle，steer indicator 約以 ±45° 顯示，counter 狀態會參考 drift angle 和 steer 對齊。torque 顯示依 torque_nm 或 torque_ftlbs 選擇單位。

使用與設定

使用一般 scale、unit、elements 和共用 card 設定即可。Drift 不再提供 resolution preset；固定資訊框架由 HUD 繪製，外層 scale/viewport 由 framework 管理。不要在 control page 重新加入已移除的 preset。

維護注意

onFrame 只更新最新狀態，完整渲染留在單一 render loop。新增衍生指標時要明確寫出輸入欄位、clamp、平滑係數和門檻，避免與其他 HUD 對同一物理量產生不同語意。

fm4ui — Forza Motorsport 4

功能

重現 Forza Motorsport 4 的數位儀表風格，重點是 RPM 分段弧面、速度、檔位和 shift sweep，適合喜歡原作視覺資產的使用者。

技術解析

package/discovery ID 是 fm4ui，但頁面內 HUDCore.registerStyle() 和 HUDCore.init() 使用 fm4_re；這是刻意保留的相容例外。Canvas 約 270x270，scaleMultiplier 為 1.4。rpm_bands 依車輛 maximum RPM 選擇背景和 frame rate，資產包含例如 rpm_4600、rpm_6200、rpm_8000、rpm_12100、rpm_16500 等級距。

使用與設定

只需共用 style、scale、unit、elements 和 glow 設定；RPM band 由 runtime 依最大 RPM 選擇，不提供使用者手動切換。若樣式不出現在清單，先查 /api/hud/styles 的 fm4ui，不要把 selector 直接改成 fm4_re。

維護注意

新增 RPM band 應同時補 metadata、圖片資產、fallback 與 frame-rate mapping。registry ID 與目錄 ID 的雙名稱要在 code review 和文件中保留說明。

gt7 — Gran Turismo 7

功能

底部寬幅 layout，結合輪胎溫度、踏板輸入、G-Force、Boost、速度/檔位與圖片化視覺背景。適合寬螢幕、想把主要儀表和中央車況橫向排列的使用情境。

技術解析

主 Canvas 約 1740x240，scaleMultiplier 為 1.0。drawTires、drawBoost 和 renderGT7 在預載資產上疊加 Canvas 動態資料；大畫布會使用 context translate 容納 layout 需要的座標。共用 Telemetry Cards 仍由 host 管理，不能因為 GT7 自己畫 tire cluster 就假定 shared cards 已關閉。

使用與設定

使用一般 scale、unit、elements、glow 和共用 cards 控制。沒有額外 style-specific 設定；若背景或數字缺失，先檢查 asset path、預載完成與 onAnimate 是否在資產 ready 前被延後。

維護注意

保持 asset preload 和 sweepPending 模式；不要在 onFrame 直接新建圖片。變更寬幅座標時要用實際 viewport 驗證底部邊界與不同縮放倍率。

mw2005 — NFS Most Wanted 2005

功能

類比轉速表搭配獨立 boost/NOS gauge、needle、gear/speed 數字和 shift flash，視覺接近 NFS Most Wanted 2005。

技術解析

Canvas 約 390x390，scaleMultiplier 為 0.95。背景、RPM line、boost_gauge、boost_needle、nos_time、shift_flash 以圖片 layer 合成；指針在獨立 transform/rotate 層繪製。資產以 isReady、sweepPending 控制啟動動畫。

使用與設定

Boost/NOS 是否顯示取決於共用 elements/資料有效性；沒有額外需要填寫的 style-specific 設定。若想減少畫面資訊，可關閉共用 cards 或不需要的 motion/gauge 元素。

維護注意

確認每個圖片的 onload 和 onerror 都會完成 preload 計數。修改針角、boost 範圍或 NOS 時間顯示時，要以 canonical boost/unit 和狀態 fallback 為準。

nfs15 — Need for Speed 2015

功能

資產驅動的現代數位弧形儀表，包含速度/檔位、RPM 動畫、redline 變化和一次性的換檔閃光。

技術解析

Canvas 約 331x320，scaleMultiplier 為 1.5。實作預載約 359 張 RPM sequence frame 與 19 張 redline frame，依 RPM/max RPM 算出 frame index；lastGear 變更時觸發 shift flash。這是高資產數量樣式，啟動時一定要等待 preload 或使用 sweepPending。

使用與設定

使用共用 scale、unit、elements、glow、color 和 cards。沒有額外 style-specific 設定；高 DPI 或載入較慢時，先確認所有資產完成，再判斷是否是渲染效能問題。

維護注意

不可把 359 張 frame 轉成每幀新建的 DOM/image。新增或替換 sequence 時要檢查 frame 數、索引邊界、缺圖 fallback、redline frame 對應和 gear transition。

s650_hmi — Ford Mustang HMI

功能

多主題 Mustang S650 HMI cluster，提供 normal、track、heritage67、foxbody 四種 theme，並可切換中央 widget：disable、drive、tire_temp、performance。適合希望使用車廠 HMI 語彙或需要主題切換的使用者。

技術解析

Canvas contract 固定為 1280x480，safe zone 為 top/left/right/bottom 40/48/48/40，左右 gauge center 約為 (256,250) 和 (1024,250)，半徑約 180。renderer 分成 contract、tokens、primitives、cluster components、performance clusters、base driving、center info、layout profiles/layouts/frame；以 Canvas 作為 60Hz 邊界。HUDCore registry ID 為 s650_hmi，使用 S650 專屬 scale baseline/multiplier。

Contract 的 frame 會使用 speed、RPM、gear、pedals、distance、heading、四輪胎溫、power/torque、boost、fuel/lap/race position 等欄位；單位由共用 payload 統一。

使用與設定

設定	可用值	用途
s650Theme	normal、track、heritage67、foxbody	選擇 HMI 外觀/色彩/配置
s650CenterWidget	disable、drive、tire_temp、performance	選擇中央資訊模組
s650HmiOffsetY	數字，預設約 60	HMI outer container 垂直位置

這三個設定只有 S650 會消費；其他 style 不應讀取它們。

維護注意

修改 contract 欄位或 layout profile 時，要同步確認 renderer、theme token、control page、legacy normalization 和四種 theme。不要在每個 theme 重複寫單位或 telemetry mapping。

shift_tacho — Need for Speed Shift

功能

高對比 NFS Shift 類比轉速表，中央速度/檔位搭配 7 段 shift light；另有 ABS/TCS 等視覺 indicator array。

技術解析

Canvas/容器約 440x280，scaleMultiplier 為 0.9。七段 shift light 由綠色前兩段、黃色中間兩段、橙/紅色最後三段組成，依 RPM/redline 門檻點亮。indicator 以預載圖片資產顯示。

使用與設定

使用共用 RPM、scale、unit、elements、glow 和 cards。ABS/TCS 圖示目前沒有對應的 telemetry data source，應視為 placeholder，不要在文件或 UI 宣稱它們是已驗證的即時狀態。

維護注意

若改 shift light 門檻，仍要以 payload.redlineRpm 為共用基準。圖片預載需處理 error completion；不要為了讓 indicator 亮起而在 style 內猜測 ABS/TCS 狀態。

simple — Simple Gauge

功能

簡潔圓形儀表，中央清楚顯示速度與檔位，另有 RPM arc、needle、glow、LC/LOCK badge 和共用 telemetry cards。適合日常使用、低視覺負擔或需要快速讀取速度/檔位的畫面。

技術解析

Canvas 約 750x750，scaleMultiplier 為 0.6。Canvas 負責 RPM arc、needle、glow；DOM 負責 speed、gear 和 badge，並以 cache 避免速度未變時重建數字 span。custom color 透過 window._currentCustomColor、window._currentUseDefaultColors 與 style CSS variable 同步。

使用與設定

可使用一般 scale、unit、glow、custom color、enableSmoothing、motion effect 和所有共用 cards。沒有額外 style-specific 設定。若要最小化畫面，保留 gauge/speed/gear，關閉不需要的 cards 和 motion。

維護注意

Canvas palette 和 DOM palette 必須來自同一份 config。離散 LC/LOCK 狀態應用 class/badge；不要為了 badge 狀態重繪整張 Canvas。

vfd — Retro VFD

功能

Retro VFD 數字/segment 風格儀表，提供速度、RPM、檔位、Boost/EV regeneration 顯示，並整合 32 段音訊 visualizer、左右 VU、媒體標題/演出者、播放狀態、marquee 和視覺/音效 feedback。適合希望 HUD 同時扮演賽車儀表和音訊播放器資訊面板的使用者。

技術解析

主 Canvas 約 1120x520，scaleMultiplier 為 0.75。renderer 以 14-segment/格狀方式繪製文字和 RPM bars，保存 session maxima，音訊 hook 接收 spectrum/VU 並用 peak hold/衰減避免頻譜閃爍；media hook 會過濾不適合的文字、轉成可顯示 ASCII，過長內容才啟用 marquee。Canvas loop 與共用 cards 分開管理。

使用與設定

設定/來源	行為
vfdVuOffset	已接通；調整 VU/音訊區域位置
vfdAudioOffset	設定與控制欄位存在，但目前 VFD page 未使用；不要把它當成已生效功能
audioDeviceId	在 Audio controls 選擇 WASAPI playback device；影響頻譜來源
hud:media	由 GSMTC 提供 title/artist/status；沒有媒體時顯示空狀態

系統音訊不可用時應衰減到靜音，不要停留在最後一個 peak；媒體 paused/none 時不要把舊歌名當成正在播放。

維護注意

onAudio/onMedia 只更新狀態，不要在 hook 內做完整重繪。頻譜固定 32 段且 clamp 到 0–1；修改 VFD 字元轉換或 marquee 時要保留長文字、特殊字元和空資料 fallback。

共用設定快速參考

設定類別	欄位例子	適用
一般	enabled、hudStyle、selectedMonitorIndex、scale	所有 style
單位	unit、followAppUnits、units	所有 style，實際欄位由 coordinator 統一整理
視覺	glowIntensity、customColor、useDefaultColors	所有 style，但各 style 的 palette 角色不同
元素	elements、pauseTelemetryViewWhenActive、enableSmoothing	所有 style/host cards，實際支援仍應逐項驗證
cards	telemetryOpacity、各 card scale/position/offset、Live Map 設定	host-level Telemetry Cards
音訊	audioDeviceId、soundEnabled	使用音訊路徑的 style，尤其 VFD
S650	s650Theme、s650CenterWidget、s650HmiOffsetY	僅 s650_hmi
VFD	vfdVuOffset、vfdAudioOffset	前者有效；後者目前未接線

維護決策

新增 style-specific 設定前，先問它是否能由既有 elements、scale、unit、palette 或 cards 契約解決。若確實是 style 需要的設定，才同步 config type/default、控制頁、launcher normalization、Core payload、style consumer、測試和本頁。新增 style 本身只需要 package、author.json、HUDCore registration 和驗收，不要修改靜態 HUD map。

來源檔案

• hud_overlay/HUD_DEVELOPMENT_GUIDE.md
• frontend/src/features/overlay_control/hudStyleScanner.ts
• hudConfig.ts
• advanced/index.html
• drift/index.html
• s650_hmi/assets/s650_contract.js
• s650_hmi/assets/s650_renderer.js
• vfd/index.html

English

The repository currently contains ten built-in HUD packages: advanced, drift, fm4ui, gt7, mw2005, nfs15, s650_hmi, shift_tacho, simple, and vfd. This reference describes each style’s purpose, rendering architecture, common controls, and verified special settings. s650_hmi has four themes and configurable center widgets; VFD consumes vfdVuOffset, while vfdAudioOffset is currently not wired into the renderer.

日本語

現在の Repository には advanced、drift、fm4ui、gt7、mw2005、nfs15、s650_hmi、shift_tacho、simple、vfd の 10 個の内蔵 HUD package があります。本ページでは各スタイルの目的、描画構成、共通設定、確認済みの追加設定を説明します。s650_hmi は 4 テーマと中央 widget を持ち、VFD は vfdVuOffset を使用しますが、vfdAudioOffset は現在 renderer に接続されていません。