Dashboard

Vettura has two kinds of instrument. A vehicle can use either or both:

	Gauges	Screens
What it is	Parts of the model, the needle turning on a bone	A canvas in the cab, drawn by Vettura every frame
Good for	Mechanical dials	LCDs, digital speed, the gear, a clock, fuel bars
How	Model it in Blender, set the scales in gauges	Describe it in screens, optionally with fonts

Gauges

1. Modelling

All of this goes in the <name>_cab collection.

1. Model the dial face. Its part name ends in _dial, e.g. body_speedo_dial. The scale can be in the texture or modelled.
2. Put an Empty on the needle's pivot, named after the bone in the table below.
3. Model the needle. Its part name is <bone>_needle (e.g. speedo_needle), parented to that Empty.

Bone	Reading	Unit
speedo	speed	km/h
tach	engine speed	rpm
fuel_gauge	fuel	0 to 1
temp_gauge	coolant	°C

Leave out the ones you don't need: a vehicle with no rev counter has no tach.

_dial and _needle parts light up while the electrics are on.

2. Model the needle at its lowest reading

Wherever the needle sits in the model is its lowest reading. The game turns it clockwise from there (as the driver sees it), by:

(reading − min) ÷ (max − min) × sweep

So put the needle on the dial's zero mark, not pointing straight up. On a speedometer that runs 270° from bottom left to bottom right, the needle sits at bottom left.

The needle turns about the vehicle's fore-and-aft axis (Blender's Y), not about the normal of the dial. On a dial that leans back, the tip can touch the face at the top of its travel. Keep the needle in a vertical plane, a few millimetres clear of the face. For a dial that leans a lot, use a screen instead.

3. Set the scales

In vehicles/<name>.json:

"gauges": {
  "speedo": {"min": 0, "max": 160, "sweep": 240},
  "tach": {"min": 0, "max": 7000, "sweep": 240},
  "fuel": {"min": 0, "max": 1, "sweep": 90},
  "temp": {"min": 40, "max": 120, "sweep": 90}
}

• min, max: the readings at the two ends of the dial, in the units above.
• sweep: the angle in degrees from min to max. Measure it between the end marks on the dial.
• Past max the needle goes at most 2% further.
• Any left out keep the T15's: rpm 0–5000 and speed 0–180 over 270°, fuel 0–1 and coolant 40–120 over 120°.

Speed is always in km/h. For a dial marked in miles, convert max: 100 mph is 161.

Screens

A screen is a flat canvas with its own pixel coordinates (x right, y down). It shows only while the electrics are on and lights itself.

1. Measure where it goes

Three corners place the canvas: top left tl, top right tr and bottom left bl as the driver sees it, in metres, in the model frame.

In Blender, select a corner of the screen, press Shift+S and choose Cursor to Selected, then press N and read the 3D cursor's (x, y, z). Write [x, z, -y].

Vettura lifts the canvas 1.5 mm towards the driver, so put it right on the modelled face. Corners in the wrong order give a mirrored or upside-down picture.

2. Describe the page

"screens": [
  {
    "corners": {"tl": [-0.50, 0.84, -0.74], "tr": [-0.22, 0.84, -0.74], "bl": [-0.50, 0.74, -0.73]},
    "size": [1200, 440],
    "background": "mypack:textures/screen/main.png",
    "elements": [
      {"type": "needle", "value": "rpm", "pivot": [600, 240], "from": 0, "to": 7000, "angles": [240, 480],
       "radius": [110, 180], "width": [8, 6], "color": "#D12C20"},
      {"type": "text", "value": "speed", "at": [600, 240], "size": 60, "align": "center", "font": "digits"},
      {"type": "text", "value": "gear", "at": [600, 300], "size": 42, "align": "center", "font": "digits"},
      {"type": "cells", "value": "fuel", "count": 8, "at": [900, 200], "step": [25, 0], "cell": [11, 6], "on": "#FFFFFF", "off": "#2A2A2A"},
      {"type": "image", "image": "mypack:textures/screen/high_beam.png", "at": [60, 40], "size": [48, 48], "when": "high_beam"}
    ]
  }
]

size is the canvas in pixels. Every element's coordinates use it, whatever the size of the image. background is optional and stretches over the canvas. A vehicle can have several screens.

Elements:

type	Fields	Notes
needle	value pivot from to angles radius width color	A needle. At reading from it points at angles[0], at to at angles[1]. Angles are clock angles: 0 up, clockwise, and may pass 360. radius is the distance of its root and tip from the pivot, width their widths (default [6, 4])
text	value at size align color font	Text. at is the left end, middle or right end of the line (by align: left center right), at the line's middle height. size defaults to 32. Without font, Minecraft's font
cells	value count at step cell on off	A row of boxes. step is the [x, y] from one to the next, cell a box's width and height. Lit up to the reading's share
image	image at size when	An image. Without when, always shown

Readings (value):

Reading	What	Works in
rpm	engine speed	needle text cells (share of the cut-off rpm)
speed	speed, in the player's unit	needle text
speed_kmh speed_mph	speed in a fixed unit	needle text
fuel	fuel, 0 to 1	needle cells
coolant	coolant, °C	needle text cells (share of 40–120 °C)
air	outside air, °C	needle text
gear	the gear: R N 1…, an automatic's D3 M3	text
clock	the world's time, hh:mm	text

when: low_fuel (below 12%), high_beam, headlights. With any other name the image never shows.

3. Fonts (optional)

LCD digits look right only in their own bitmap font. Lay the characters out in one image, describe it in fonts, and name it in a text element's font:

"fonts": {
  "digits": {
    "image": "mypack:textures/screen/digits.png",
    "size": [512, 256],
    "lineHeight": 96,
    "glyphs": {
      "0": [0, 0, 48, 72, 52, 12, 0],
      "1": [52, 0, 48, 72, 52, 12, 0],
      " ": [0, 0, 0, 0, 26, 0, 0]
    }
  }
}

• size: the font image in pixels.
• lineHeight: the height of a line. A text element whose size equals it is drawn 1:1.
• Each of the glyphs has seven numbers: its x, y, width, height in the image, how far the pen then moves (advance), how far it sits from the top of the line (yOffset) and from the pen (xOffset).
• Characters not listed are skipped, so list the R N D M : that gear and clock use.

Images go under assets/<pack id>/textures/, for example textures/screen/. The id is <pack id>:textures/screen/main.png, with the .png.

Checking

1. Misspelt field names in gauges, screens and fonts are not reported: you just get the default or nothing, so go through the tables above. A wrong element type or a colour that isn't #rrggbb is reported.
2. Take the automatic screenshots on the Testing page and look at driver_running: screens only show with the electrics on, and the engine is running in that one.
3. Drive it:
   • with the engine off, the needles rest on their lowest reading;
   • at a known speed, compare the needle with the HUD;
   • fill the tank and see the fuel gauge reach full;
   • turn on the high beam and see the high_beam image light.
4. A mirrored or upside-down screen: check the order of tl, tr, bl and the conversion to [x, z, -y].