Show live data

Keep npm run dev from the last step running and open http://localhost:5173/?demo in a browser, so you see each change at once.

How the overlay gets data

Open src/main.ts. All talk with Racelink happens in two places:

const overlay = createOverlay<Settings>({ defaults: defaultSettings });

// …

overlay.on('telemetry', (telemetry) => {
  if (overlay.ready) render(telemetry);
});

• createOverlay connects to Racelink (or turns on demo data) and returns the overlay object.
• overlay.on('telemetry', …) calls your function whenever new data arrives. The template passes it to render, which updates the page.

The data is grouped in topics: car — pedals, speed, gear; timing — lap times; fuel — fuel; drivers — every car in the session; weather — the weather, and more. Each topic comes at its own rate: car up to 60 times a second, timing 4, weather 1.

Where to find fields

The full path to a value is the topic and the field with a dot. There are three ways to find one.

Studio → API data

In Racelink open Studio and the API data tab: every field with its description, rate and current value. You can search by path and description and turn on Only fields of the current game. Clicking a path copies it; right-click → Copy as code gives a ready line such as overlay.telemetry.car.rpm. Without a game the values are empty, but the list of fields is always there.

Field reference

The file node_modules/@racelink/overlay/docs/reference/fields.md in your project: every field, its type, unit and the games that fill it. Open it in VS Code and press Ctrl + Shift + V to see the tables.

Editor suggestions

The SDK is written in TypeScript, so the editor knows every field. Type car. inside render and VS Code lists the fields; if the list does not appear, press Ctrl + Space.

Add the last lap time

In the reference or in API data find timing.lap.lastSeconds: the last lap time in seconds, type number | null. We show it under the speed. Make four changes in src/main.ts and src/style.css.

1. Add an element for the lap to the markup, after <span class="speed">:

  <div class="readout"><strong class="gear">N</strong><span class="speed"></span><span class="lap"></span></div>

2. Below the const speed = … line, find that element and add a function that turns seconds into the usual form:

const lap = root.querySelector<HTMLElement>('.lap');

// Lap time as 1:42.315; a dash while there is none.
const formatLap = (seconds: number | null): string => {
  if (seconds === null) return '—';
  const minutes = Math.floor(seconds / 60);
  return `${minutes}:${(seconds - minutes * 60).toFixed(3).padStart(6, '0')}`;
};

3. In render take the timing topic as well as car, and show the time at the end of the function:

const render = ({ car, timing }: TelemetryTopics): void => {
  // …the existing lines stay as they are…
  if (lap) lap.textContent = formatLap(timing.lap.lastSeconds);
};

4. Add a style at the end of src/style.css:

.lap {
  font-size: clamp(10px, 12cqh, 28px);
  font-variant-numeric: tabular-nums;
  opacity: 0.8;
}

Save both files. With ?demo a time such as 1:44.200 appears under the speed. Remove ?demo from the address: with Racelink running and no game, you see a dash instead. font-variant-numeric: tabular-nums gives all digits the same width, so the time does not jitter as it changes.

Values that are missing

The dash is no accident. Not every game gives every value, and not at every moment: before the first completed lap there is no last lap time, and in Assetto Corsa Rally Racelink does not send lap times. Such a value is null. The field itself always exists, in every game, so the code only has to handle null.

TypeScript keeps track of this. Write timing.lap.lastSeconds.toFixed(3) and the editor underlines the line in red:

'timing.lap.lastSeconds' is possibly 'null'.

It means: “this can be null; decide what to show then”. Usually that is a dash, or the element is hidden. In the reference such fields have the type number | null, and the Games column shows which games fill them.

Units are the same in every game

Racelink converts every game’s data to the same units, so the same code works everywhere. The unit is often in the field’s name:

Speed

km/h — car.speedKph

Pedals

0 to 1 — car.throttle, car.brake

Time

seconds — timing.lap.lastSeconds

Fuel

litres — fuel.levelLiters

Temperature

°C — weather.trackTemperatureC

Angles

radians — car.headingRad

If the player prefers miles per hour, convert when you show the value, as the template does with the speed. The data itself does not change.

If something goes wrong

• Nothing changed. Check that you saved both files and that npm run dev still runs.
• The overlay disappeared and the browser console says Cannot read properties of undefined — a typo in a path, such as timing.laps instead of timing.lap. VS Code underlines such typos in red too.
• The time does not change. That is expected: the last lap changes once per lap, in the demo about every 1 minute 44 seconds.