🏎️ Gauge
The Gauge widget is a high-fidelity analog-style indicator. Unlike the simple Arc, the Gauge includes structured scales, major and minor tick marks, and a needle indicator, making it the perfect choice for industrial dashboards, automotive clusters, and professional monitoring tools.
⚙️ Properties (Props)
The Gauge configuration is defined by the GaugeWidget interface. It combines geometric pathing with data-driven labels.
| Property | Type | Description |
|---|---|---|
| Value | number | The current position of the needle. |
| Range | number | The Min and Max values of the scale (e.g., 0-8000 for RPM). |
| Scale Angle | number | The total sweep of the gauge in degrees (e.g., 240° or 270°). |
| Tick Count | number | The number of major divisions (labels) on the scale. |
| Critical Value | number | A threshold value that triggers a visual change (e.g., the "Redline"). |
🛠 Anatomy of a Gauge
The Gauge is composed of three primary layers that can be customized in the Style Panel:
- The Scale (Main): The background arc where the tick marks and labels are rendered.
- Tick Marks: Major ticks (usually with numbers) and minor ticks (for precision). You can adjust their length, thickness, and color.
- The Needle: The moving indicator. You can change its shape from a simple line to a tapered needle or even a custom image.
🎨 Visual Thresholds
Using the criticalValue property, you can define a "Danger Zone." When the needle surpasses this value, the engine can automatically:
- Change the color of the scale arc.
- Flash the needle color.
- Trigger a specific Event to alert the user.
⚡ Runtime API (Lua)
The Gauge is highly responsive to real-time data input.
-- Update the needle position smoothly
gauge_speedo:set_value(data.speed)
-- Dynamically change the critical threshold
-- Useful for variable redlines based on engine temperature
gauge_rpm:set_critical_value(6500)
-- Adjust the scale labels at runtime
gauge_volt:set_range(0, 24)
For a "Modern Electric" look, keep the Tick Count low and use a wide Scale Angle. For a "Classic Analog" look, use more ticks and a shorter, thicker needle.
🚀 Next Steps
- Arc — A simpler version of the gauge without ticks or needles.
- Meter — Use this for vertical or horizontal linear scales.
- Logic and Events — Connect your gauge to hardware sensors via Lua.