gaugeClusters

A car's speedometer, rev counter and gear display in ten looks, switched live with one word. Every style shows the same three things: speed (km/h or mph), revs with a redline zone, and the gear (R, N, 1…). Each one is drawn with the engine UI and reads like a real instrument: needles, shift lights, seven-segment digits, pixel fonts and holographic arcs.

First example

Paste this into any world. The dummy car pretends to drive (through the gears, braking, reverse), so the gauge moves with no real car:

local dummy = entity.spawn("dummyCar")
dummy.component.add("FakeCar")

local hud = entity.spawn("hud")
hud.component.add("GaugeCluster", { style = "analog", car = dummy })

-- switch the look live, any time:
hud.component.get("GaugeCluster").style = "rally"

Enter play to see it move. With a real car (for example the torqueCars README car), leave car out: the cluster follows the local player's own car.

entity.spawn("hud").component.add("GaugeCluster", { style = "digital", units = "mph" })

GaugeCluster settings

Methods: gauge:setStyle(id), gauge:cycleStyle(dir?), gauge:target() (the car id being read), gauge:reading() (what it shows right now).

From code, without a component

local Gauges = require("gaugeClusters.gauges")
Gauges.show("scifi")                     -- follows the local player's car
Gauges.show("truck", someCar, { units = "mph", anchor = "bottomLeft" })
Gauges.setStyle("pixel")
Gauges.setCar(otherCar)
Gauges.hide()
Gauges.styles()                          --> { "analog", "digital", ..., "truck" }

The parts are public too: gaugeClusters.reader reads any car into one table (read, resolve, gearLabel), gaugeClusters.styles builds each look as a widget tree (S.get(id).build(view, scale, state)), and gaugeClusters.draw holds the canvas helpers (arcs, needles, seven-segment digits, a 3x5 pixel font).

What it reads

The driving contract's named values on the car's chassis entity (see torqueCars.package/CONTRACT.md): car.kmh (or car.speed), car.rpm, car.gear (-1 R, 0 N, 1..n), car.rpmRedline, car.rpmMax, and for flavour car.throttle, car.brake, car.boost, car.limiter. Any car that writes them works. A plain builtin VehicleController car with no values reads too: speed from Physics.vehicleState, 0 rpm, gear -.

Gallery

gallery (a scene) shows all ten side by side, driven by a pretend car:

layers.load(asset.ref("gaugeClusters.gallery", "scene"), { additive = true })

Or put GaugeGallery on any entity (focus = "truck" shows one style large).

Screens and phones

Each cluster fits itself to the screen: about a third of a desktop screen's width, nearly the full width of a phone held upright, and never more than about 36% of the height, so the road stays visible. It lays out inside the safe area, so notches, cutouts and gesture bars never cover it. The UI is a personal overlay: each player sees their own car's cluster, and nothing is synced.

What is inside

Known limits

• What it needs from a car — a car that does not write the driving contract's values shows speed only (from Physics.vehicleState), 0 rpm and gear -.
• Finding your own car — with car empty the cluster reads the car announced as player.vehicle on the local player's avatar or the main camera (torqueCars cars announce themselves while the player drives them), else the avatar or what the camera follows when that is a car. A car that writes the values but announces nothing needs car set.
• #21241 — car is an entity reference and is not synced; the cluster is a personal overlay, so every player's cluster resolves its own car locally.
• Cost — each cluster redraws its UI every frame, about 0.5 ms on a desktop.
• #20946 — phone layouts were checked at phone sizes in the native engine; the web build has not been run.